@oceanum/oceanumlab 4.7.2 → 4.8.0

package/src/__tests__/OceanumPanel.spec.tsx

@@ -16,6 +16,8 @@ interface IPanelOptions {
   token?: string;
   /** Register the host's sign-in commands, and say whether someone is signed in. */
   signedIn?: boolean;
+  /** Widget props to use instead of the defaults below. */
+  props?: Record<string, unknown>;
 }
 
 function panel(options: IPanelOptions = {}): DatameshConnectWidget {
@@ -48,7 +50,8 @@ function panel(options: IPanelOptions = {}): DatameshConnectWidget {
     settingsChanged: new Signal<unknown, void>({}),
     commands,
     getCurrentWidget: () => new Widget(),
-    auth: null
+    auth: null,
+    ...options.props
   } as unknown as ConstructorParameters<typeof DatameshConnectWidget>[0]);
 }
 
@@ -155,3 +158,98 @@ describe('the Oceanum panel', () => {
     widget.dispose();
   });
 });
+
+describe('the Examples switch in the Oceanum panel', () => {
+  const DEMO_ID = '3e4f5a6b-4444-4a2b-8c3d-9e8f7a6b5c4d';
+  const EXAMPLE = '0b7d9f2e-1111-4a2b-8c3d-9e8f7a6b5c4d';
+  const originalFetch = globalThis.fetch;
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const until = async (test: () => boolean): Promise<void> => {
+    const deadline = Date.now() + 4000;
+    while (!test()) {
+      if (Date.now() > deadline) {
+        throw new Error('timed out');
+      }
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  };
+
+  it('saves the choice, and follows the setting once it has changed', async () => {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const demo = String(input).includes('/specs/notebook-demo/');
+      const data: unknown = demo
+        ? {
+            id: DEMO_ID,
+            name: 'Notebook Demo',
+            description: null as string | null,
+            modified: '2026-09-22T10:00:00',
+            creator: null as string | null,
+            spec: {
+              kind: 'notebook-demo',
+              version: 1,
+              sections: [
+                { title: 'Start', items: [{ id: EXAMPLE, title: 'Query' }] }
+              ]
+            }
+          }
+        : [];
+      return { ok: true, status: 200, json: async () => data } as Response;
+    }) as typeof fetch;
+    const auth = {
+      environment: { notebookDemo: DEMO_ID },
+      urls: { specs: 'https://specs.example.com' },
+      ready: Promise.resolve(),
+      user: {
+        sub: 'auth0|1',
+        email: 'me@example.com',
+        name: null as string | null,
+        activeOrg: null as string | null,
+        colorScheme: null as string | null
+      },
+      userChanged: new Signal<unknown, unknown>({}),
+      tokenChanged: new Signal<unknown, unknown>({}),
+      signIn: async (): Promise<void> => undefined,
+      signOut: async (): Promise<void> => undefined,
+      getAccessToken: async (): Promise<string> => 'tok'
+    };
+    // What the host keeps: the setting, and the signal it emits when it changes.
+    // Null until the host's settings load.
+    let shown: boolean | null = null;
+    const saved: boolean[] = [];
+    const settingsChanged = new Signal<unknown, void>({});
+    const widget = await mount({
+      props: {
+        auth,
+        settingsChanged,
+        showExamples: () => shown,
+        setShowExamples: (show: boolean) => saved.push(show)
+      }
+    });
+    const toggle = (): HTMLButtonElement | null =>
+      widget.node.querySelector<HTMLButtonElement>('[role="switch"]');
+    // The tab has loaded, but the examples wait for the setting.
+    await until(() => widget.node.querySelector('.oceanum-notebooks') !== null);
+    expect(toggle()).toBeNull();
+    expect(widget.node.querySelector('[data-example-id]')).toBeNull();
+
+    shown = true;
+    settingsChanged.emit();
+    await until(() => toggle() !== null);
+    expect(toggle()!.getAttribute('aria-checked')).toBe('true');
+    expect(widget.node.querySelector('[data-example-id]')).not.toBeNull();
+
+    toggle()!.click();
+    expect(saved).toEqual([false]);
+
+    // The host saves the setting and says so; the panel reads it again.
+    shown = false;
+    settingsChanged.emit();
+    await until(() => toggle()?.getAttribute('aria-checked') === 'false');
+    expect(widget.node.querySelector('[data-example-id]')).toBeNull();
+
+    widget.dispose();
+  });
+});

package/src/__tests__/StoredNotebooks.spec.tsx

@@ -5,7 +5,9 @@ import React from 'react';
 
 import { IOceanumAuth, IOceanumUser } from '../auth/tokens';
 import { notebooksChanged } from '../share/events';
-import { StoredNotebooks } from '../StoredNotebooks';
+import type { INotebookDemoItem } from '../share/notebook';
+import { NOTEBOOK_ITEM_SELECTOR } from '../share/plugin';
+import { IStoredNotebooksProps, StoredNotebooks } from '../StoredNotebooks';
 
 /** A signed-out auth that records whether sign-in was asked for. */
 function signedOut(): IOceanumAuth & { signIns: number } {
@@ -31,13 +33,22 @@ function signedOut(): IOceanumAuth & { signIns: number } {
 class Harness extends ReactWidget {
   constructor(
     private readonly _auth: IOceanumAuth,
-    private readonly _onSignIn?: () => void
+    private readonly _onSignIn?: () => void,
+    private readonly _onOpenExample?: (item: INotebookDemoItem) => void,
+    private readonly _more: Partial<IStoredNotebooksProps> = {}
   ) {
     super();
   }
 
   render(): React.ReactElement {
-    return <StoredNotebooks auth={this._auth} onSignIn={this._onSignIn} />;
+    return (
+      <StoredNotebooks
+        auth={this._auth}
+        onSignIn={this._onSignIn}
+        onOpenExample={this._onOpenExample}
+        {...this._more}
+      />
+    );
   }
 }
 
@@ -117,6 +128,366 @@ describe('the Notebooks tab while signed in', () => {
   });
 });
 
+describe('the Examples in the Notebooks tab', () => {
+  const MINE = '6f1c1a52-4b8e-4c0f-9a57-1d2e3f4a5b6c';
+  const PUBLIC_EXAMPLE = '0b7d9f2e-1111-4a2b-8c3d-9e8f7a6b5c4d';
+  const OTHER_EXAMPLE = '1c2d3e4f-2222-4a2b-8c3d-9e8f7a6b5c4d';
+  const SHARED = '2d3e4f5a-3333-4a2b-8c3d-9e8f7a6b5c4d';
+  const DEMO_ID = '3e4f5a6b-4444-4a2b-8c3d-9e8f7a6b5c4d';
+
+  const summary = (id: string, name: string, creator: string | null) => ({
+    id,
+    name,
+    description: null as string | null,
+    modified: '2026-09-12T10:00:00',
+    creator
+  });
+
+  // The listing returns a public example as shared with every signed-in user.
+  const LISTING = [
+    summary(MINE, 'Mine', 'me@example.com'),
+    summary(PUBLIC_EXAMPLE, 'Query (example)', null),
+    summary(SHARED, 'Shared', null)
+  ];
+
+  const DEMO = {
+    ...summary(DEMO_ID, 'Notebook Demo', null),
+    spec: {
+      kind: 'notebook-demo',
+      version: 1,
+      sections: [
+        {
+          title: 'Getting started',
+          items: [
+            {
+              id: PUBLIC_EXAMPLE,
+              title: 'Query a datasource',
+              summary: 'One line'
+            },
+            { id: OTHER_EXAMPLE, title: 'Plot waves' }
+          ]
+        },
+        // A curator's own example is also theirs: it stays in My notebooks.
+        { title: 'Advanced', items: [{ id: MINE, title: 'Spectra' }] }
+      ]
+    }
+  };
+
+  const ok = (data: unknown): Response =>
+    ({ ok: true, status: 200, json: async () => data }) as unknown as Response;
+
+  function signedIn(notebookDemo?: string): IOceanumAuth {
+    const auth = signedOut();
+    (auth as { user: IOceanumUser | null }).user = {
+      sub: 'auth0|1',
+      email: 'me@example.com',
+      name: null,
+      activeOrg: null,
+      colorScheme: null
+    };
+    auth.getAccessToken = async () => 'tok';
+    (auth as { environment: unknown }).environment = notebookDemo
+      ? { notebookDemo }
+      : {};
+    return auth;
+  }
+
+  const originalFetch = globalThis.fetch;
+  let fetches: string[];
+  function stubFetch(demo: () => Response = () => ok(DEMO)): void {
+    fetches = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      fetches.push(url);
+      return url.includes('/specs/notebook-demo/') ? demo() : ok(LISTING);
+    }) as typeof fetch;
+  }
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  async function render(
+    auth: IOceanumAuth,
+    onOpenExample?: (item: INotebookDemoItem) => void,
+    more: Partial<IStoredNotebooksProps> = {}
+  ): Promise<Harness> {
+    const widget = new Harness(auth, undefined, onOpenExample, more);
+    Widget.attach(widget, document.body);
+    const deadline = Date.now() + 4000;
+    while (!widget.node.querySelector('.oceanum-notebooks')) {
+      if (Date.now() > deadline) {
+        throw new Error('the Notebooks tab did not load within 4s');
+      }
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+    return widget;
+  }
+
+  /** The section whose heading starts with `title`. */
+  function section(widget: Harness, title: string): HTMLElement | null {
+    const sections = widget.node.querySelectorAll<HTMLElement>(
+      '.oceanum-notebooks-section'
+    );
+    return (
+      Array.from(sections).find(node =>
+        node
+          .querySelector('.oceanum-notebooks-heading')
+          ?.textContent?.startsWith(title)
+      ) ?? null
+    );
+  }
+
+  const idsIn = (node: HTMLElement | null, attribute: string): string[] =>
+    Array.from(node?.querySelectorAll(`[${attribute}]`) ?? []).map(
+      row => row.getAttribute(attribute) ?? ''
+    );
+
+  it('offers Upload where the host can upload, and runs it on click', async () => {
+    stubFetch();
+    let uploads = 0;
+    const widget = await render(signedIn(), undefined, {
+      onUpload: () => {
+        uploads++;
+      }
+    });
+
+    const button = widget.node.querySelector<HTMLButtonElement>(
+      '.oceanum-notebooks-upload'
+    );
+    button!.click();
+
+    expect(uploads).toBe(1);
+    Widget.detach(widget);
+  });
+
+  it('has no Upload button where the host cannot upload', async () => {
+    stubFetch();
+    const widget = await render(signedIn());
+
+    expect(widget.node.querySelector('.oceanum-notebooks-upload')).toBeNull();
+    Widget.detach(widget);
+  });
+
+  it('lists the record’s examples in order, under their section titles', async () => {
+    stubFetch();
+    const widget = await render(signedIn(DEMO_ID));
+
+    const examples = section(widget, 'Examples')!;
+    expect(examples).not.toBeNull();
+    expect(
+      Array.from(
+        examples.querySelectorAll('.oceanum-notebooks-subheading'),
+        node => node.textContent
+      )
+    ).toEqual(['Getting started', 'Advanced']);
+    const rows = Array.from(
+      examples.querySelectorAll<HTMLElement>('[data-example-id]')
+    );
+    expect(rows.map(row => row.textContent)).toEqual([
+      'Query a datasource',
+      'Plot waves',
+      'Spectra'
+    ]);
+    expect(rows.map(row => row.getAttribute('data-example-id'))).toEqual([
+      PUBLIC_EXAMPLE,
+      OTHER_EXAMPLE,
+      MINE
+    ]);
+    expect(rows[0].getAttribute('title')).toBe('One line');
+    expect(
+      examples.querySelector('.oceanum-notebooks-count')?.textContent
+    ).toBe('3');
+    expect(fetches).toContain(
+      `https://specs.example.com/specs/notebook-demo/${DEMO_ID}`
+    );
+    widget.dispose();
+  });
+
+  it('moves examples out of Shared with me, but leaves My notebooks alone', async () => {
+    stubFetch();
+    const widget = await render(signedIn(DEMO_ID));
+
+    expect(idsIn(section(widget, 'Shared with me'), 'data-spec-id')).toEqual([
+      SHARED
+    ]);
+    expect(idsIn(section(widget, 'My notebooks'), 'data-spec-id')).toEqual([
+      MINE
+    ]);
+    widget.dispose();
+  });
+
+  it('asks for nothing more and shows no Examples where none is configured', async () => {
+    stubFetch();
+    const widget = await render(signedIn());
+
+    expect(section(widget, 'Examples')).toBeNull();
+    expect(fetches).toEqual(['https://specs.example.com/specs/notebook']);
+    // Without a record, a public example is just another shared notebook.
+    expect(idsIn(section(widget, 'Shared with me'), 'data-spec-id')).toEqual([
+      PUBLIC_EXAMPLE,
+      SHARED
+    ]);
+    widget.dispose();
+  });
+
+  it('says so when the record cannot be read, and still lists the rest', async () => {
+    stubFetch(
+      () => ({ ok: false, status: 404, json: async () => ({}) }) as Response
+    );
+    const widget = await render(signedIn(DEMO_ID));
+
+    const examples = section(widget, 'Examples')!;
+    expect(
+      examples.querySelector('.oceanum-text-error')?.textContent
+    ).toContain('The examples could not be loaded.');
+    expect(examples.querySelector('[data-example-id]')).toBeNull();
+    expect(idsIn(section(widget, 'My notebooks'), 'data-spec-id')).toEqual([
+      MINE
+    ]);
+    expect(idsIn(section(widget, 'Shared with me'), 'data-spec-id')).toEqual([
+      PUBLIC_EXAMPLE,
+      SHARED
+    ]);
+    widget.dispose();
+  });
+
+  it('keeps example rows out of the stored-notebook row menu', async () => {
+    // Its Rename and Delete would act on Oceanum's own example records.
+    stubFetch();
+    const widget = await render(signedIn(DEMO_ID), () => undefined);
+
+    const rows = section(widget, 'Examples')!.querySelectorAll('button');
+    expect(rows).toHaveLength(3);
+    for (const row of Array.from(rows)) {
+      expect(row.matches(NOTEBOOK_ITEM_SELECTOR)).toBe(false);
+    }
+    widget.dispose();
+  });
+
+  it('opens an example through onOpenExample, with its title', async () => {
+    stubFetch();
+    const opened: INotebookDemoItem[] = [];
+    const widget = await render(signedIn(DEMO_ID), item => opened.push(item));
+
+    section(widget, 'Examples')!
+      .querySelector<HTMLButtonElement>(`[data-example-id="${OTHER_EXAMPLE}"]`)!
+      .click();
+
+    expect(opened).toEqual([{ id: OTHER_EXAMPLE, title: 'Plot waves' }]);
+    widget.dispose();
+  });
+
+  const switchIn = (widget: Harness): HTMLButtonElement | null =>
+    section(widget, 'Examples')!.querySelector<HTMLButtonElement>(
+      '[role="switch"]'
+    );
+
+  it('puts a switch on the Examples heading that asks to hide them', async () => {
+    stubFetch();
+    const changes: boolean[] = [];
+    const widget = await render(signedIn(DEMO_ID), undefined, {
+      showExamples: true,
+      onShowExamplesChange: show => changes.push(show)
+    });
+
+    const toggle = switchIn(widget)!;
+    expect(toggle.getAttribute('aria-checked')).toBe('true');
+    expect(toggle.getAttribute('aria-label')).toBe('Show examples');
+    expect(
+      section(widget, 'Examples')!
+        .querySelector('.oceanum-notebooks-heading')!
+        .contains(toggle)
+    ).toBe(true);
+
+    toggle.click();
+
+    expect(changes).toEqual([false]);
+    widget.dispose();
+  });
+
+  it('keeps hidden examples folded under their heading, with the switch to bring them back', async () => {
+    stubFetch();
+    const changes: boolean[] = [];
+    const widget = await render(signedIn(DEMO_ID), undefined, {
+      showExamples: false,
+      onShowExamplesChange: show => changes.push(show)
+    });
+
+    const examples = section(widget, 'Examples')!;
+    expect(examples.querySelector('[data-example-id]')).toBeNull();
+    expect(
+      examples.querySelector('.oceanum-notebooks-count')?.textContent
+    ).toBe('3');
+    // Hidden, not forgotten: the record is still read, and its examples stay out of
+    // Shared with me.
+    expect(fetches).toContain(
+      `https://specs.example.com/specs/notebook-demo/${DEMO_ID}`
+    );
+    expect(idsIn(section(widget, 'Shared with me'), 'data-spec-id')).toEqual([
+      SHARED
+    ]);
+
+    const toggle = switchIn(widget)!;
+    expect(toggle.getAttribute('aria-checked')).toBe('false');
+    toggle.click();
+
+    expect(changes).toEqual([true]);
+    widget.dispose();
+  });
+
+  it('shows no error for examples the user has hidden', async () => {
+    stubFetch(
+      () => ({ ok: false, status: 404, json: async () => ({}) }) as Response
+    );
+    const widget = await render(signedIn(DEMO_ID), undefined, {
+      showExamples: false,
+      onShowExamplesChange: () => undefined
+    });
+
+    const examples = section(widget, 'Examples')!;
+    expect(examples.querySelector('.oceanum-text-error')).toBeNull();
+    expect(switchIn(widget)).not.toBeNull();
+    widget.dispose();
+  });
+
+  it('offers no switch where the choice could not be kept', async () => {
+    stubFetch();
+    const widget = await render(signedIn(DEMO_ID));
+
+    expect(switchIn(widget)).toBeNull();
+    expect(
+      section(widget, 'Examples')!.querySelectorAll('[data-example-id]')
+    ).toHaveLength(3);
+    widget.dispose();
+  });
+
+  it('shows no examples while the setting is still loading', async () => {
+    // Otherwise examples a user has hidden would show for a moment on every reload.
+    stubFetch();
+    const widget = await render(signedIn(DEMO_ID), undefined, {
+      showExamples: null,
+      onShowExamplesChange: () => undefined
+    });
+
+    expect(section(widget, 'Examples')).toBeNull();
+    // They are still kept out of Shared with me in the meantime.
+    expect(idsIn(section(widget, 'Shared with me'), 'data-spec-id')).toEqual([
+      SHARED
+    ]);
+    widget.dispose();
+  });
+
+  it('shows nothing for hidden examples that no switch could bring back', async () => {
+    stubFetch();
+    const widget = await render(signedIn(DEMO_ID), undefined, {
+      showExamples: false
+    });
+
+    expect(section(widget, 'Examples')).toBeNull();
+    widget.dispose();
+  });
+});
+
 describe('the Notebooks tab while signed out', () => {
   it('links "Sign in" to starting a sign-in', async () => {
     const auth = signedOut();

package/src/__tests__/oceanumOnly.spec.ts

@@ -7,13 +7,17 @@ import {
   FILE_BROWSER_ID,
   hideFileBrowser,
   LOCAL_FILE_COMMANDS,
+  moveToTop,
+  NON_NOTEBOOK_NEW_COMMANDS,
+  OCEANUM_PANEL_ID,
   pruneBeforeEachOpen,
   pruneFileMenu,
   routeSaves
 } from '../share/oceanumOnly';
 
 describe('hideFileBrowser', () => {
-  it('closes the file browser without disposing it, and leaves the rest', () => {
+  /** A left area holding the file browser and the running-sessions panel. */
+  function leftArea(): { left: Panel; browser: Widget; running: Widget } {
     const left = new Panel();
     const browser = new Widget();
     browser.id = FILE_BROWSER_ID;
@@ -21,8 +25,24 @@ describe('hideFileBrowser', () => {
     running.id = 'jp-running-sessions';
     left.addWidget(browser);
     left.addWidget(running);
+    return { left, browser, running };
+  }
+
+  function shell(left: Panel) {
+    const activated: string[] = [];
+    return {
+      activated,
+      widgets: () => left.widgets,
+      activateById: (id: string): void => {
+        activated.push(id);
+      }
+    };
+  }
+
+  it('closes the file browser without disposing it, and leaves the rest', () => {
+    const { left, browser, running } = leftArea();
 
-    expect(hideFileBrowser({ widgets: () => left.widgets })).toBe(true);
+    expect(hideFileBrowser(shell(left))).toBe(true);
 
     expect(left.widgets).toEqual([running]);
     // Other extensions still hold it through IDefaultFileBrowser.
@@ -31,7 +51,30 @@ describe('hideFileBrowser', () => {
 
   it('reports when there is none to hide', () => {
     const left = new Panel();
-    expect(hideFileBrowser({ widgets: () => left.widgets })).toBe(false);
+    expect(hideFileBrowser(shell(left))).toBe(false);
+  });
+
+  it('opens the replacement when the file browser was the open panel', () => {
+    const { left } = leftArea();
+    Widget.attach(left, document.body);
+    const fake = shell(left);
+
+    hideFileBrowser(fake, OCEANUM_PANEL_ID);
+
+    expect(fake.activated).toEqual([OCEANUM_PANEL_ID]);
+    Widget.detach(left);
+  });
+
+  it('leaves a collapsed sidebar collapsed', () => {
+    const { left, browser } = leftArea();
+    Widget.attach(left, document.body);
+    browser.hide();
+    const fake = shell(left);
+
+    hideFileBrowser(fake, OCEANUM_PANEL_ID);
+
+    expect(fake.activated).toEqual([]);
+    Widget.detach(left);
   });
 });
 
@@ -191,3 +234,84 @@ describe('routeSaves', () => {
     expect(pushed).toEqual([first.panel, second.panel, first.panel]);
   });
 });
+
+describe('the File > New menu', () => {
+  it('loses the entries for files that are not notebooks', () => {
+    const { menu } = fileMenu([
+      'console:create',
+      'notebook:create-new',
+      ...NON_NOTEBOOK_NEW_COMMANDS
+    ]);
+
+    expect(pruneFileMenu(menu, NON_NOTEBOOK_NEW_COMMANDS)).toBe(2);
+
+    expect(menuCommands(menu)).toEqual([
+      'console:create',
+      'notebook:create-new'
+    ]);
+  });
+});
+
+describe('moveToTop', () => {
+  /** A left area in a saved order, and a shell that re-adds by rank as JupyterLab does. */
+  function sidebar(ids: string[]) {
+    const left = new Panel();
+    for (const id of ids) {
+      const widget = new Widget();
+      widget.id = id;
+      left.addWidget(widget);
+    }
+    Widget.attach(left, document.body);
+    const activated: string[] = [];
+    const added: [string, number][] = [];
+    const shell = {
+      widgets: () => left.widgets,
+      add: (widget: Widget, _: 'left', options: { rank: number }): void => {
+        added.push([widget.id, options.rank]);
+        widget.hide();
+        left.insertWidget(0, widget);
+      },
+      activateById: (id: string): void => {
+        activated.push(id);
+      }
+    };
+    const order = (): string[] => left.widgets.map(widget => widget.id);
+    const get = (id: string): Widget => left.widgets.find(w => w.id === id)!;
+    return { left, shell, activated, added, order, get };
+  }
+
+  it('puts a panel a returning user had last back in front, and reopens it', () => {
+    const bar = sidebar(['jp-running-sessions', OCEANUM_PANEL_ID]);
+    bar.get('jp-running-sessions').hide();
+
+    expect(moveToTop(bar.shell, OCEANUM_PANEL_ID)).toBe(true);
+
+    expect(bar.added).toEqual([[OCEANUM_PANEL_ID, 0]]);
+    expect(bar.order()).toEqual([OCEANUM_PANEL_ID, 'jp-running-sessions']);
+    expect(bar.activated).toEqual([OCEANUM_PANEL_ID]);
+    Widget.detach(bar.left);
+  });
+
+  it('does not open a panel that was closed', () => {
+    const bar = sidebar(['jp-running-sessions', OCEANUM_PANEL_ID]);
+    bar.get(OCEANUM_PANEL_ID).hide();
+
+    moveToTop(bar.shell, OCEANUM_PANEL_ID);
+
+    expect(bar.order()[0]).toBe(OCEANUM_PANEL_ID);
+    expect(bar.activated).toEqual([]);
+    Widget.detach(bar.left);
+  });
+
+  it('leaves the sidebar alone when the panel is already first or absent', () => {
+    const first = sidebar([OCEANUM_PANEL_ID, 'jp-running-sessions']);
+    expect(moveToTop(first.shell, OCEANUM_PANEL_ID)).toBe(false);
+    expect(first.added).toEqual([]);
+    Widget.detach(first.left);
+
+    const absent = sidebar(['jp-running-sessions']);
+    expect(moveToTop(absent.shell, OCEANUM_PANEL_ID)).toBe(false);
+    expect(absent.added).toEqual([]);
+    Widget.detach(absent.left);
+  });
+});

package/src/__tests__/settingsSchema.spec.ts

@@ -44,10 +44,20 @@ describe('the datamesh-connect settings schema', () => {
       'datameshToken',
       'injectToken',
       'autoRunCode',
-      'iterate'
+      'iterate',
+      'showExamples'
     ]);
   });
 
+  it('shows the examples unless the user has hidden them', async () => {
+    // Settings stored before the switch existed must still load, showing examples.
+    const before = await registryWith({ datameshToken: 'a-token' }).load(ID);
+    expect(before.get('showExamples').composite).toBe(true);
+
+    const hidden = await registryWith({ showExamples: false }).load(ID);
+    expect(hidden.get('showExamples').composite).toBe(false);
+  });
+
   it('still loads settings stored when they were', async () => {
     const registry = registryWith({
       datameshToken: 'a-token',