@xemahq/ui-kernel 0.1.4

package/src/registry/lib/primitives/SessionEventCard.tsx

@@ -0,0 +1,138 @@
+/**
+ * Generic event-row primitive a biome can use as the rendered form of
+ * a `SessionActivityEvent` it owns. Matches the host's built-in
+ * console row visually (time gutter + icon chip + title + detail) so
+ * biome-rendered events sit inside the host timeline without looking
+ * grafted on.
+ *
+ * Biomes compose this when they register an `ActivityRendererContribution`:
+ *
+ *   render: ({ event }) => (
+ *     <SessionEventCard
+ *       time={event.createdAt}
+ *       icon={<JiraIcon />}
+ *       title={event.title}
+ *       detail={event.detail}
+ *       tone={event.status === 'error' ? 'error' : 'default'}
+ *     />
+ *   )
+ *
+ * Inline-styled with CSS-variable tokens for the same portability
+ * reasons as `SessionMutationBar`.
+ */
+import { type CSSProperties, type ReactNode, type ReactElement } from 'react';
+
+export type SessionEventCardTone = 'default' | 'pending' | 'success' | 'error' | 'info';
+
+const TONE_DOT: Record<SessionEventCardTone, string> = {
+  default: 'hsl(var(--ink-4, 228 6% 58%))',
+  pending: 'hsl(var(--info, 220 70% 50%))',
+  success: 'hsl(var(--success, 152 50% 35%))',
+  error: 'hsl(var(--destructive, 8 70% 50%))',
+  info: 'hsl(var(--info, 220 70% 50%))',
+};
+
+const TONE_BG: Record<SessionEventCardTone, string> = {
+  default: 'hsl(var(--paper-elev, 0 0% 100%))',
+  pending: 'hsl(var(--info, 220 70% 50%) / 0.08)',
+  success: 'hsl(var(--success, 152 50% 35%) / 0.08)',
+  error: 'hsl(var(--destructive, 8 70% 50%) / 0.10)',
+  info: 'hsl(var(--info, 220 70% 50%) / 0.08)',
+};
+
+export interface SessionEventCardProps {
+  /** ISO timestamp; the primitive renders HH:MM:SS in the gutter. */
+  readonly time: string;
+  readonly icon?: ReactNode;
+  readonly title: ReactNode;
+  readonly detail?: ReactNode;
+  /** Optional inline body (collapsible content, code block, …). */
+  readonly children?: ReactNode;
+  readonly tone?: SessionEventCardTone;
+  readonly style?: CSSProperties;
+  readonly className?: string;
+}
+
+function formatTime(iso: string): string {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return '—';
+  return date.toLocaleTimeString([], {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+}
+
+export function SessionEventCard({
+  time,
+  icon,
+  title,
+  detail,
+  children,
+  tone = 'default',
+  style,
+  className,
+}: SessionEventCardProps): ReactElement {
+  return (
+    <div
+      className={className}
+      style={{
+        display: 'flex',
+        gap: 10,
+        padding: '4px 8px',
+        borderRadius: 6,
+        fontSize: 12,
+        ...style,
+      }}
+    >
+      <span
+        style={{
+          width: 56,
+          flexShrink: 0,
+          fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+          fontSize: 11,
+          color: 'hsl(var(--ink-4, 228 6% 58%))',
+          fontVariantNumeric: 'tabular-nums',
+        }}
+      >
+        {formatTime(time)}
+      </span>
+      <div
+        style={{
+          width: 20,
+          height: 20,
+          flexShrink: 0,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          borderRadius: 4,
+          background: TONE_BG[tone],
+        }}
+      >
+        {icon ?? (
+          <span
+            style={{
+              width: 6,
+              height: 6,
+              borderRadius: '50%',
+              background: TONE_DOT[tone],
+            }}
+          />
+        )}
+      </div>
+      <div style={{ minWidth: 0, flex: 1 }}>
+        <div style={{ display: 'flex', gap: 6, alignItems: 'baseline', flexWrap: 'wrap' }}>
+          <span style={{ color: 'hsl(var(--ink, 228 14% 11%))', wordBreak: 'break-word' }}>
+            {title}
+          </span>
+          {detail != null && (
+            <span style={{ color: 'hsl(var(--ink-3, 228 6% 40%))', wordBreak: 'break-word' }}>
+              {detail}
+            </span>
+          )}
+        </div>
+        {children != null && <div style={{ marginTop: 4 }}>{children}</div>}
+      </div>
+    </div>
+  );
+}

package/src/registry/lib/primitives/SessionEventTimeline.tsx

@@ -0,0 +1,89 @@
+/**
+ * Generic event timeline a biome can use to render a stream of its
+ * own events inside a custom surface — e.g. a "Deploys" panel that
+ * lists deploy attempts the same way the session console lists tool
+ * calls. Biomes keep ownership of the data model; this primitive
+ * supplies the scroll behaviour, auto-stick-to-bottom, and consistent
+ * spacing.
+ *
+ * The primitive does NOT subscribe to the biome registry or any SSE
+ * stream — callers pass in an items array. Auto-scroll-to-latest
+ * fires only when the user is already pinned to the bottom; if they
+ * scrolled up to read history we stay parked so live events don't
+ * yank context away.
+ */
+import {
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+
+export interface SessionEventTimelineProps<TItem> {
+  readonly items: readonly TItem[];
+  readonly getKey: (item: TItem) => string;
+  readonly renderItem: (item: TItem) => ReactNode;
+  /** Banner above the list (e.g. "stream recovering…"). */
+  readonly banner?: ReactNode;
+  /** Empty state when `items.length === 0`. */
+  readonly empty?: ReactNode;
+  /** Pixel threshold for "pinned to bottom" detection. Default 32. */
+  readonly stickThreshold?: number;
+  readonly style?: CSSProperties;
+  readonly className?: string;
+}
+
+export function SessionEventTimeline<TItem>({
+  items,
+  getKey,
+  renderItem,
+  banner,
+  empty,
+  stickThreshold = 32,
+  style,
+  className,
+}: SessionEventTimelineProps<TItem>): ReactElement {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [stuckToBottom, setStuckToBottom] = useState(true);
+
+  useEffect(() => {
+    const node = scrollRef.current;
+    if (!node) return;
+    const handler = () => {
+      const distanceFromBottom =
+        node.scrollHeight - node.scrollTop - node.clientHeight;
+      setStuckToBottom(distanceFromBottom < stickThreshold);
+    };
+    node.addEventListener('scroll', handler, { passive: true });
+    return () => node.removeEventListener('scroll', handler);
+  }, [stickThreshold]);
+
+  useLayoutEffect(() => {
+    if (!stuckToBottom) return;
+    const node = scrollRef.current;
+    if (!node) return;
+    node.scrollTop = node.scrollHeight;
+  }, [items, stuckToBottom]);
+
+  return (
+    <div
+      ref={scrollRef}
+      className={className}
+      style={{
+        height: '100%',
+        overflowY: 'auto',
+        padding: '8px 4px',
+        ...style,
+      }}
+    >
+      {banner}
+      {items.length === 0 && empty}
+      {items.map((item) => (
+        <div key={getKey(item)}>{renderItem(item)}</div>
+      ))}
+    </div>
+  );
+}

package/src/registry/lib/primitives/SessionMutationBar.tsx

@@ -0,0 +1,76 @@
+/**
+ * Generic sticky strip a biome can use as a session-level status row
+ * (linked Jira ticket, AWS deploy state, git branch, …). Wraps the
+ * biome's content in the host's editorial chrome — rule border,
+ * paper-elev background, consistent padding — so bars contributed by
+ * different biomes look like one product surface even when authored
+ * independently.
+ *
+ * The primitive is intentionally style-agnostic at the JS layer: it
+ * inlines CSS-variable references so it works against any host whose
+ * design system publishes `--paper-elev` / `--rule` / `--ink` on
+ * `:root`. Tailwind classes are NOT used because biomes must work
+ * across hosts whose CSS pipelines differ.
+ */
+import { type CSSProperties, type ReactNode, type ReactElement } from 'react';
+
+export type SessionMutationBarTone = 'default' | 'accent' | 'warning' | 'destructive';
+
+const TONE_STYLES: Record<SessionMutationBarTone, CSSProperties> = {
+  default: {
+    background: 'hsl(var(--paper-elev, 0 0% 100%))',
+    borderBottom: '1px solid hsl(var(--rule, 40 14% 86%))',
+  },
+  accent: {
+    background: 'hsl(var(--accent-tint, 230 50% 96%))',
+    borderBottom: '1px solid hsl(var(--rule, 40 14% 86%))',
+    color: 'hsl(var(--accent-ink, 230 50% 30%))',
+  },
+  warning: {
+    background: 'hsl(var(--warning, 32 80% 50%) / 0.10)',
+    borderBottom: '1px solid hsl(var(--warning, 32 80% 50%) / 0.30)',
+    color: 'hsl(var(--ink, 228 14% 11%))',
+  },
+  destructive: {
+    background: 'hsl(var(--destructive, 8 70% 50%) / 0.10)',
+    borderBottom: '1px solid hsl(var(--destructive, 8 70% 50%) / 0.30)',
+    color: 'hsl(var(--ink, 228 14% 11%))',
+  },
+};
+
+export interface SessionMutationBarProps {
+  readonly tone?: SessionMutationBarTone;
+  readonly children: ReactNode;
+  /**
+   * Extra inline styles merged on top of the tone styles. Use for one-off
+   * sizing tweaks; do not override `background` or `borderBottom` here
+   * because that defeats the visual-consistency point of the primitive.
+   */
+  readonly style?: CSSProperties;
+  /** Optional className passthrough for hosts that DO use Tailwind. */
+  readonly className?: string;
+}
+
+export function SessionMutationBar({
+  tone = 'default',
+  children,
+  style,
+  className,
+}: SessionMutationBarProps): ReactElement {
+  return (
+    <div
+      className={className}
+      style={{
+        ...TONE_STYLES[tone],
+        padding: '6px 12px',
+        fontSize: 13,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 8,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/registry/lib/primitives/SessionTabbedDrawer.tsx

@@ -0,0 +1,155 @@
+/**
+ * Generic tabbed drawer primitive a biome can use to build its own
+ * inspector surface — same shape as the host's session secondary
+ * drawer (tab strip across the top, switch-bodies below). Biome
+ * authors compose this when their biome owns a side surface that
+ * isn't part of the canonical session drawer.
+ *
+ * Headless on purpose: this primitive does NOT own a Dialog wrapper.
+ * Biomes decide whether to mount it inside their own dialog, a
+ * resizable panel, or inline — the only behaviour the primitive
+ * guarantees is "render exactly one tab body at a time, with a
+ * shared tab strip and keyboard navigation".
+ */
+import {
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+export interface SessionTabbedDrawerTab {
+  readonly id: string;
+  readonly label: ReactNode;
+  readonly icon?: ReactNode;
+  readonly badge?: ReactNode;
+  readonly render: () => ReactNode;
+}
+
+export interface SessionTabbedDrawerProps {
+  readonly tabs: readonly SessionTabbedDrawerTab[];
+  readonly initialTabId?: string;
+  readonly activeTabId?: string;
+  readonly onActiveTabChange?: (id: string) => void;
+  /**
+   * When true, ⌘1..⌘N / Ctrl+1..N selects the corresponding tab while
+   * the drawer is mounted. Defaults to true.
+   */
+  readonly enableKeyboardShortcuts?: boolean;
+  readonly style?: CSSProperties;
+  readonly className?: string;
+}
+
+export function SessionTabbedDrawer({
+  tabs,
+  initialTabId,
+  activeTabId,
+  onActiveTabChange,
+  enableKeyboardShortcuts = true,
+  style,
+  className,
+}: SessionTabbedDrawerProps): ReactElement {
+  const fallbackTabId = initialTabId ?? tabs[0]?.id ?? '';
+  const [internalActive, setInternalActive] = useState<string>(fallbackTabId);
+  const effectiveActive = activeTabId ?? internalActive;
+
+  const select = useMemo(() => {
+    return (id: string) => {
+      if (activeTabId === undefined) setInternalActive(id);
+      onActiveTabChange?.(id);
+    };
+  }, [activeTabId, onActiveTabChange]);
+
+  useEffect(() => {
+    if (!enableKeyboardShortcuts) return;
+    const handler = (event: KeyboardEvent) => {
+      if (!(event.metaKey || event.ctrlKey)) return;
+      const idx = Number.parseInt(event.key, 10);
+      if (Number.isNaN(idx) || idx < 1 || idx > tabs.length) return;
+      const target = tabs[idx - 1];
+      if (!target) return;
+      event.preventDefault();
+      select(target.id);
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [enableKeyboardShortcuts, tabs, select]);
+
+  const active = tabs.find((tab) => tab.id === effectiveActive) ?? tabs[0];
+
+  return (
+    <div
+      className={className}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        height: '100%',
+        minHeight: 0,
+        ...style,
+      }}
+    >
+      <div
+        role="tablist"
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 4,
+          padding: '8px 16px 0',
+          borderBottom: '1px solid hsl(var(--rule, 40 14% 86%))',
+          overflowX: 'auto',
+        }}
+      >
+        {tabs.map((tab, idx) => {
+          const isActive = tab.id === active?.id;
+          return (
+            <button
+              key={tab.id}
+              type="button"
+              role="tab"
+              aria-selected={isActive}
+              onClick={() => select(tab.id)}
+              title={`${typeof tab.label === 'string' ? tab.label : 'Tab'} (⌘${idx + 1})`}
+              style={{
+                position: 'relative',
+                display: 'inline-flex',
+                alignItems: 'center',
+                gap: 6,
+                padding: '8px 12px',
+                fontSize: 13,
+                background: 'transparent',
+                border: 'none',
+                cursor: 'pointer',
+                color: isActive
+                  ? 'hsl(var(--ink, 228 14% 11%))'
+                  : 'hsl(var(--ink-3, 228 6% 40%))',
+                whiteSpace: 'nowrap',
+              }}
+            >
+              {tab.icon}
+              {tab.label}
+              {tab.badge}
+              {isActive && (
+                <span
+                  aria-hidden
+                  style={{
+                    position: 'absolute',
+                    inset: '0 4px -1px',
+                    top: 'auto',
+                    height: 2,
+                    background: 'hsl(var(--primary, 230 50% 45%))',
+                    borderRadius: 1,
+                  }}
+                />
+              )}
+            </button>
+          );
+        })}
+      </div>
+      <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>
+        {active?.render()}
+      </div>
+    </div>
+  );
+}

package/src/registry/lib/primitives/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Reusable session-shell primitives exported from the SDK so biome
+ * authors can compose the same UI vocabulary the host shell uses —
+ * mutation bars, event cards, event timelines, tabbed drawers —
+ * without forking the host or rebuilding the editorial chrome from
+ * scratch.
+ *
+ * Every primitive in this directory:
+ *   - Is style-portable (inline styles + CSS-variable tokens; no
+ *     Tailwind dependency).
+ *   - Has zero registry subscriptions (biomes pass data in).
+ *   - Composes with the host's session shell as well as with a
+ *     biome's own bespoke surfaces.
+ */
+export * from './SessionEventCard';
+export * from './SessionEventTimeline';
+export * from './SessionMutationBar';
+export * from './SessionTabbedDrawer';

package/src/registry/lib/session-context-builder.ts

@@ -0,0 +1,68 @@
+/**
+ * Single helper hook the host's session shell calls once per render to
+ * build the `SessionContext` it passes into every contribution selector.
+ *
+ * Inputs are the loose, host-shaped session fields (any DTO with these
+ * keys); the helper resolves the profile descriptor through the biome
+ * registry, frozes a capabilities set, and returns a stable
+ * `SessionContext`. Memoised by the underlying selectors — callers can
+ * pass the result as a dep without worrying about identity churn.
+ *
+ * Keeping this helper in the SDK (rather than the host) is what lets
+ * biomes also build a context — e.g. from inside a slash command
+ * handler that wants to gate behaviour against capabilities.
+ */
+import { useMemo } from 'react';
+
+import {
+  type SessionContext,
+  useSessionProfileDescriptor,
+} from '../../index';
+
+export interface BuildSessionContextInput {
+  readonly sessionId: string;
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly biomeId?: string;
+  readonly profileKey?: string;
+  readonly status: string;
+  readonly isActive: boolean;
+}
+
+const TERMINAL_STATUSES = new Set([
+  'paused',
+  'completed',
+  'cancelled',
+  'failed',
+  'terminated',
+]);
+
+export function isStatusActive(status: string): boolean {
+  return !TERMINAL_STATUSES.has(status);
+}
+
+export function useSessionContext(input: BuildSessionContextInput): SessionContext {
+  const descriptor = useSessionProfileDescriptor(input.biomeId, input.profileKey);
+  return useMemo<SessionContext>(
+    () => ({
+      sessionId: input.sessionId,
+      orgId: input.orgId,
+      projectId: input.projectId,
+      biomeId: input.biomeId ?? descriptor.biomeId,
+      profileKey: input.profileKey ?? descriptor.key,
+      status: input.status,
+      capabilities: Object.freeze(new Set(descriptor.capabilities)),
+      isActive: input.isActive,
+    }),
+    [
+      input.sessionId,
+      input.orgId,
+      input.projectId,
+      input.biomeId,
+      input.profileKey,
+      input.status,
+      input.isActive,
+      descriptor,
+    ],
+  );
+}

package/src/registry/lib/session-context-provider.tsx

@@ -0,0 +1,50 @@
+/**
+ * React context that publishes the current `SessionContext` to every
+ * descendant. The host's session shell mounts the provider once around
+ * the entire session page; biome-rendered slot panels and host
+ * primitives both read the context via `useCurrentSessionContext()`
+ * (throws fail-fast if no provider is mounted, since reading the
+ * context outside a session view is a wiring bug).
+ *
+ * Keeping this in the SDK rather than the host gives biome authors a
+ * stable, importable hook — `import { useCurrentSessionContext } from
+ * '@xemahq/ui-kernel/registry'`.
+ */
+import { type ReactNode, type ReactElement, createContext, useContext } from 'react';
+
+import type { SessionContext } from '../../index';
+
+const Ctx = createContext<SessionContext | null>(null);
+Ctx.displayName = 'SessionContext';
+
+export interface SessionContextProviderProps {
+  readonly value: SessionContext;
+  readonly children: ReactNode;
+}
+
+export function SessionContextProvider({
+  value,
+  children,
+}: SessionContextProviderProps): ReactElement {
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useCurrentSessionContext(): SessionContext {
+  const ctx = useContext(Ctx);
+  if (!ctx) {
+    throw new Error(
+      '[biome-registry-web] useCurrentSessionContext() called outside <SessionContextProvider>. ' +
+        'The host shell must wrap session UI with the provider before any biome reads it.',
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Non-throwing variant for components that may render outside a session
+ * context (e.g. shared primitives reused on the design-system-builder page).
+ * Returns `null` instead of throwing.
+ */
+export function useOptionalSessionContext(): SessionContext | null {
+  return useContext(Ctx);
+}