@kabmo-labs/kabmo 0.3.1 → 0.5.0

package/src/shared/lib/workspace/left-dock.test.ts

@@ -0,0 +1,203 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The left dock's placement rules.
+ *
+ * Three properties, and each fails SILENTLY when broken:
+ *
+ * - **The sessions view is always on the left and cannot be placed anywhere
+ *   else.** It is the dock's own view, so a stored row naming it is dropped
+ *   rather than accepted — otherwise a blob could leave the left column showing
+ *   a plugin with no way back to the session list.
+ * - **A panel is on ONE side at a time.** The same id keys the enablement set,
+ *   the width map and the stored order, so a panel present in both lists would
+ *   be two buttons for one panel and one of them would draw nothing.
+ * - **A row this build does not recognise is dropped.** The list is not only a
+ *   preference here: it decides which buttons the dock draws, so a stale id
+ *   would be a button that resolves to nothing.
+ */
+
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { primeKabmoSettings, readKabmoSetting } from '@/shared/lib/settings/client';
+import {
+  LEFT_DOCK_SETTING_KEY,
+  SESSIONS_VIEW_ID,
+  isLeftDockPanelId,
+  leftPanelIds,
+  panelSideOf,
+  readLeftDock,
+  ridesSides,
+  setPanelSide,
+  writeLeftDock,
+} from '@/shared/lib/workspace/left-dock';
+import {
+  LEFT_DOCK_WIDTHS_SETTING_KEY,
+  MIN_LEFT_DOCK_PLUGIN_WIDTH,
+  resolveLeftDockWidth,
+  saveLeftDockWidth,
+} from '@/shared/lib/workspace/left-dock-width';
+import { MAX_LEFT_PANEL_WIDTH, MIN_LEFT_PANEL_WIDTH } from '@/shared/lib/workspace/sidebar-width';
+
+beforeEach(() => primeKabmoSettings({}));
+
+describe('readLeftDock', () => {
+  test('nothing stored means OFF with no placed panels', () => {
+    expect(readLeftDock()).toEqual({ enabled: false, panels: [] });
+  });
+
+  test('a malformed row is filtered rather than keyed', () => {
+    primeKabmoSettings({
+      [LEFT_DOCK_SETTING_KEY]: { enabled: true, panels: ['plugin:a:rightPanel', 3, '', null, 'plugin:a:rightPanel', 'git', 'plugin:b:rightPanel'] },
+    });
+    // Built-in ids and duplicates are dropped: a bare `git` names a view whose
+    // floor and width slot were declared for the RIGHT column.
+    expect(readLeftDock()).toEqual({
+      enabled: true,
+      panels: ['plugin:a:rightPanel', 'plugin:b:rightPanel'],
+    });
+  });
+
+  test('the sessions view is never a placed panel', () => {
+    primeKabmoSettings({ [LEFT_DOCK_SETTING_KEY]: { enabled: true, panels: [SESSIONS_VIEW_ID] } });
+    expect(readLeftDock().panels).toEqual([]);
+  });
+
+  test('a non-object row reads as OFF', () => {
+    primeKabmoSettings({ [LEFT_DOCK_SETTING_KEY]: 'yes' });
+    expect(readLeftDock()).toEqual({ enabled: false, panels: [] });
+  });
+});
+
+describe('writeLeftDock / setPanelSide', () => {
+  test('the switch and the placement are independent halves', () => {
+    writeLeftDock({ enabled: true });
+    expect(readLeftDock()).toEqual({ enabled: true, panels: [] });
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(readLeftDock()).toEqual({ enabled: true, panels: ['plugin:a:rightPanel'] });
+  });
+
+  test('placing twice is idempotent, and moving back removes it', () => {
+    setPanelSide('plugin:a:rightPanel', 'left');
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(readLeftDock().panels).toEqual(['plugin:a:rightPanel']);
+    setPanelSide('plugin:a:rightPanel', 'right');
+    expect(readLeftDock().panels).toEqual([]);
+  });
+
+  test('a built-in id and the sessions view are refused', () => {
+    setPanelSide('git', 'left');
+    setPanelSide(SESSIONS_VIEW_ID, 'left');
+    expect(readLeftDock().panels).toEqual([]);
+  });
+});
+
+describe('placing a panel turns the rail on', () => {
+  test('a placement with the rail off enables it in the same state', () => {
+    // The rail exists to reach the panels on it: a successful placement with
+    // the rail still off is a move with no button and no view, which reads as
+    // nothing having happened.
+    expect(readLeftDock().enabled).toBe(false);
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(readLeftDock()).toEqual({ enabled: true, panels: ['plugin:a:rightPanel'] });
+  });
+
+  test('moving a panel back to the right leaves the rail as the user set it', () => {
+    // The switch is the user's, so only a PLACEMENT turns it on; a removal must
+    // not turn it off behind their back.
+    writeLeftDock({ enabled: true });
+    setPanelSide('plugin:a:rightPanel', 'left');
+    setPanelSide('plugin:a:rightPanel', 'right');
+    expect(readLeftDock()).toEqual({ enabled: true, panels: [] });
+  });
+
+  test('a placement made BY HAND on a disabled dock stays off until the UI places it', () => {
+    // `writeLeftDock` is the raw store; the coupling lives at the placement
+    // action, so a blob written directly is not silently rewritten.
+    writeLeftDock({ enabled: false, panels: ['plugin:a:rightPanel'] });
+    expect(readLeftDock()).toEqual({ enabled: false, panels: ['plugin:a:rightPanel'] });
+  });
+});
+
+describe('panelSideOf / leftPanelIds', () => {
+  test('the sessions view is left; a placed plugin is left; everything else right', () => {
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(panelSideOf(SESSIONS_VIEW_ID)).toBe('left');
+    expect(panelSideOf('plugin:a:rightPanel')).toBe('left');
+    expect(panelSideOf('plugin:b:rightPanel')).toBe('right');
+    expect(panelSideOf('git')).toBe('right');
+  });
+
+  test('the bar order is the sessions view then the placed panels', () => {
+    setPanelSide('plugin:b:rightPanel', 'left');
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(leftPanelIds()).toEqual([SESSIONS_VIEW_ID, 'plugin:b:rightPanel', 'plugin:a:rightPanel']);
+  });
+});
+
+describe('slot rules', () => {
+  test('a view rides the rails; a takeover rides the editor column', () => {
+    // The rule is the SLOT's shape, not the plugin's identity: a `rightPanel` is
+    // an activity-bar view, a `panel` takes the editor column over whole.
+    expect(ridesSides('rightPanel')).toEqual(['left', 'right']);
+    expect(ridesSides('panel')).toEqual(['editor']);
+  });
+
+  test('a takeover cannot be placed on a rail', () => {
+    // A button on a rail that opens a column somewhere else is a control that
+    // lies about where it goes.
+    setPanelSide('plugin:x:panel', 'left');
+    expect(readLeftDock().panels).toEqual([]);
+  });
+
+  test('a view cannot be placed in the editor column', () => {
+    setPanelSide('plugin:x:rightPanel', 'editor');
+    // Refused, and the refusal leaves the panel where it was: the right column.
+    expect(panelSideOf('plugin:x:rightPanel')).toBe('right');
+  });
+
+  test('a takeover is in the editor column by default', () => {
+    expect(panelSideOf('plugin:x:panel')).toBe('editor');
+  });
+
+  test('two panels of one plugin are placed independently', () => {
+    // The whole reason placement is per PANEL: moving the right panel onto the
+    // left dock must not drag the plugin's editor takeover with it.
+    setPanelSide('plugin:session-info:rightPanel', 'left');
+    expect(panelSideOf('plugin:session-info:rightPanel')).toBe('left');
+    expect(panelSideOf('plugin:session-info:panel')).toBe('editor');
+  });
+});
+
+describe('isLeftDockPanelId', () => {
+  test('accepts the sessions view and a plugin key only', () => {
+    expect(isLeftDockPanelId(SESSIONS_VIEW_ID)).toBe(true);
+    expect(isLeftDockPanelId('plugin:a:rightPanel')).toBe(true);
+    expect(isLeftDockPanelId('files')).toBe(false);
+    expect(isLeftDockPanelId('plugin:')).toBe(false);
+  });
+});
+
+describe('left dock widths', () => {
+  test('a remembered width wins and is clamped to the view floor', () => {
+    saveLeftDockWidth('plugin:a:rightPanel', 400);
+    expect(resolveLeftDockWidth('plugin:a:rightPanel')).toBe(400);
+    saveLeftDockWidth('plugin:a:rightPanel', 10);
+    expect(resolveLeftDockWidth('plugin:a:rightPanel')).toBe(MIN_LEFT_DOCK_PLUGIN_WIDTH);
+    saveLeftDockWidth('plugin:a:rightPanel', 10_000);
+    expect(resolveLeftDockWidth('plugin:a:rightPanel')).toBe(MAX_LEFT_PANEL_WIDTH);
+  });
+
+  test('the session list keeps its own floor, and the setting it already had', () => {
+    primeKabmoSettings({ omp_sidebar_width: 333 });
+    expect(resolveLeftDockWidth(SESSIONS_VIEW_ID)).toBe(333);
+    saveLeftDockWidth(SESSIONS_VIEW_ID, 10);
+    expect(resolveLeftDockWidth(SESSIONS_VIEW_ID)).toBe(MIN_LEFT_PANEL_WIDTH);
+    // The dock's map is its own key: a plugin's width never rewrites the list's.
+    saveLeftDockWidth('plugin:a:rightPanel', 500);
+    expect(resolveLeftDockWidth(SESSIONS_VIEW_ID)).toBe(MIN_LEFT_PANEL_WIDTH);
+    expect((readKabmoSetting<Record<string, number>>(LEFT_DOCK_WIDTHS_SETTING_KEY) ?? {})['plugin:a:rightPanel']).toBe(500);
+  });
+});

package/src/shared/lib/workspace/left-dock.ts

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The LEFT dock: which view fills it, and which panels may live there.
+ *
+ * The left column used to be the session sidebar and nothing else. It is now a
+ * DOCK with a view on it, exactly as the right column is — the sessions list is
+ * the built-in view, and a plugin panel can be placed beside it by the user.
+ *
+ * Three decisions are encoded here rather than at a call site:
+ *
+ * - **The dock is OPTIONAL and OFF by default.** Its activity bar is a setting,
+ *   and while it is off the dock shows only its active view with no rail and no
+ *   second width to reserve. That is what makes the feature free for the many
+ *   users who never place a panel on the left: nothing renders, nothing is
+ *   measured, and no extra panel competes with the chat for the group's budget.
+ * - **Placement is the USER's, never the plugin's.** A plugin keeps registering
+ *   `app.rightPanel(...)`; where it is drawn is a per-install preference. That
+ *   is what keeps ONE id (`plugin:<id>`) meaning one panel — the id the server
+ *   gates the bundle with, the enablement set stores, the width map keys and the
+ *   stored order ranks. A second slot name would have split all four.
+ * - **The sessions view cannot be moved.** It is the reason the left column
+ *   exists, and moving it would leave a chat with no way to reach another one.
+ *
+ * Stored GLOBAL (`app_settings.omp_left_panels`), like the right panel's order:
+ * the dock lists the same panels in every session, so a per-session placement
+ * would move the user's own arrangement when they picked another chat.
+ */
+
+import { readKabmoSetting, writeSetting } from '@/shared/lib/settings/client';
+import { pluginKeyOf, pluginSlotOf, type PluginPanelSlot } from '@/shared/lib/workspace/panel-ids';
+
+/** `app_settings` key holding the dock's own state. */
+export const LEFT_DOCK_SETTING_KEY = 'omp_left_panels';
+
+/** The built-in view that owns the left column unless the user places another. */
+export const SESSIONS_VIEW_ID = 'sessions';
+
+/**
+ * Where a panel is drawn.
+ *
+ * `editor` is the third destination and it is the one that makes a two-panel
+ * plugin coherent: `session-info` registers a `rightPanel` AND a `panel`, and
+ * with per-instance placement they are independent — either may sit on the left,
+ * the other may stay right or take the editor column. Placement is per PANEL, so
+ * moving one never drags its sibling along.
+ *
+ * The left column holds ONE panel, and a plugin's second panel goes to the
+ * editor column — that is what its `panel` slot is FOR. A second left pane was
+ * built and removed: it made the left column two columns' worth of width for a
+ * plugin that already had a home for its second panel, and a pane with no
+ * switcher is a surface whose occupant nothing on screen names.
+ */
+export type PanelSide = 'left' | 'right' | 'editor';
+
+/** The destinations a PLUGIN panel may be placed on. */
+export const PLUGIN_SIDES: readonly PanelSide[] = ['left', 'right', 'editor'];
+
+/**
+ * Where a panel may go, given its SLOT.
+ *
+ * Not every slot can use every destination, and the rule is the slot's shape:
+ *
+ * - `rightPanel` is a VIEW — an activity-bar button and a body in a column — so
+ *   it may sit on the left dock or on the right, never in the editor column
+ *   (which a takeover owns whole).
+ * - `panel` is a TAKEOVER — it draws the editor column with no tab strip and no
+ *   chrome — so it may sit there and nowhere else. A takeover on a rail would be
+ *   a button that opens a column that is not the one it is on.
+ */
+export function ridesSides(slot: PluginPanelSlot | null): readonly PanelSide[] {
+  if (slot === 'panel') return ['editor'];
+  if (slot === 'rightPanel') return ['left', 'right'];
+  return [];
+}
+
+/** The dock's stored state, validated. */
+export interface LeftDockState {
+  /** Whether the dock's activity bar is drawn at all. OFF unless set. */
+  enabled: boolean;
+  /** Panel ids the user placed on the left dock, in bar order. */
+  panels: string[];
+}
+
+const EMPTY: LeftDockState = { enabled: false, panels: [] };
+
+/**
+ * The ids that may live on the left.
+ *
+ * The sessions view is the dock's own; anything else must be a plugin panel —
+ * a bare built-in id (`git`, `files`) names a view whose width slot, floor and
+ * workspace gate were all declared for the RIGHT column, and moving it is a
+ * second feature rather than a placement.
+ */
+export function isLeftDockPanelId(value: unknown): value is string {
+  if (value === SESSIONS_VIEW_ID) return true;
+  return pluginKeyOf(value) !== null;
+}
+
+/**
+ * The stored state, validated.
+ *
+ * A row this build does not recognise is DROPPED rather than kept: unlike the
+ * right panel's order, this list is also the enablement of the dock's buttons,
+ * so a stale id would draw a button that resolves to nothing.
+ */
+export function readLeftDock(): LeftDockState {
+  const stored = readKabmoSetting<unknown>(LEFT_DOCK_SETTING_KEY);
+  if (typeof stored !== 'object' || stored === null) return EMPTY;
+  const raw = stored as { enabled?: unknown; panels?: unknown };
+  const panels: string[] = [];
+  const seen = new Set<string>();
+  if (Array.isArray(raw.panels)) {
+    for (const value of raw.panels) {
+      if (!isLeftDockPanelId(value) || value === SESSIONS_VIEW_ID || seen.has(value)) continue;
+      seen.add(value);
+      panels.push(value);
+    }
+  }
+  return { enabled: raw.enabled === true, panels };
+}
+
+/** Persist one change to the dock, keeping the other half. */
+export function writeLeftDock(patch: Partial<LeftDockState>): LeftDockState {
+  const current = readLeftDock();
+  const next: LeftDockState = {
+    enabled: patch.enabled ?? current.enabled,
+    panels: patch.panels
+      ? [
+          ...new Set(
+            patch.panels.filter(
+              (id) => isLeftDockPanelId(id) && ridesSides(pluginSlotOf(id)).includes('left'),
+            ),
+          ),
+        ]
+      : current.panels,
+  };
+  writeSetting(LEFT_DOCK_SETTING_KEY, next);
+  return next;
+}
+
+/**
+ * Place a plugin panel on the left, or take it back to the right.
+ *
+ * **Placing a panel turns the rail ON.** The rail exists to reach the panels on
+ * it, so a successful placement with the rail still off is a move with no
+ * button, no view and nothing on screen to undo it — the settings row would be
+ * the only control, which is the state a user reads as broken. The switch is
+ * written in the SAME state as the placement, so no reader can observe one
+ * without the other.
+ *
+ * Moving a panel back does NOT turn the rail off: that switch is the user's, and
+ * the dock may still be worth showing without this panel on it.
+ */
+export function setPanelSide(panelId: string, side: PanelSide): LeftDockState {
+  if (!isLeftDockPanelId(panelId) || panelId === SESSIONS_VIEW_ID) return readLeftDock();
+  // A destination the slot cannot use is refused, not stored: a `panel`
+  // takeover on a rail, or a view inside the editor column, is a placement
+  // that could never be drawn.
+  if (!ridesSides(pluginSlotOf(panelId)).includes(side)) return readLeftDock();
+  const current = readLeftDock();
+  const placed = current.panels.includes(panelId);
+  if (side === 'left') {
+    if (placed && current.enabled) return current;
+    const panels = placed ? current.panels : [...current.panels, panelId];
+    return writeLeftDock({ enabled: true, panels });
+  }
+  if (!placed) return current;
+  return writeLeftDock({ panels: current.panels.filter((id) => id !== panelId) });
+}
+
+/**
+ * Which side a panel is drawn on.
+ *
+ * The sessions view is left by construction; a plugin panel is left only while
+ * the user has placed it there; a built-in view is always right.
+ */
+export function panelSideOf(panelId: string, dock: LeftDockState = readLeftDock()): PanelSide {
+  if (panelId === SESSIONS_VIEW_ID) return 'left';
+  const key = pluginKeyOf(panelId) ?? panelId;
+  if (dock.panels.includes(key)) return 'left';
+  // A takeover's home is the editor column: that is the only place its slot can
+  // be drawn, so it is where it is when the user has not moved it.
+  if (pluginSlotOf(panelId) === 'panel') return 'editor';
+  return 'right';
+}
+
+/**
+ * The left column's views in bar order: the dock's own view, then every placed
+ * plugin in the order they were placed.
+ */
+export function leftPanelIds(dock: LeftDockState = readLeftDock()): string[] {
+  return [SESSIONS_VIEW_ID, ...dock.panels];
+}

package/src/shared/lib/workspace/mobile-dock.test.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which panels each phone drawer offers.
+ *
+ * Both rules are silent failures when wrong, which is why they are pinned:
+ * a panel on BOTH strips is one panel with two chips (and one of them is a
+ * second place to be), while a panel on NEITHER is a placement that looks like
+ * an uninstall.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { phoneLeftStripVisible, phoneRightPanels } from '@/shared/lib/workspace/mobile-dock';
+import type { PanelSide } from '@/shared/lib/workspace/left-dock';
+
+const SESSIONS = 'sessions';
+
+function panels(...rows: [string, PanelSide][]) {
+  return rows.map(([id, side]) => ({ id, side }));
+}
+
+describe('phoneRightPanels', () => {
+  test('drops the session list, which the phone draws as its own screen', () => {
+    const all = panels([SESSIONS, 'left'], ['files', 'right']);
+    expect(phoneRightPanels(all, SESSIONS, false).map((p) => p.id)).toEqual(['files']);
+  });
+
+  test('with the rail OFF a left-placed panel stays here — the left drawer cannot reach it', () => {
+    const all = panels([SESSIONS, 'left'], ['files', 'right'], ['plugin:demo:rightPanel', 'left']);
+    expect(phoneRightPanels(all, SESSIONS, false).map((p) => p.id)).toEqual(['files', 'plugin:demo:rightPanel']);
+  });
+
+  test('with the rail ON the left drawer owns it, so this one must not draw it twice', () => {
+    const all = panels([SESSIONS, 'left'], ['files', 'right'], ['plugin:demo:rightPanel', 'left']);
+    expect(phoneRightPanels(all, SESSIONS, true).map((p) => p.id)).toEqual(['files']);
+  });
+
+  test('the rail being on never hides a RIGHT-column view', () => {
+    const all = panels(['git', 'right'], ['todo', 'right']);
+    expect(phoneRightPanels(all, SESSIONS, true).map((p) => p.id)).toEqual(['git', 'todo']);
+  });
+});
+
+describe('phoneLeftStripVisible', () => {
+  test('no rail, no strip', () => {
+    expect(phoneLeftStripVisible(false, 2, true)).toBe(false);
+  });
+
+  test('a strip holding only Sessions is chrome that never changes', () => {
+    expect(phoneLeftStripVisible(true, 0, true)).toBe(false);
+  });
+
+  test('a placed panel is a second destination, so the strip appears', () => {
+    expect(phoneLeftStripVisible(true, 1, true)).toBe(true);
+  });
+
+  test('a stored view that no longer resolves still gets the strip — its body is a notice', () => {
+    // Without this the drawer would be stuck on a notice with no way back to
+    // the session list: the body has no chips of its own.
+    expect(phoneLeftStripVisible(true, 0, false)).toBe(true);
+  });
+});

package/src/shared/lib/workspace/mobile-dock.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which panels each phone drawer offers.
+ *
+ * The phone has TWO drawers and one catalog, so the split is a rule rather
+ * than a per-component filter. It used to be one rule for the right drawer
+ * (`all`, minus the session list), because a panel placed on the left had
+ * nowhere else to be reached — the left drawer was a plain session list. Now
+ * the left drawer draws the dock too, so leaving `all` in the right one puts a
+ * single panel on two strips of one phone.
+ *
+ * Pure, and separate from both components, so the two drawers cannot drift and
+ * the rule can be tested without mounting either.
+ */
+
+import type { PanelSide } from '@/shared/lib/workspace/left-dock';
+
+/** The parts of a catalog entry these rules read. */
+interface SidedPanel {
+  id: string;
+  side: PanelSide;
+}
+
+/**
+ * The right drawer's chips.
+ *
+ * `all` while the left rail is OFF: a placed panel is then unreachable from the
+ * left drawer (it has no strip), and hiding it from both would make the
+ * placement look like an uninstall. With the rail on the left drawer owns them.
+ */
+export function phoneRightPanels<T extends SidedPanel>(
+  panels: readonly T[],
+  sessionsViewId: string,
+  dockEnabled: boolean,
+): T[] {
+  return panels.filter(
+    (panel) => panel.id !== sessionsViewId && !(dockEnabled && panel.side === 'left'),
+  );
+}
+
+/**
+ * Whether the left drawer draws its chip strip.
+ *
+ * A strip holding one chip is chrome that never changes, so it needs a second
+ * destination — either a placed panel, or a stored view that no longer
+ * resolves. The second half is the escape hatch: that body is a notice, and
+ * without the strip the session list would be unreachable.
+ */
+export function phoneLeftStripVisible(dockEnabled: boolean, placedCount: number, showingSessions: boolean): boolean {
+  return dockEnabled && (placedCount > 0 || !showingSessions);
+}

package/src/shared/lib/workspace/panel-ids.test.ts

@@ -13,24 +13,48 @@
  */
 
 import { test, expect, describe } from 'bun:test';
-import { isPanelId, pluginIdOf, pluginKeyOf, pluginPanelKey } from '@/shared/lib/workspace/panel-ids';
+import {
+  isPanelId,
+  migrateLegacyPanelId,
+  pluginEnablementKey,
+  pluginIdOf,
+  pluginKeyOf,
+  pluginPanelKey,
+  pluginSlotOf,
+} from '@/shared/lib/workspace/panel-ids';
 
 describe('pluginPanelKey', () => {
-  test('builds the id from the plugin id', () => {
-    expect(pluginPanelKey('hello')).toBe('plugin:hello');
+  test('names ONE panel: the plugin id AND the slot', () => {
+    expect(pluginPanelKey('hello', 'rightPanel')).toBe('plugin:hello:rightPanel');
+    expect(pluginPanelKey('hello', 'panel')).toBe('plugin:hello:panel');
+    // Two panels of one plugin are two keys, which is what lets a placement and
+    // a width follow one of them without dragging the other along.
+    expect(pluginPanelKey('hello', 'panel')).not.toBe(pluginPanelKey('hello', 'rightPanel'));
+  });
+});
+
+describe('pluginEnablementKey', () => {
+  test('names the PLUGIN, whatever it contributes', () => {
+    // Enablement is per plugin: the switch says "Disable <plugin>" and the
+    // server gates that plugin's bundle on this key, so one switch is one id.
+    expect(pluginEnablementKey('hello')).toBe('plugin:hello');
   });
 });
 
 describe('pluginKeyOf', () => {
-  test('accepts a well-formed plugin key', () => {
-    expect(pluginKeyOf('plugin:hello')).toBe('plugin:hello');
+  test('accepts both forms, normalizing the retired one to rightPanel', () => {
+    expect(pluginKeyOf('plugin:hello:rightPanel')).toBe('plugin:hello:rightPanel');
+    expect(pluginKeyOf('plugin:hello:panel')).toBe('plugin:hello:panel');
+    // The form that shipped, before the slot segment: the only reachable slot
+    // then was the right panel, so that is where such a row still points.
+    expect(pluginKeyOf('plugin:hello')).toBe('plugin:hello:rightPanel');
   });
 
-  test('rejects a bare prefix and an extra segment', () => {
+  test('rejects a bare prefix, a slash, a third segment and an unknown slot', () => {
     expect(pluginKeyOf('plugin:')).toBeNull();
-    // The id used to carry a panel segment; a blob written then must not be
-    // adopted as a plugin id that no registry can report.
     expect(pluginKeyOf('plugin:hello/greeter')).toBeNull();
+    expect(pluginKeyOf('plugin:a:b:c')).toBeNull();
+    expect(pluginKeyOf('plugin:hello:headerPanel')).toBeNull();
   });
 
   test('rejects a built-in view id and a non-string', () => {
@@ -40,9 +64,33 @@ describe('pluginKeyOf', () => {
   });
 });
 
+describe('migrateLegacyPanelId', () => {
+  test('reports the retired form and what it becomes', () => {
+    expect(migrateLegacyPanelId('plugin:hello')).toEqual({
+      from: 'plugin:hello',
+      to: 'plugin:hello:rightPanel',
+    });
+  });
+
+  test('says nothing for a value that is already current or not a panel id', () => {
+    expect(migrateLegacyPanelId('plugin:hello:panel')).toBeNull();
+    expect(migrateLegacyPanelId('files')).toBeNull();
+    expect(migrateLegacyPanelId(null)).toBeNull();
+  });
+});
+
+describe('pluginSlotOf', () => {
+  test('names the slot, so a placement can be per panel', () => {
+    expect(pluginSlotOf('plugin:hello:panel')).toBe('panel');
+    expect(pluginSlotOf('plugin:hello')).toBe('rightPanel');
+    expect(pluginSlotOf('files')).toBeNull();
+  });
+});
+
 describe('pluginIdOf', () => {
-  test('unwraps the plugin id', () => {
+  test('unwraps the plugin id, from either form', () => {
     expect(pluginIdOf('plugin:hello')).toBe('hello');
+    expect(pluginIdOf('plugin:hello:panel')).toBe('hello');
     expect(pluginIdOf('files')).toBeNull();
   });
 });
@@ -54,8 +102,9 @@ describe('isPanelId', () => {
     expect(isPanelId('plan')).toBe(true);
   });
 
-  test('accepts a plugin key', () => {
+  test('accepts a plugin panel key, in both forms', () => {
     expect(isPanelId('plugin:hello')).toBe(true);
+    expect(isPanelId('plugin:hello:panel')).toBe(true);
   });
 
   test('rejects an unknown view and a malformed plugin key', () => {