@kabmo-labs/kabmo 0.5.3 → 0.6.1

package/marketplace/plugins/stats/src/HeaderReadout.tsx

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The navbar readout: CPU and RAM for the whole omp stack, two columns wide.
+ *
+ * ## It is a readout, not a control
+ *
+ * The host wraps this component in the button that opens the panel (the
+ * registration's `opensPanel`), so nothing here is clickable, focusable or
+ * keyboard-reachable. That split is the header contract: a trigger renders what
+ * the entry READS, and the host owns the interaction.
+ *
+ * ## Two lines, because the labels and the figures answer different questions
+ *
+ * ```
+ * CPU   RAM
+ * 18%   2.5G
+ * ```
+ *
+ * The labels are 9px uppercase mono and muted; the figures are 12px mono and
+ * full ink. That is the header's own type scale (`context-usage-button`'s ring
+ * label sits at the same size), and the contrast is what lets the numbers be
+ * scanned without reading the words above them twice.
+ *
+ * ## It samples while it is on screen, and only then
+ *
+ * A figure nobody is looking at costs a process-table sweep per tick, so the
+ * readout arms the server's sampler on mount and disarms it on unmount — the
+ * same `watch`/`unwatch` pair the panel uses, which is why the two can be open
+ * at once without the loop being armed twice. A BACKGROUND tab is not looking:
+ * the watch is released while the document is hidden, so a tab left open
+ * overnight does not sample until it is brought forward again.
+ *
+ * ## The states that are not zero
+ *
+ * - **No sample yet** — the first tick carries RSS and no CPU rate, so the CPU
+ *   column reads `—` rather than `0%`.
+ * - **The server half is not loaded** — a plugin installed into a running Kabmo
+ *   answers no `watch` and no topic. The readout then reads `—` in both
+ *   columns; the panel itself explains why, and a header has no room to.
+ * - **A platform with no probe** — the snapshot says so and both columns read
+ *   `—`.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+import { useRealtime, useRpc } from '@kabmo-labs/kabmo-ui';
+
+import { formatCompactBytes, formatCompactPercent } from './format';
+import type { StatsSnapshot } from './sampler';
+
+/**
+ * Whether this tab is being looked at.
+ *
+ * `visibilityState` rather than a focus check: a window that is visible but not
+ * focused is still on screen, and its readout still has a reader.
+ */
+function useDocumentVisible(): boolean {
+  const [visible, setVisible] = useState(() => document.visibilityState !== 'hidden');
+  useEffect(() => {
+    const onChange = () => setVisible(document.visibilityState !== 'hidden');
+    document.addEventListener('visibilitychange', onChange);
+    return () => document.removeEventListener('visibilitychange', onChange);
+  }, []);
+  return visible;
+}
+
+/** One column of the readout: a label above, a figure below. */
+function ReadoutCell({ label, value, title }: { label: string; value: string; title: string }) {
+  return (
+    <span class="flex flex-col leading-none" title={title}>
+      <span class="text-[9px] uppercase font-mono text-ink/40 tracking-wide">{label}</span>
+      <span class="text-[12px] font-mono font-semibold text-ink tabular-nums">{value}</span>
+    </span>
+  );
+}
+
+export function StatsHeaderReadout() {
+  const realtime = useRealtime<StatsSnapshot>();
+  const watch = useRpc<undefined, { watching: number }>('watch');
+  const unwatch = useRpc<undefined, { watching: number }>('unwatch');
+  const visible = useDocumentVisible();
+
+  // Arm while the readout is on screen and the tab is visible. The cleanup
+  // always unwatches: a mount that failed to arm answers `plugin_not_loaded`
+  // and decrements to zero, which the server clamps — the alternative is a
+  // counter that drifts up on every failed load and never releases the loop.
+  useEffect(() => {
+    if (!visible) return;
+    void watch.call(undefined);
+    return () => {
+      void unwatch.call(undefined);
+    };
+    // `call` is stable per method+plugin; the effect keys on what it means.
+  }, [visible, watch.call, unwatch.call]);
+
+  const snapshot = realtime.value;
+  const measurable = snapshot !== null && snapshot.probe.supported;
+  const cpu = measurable ? formatCompactPercent(snapshot.total.cpuPercent) : '—';
+  const ram = measurable ? formatCompactBytes(snapshot.total.rss) : '—';
+  // A figure with no sample behind it must not look like a measurement: the
+  // tooltip is the only place the header can say so.
+  const title = measurable
+    ? `omp stack — ${ram} RAM, ${cpu} CPU. Click for the process table.`
+    : 'Stats — no measurement yet. Click for details.';
+
+  return (
+    <span class="flex items-center gap-2.5" aria-label={`CPU ${cpu}, RAM ${ram}`} title={title}>
+      <ReadoutCell label="CPU" value={cpu} title="CPU over the last sample interval, across every process" />
+      <ReadoutCell label="RAM" value={ram} title="Resident memory across every process" />
+    </span>
+  );
+}

package/marketplace/plugins/stats/src/app.tsx

@@ -33,6 +33,7 @@ import { Empty, Note, Panel } from '@kabmo-labs/kabmo-ui/components';
 import { ProcessTable } from './ProcessTable';
 import { Sparkline } from './Sparkline';
 import { MachineFacts, TotalsBar } from './TotalsBar';
+import { StatsHeaderReadout } from './HeaderReadout';
 import { formatAge, formatBytes, formatPercent } from './format';
 import type { StatsSnapshot } from './sampler';
 
@@ -180,4 +181,14 @@ export default definePluginApp((app) => {
     // Kabmo's own Context view takes.
     minWidth: 420,
   });
+  // The navbar readout: CPU and RAM in two columns, and a click that opens the
+  // panel above. `opensPanel` names the SLOT, not a column — the host resolves
+  // it to this plugin's `rightPanel` instance and shows it wherever the user
+  // placed it (left dock, right column, or the phone drawer that holds it).
+  app.headerPanel({
+    id: 'resources',
+    title: 'Stats — CPU & RAM',
+    component: StatsHeaderReadout,
+    opensPanel: 'rightPanel',
+  });
 });

package/marketplace/plugins/stats/src/format.test.ts

@@ -15,7 +15,7 @@
 
 import { describe, expect, test } from 'bun:test';
 
-import { formatAge, formatBytes, formatPercent } from './format';
+import { formatAge, formatBytes, formatCompactBytes, formatCompactPercent, formatPercent } from './format';
 import { procProbe } from './proc';
 import { readDaemonRegistry } from './daemons';
 
@@ -123,3 +123,29 @@ describe('procProbe against this machine', () => {
     }
   });
 });
+
+describe('formatCompactBytes', () => {
+  test('one character of unit, one decimal past megabytes', () => {
+    expect(formatCompactBytes(0)).toBe('0B');
+    expect(formatCompactBytes(512)).toBe('512B');
+    expect(formatCompactBytes(2048)).toBe('2K');
+    expect(formatCompactBytes(512 * 1024 ** 2)).toBe('512M');
+    expect(formatCompactBytes(2.5 * 1024 ** 3)).toBe('2.5G');
+    expect(formatCompactBytes(3 * 1024 ** 3)).toBe('3G');
+  });
+
+  test('a sub-megabyte figure never rounds to 0M', () => {
+    // The failure this pins: a header reading `0M` looks like "this stack uses
+    // nothing", which is the opposite of what a 410 KB figure means.
+    expect(formatCompactBytes(0.4 * 1024 ** 2)).toBe('410K');
+  });
+});
+
+describe('formatCompactPercent', () => {
+  test('whole percent, and a dash for no measurement', () => {
+    expect(formatCompactPercent(null)).toBe('—');
+    expect(formatCompactPercent(0)).toBe('0%');
+    expect(formatCompactPercent(18.4)).toBe('18%');
+    expect(formatCompactPercent(140.2)).toBe('140%');
+  });
+});

package/marketplace/plugins/stats/src/format.ts

@@ -51,3 +51,44 @@ export function formatAge(sampledAt: number, now: number): string {
   const minutes = Math.floor(seconds / 60);
   return `${minutes}m ago`;
 }
+
+/**
+ * A byte count as the NAVBAR reads it: `2.5G`, `512M`, `0B`.
+ *
+ * The panel's own `formatBytes` spells the unit out (`2.5 GB`) because a table
+ * has a column header and room to be unambiguous. A header readout sits beside
+ * the context ring and the window controls, so it is two characters of unit and
+ * one decimal — the same number, in the space it has.
+ *
+ * Megabytes and below stay whole: `512M` is already precise enough that a
+ * decimal would be a digit the reader cannot act on, and a sub-megabyte figure
+ * that printed `0G` would read as nothing at all.
+ */
+export function formatCompactBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0B';
+  const units = ['B', 'K', 'M', 'G', 'T'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  if (unit <= 2) return `${Math.round(value)}${units[unit]}`;
+  // One decimal, and `.0` trimmed: `2G` rather than `2.0G` — the trailing zero
+  // is a character the header pays for and nobody reads.
+  const rounded = value.toFixed(1).replace(/\.0$/, '');
+  return `${rounded}${units[unit]}`;
+}
+
+/**
+ * A CPU percent as the navbar reads it: `18%`, `140%`, `—`.
+ *
+ * `null` stays a dash for the reason `formatPercent` gives — the first sample
+ * has no rate, and `0%` would claim the stack is idle. A header is worse than a
+ * table here: nobody scrolls a navbar looking for the footnote that says the
+ * figure is not a measurement.
+ */
+export function formatCompactPercent(value: number | null): string {
+  if (value === null || !Number.isFinite(value)) return '—';
+  return `${Math.round(value)}%`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabmo-labs/kabmo",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "Web console and diagnostic workbench for AI coding agents — Elysia + Preact on Bun.",
   "license": "UNLICENSED",
   "author": "Wijanarko Putra Rajeb <wijanarko.rajeb@gmail.com>",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@fontsource/fira-code": "^5.3.0",
-    "@kabmo-labs/kabmo-sdk": "0.0.1",
+    "@kabmo-labs/kabmo-sdk": "0.1.0",
     "@kabmo-labs/kabmo-ui": "0.0.1",
     "@shikijs/langs": "^4.4.3",
     "@shikijs/themes": "^4.4.3",

package/src/client/bootstrap.d.ts

@@ -30,6 +30,17 @@ export interface KabmoBootstrap {
    * behind the published APK.
    */
   shellVersion?: string | null;
+  /**
+   * The iOS shell's version, when this page was requested by the IPA
+   * (`KabmoIOS/<version>` in the User-Agent). Null in every browser.
+   *
+   * A separate field from `shellVersion` rather than one "shell version",
+   * because the two shells are two different artifacts on two different release
+   * tracks: an APK update is an `.apk` download, an IPA update is an App Store
+   * or TestFlight page. Folding them would let one shell's version be compared
+   * against the other's published artifact.
+   */
+  iosShellVersion?: string | null;
   /**
    * Whether this request came from an Android device at all — the app, or a
    * browser running on it.

package/src/client/components/common/header-controls/MoreMenu.tsx

@@ -31,11 +31,22 @@ import { Ellipsis, Lock, LockOpen, RefreshCw } from 'lucide-preact';
 import { useEffect, useRef, useState } from 'preact/hooks';
 import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
 import { logout, useAuthEnabled, useAuthState } from '@/client/hooks/ui/auth';
+import { PluginIdProvider } from '@kabmo-labs/kabmo-ui';
+import { requestOpenPanel } from '@/shared/lib/workspace/panel-open';
+import type { HeaderEntry } from '@/client/components/common/header-panel-buttons/entries';
 
 const ROW_CLASS =
   'w-full text-left px-3 py-2 flex items-center gap-2 transition-colors text-ink/75 hover:bg-ink/5 hover:text-ink cursor-pointer';
 
-export function HeaderMoreMenu() {
+/**
+ * `entries` are the plugin header entries the row could not hold.
+ *
+ * They are ACTION entries only — a dropdown needs its trigger's anchor and a
+ * static readout has no action, so neither can become a menu row. Here the
+ * action is the same one the row would have performed: the panel key travels on
+ * the same event, and the layout opens it wherever the user placed it.
+ */
+export function HeaderMoreMenu({ entries = [] }: { entries?: HeaderEntry[] }) {
   const authEnabled = useAuthEnabled();
   const authState = useAuthState();
   const [open, setOpen] = useState(false);
@@ -115,6 +126,32 @@ export function HeaderMoreMenu() {
             <span>Reload page</span>
           </button>
 
+          {entries.map((entry) => (
+            <button
+              key={entry.pluginId}
+              type="button"
+              role="menuitem"
+              onClick={() => {
+                setOpen(false);
+                if (entry.opensPanelKey) requestOpenPanel(entry.opensPanelKey);
+              }}
+              className={ROW_CLASS}
+              // The row IS the plugin's readout — naming it twice (a label plus
+              // the same figures) was what the first cut rendered. The title is
+              // the accessible name and the tooltip, exactly as it is on the
+              // button this row stands in for.
+              title={entry.title}
+              aria-label={entry.title}
+            >
+              {/* Scoped to its plugin: `useRpc` and `useRealtime` read the id
+                  from this provider, so without it a folded entry would render
+                  a dash over a live figure. */}
+              <PluginIdProvider pluginId={entry.pluginId}>
+                <entry.Trigger sessionId={null} workspacePath={null} />
+              </PluginIdProvider>
+            </button>
+          ))}
+
           {canSignOut && (
             <button
               type="button"

package/src/client/components/common/header-controls/index.tsx

@@ -4,6 +4,7 @@ import { ReloadPageButton } from '@/client/components/common/ReloadPageButton';
 import { SignOutButton } from '@/client/components/common/SignOutButton';
 import { ContextUsageButton } from '@/client/components/common/context-usage-button';
 import { HeaderPanelButtons } from '@/client/components/common/header-panel-buttons';
+import { useHeaderEntries } from '@/client/components/common/header-panel-buttons/entries';
 import { HeaderMoreMenu } from '@/client/components/common/header-controls/MoreMenu';
 import { useAuthEnabled, useAuthState } from '@/client/hooks/ui/auth';
 import { useViewportAtLeast } from '@/client/hooks/ui/media-query';
@@ -104,11 +105,15 @@ export function HeaderControls({
   const wideEnoughForAll = layout === 'desktop' || wideRow;
   // A phone folds the two rare controls only while the row cannot hold them.
   const folded = layout === 'mobile' && !wideEnoughForAll;
+  // ONE resolution of what the plugin entries do, because two surfaces draw it:
+  // the row (inline) and the `⋯` menu (folded). Asking twice would be two media
+  // queries deciding one row, and the two halves could disagree mid-resize.
+  const headerEntries = useHeaderEntries(layout);
 
   return (
     <div className="flex items-center space-x-1">
       {layout === 'desktop' && <PWAInstallButton />}
-      <HeaderPanelButtons layout={layout} />
+      <HeaderPanelButtons layout={layout} entries={headerEntries.inline} />
       {/* The cluster's ORDER is fixed; what changes on a narrow phone is that
           reload and sign-out move behind `⋯`, which sits in the slot they
           left. Nothing is hidden at a width that can hold it: measured, the
@@ -150,7 +155,9 @@ export function HeaderControls({
           {showRightPanel ? <PanelRightClose size={size} /> : <PanelRight size={size} />}
         </button>
       )}
-      {folded && <HeaderMoreMenu />}
+      {(folded || headerEntries.folded.length > 0) && (
+        <HeaderMoreMenu entries={headerEntries.folded} />
+      )}
       {layout === 'desktop' && onSwitchToMobile && (
         <button
           type="button"

package/src/client/components/common/header-controls/plugin-entry.test.tsx

@@ -0,0 +1,229 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A plugin's navbar entry, and where it goes when the row runs out of room.
+ *
+ * Two facts, and both are a control that becomes unreachable when broken:
+ *
+ * - an `opensPanel` entry is an ACTION: the row's button asks the layout for
+ *   the plugin's panel by its instance key, so the layout can open it wherever
+ *   the user placed it;
+ * - on a phone too narrow to hold it, that action MOVES into the `⋯` menu
+ *   rather than shrinking or disappearing. Measured with a `CPU 18% / RAM 2.5G`
+ *   readout (73px) at 390px: the session title kept 48px of its 74px and was
+ *   clipped. At 430px it kept all of it, which is why that is the threshold.
+ *
+ * Rendered through the real `HeaderControls` against a real realtime server: the
+ * split between the row and the menu lives in that component's own call, so a
+ * test of the resolver alone would pass while the call site rendered something
+ * else.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { definePluginApp } from '@kabmo-labs/kabmo-sdk/app';
+import { HeaderControls } from '@/client/components/common/header-controls';
+import { SessionStateProvider } from '@/client/components/common/session-state-provider/index';
+import { registerPluginBundle, resetPluginSlots } from '@/client/lib/plugins/slots';
+import { primeAuthState } from '@/client/hooks/ui/auth';
+import { resetRealtimeClient } from '@/shared/lib/realtime/client';
+import { invalidateModelsCache } from '@/shared/lib/models/client';
+import { sessionTelemetryTopic, TOPIC_PANELS } from '@/shared/lib/realtime/protocol';
+import type { PanelRegistryPayload } from '@/shared/types';
+import type { SessionContextTelemetry } from '@/shared/types/context';
+import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support/realtime-server';
+import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
+import type { TopicResolver } from '@/server/lib/realtime/hub.server';
+
+const SESSION = 'session-header-plugin-entry';
+const nativeFetch = Bun.fetch;
+const Noop = () => null;
+
+let container: HTMLElement;
+let server: RealtimeTestServer;
+
+const PANELS: PanelRegistryPayload = {
+  panels: [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', appUrl: '/api/panels/bundle/demo.js' }],
+  marketplaces: [],
+  errors: [],
+  plugins: [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', isPackage: true, built: true, enabled: true, bundled: false, gitOrigin: null }],
+  catalog: [],
+  disabledPanels: [],
+  gitStatus: {},
+  autoUpdate: false,
+  syncBlocked: {},
+};
+
+function telemetry(): SessionContextTelemetry {
+  return {
+    sessionId: SESSION,
+    sessionTitle: 'Header',
+    modelId: 'kenari/deepseek-v4-1-flash',
+    modelName: 'deepseek-v4-1-flash',
+    timestamp: 'today',
+    contextUsed: 12_000,
+    contextLimit: 100_000,
+    contextPercent: 12,
+    messagesCount: 3,
+    userCount: 1,
+    assistantCount: 2,
+    totalCost: 0.01,
+    costFormatted: '$0.01',
+    cacheHitAverage: 90,
+    lastMessage: { input: 10, output: 4, reasoning: 0, cacheRead: 2, cacheWrite: 0, cacheHitPercent: 16.6 },
+    distribution: { userTokens: 1, userPercent: 25, assistantTokens: 1, assistantPercent: 25, toolTokens: 1, toolPercent: 25, otherTokens: 1, otherPercent: 25 },
+    rawMessages: [],
+  };
+}
+
+/** Register a plugin whose header ACTION opens its own right panel. */
+function registerActionPlugin(): void {
+  registerPluginBundle('demo', {
+    default: definePluginApp((app) => {
+      app.rightPanel({ id: 'r', title: 'Resources', component: Noop });
+      app.headerPanel({ id: 'h', title: 'Demo Stats', component: Noop, opensPanel: 'rightPanel' });
+    }),
+  });
+}
+
+beforeEach(async () => {
+  invalidateModelsCache();
+  const panels: TopicResolver = async () => PANELS;
+  const telemetryTopic: TopicResolver = async () => telemetry();
+  server = await startRealtimeTestServer(new Map<string, TopicResolver>([
+    [TOPIC_PANELS, panels],
+    [sessionTelemetryTopic(SESSION), telemetryTopic],
+  ]));
+  installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+  const target = globalThis as unknown as Record<string, unknown>;
+  target.WebSocket = pristineWebSocket;
+  target.fetch = async (input: unknown) => {
+    const json = (body: unknown) => new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+    const url = String(input);
+    if (url.includes('/api/sessions/')) return json({ state: {} });
+    if (url.includes('/api/telemetry/context')) return json({ telemetry: telemetry() });
+    if (url.includes('/api/models')) return json({ modelList: [], connectedProviders: [] });
+    return json({});
+  };
+  resetPluginSlots();
+  registerActionPlugin();
+  // No password: the sign-out control would otherwise add a row to the menu
+  // this suite asserts on.
+  primeAuthState(false, false);
+});
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+  }
+  resetPluginSlots();
+  resetRealtimeClient();
+  server?.stop();
+  (globalThis as unknown as Record<string, unknown>).fetch = nativeFetch;
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+});
+
+async function mount(layout: 'desktop' | 'mobile', width: number): Promise<void> {
+  Object.defineProperty(window, 'innerWidth', { value: width, configurable: true, writable: true });
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(
+      h(SessionStateProvider, {
+        sessionId: SESSION,
+        children: h(HeaderControls, {
+          layout,
+          sessionId: SESSION,
+          showRightPanel: false,
+          onToggleRightPanel: () => {},
+        }),
+      }),
+      container,
+    );
+  });
+  await server.waitForTopic(TOPIC_PANELS, (value) => value !== null);
+  for (let i = 0; i < 10; i += 1) await act(async () => {});
+}
+
+/** Every control in the row, by its accessible name. */
+function rowNames(): string[] {
+  return [...container.querySelectorAll('button, [title]')]
+    .map((element) => element.getAttribute('aria-label') ?? element.getAttribute('title') ?? '')
+    .map((label) => label.replace(/ \([^)]*\)$/, ''));
+}
+
+describe('a plugin header action', () => {
+  test('desktop: a button that asks for its own panel by instance key', async () => {
+    await mount('desktop', 1024);
+
+    const events: string[] = [];
+    const listener = (event: Event) => {
+      const detail = (event as CustomEvent<{ panelKey?: string }>).detail;
+      if (detail?.panelKey) events.push(detail.panelKey);
+    };
+    window.addEventListener('omp:open-panel', listener);
+    const button = container.querySelector('button[aria-label="Demo Stats"]') as HTMLElement;
+    expect(button).toBeTruthy();
+    await act(async () => {
+      button.click();
+    });
+    window.removeEventListener('omp:open-panel', listener);
+
+    expect(events).toEqual(['plugin:demo:rightPanel']);
+  });
+
+  test('a narrow phone folds it into the menu, and the row keeps the title space', async () => {
+    await mount('mobile', 390);
+
+    expect(rowNames()).not.toContain('Demo Stats');
+
+    const trigger = container.querySelector('button[aria-label="More actions"]') as HTMLElement;
+    expect(trigger).toBeTruthy();
+    await act(async () => {
+      trigger.click();
+    });
+    // The row IS the plugin's readout: the title is its accessible name, not a
+    // second label printed beside the same figures.
+    const row = container.querySelector('[role="menu"] [role="menuitem"][aria-label="Demo Stats"]');
+    expect(row).toBeTruthy();
+  });
+
+  test('the menu row opens the panel, on the same event', async () => {
+    await mount('mobile', 390);
+    const trigger = container.querySelector('button[aria-label="More actions"]') as HTMLElement;
+    await act(async () => {
+      trigger.click();
+    });
+
+    const events: string[] = [];
+    const listener = (event: Event) => {
+      const detail = (event as CustomEvent<{ panelKey?: string }>).detail;
+      if (detail?.panelKey) events.push(detail.panelKey);
+    };
+    window.addEventListener('omp:open-panel', listener);
+    const row = container.querySelector('[role="menu"] [role="menuitem"][aria-label="Demo Stats"]') as HTMLElement;
+    await act(async () => {
+      row.click();
+    });
+    window.removeEventListener('omp:open-panel', listener);
+
+    expect(events).toEqual(['plugin:demo:rightPanel']);
+  });
+
+  test('a wide enough phone keeps it in the row', async () => {
+    await mount('mobile', 500);
+    expect(rowNames()).toContain('Demo Stats');
+  });
+});

package/src/client/components/common/header-panel-buttons/entries.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Where a plugin's navbar entry goes, and why the answer is not "the row".
+ *
+ * A phone header shares 320–430px between the wordmark, the session title and
+ * the controls used mid-conversation. A plugin readout is the first thing that
+ * has to give way, and the measured cost of not folding it is the session title:
+ * with a `CPU 18% / RAM 2.5G` readout (73px) in the row at 390px, the title kept
+ * 48px of its 74px and was clipped; at 430px it kept all of it.
+ *
+ * Three rules, and each is a control that becomes unreachable when broken:
+ *
+ * - **An ACTION entry folds into `⋯`.** It has one click and no UI of its own,
+ *   so a menu row is the same action in words.
+ * - **A dropdown or a static readout never folds.** A dropdown needs its
+ *   trigger's anchor, and a static readout has no action to perform; folding
+ *   either would be a different control rather than the same one moved.
+ * - **A wide enough phone, and every desktop, draws everything in the row.**
+ *   The threshold is a WIDTH, not a device class — the same rule the header's
+ *   own reload/sign-out fold follows.
+ *
+ * The hook half is exercised through `HeaderControls` (which is where the row
+ * and the menu actually split); this file pins the pure decision it encodes.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { MOBILE_HEADER_ACTION_PX, MOBILE_HEADER_ENTRY_MAX_PX } from '@/client/components/common/header-panel-buttons/entries';
+
+describe('the header entry thresholds', () => {
+  test('the action threshold is past the width where the title clips', () => {
+    // Measured: 390px clips the title to 48px of 74px; 430px does not.
+    expect(MOBILE_HEADER_ACTION_PX).toBe(430);
+    expect(MOBILE_HEADER_ACTION_PX).toBeGreaterThan(390);
+  });
+
+  test('the per-entry cap holds a two-column readout and no more', () => {
+    // The measured readout is 73px wide at 12px mono; the cap leaves room for a
+    // longer figure without letting one plugin take the row.
+    expect(MOBILE_HEADER_ENTRY_MAX_PX).toBeGreaterThanOrEqual(73);
+    expect(MOBILE_HEADER_ENTRY_MAX_PX).toBeLessThan(120);
+  });
+});