@kabmo-labs/kabmo-ui 0.0.0-stage → 0.0.1

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@kabmo-labs/kabmo-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Preact hooks and components for Kabmo panel plugins.",
+  "exports": {
+    ".": "./src/index.tsx",
+    "./components": "./src/components.tsx"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "preact": "^10.29.8",
+    "@kabmo-labs/kabmo-sdk": "0.0.1"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kabmo-labs/kabmo.git",
+    "directory": "packages/kabmo-ui"
+  },
+  "homepage": "https://github.com/kabmo-labs/kabmo#readme",
+  "bugs": {
+    "url": "https://github.com/kabmo-labs/kabmo/issues"
+  },
+  "keywords": [
+    "kabmo",
+    "panel",
+    "plugin",
+    "preact",
+    "ui"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  }
+}

package/src/components.tsx

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The panel UI kit.
+ *
+ * These are ordinary host components, not a sandboxed mini-app's widgets: a
+ * plugin renders inside Kabmo's own tree, so the kit uses Kabmo's
+ * theme variables and Tailwind utilities directly and looks native in every
+ * palette with no CSS bridge.
+ *
+ * The kit exists so a plugin does not re-invent the same six shapes — a titled
+ * panel, a label/value row, a text field, a button, an empty state, a note —
+ * and so those shapes stay consistent across plugins the way they are within
+ * Kabmo itself.
+ *
+ * Every component takes its colours from the theme variables (`bg-paper`,
+ * `text-ink`, `border-ink/10`), never a literal, which is what keeps a plugin
+ * legible in the light and dark palettes without knowing they exist.
+ */
+
+import type { ComponentChildren } from 'preact';
+import { uiKitServices } from './services';
+
+interface PanelProps {
+  title: string;
+  children: ComponentChildren;
+}
+
+/** A panel's outer chrome: a title bar over a scrolling body. */
+export function Panel({ title, children }: PanelProps) {
+  return (
+    <div class="flex flex-col h-full w-full bg-paper text-ink">
+      <div class="flex-shrink-0 border-b border-ink/10 px-3 py-2">
+        <span class="text-xs font-semibold text-ink">{title}</span>
+      </div>
+      <div class="flex-1 min-h-0 overflow-auto p-3">{children}</div>
+    </div>
+  );
+}
+
+interface FieldProps {
+  label: string;
+  value: string;
+  hint?: string;
+}
+
+/** One labelled fact. The label is a micro-header, the value is machine text. */
+export function Field({ label, value, hint }: FieldProps) {
+  return (
+    <div class="flex flex-col gap-0.5">
+      <span class="text-[10px] uppercase font-mono text-ink/40">{label}</span>
+      <span class="text-xs font-mono text-ink break-all">{value}</span>
+      {hint ? <span class="text-[11px] text-ink/50">{hint}</span> : null}
+    </div>
+  );
+}
+
+/** A stack of `Field`s. */
+export function FieldList({ children }: { children: ComponentChildren }) {
+  return <div class="flex flex-col gap-3">{children}</div>;
+}
+
+interface TextAreaFieldProps {
+  id: string;
+  label: string;
+  value: string;
+  placeholder?: string;
+  hint?: string;
+  onInput: (value: string) => void;
+}
+
+/**
+ * A labelled textarea.
+ *
+ * Controlled through `onInput` rather than owning its own state, so the caller
+ * decides what a keystroke means — the session-persisting hook debounces the
+ * write, while a purely local field can keep the value in the caller.
+ */
+export function TextAreaField({ id, label, value, placeholder, hint, onInput }: TextAreaFieldProps) {
+  return (
+    <div class="flex flex-col gap-1">
+      <label for={id} class="text-[10px] uppercase font-mono text-ink/40">
+        {label}
+      </label>
+      <textarea
+        id={id}
+        value={value}
+        placeholder={placeholder}
+        onInput={(event) => onInput((event.currentTarget as HTMLTextAreaElement).value)}
+        class="w-full min-h-20 resize-y bg-canvas border border-ink/15 rounded px-2.5 py-1.5 text-xs font-mono text-ink placeholder-ink/35 focus:outline-none focus:border-ink/40"
+      />
+      {hint ? <span class="text-[11px] text-ink/50">{hint}</span> : null}
+    </div>
+  );
+}
+
+interface ButtonProps {
+  children: ComponentChildren;
+  onClick: () => void;
+  disabled?: boolean;
+  /** The one action a panel wants the user to take. */
+  variant?: 'default' | 'primary';
+}
+
+/** A button. */
+export function Button({ children, onClick, disabled, variant = 'default' }: ButtonProps) {
+  const tone =
+    variant === 'primary'
+      ? 'bg-ink text-canvas border-ink hover:opacity-90'
+      : 'border-ink/15 hover:bg-ink/5 text-ink';
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      class={`inline-flex items-center gap-1.5 px-2.5 py-1.5 text-xs rounded border transition-colors disabled:opacity-40 disabled:cursor-default ${tone}`}
+    >
+      {children}
+    </button>
+  );
+}
+
+/** Centred placeholder for a panel with nothing to show. */
+export function Empty({ children }: { children: ComponentChildren }) {
+  return (
+    <div class="h-full flex items-center justify-center px-6 text-center">
+      <p class="text-xs text-ink/45 font-mono">{children}</p>
+    </div>
+  );
+}
+
+/** A message. `error` is the only chroma a panel should use. */
+export function Note({ children, tone = 'default' }: { children: ComponentChildren; tone?: 'default' | 'error' }) {
+  const colour = tone === 'error' ? 'text-error' : 'text-ink/60';
+  return <p class={`text-[11px] ${colour}`}>{children}</p>;
+}
+
+interface MarkdownProps {
+  content: string;
+  className?: string;
+}
+
+/**
+ * Render markdown through Kabmo's own pipeline.
+ *
+ * The pipeline itself is not in this package: it is Kabmo's marked /
+ * KaTeX / mermaid / Shiki chain plus its file-opening and clipboard hooks, and
+ * bundling it here would make every plugin carry a second copy of a large tree.
+ * The host injects the component (`UiKitServices.markdown`), so a wiki page or
+ * a plan reads exactly like the chat timeline without the kit owning any of it.
+ *
+ * A host that injects nothing renders the source as plain text rather than
+ * failing: a panel showing raw markdown is degraded, not broken.
+ */
+export function Markdown({ content, className }: MarkdownProps) {
+  const Renderer = uiKitServices()?.markdown?.() ?? null;
+  if (!Renderer) return <pre class={`text-xs font-mono whitespace-pre-wrap ${className ?? ''}`}>{content}</pre>;
+  return <Renderer content={content} className={className} />;
+}
+

package/src/fetch.test.tsx

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `useKabmoFetch` — the kit's own reader for a plugin panel that reaches the
+ * Kabmo's HTTP API.
+ *
+ * It replaced two hand-rolled copies (`useSessionTodos`, `useSessionPlan`) that
+ * had the same three behaviours and the same three bugs waiting to happen, so
+ * this file pins the behaviours rather than the call sites (Kabmo's own
+ * views have since moved to the realtime socket):
+ *
+ * - **A late answer never overwrites a newer one.** Switching sessions fires a
+ *   second request while the first is in flight; without the sequence guard the
+ *   previous session's payload lands under the new title.
+ * - **A new URL DROPS the old payload first.** Not merely re-reads: a stale list
+ *   visible under a new session's name is the failure a user actually sees.
+ * - **Hidden and disabled panels do not poll.** A background tab cannot render
+ *   the result, and a hidden view's poll is pure waste.
+ *
+ * Rendered with `h()` (no JSX) against happy-dom.
+ */
+
+import { 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 { configureUiKit, useKabmoFetch, type PanelContext, type UiKitServices } from '@kabmo-labs/kabmo-ui';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event', 'MouseEvent', 'KeyboardEvent'] as const;
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+const CONTEXT: PanelContext = { sessionId: 's1', workspacePath: '/ws', theme: 'paper' };
+const SERVICES: UiKitServices = {
+  context: () => CONTEXT,
+  subscribe: () => () => {},
+  getSessionValue: () => null,
+  setSessionValue: () => {},
+  readWorkspaceFile: async () => '',
+};
+
+/** One fetch call, and the promise its caller is waiting on. */
+interface PendingRequest {
+  url: string;
+  resolve: (body: unknown, status?: number) => void;
+}
+
+let container: HTMLElement;
+let requests: PendingRequest[] = [];
+/** The reads a disabled/hidden hook was expected NOT to make. */
+let calls = 0;
+
+function installFetch(): void {
+  (globalThis as unknown as Record<string, unknown>).fetch = (input: unknown) => {
+    calls += 1;
+    const url = String(input);
+    return new Promise<Response>((resolve) => {
+      requests.push({
+        url,
+        resolve: (body, status = 200) =>
+          resolve(new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } })),
+      });
+    });
+  };
+}
+
+beforeEach(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in nativeGlobals)) nativeGlobals[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  container = document.createElement('div') as unknown as HTMLElement;
+  document.body.appendChild(container as never);
+  requests = [];
+  calls = 0;
+  installFetch();
+  configureUiKit(SERVICES);
+});
+
+afterEach(() => {
+  render(null, container);
+  container.remove();
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (key in nativeGlobals) target[key] = nativeGlobals[key];
+    else delete target[key];
+  }
+});
+
+/** Render the hook and expose what it holds, so a test can read the DOM. */
+function Probe({ url, enabled = true }: { url: string | null; enabled?: boolean }) {
+  const { data, isLoading, error } = useKabmoFetch<{ value: number }>(url, { enabled, pollMs: 0 });
+  return h(
+    'div',
+    { id: 'probe' },
+    `${data === null ? 'null' : data.value}|${isLoading ? 'loading' : 'idle'}|${error ?? 'ok'}`,
+  );
+}
+
+const read = () => (container.querySelector('#probe') as HTMLElement | null)?.textContent ?? '';
+
+async function settle(): Promise<void> {
+  for (let i = 0; i < 8; i += 1) await act(async () => {});
+}
+
+describe('useKabmoFetch', () => {
+  test('a late answer from a superseded request never lands', async () => {
+    await act(async () => render(h(Probe, { url: '/api/a' }), container));
+    await settle();
+    expect(requests).toHaveLength(1);
+
+    // The caller moves on while the first request is still in flight.
+    await act(async () => render(h(Probe, { url: '/api/b' }), container));
+    await settle();
+    expect(requests).toHaveLength(2);
+    expect(read()).toBe('null|loading|ok');
+
+    // The SECOND settles first, then the first arrives late.
+    await act(async () => requests[1].resolve({ value: 2 }));
+    await settle();
+    expect(read()).toStartWith('2|');
+
+    await act(async () => requests[0].resolve({ value: 1 }));
+    await settle();
+    // Still B, not A: the stale answer was dropped rather than written.
+    expect(read()).toStartWith('2|');
+  });
+
+  test('a new URL drops the previous payload rather than showing it under the new name', async () => {
+    await act(async () => render(h(Probe, { url: '/api/a' }), container));
+    await settle();
+    await act(async () => requests[0].resolve({ value: 1 }));
+    await settle();
+    expect(read()).toStartWith('1|');
+
+    await act(async () => render(h(Probe, { url: '/api/b' }), container));
+    // Not "1|loading" — the old list must not render under the new session.
+    expect(read()).toBe('null|loading|ok');
+  });
+
+  test('a disabled or absent URL makes no request at all', async () => {
+    await act(async () => render(h(Probe, { url: '/api/a', enabled: false }), container));
+    await settle();
+    expect(calls).toBe(0);
+
+    await act(async () => render(h(Probe, { url: null }), container));
+    await settle();
+    expect(calls).toBe(0);
+  });
+
+  test('a failed read keeps the reason and the previous payload', async () => {
+    await act(async () => render(h(Probe, { url: '/api/a' }), container));
+    await settle();
+    await act(async () => requests[0].resolve({ value: 7 }));
+    await settle();
+
+    await act(async () => render(h(Probe, { url: '/api/b' }), container));
+    await settle();
+    await act(async () => requests[1].resolve({ error: 'nope' }, 500));
+    await settle();
+    expect(read()).toBe('null|idle|nope');
+  });
+});

package/src/fetch.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Fetching Kabmo's HTTP API from a plugin panel.
+ *
+ * A plugin cannot import Kabmo's hooks, so this is the one place it
+ * reaches the server: `GET /api/...` with the session's cookie, plus the three
+ * behaviours every built-in panel hand-rolled and a plugin would get wrong —
+ *
+ * - **Polling that pauses while hidden.** A background tab cannot render the
+ *   result, so each tick would be wasted work (and on mobile it keeps waking the
+ *   CPU). A visibilitychange back to visible re-reads at once, so the panel is
+ *   never stale when the user returns.
+ * - **A guard against overlapping reads.** A panel's fetcher aborts its previous
+ *   request whenever a new one starts, so an unguarded tick would cancel every
+ *   slow read before it could finish and the panel would sit on "loading"
+ *   forever.
+ * - **Event-driven re-reads.** Name the window events your panel should follow
+ *   and the hook re-reads on each, coalescing a burst through a throttle.
+ *
+ * The Kabmo's own views do NOT use this — they read the unified realtime
+ * socket (`useRealtimeTopic`), which is not part of the kit's surface. This
+ * stays for a plugin that reaches an HTTP endpoint directly.
+ *
+ * A response for a request the user has already moved past is DROPPED: the
+ * hook keeps a sequence number, and a late answer never overwrites a newer one.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+
+/** How often a visible panel re-reads by default. */
+export const DEFAULT_POLL_MS = 5_000;
+
+export interface KabmoFetchOptions {
+  /** False while the view is hidden: no poll, no event listener. */
+  enabled?: boolean;
+  /** Poll cadence in ms. `0` disables polling and keeps the event path. */
+  pollMs?: number;
+  /** Window events that re-read, throttled by `eventThrottleMs`. */
+  events?: readonly string[];
+  /** Coalescing window for the event path. */
+  eventThrottleMs?: number;
+  /** Skip the fetch entirely (a request that cannot be built yet). */
+  skip?: boolean;
+}
+
+export interface KabmoFetchState<T> {
+  data: T | null;
+  isLoading: boolean;
+  /** Set when the last read failed; the previous payload is kept meanwhile. */
+  error: string | null;
+  /** Re-read now, ignoring the poll cadence. */
+  reload: () => void;
+}
+
+/**
+ * Read a Kabmo API path, re-reading on a poll and on the given events.
+ *
+ * `url` is a FULL path rather than a builder, because a caller that changes the
+ * query — a session switch, a picked plan — must also change the request, and
+ * rebuilding the URL is how the hook knows to drop the old answer and read
+ * again.
+ */
+export function useKabmoFetch<T>(url: string | null, options: KabmoFetchOptions = {}): KabmoFetchState<T> {
+  const { enabled = true, pollMs = DEFAULT_POLL_MS, events, eventThrottleMs = 400, skip = false } = options;
+
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Latest url for the fetcher, so a caller that rebuilds it every render does
+  // not tear down the poll interval each time.
+  const urlRef = useRef(url);
+  urlRef.current = url;
+  // Guards against a response for a request the user has already left being
+  // written into the panel that now shows another.
+  const requestRef = useRef(0);
+  const active = enabled && !skip && url !== null;
+
+  const load = useCallback(() => {
+    const target = urlRef.current;
+    if (!target) return;
+    const seq = ++requestRef.current;
+    setIsLoading(true);
+    fetch(target, { credentials: 'same-origin' })
+      .then(async (response) => {
+        if (seq !== requestRef.current) return;
+        if (!response.ok) {
+          const body = (await response.json().catch(() => null)) as { error?: string } | null;
+          throw new Error(body?.error ?? `Request failed (${response.status})`);
+        }
+        const payload = (await response.json()) as T;
+        if (seq !== requestRef.current) return;
+        setData(payload);
+        setError(null);
+      })
+      .catch((cause: unknown) => {
+        if (seq !== requestRef.current) return;
+        setError(cause instanceof Error ? cause.message : String(cause));
+      })
+      .finally(() => {
+        if (seq !== requestRef.current) return;
+        setIsLoading(false);
+      });
+  }, []);
+
+  // A new URL is a new question: drop the old payload so the previous session's
+  // answer cannot render under the new title, then read.
+  useEffect(() => {
+    setData(null);
+    setError(null);
+    if (active) load();
+  }, [url, active, load]);
+
+  useEffect(() => {
+    if (!active || pollMs <= 0) return;
+    let visible = typeof document === 'undefined' || document.visibilityState === 'visible';
+    let inFlight = false;
+    const id = setInterval(() => {
+      if (visible && !inFlight) {
+        inFlight = true;
+        Promise.resolve(load()).finally(() => {
+          inFlight = false;
+        });
+      }
+    }, pollMs);
+    const onVisibility = () => {
+      const next = document.visibilityState === 'visible';
+      if (next && !visible) load();
+      visible = next;
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+    return () => {
+      clearInterval(id);
+      document.removeEventListener('visibilitychange', onVisibility);
+    };
+  }, [active, pollMs, load]);
+
+  const throttleRef = useRef<number | undefined>(undefined);
+  useEffect(() => {
+    if (!active || !events || events.length === 0) return;
+    const schedule = () => {
+      window.clearTimeout(throttleRef.current);
+      throttleRef.current = window.setTimeout(load, eventThrottleMs);
+    };
+    for (const name of events) window.addEventListener(name, schedule);
+    return () => {
+      for (const name of events) window.removeEventListener(name, schedule);
+      window.clearTimeout(throttleRef.current);
+    };
+  }, [active, events, eventThrottleMs, load]);
+
+  useEffect(() => () => window.clearTimeout(throttleRef.current), []);
+
+  return { data, isLoading, error, reload: load };
+}
+
+/**
+ * @deprecated Use `useKabmoFetch`.
+ *
+ * A published package's export is what a plugin bundle was built against, so the
+ * old names stay as aliases of the SAME implementation rather than a copy.
+ */
+export const useChamberFetch = useKabmoFetch;
+
+/** @deprecated Use `KabmoFetchOptions`. */
+export type ChamberFetchOptions = KabmoFetchOptions;
+
+/** @deprecated Use `KabmoFetchState`. */
+export type ChamberFetchState<T> = KabmoFetchState<T>;

package/src/index.tsx

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The UI kit a plugin renders with, and the host services it reads through.
+ *
+ * Everything here runs IN THE HOST'S TREE — same Preact instance, same
+ * document, same theme — so the kit is plain Preact components, not a
+ * message-passing client. What it still must not do is reach into the host's
+ * own source: this is a published package, so the host INJECTS its services
+ * once at boot via `configureUiKit`, and the hooks read them.
+ *
+ * Two rules the hooks exist to enforce, because a plugin gets them wrong:
+ *
+ * - **Context arrives late.** The active session and workspace are resolved
+ *   asynchronously, so a component that captured them once would show "none"
+ *   over a real workspace. Every hook subscribes and re-renders.
+ * - **Session state is not component state.** The component is unmounted when
+ *   its panel is hidden, so a value kept in `useState` alone would be lost on
+ *   every tab switch. `useSessionValue` reads Kabmo's store.
+ *
+ * The surface is split across modules by what it is FOR, so a consumer imports
+ * the piece it needs rather than one growing file:
+ *
+ * | Module | What it holds |
+ * |---|---|
+ * | `./services` | The injected services and the prop contracts |
+ * | `./panels` | `usePanelInfo`, `usePanelHost`, `useSessionValue`, `useWorkspaceFile` |
+ * | `./fetch` | `useKabmoFetch` — a plugin's own read of Kabmo's HTTP API (poll + events) |
+ * | `./participant` | `useRpc`, `useRealtime`, `useComposer` — what lets a plugin ACT on the conversation |
+ * | `./components` | The presentation kit (`Panel`, `Field`, `Button`, …) |
+ */
+
+export type {
+  PanelContext,
+  PanelHostProps,
+  HostMarkdownProps,
+  UiKitServices,
+  PluginRpcError,
+  PluginRpcOutcome,
+  ComposerState,
+  ComposerService,
+  RepoScope,
+  RepoScopeRow,
+} from './services';
+export { configureUiKit, uiKitServices, requireServices } from './services';
+
+export {
+  usePanelInfo,
+  useTheme,
+  useSessionValue,
+  useSessionState,
+  useWorkspaceFile,
+  type SessionValue,
+  type WorkspaceFile,
+} from './panels';
+
+export { useRepoScope, type RepoScopeHandle } from './repo';
+export { RepoPicker, type RepoPickerProps } from './repo-picker';
+
+export { PanelHostProvider, usePanelHost } from './panel-host';
+export { PluginIdProvider, usePluginId } from './plugin-id';
+
+export {
+  useKabmoFetch,
+  useChamberFetch,
+  DEFAULT_POLL_MS,
+  type KabmoFetchOptions,
+  type KabmoFetchState,
+  type ChamberFetchOptions,
+  type ChamberFetchState,
+} from './fetch';
+
+export {
+  useRpc,
+  useRealtime,
+  useComposer,
+  type RpcState,
+  type PluginRealtimeState,
+  type ComposerHandle,
+} from './participant';
+
+export { experimental_useSidebarThreads, experimental_useSidebarThreadActions } from './sidebar';
+
+export * from './components';

package/src/panel-host.tsx

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The panel body's props, scoped to the panel that is being rendered.
+ *
+ * A Preact context rather than a service singleton, and that is the whole point:
+ * the desktop stack keeps EVERY built-in view mounted at once (hidden with CSS,
+ * so a tree's expansion and a terminal's buffer survive a switch), so "the
+ * current panel's props" is not a process-wide fact — there are eleven of them
+ * live at the same time. A module-level value would hand a wiki panel the
+ * terminal's `rootPath` and its `onClose`.
+ *
+ * The provider is rendered by whichever layout draws the panel, so a component
+ * nested deep inside a plugin's own tree reads the SAME props its top-level
+ * component was handed rather than a second derivation of them.
+ */
+
+import { createContext } from 'preact';
+import { useContext } from 'preact/hooks';
+import type { ComponentChildren } from 'preact';
+import type { PanelHostProps } from './services';
+
+const PanelHostContext = createContext<PanelHostProps | null>(null);
+
+/** Render a panel's body inside its own props scope. */
+export function PanelHostProvider({ value, children }: { value: PanelHostProps; children: ComponentChildren }) {
+  return <PanelHostContext.Provider value={value}>{children}</PanelHostContext.Provider>;
+}
+
+/**
+ * The props of the panel this component is rendered in.
+ *
+ * Falls back to a permissive default when there is no provider — a component
+ * rendered outside a panel body (the settings pane, a test) is not "disabled",
+ * it simply has no layout to describe.
+ */
+export function usePanelHost(): PanelHostProps {
+  return (
+    useContext(PanelHostContext) ?? {
+      sessionId: null,
+      enabled: true,
+      active: true,
+      refreshKey: 0,
+    }
+  );
+}