@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/marketplace/plugins/session-info/README.md

@@ -0,0 +1,23 @@
+# Session Info
+
+The example panel plugin bundled with Kabmo, and the reference for the
+plugin API.
+
+## What it adds
+
+| Slot | What you get |
+|---|---|
+| `rightPanel` | **Session Info** — the active workspace, the session id and a note kept per session. |
+| `headerPanel` | **Session Stats** — a text readout in the navbar (`s3f2 · 120 ch`) that opens a dropdown. |
+| `panel` | **Scratchpad** — a second text area, taking over the editor column. |
+
+## What it reads
+
+- `usePanelInfo()` — the session, the workspace and the live palette.
+- `useSessionValue('note')` — a value stored per session, debounced on write.
+
+## Notes
+
+Nothing here leaves your machine. The note is written to the session's own state
+in Kabmo's database, and the plugin's bundle is served from the plugin
+directory it was installed into.

package/marketplace/plugins/session-info/icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="Session Info">
+  <title>Session Info</title>
+  <!-- Geometry follows the built-in views' convention (Lucide): the art is inset
+       2/24 of the box and strokes at 2/24, so a plugin's mark carries the same
+       ink weight as the icons it sits beside. Paint is `currentColor`: the host
+       draws a vector mark through a CSS mask, so the file supplies the shape and
+       the surrounding ink supplies the colour. -->
+  <g fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="3" y="4" width="18" height="16" rx="2" />
+    <path d="M7 9h6" />
+    <path d="M7 12.5h9" />
+    <path d="M7 16h5" />
+  </g>
+</svg>

package/marketplace/plugins/session-info/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "session-info",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Shows the active workspace and keeps a note per session.",
+  "type": "module",
+  "kabmo": {
+    "id": "session-info",
+    "name": "Session Info",
+    "version": "0.0.1",
+    "description": "Shows the active workspace and keeps a note per session.",
+    "app": "dist/app.js",
+    "server": "dist/server.js",
+    "icon": "icon.svg",
+    "settings": {
+      "notePrefix": {
+        "type": "string",
+        "label": "Note prefix",
+        "description": "Prepended to every note saved by the server half.",
+        "default": ""
+      }
+    },
+    "css": "dist/app.css"
+  },
+  "peerDependencies": {
+    "@kabmo-labs/kabmo-sdk": "*",
+    "@kabmo-labs/kabmo-ui": "*",
+    "preact": "^10.29.8"
+  },
+  "peerDependenciesMeta": {
+    "@kabmo-labs/kabmo-sdk": {
+      "optional": true
+    },
+    "@kabmo-labs/kabmo-ui": {
+      "optional": true
+    },
+    "preact": {
+      "optional": true
+    }
+  }
+}

package/marketplace/plugins/session-info/src/app.test.tsx

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The bundled example plugin, tested the way a plugin author's test is written.
+ *
+ * This is the P0 gate: it runs under `bun test` with NO Kabmo process, no
+ * database and no network, using only `@kabmo-labs/kabmo-sdk/testing/app` and
+ * the published kit. It exists to prove the harness can load a real bundle —
+ * one that imports `@kabmo-labs/kabmo-sdk/app`, `@kabmo-labs/kabmo-ui` and
+ * `@kabmo-labs/kabmo-ui/components` — and then render and drive what it registered.
+ *
+ * The plugin's module is imported at the TOP of this file, before any test has
+ * run and therefore before any runtime exists. That ordering is the point:
+ * `loadPluginApp` takes the already-imported namespace, and the runtime it
+ * installs is what the module's components read when they are CALLED.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { render } from 'preact';
+import { act } from 'preact/test-utils';
+import { loadPluginApp, renderSlot, type LoadedPluginApp, type RenderedSlot } from '@kabmo-labs/kabmo-sdk/testing/app';
+import * as pluginModule from './app';
+
+const PLUGIN_ID = 'session-info';
+
+/** Let the kit's debounced write land before asserting on the store. */
+function settle(ms = 500): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * The DOM globals a happy-dom window provides, replaced for this suite only.
+ *
+ * Built here rather than imported from Kabmo's `src/test-support`: this is
+ * a plugin, and a plugin's test must run from its own directory with the
+ * published packages alone — the harness exists precisely so a plugin author
+ * never has to reach into Kabmo's source.
+ */
+const DOM_GLOBALS = [
+  'window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement',
+  'HTMLInputElement', 'HTMLTextAreaElement', 'Event', 'MouseEvent', 'KeyboardEvent',
+] as const;
+
+type DomGlobal = (typeof DOM_GLOBALS)[number];
+const pristine: Partial<Record<DomGlobal, unknown>> = {};
+let captured = false;
+
+function installDom(win: unknown): void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  if (!captured) {
+    captured = true;
+    for (const key of DOM_GLOBALS) pristine[key] = target[key];
+  }
+  target.window = win;
+  const source = win as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (key !== 'window' && source[key] !== undefined) target[key] = source[key];
+  }
+}
+
+function restoreDom(): void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (key in pristine) target[key] = pristine[key];
+    else delete target[key];
+  }
+}
+
+let loaded: LoadedPluginApp;
+let rendered: RenderedSlot | undefined;
+let container: HTMLElement;
+
+beforeEach(() => {
+  installDom(new Window({ url: 'http://localhost' }));
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  loaded = loadPluginApp(pluginModule, {
+    pluginId: PLUGIN_ID,
+    panel: { sessionId: 'session-42', workspacePath: '/workspace/demo', theme: 'paper' },
+  });
+});
+
+afterEach(() => {
+  rendered?.unmount();
+  rendered = undefined;
+  render(null, container);
+  container.remove();
+  loaded.harness.dispose();
+  restoreDom();
+});
+
+describe('session-info', () => {
+  test('registers its three slots, with the titles and sizing it declared', () => {
+    const { registrations, failures } = loaded.harness;
+    expect(failures).toEqual([]);
+    expect(registrations.rightPanel?.id).toBe('info');
+    expect(registrations.headerPanel?.id).toBe('stats');
+    expect(registrations.panel?.id).toBe('scratch');
+    expect(registrations.titles).toEqual({
+      rightPanel: 'Session Info',
+      headerPanel: 'Session Stats',
+      panel: 'Scratchpad',
+    });
+    expect(registrations.sizing.rightPanel).toEqual({ minWidth: 300, defaultFraction: 0.35 });
+    // The header is a trigger AND a dropdown, which the registrar keeps apart.
+    expect(registrations.headerDropdown).toBeFunction();
+  });
+
+  test('the right panel renders the live context', () => {
+    rendered = renderSlot(loaded.harness.registrations.rightPanel!, {
+      sessionId: 'session-42',
+      workspacePath: '/workspace/demo',
+    });
+    const text = rendered.container.textContent ?? '';
+    expect(text).toContain('session-42');
+    expect(text).toContain('/workspace/demo');
+    expect(text).toContain('paper');
+  });
+
+  test('the note field writes through the fake session store', async () => {
+    rendered = renderSlot(loaded.harness.registrations.rightPanel!, {
+      sessionId: 'session-42',
+      workspacePath: '/workspace/demo',
+    });
+    const field = rendered.container.querySelector('#session-info-note') as HTMLTextAreaElement;
+    expect(field).not.toBeNull();
+
+    await act(async () => {
+      field.value = 'remember this';
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+
+    // The write is debounced by the kit's hook (400ms default), so the store is
+    // asserted after it lands — and only after it lands is the store the truth.
+    await settle();
+    expect(loaded.harness.session.read('note')).toBe('remember this');
+  });
+
+  test('the header dropdown reads the same note the panel wrote', () => {
+    loaded.harness.session.write('note', 'four');
+    // The dropdown is not a slot of its own: the registrar keeps it beside the
+    // header registration, so a test renders it through a registration object
+    // the way the host's own navbar does.
+    const dropdown = loaded.harness.registrations.headerDropdown;
+    expect(dropdown).toBeFunction();
+    rendered = renderSlot({ id: 'stats-dropdown', component: dropdown! }, {
+      sessionId: 'session-42',
+      workspacePath: '/workspace/demo',
+    });
+    expect(rendered.container.textContent).toContain('4');
+  });
+
+  test('the panel slot persists to its own key, not the note', async () => {
+    rendered = renderSlot(loaded.harness.registrations.panel!, {
+      sessionId: 'session-42',
+      workspacePath: '/workspace/demo',
+    });
+    const field = rendered.container.querySelector('#scratchpad') as HTMLTextAreaElement;
+    await act(async () => {
+      field.value = 'rough notes';
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+
+    await settle();
+    expect(loaded.harness.session.read('scratch')).toBe('rough notes');
+    expect(loaded.harness.session.read('note')).toBeNull();
+  });
+});

package/marketplace/plugins/session-info/src/app.tsx

@@ -0,0 +1,174 @@
+import './styles.css';
+import { definePluginApp } from '@kabmo-labs/kabmo-sdk/app';
+import { usePanelInfo, useSessionValue } from '@kabmo-labs/kabmo-ui';
+import { Field, FieldList, Note, Panel, TextAreaField } from '@kabmo-labs/kabmo-ui/components';
+
+/**
+ * The bundled example plugin.
+ *
+ * One file, one bundle, three slots — which is the whole shape of a panel
+ * plugin: a `definePluginApp` default export whose `setup` registers the
+ * components, and nothing else. The components run in Kabmo's own tree,
+ * so they use Kabmo's theme classes and its hooks directly.
+ *
+ * It exists to exercise every surface a plugin can occupy, so a change that
+ * breaks one slot is visible without writing a plugin:
+ *
+ * - `rightPanel` — a view in the right panel's activity bar.
+ * - `headerPanel` — a navbar entry: a text readout that opens a dropdown.
+ * - `panel` — the editor column, taken over whole. It is NOT an editor: the
+ *   host supplies no tabs and no file tree, so a plugin that wants those builds
+ *   them itself.
+ * - `contentScript` + an imported stylesheet — the app-shell half. This is the
+ *   only contribution that touches DOM the host did not hand it, so it also
+ *   demonstrates the two rules that come with it: the script appends into the
+ *   ROOT element the context hands it (that element is what the plugin's own
+ *   CSS is scoped to), and it gives its DOM back through the disposer.
+ */
+
+/** The status line, from the same save state the field reports. */
+function noteHint(status: string, error: string | null, sessionId: string | null): string {
+  if (error) return `Could not save: ${error}`;
+  if (status === 'saved') return 'Saved.';
+  if (status === 'saving') return 'Saving…';
+  return sessionId ? `Session ${sessionId.slice(0, 8)}…` : 'No session selected.';
+}
+
+function SessionInfoPanel() {
+  const info = usePanelInfo();
+  const note = useSessionValue('note');
+
+  return (
+    <Panel title="Session Info">
+      <FieldList>
+        <Field label="workspace" value={info.workspacePath ?? 'none'} />
+        <Field label="session" value={info.sessionId ?? 'none'} />
+        <Field label="theme" value={info.theme} />
+      </FieldList>
+      <div className="mt-3">
+        <TextAreaField
+          id="session-info-note"
+          label="note (saved per session)"
+          value={note.value ?? ''}
+          placeholder="Anything you want to keep for this session…"
+          hint={noteHint(note.status, note.error, info.sessionId)}
+          onInput={note.update}
+        />
+      </div>
+    </Panel>
+  );
+}
+
+/**
+ * The navbar TRIGGER.
+ *
+ * A header entry is two components, and this is the one the user reads: plain
+ * text, styled by the plugin, sitting in the navbar. It is deliberately not a
+ * button — the host wraps it in one only when the registration also declares a
+ * dropdown, so this component never has to know which case it is in.
+ */
+function SessionStatsTrigger() {
+  const info = usePanelInfo();
+  const note = useSessionValue('note');
+  const length = (note.value ?? '').length;
+
+  return (
+    <span className="flex items-center gap-1.5 text-[11px] font-mono text-ink/70">
+      <span>{info.sessionId ? `s${info.sessionId.slice(0, 4)}` : 'no session'}</span>
+      <span className="text-ink/30">·</span>
+      <span>{length} ch</span>
+    </span>
+  );
+}
+
+/**
+ * The navbar DROPDOWN — drawn only while the entry is open.
+ *
+ * Kept short on purpose: Kabmo caps it and gives it its own scroll, but a
+ * readout nobody can take in at a glance defeats the point of a navbar entry.
+ */
+function SessionStatsDropdown() {
+  const info = usePanelInfo();
+  const note = useSessionValue('note');
+
+  return (
+    <div className="p-3 space-y-2">
+      <div className="text-xs font-semibold text-ink">Session Stats</div>
+      <FieldList>
+        <Field label="workspace" value={info.workspacePath ?? 'none'} />
+        <Field label="note length" value={String((note.value ?? '').length)} />
+      </FieldList>
+      <Note>{info.sessionId ? 'Attached to a session.' : 'No session selected yet.'}</Note>
+    </div>
+  );
+}
+
+/**
+ * The `panel` slot: the editor COLUMN, taken over whole.
+ *
+ * Nothing about this is an editor — it is a second place a view can live, and
+ * this one happens to be a scratchpad. A plugin that wanted tabs, a file list or
+ * a split would build them here; the host contributes none of it.
+ */
+function ScratchpadPanel() {
+  const info = usePanelInfo();
+  const scratch = useSessionValue('scratch');
+
+  return (
+    <Panel title="Scratchpad">
+      <TextAreaField
+        id="scratchpad"
+        label="scratch (saved per session, separate from the note)"
+        value={scratch.value ?? ''}
+        placeholder="Rough notes for this session…"
+        hint={noteHint(scratch.status, scratch.error, info.sessionId)}
+        onInput={scratch.update}
+      />
+    </Panel>
+  );
+}
+
+/**
+ * The `contentScript` slot, plus the stylesheet its import produces.
+ *
+ * The context hands over a ROOT element, and that is where this script's DOM
+ * goes. The element carries this plugin's scope attribute, which is what the
+ * imported stylesheet is scoped to — a node appended to `document.body`
+ * instead would sit outside the surface and its own CSS could not reach it.
+ *
+ * The disposer releases what the host cannot. The DOM here needs no undoing —
+ * the host removes the whole root subtree on teardown — but a script that
+ * registered a listener or a timer has no other place to release it, and that
+ * is what the returned function is for.
+ */
+function mountShellDecoration(context: { pluginId: string; root: HTMLElement }): () => void {
+  const badge = context.root.ownerDocument.createElement('span');
+  badge.className = 'session-info-badge';
+  badge.textContent = 'session info active';
+  context.root.appendChild(badge);
+
+  return () => {
+    badge.remove();
+  };
+}
+
+export default definePluginApp((app) => {
+  app.contentScript({ id: 'shell-decoration', mount: mountShellDecoration });
+  app.rightPanel({
+    id: 'info',
+    title: 'Session Info',
+    component: SessionInfoPanel,
+    minWidth: 300,
+    defaultFraction: 0.35,
+  });
+  // A trigger and a dropdown are separate components: the navbar reads the
+  // first, and the second is what opening it shows. Declaring no dropdown would
+  // make this a static readout with no interaction at all.
+  app.headerPanel({
+    id: 'stats',
+    title: 'Session Stats',
+    component: SessionStatsTrigger,
+    dropdown: { component: SessionStatsDropdown },
+  });
+  app.panel({ id: 'scratch', title: 'Scratchpad', component: ScratchpadPanel });
+});

package/marketplace/plugins/session-info/src/server.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The bundled example plugin's SERVER half.
+ *
+ * It exists to exercise every member of `KabmoPluginApi` in one small file,
+ * so a change that breaks one of them is visible without writing a plugin. What
+ * each part is FOR is stated where it is used; what matters here is that all of
+ * it is disposed: a plugin that registers a method, a route and a topic and
+ * then forgets one of them is the failure this example would otherwise teach.
+ *
+ * The default export is a FACTORY (`export default function plugin(api) {}`),
+ * not an object. That is what lets the host hand a plugin the subset of the API
+ * it is willing to give, and defer running it until the plugin is loaded.
+ */
+
+import type { KabmoPluginApi } from '@kabmo-labs/kabmo-sdk';
+
+/** Notes the server half keeps, one per session, in the plugin's own storage. */
+const NOTES_COLLECTION = 'notes';
+
+export default function plugin(api: KabmoPluginApi) {
+  api.log.info('session-info server half loaded');
+
+  /**
+   * The RPC surface: what the plugin's own client half calls.
+   *
+   * No input schema on `get` — a session id is the only argument and the handler
+   * treats a missing one as "no session" — while `save` validates, because a
+   * note that arrives as a number would otherwise be stored as the string
+   * `"42"` and read back as text the user never typed.
+   */
+  api.rpc.register('get', {
+    handler: async (sessionId: unknown) => {
+      if (typeof sessionId !== 'string' || !sessionId) return null;
+      return (await api.storage.records.get(NOTES_COLLECTION, sessionId)) ?? null;
+    },
+  });
+
+  api.rpc.register<{ sessionId: string; note: string }, { saved: boolean }>('save', {
+    input: {
+      '~standard': {
+        version: 1,
+        vendor: 'session-info',
+        validate: (value: unknown) => {
+          if (typeof value !== 'object' || value === null) {
+            return { issues: [{ message: 'expected { sessionId, note }' }] };
+          }
+          const candidate = value as { sessionId?: unknown; note?: unknown };
+          if (typeof candidate.sessionId !== 'string' || !candidate.sessionId) {
+            return { issues: [{ message: 'sessionId must be a non-empty string', path: ['sessionId'] }] };
+          }
+          if (typeof candidate.note !== 'string') {
+            return { issues: [{ message: 'note must be a string', path: ['note'] }] };
+          }
+          return { value: { sessionId: candidate.sessionId, note: candidate.note } };
+        },
+      },
+    },
+    handler: async ({ sessionId, note }) => {
+      const prefix = (await api.settings.readOne<string>('notePrefix')) ?? '';
+      await api.storage.records.put(NOTES_COLLECTION, sessionId, { note: `${prefix}${note}`, savedAt: Date.now() });
+      // The plugin's own topic carries the count, so a panel can render it
+      // without polling and without a second read of its storage.
+      const rows = await api.storage.records.list(NOTES_COLLECTION, { limit: 1000 });
+      api.realtime.publish({ noteCount: rows.length });
+      return { saved: true };
+    },
+  });
+
+  /**
+   * The HTTP surface: what anything ELSE can call.
+   *
+   * A plain `Request → Response` handler, which is what a shareable URL or a
+   * webhook needs — the shape an RPC method deliberately does not have.
+   */
+  api.http.route('/notes', async (request) => {
+    const rows = await api.storage.records.list(NOTES_COLLECTION, { limit: 100 });
+    return Response.json({
+      method: request.method,
+      count: rows.length,
+      ids: rows.map((row) => row.id),
+    });
+  });
+
+  /**
+   * The event surface: the plugin hears its own names, and announces one.
+   *
+   * The announcement is what a second surface (a future badge, another plugin)
+   * subscribes to; it is deliberately not the same channel as the realtime
+   * topic, because an event is a MOMENT and a topic is a VALUE.
+   */
+  api.events.on('note-saved', (payload) => {
+    api.log.debug('a note was saved', payload ?? null);
+  });
+
+  // The seed, so a subscriber that arrives before the first save gets a value
+  // rather than an empty topic.
+  api.realtime.seed({ noteCount: 0 });
+
+  /**
+   * Background work: one interval that republishes the count.
+   *
+   * Declared rather than run by the plugin, so Kabmo's own scheduler owns
+   * the timer and a reload cannot leave a second one behind.
+   */
+  api.background.schedule('refresh-count', '5m', async () => {
+    const rows = await api.storage.records.list(NOTES_COLLECTION, { limit: 1000 });
+    api.realtime.publish({ noteCount: rows.length });
+  });
+
+  api.onDispose(() => {
+    api.log.info('session-info server half disposed');
+  });
+}

package/marketplace/plugins/session-info/src/styles.css

@@ -0,0 +1,48 @@
+/*
+ * A stylesheet the demo plugin IMPORTS, which is the case this file exists to
+ * prove: `Bun.build` emits it beside the bundle (`dist/app.css`) and the emitted
+ * JS never references it, so without `css` in the manifest nothing would load
+ * it. The manifest declares it and the host loads it for as long as this
+ * plugin's content script is mounted.
+ *
+ * THE HOST SCOPES THIS FOR YOU. The server serves the file wrapped in
+ * `@scope ([data-plugin-surface="session-info"])`, so these rules can only match
+ * inside this plugin's own DOM — its slot components and its content script's
+ * root. Write them the way you would write ordinary CSS for your own markup.
+ *
+ * Do NOT reach for the host's classes. This file used to say
+ * `html[data-session-info] .code-block::before`, and that is the leak the
+ * scoping replaced: `.code-block` is Kabmo's class and `html[…]` is an
+ * ancestor of everything, so the rule drew a gradient line over every code block
+ * in the chat. Under `@scope` a selector like that matches nothing — which is
+ * the honest outcome, and the reason the content-script contract hands you a
+ * root element to put your own markup in.
+ */
+
+/* This plugin's own marker element, appended to the content script's root. */
+.session-info-badge {
+  position: fixed;
+  right: 0.75rem;
+  bottom: 0.75rem;
+  z-index: 40;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.25rem 0.5rem;
+  border: 1px solid color-mix(in srgb, var(--theme-ink) 15%, transparent);
+  border-radius: 0.375rem;
+  background: var(--theme-paper);
+  color: color-mix(in srgb, var(--theme-ink) 60%, transparent);
+  font-family: 'Fira Code', monospace;
+  font-size: 0.625rem;
+  line-height: 1;
+  pointer-events: none;
+}
+
+.session-info-badge::before {
+  content: '';
+  width: 0.375rem;
+  height: 0.375rem;
+  border-radius: 9999px;
+  background: var(--theme-success);
+}

package/marketplace/plugins/session-info/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ESNext",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": [],
+    "allowArbitraryExtensions": true
+  },
+  "include": [
+    "src"
+  ]
+}