@xemahq/ui-kernel 0.1.4

package/src/registry/lib/session-selectors.ts

@@ -0,0 +1,231 @@
+/**
+ * Typed selector hooks the host session shell calls to read biome
+ * contributions for the current session. Each selector:
+ *
+ *   1. Walks `biomeRegistry.list()` once.
+ *   2. Filters by the contribution's `appliesTo` predicate against the
+ *      current `SessionContext`.
+ *   3. Sorts deterministically (`weight`/`order`, then `id`).
+ *   4. Re-runs whenever the registry revision changes (biome add /
+ *      remove) or the session context changes.
+ *
+ * Selectors return frozen arrays — consumers should not mutate them.
+ *
+ * Naming: each selector is named after the contribution surface
+ * (`useSessionSlashCommands`, `useSessionDrawerTabs`, …) so the call
+ * site reads as "give me all session X for this context".
+ */
+import { useMemo } from 'react';
+
+import {
+  type ActivityRendererContribution,
+  type AttachmentClassContribution,
+  type HeaderChipContribution,
+  type MutationBarContribution,
+  type SecondaryDrawerTabContribution,
+  type SessionActivityEvent,
+  type SessionContext,
+  type SessionToolCallEvent,
+  type SlashCommandContribution,
+  type ToolCallRendererContribution,
+  biomeRegistry,
+  useBiomeRegistryRevision,
+} from '../../index';
+
+function sortByWeight<
+  T extends { readonly id: string; readonly weight?: number; readonly order?: number },
+>(items: readonly T[]): readonly T[] {
+  return [...items].sort((a, b) => {
+    const aw = a.weight ?? a.order ?? 100;
+    const bw = b.weight ?? b.order ?? 100;
+    if (aw !== bw) return aw - bw;
+    return a.id.localeCompare(b.id);
+  });
+}
+
+type PredicateOf<T> = T extends { readonly appliesTo?: (...args: infer A) => boolean }
+  ? (...args: A) => boolean
+  : never;
+
+function applies<T extends { readonly appliesTo?: (...args: never[]) => boolean }>(
+  item: T,
+  args: Parameters<PredicateOf<T>>,
+): boolean {
+  const predicate = item.appliesTo as PredicateOf<T> | undefined;
+  return predicate == null ? true : predicate(...args);
+}
+
+// ── Slash commands ────────────────────────────────────────────────────
+
+export function useSessionSlashCommands(
+  session: SessionContext,
+): readonly SlashCommandContribution[] {
+  const revision = useBiomeRegistryRevision();
+  return useMemo(() => {
+    const out: SlashCommandContribution[] = [];
+    for (const biome of biomeRegistry.list()) {
+      for (const cmd of biome.session?.slashCommands ?? []) {
+        if (!applies(cmd, [session])) continue;
+        out.push(cmd);
+      }
+    }
+    return Object.freeze(sortByWeight(out));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revision, session]);
+}
+
+// ── Secondary drawer tabs ─────────────────────────────────────────────
+
+export function useSessionDrawerTabs(
+  session: SessionContext,
+): readonly SecondaryDrawerTabContribution[] {
+  const revision = useBiomeRegistryRevision();
+  return useMemo(() => {
+    const out: SecondaryDrawerTabContribution[] = [];
+    for (const biome of biomeRegistry.list()) {
+      for (const tab of biome.session?.secondaryDrawerTabs ?? []) {
+        if (!applies(tab, [session])) continue;
+        out.push(tab);
+      }
+    }
+    return Object.freeze(sortByWeight(out));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revision, session]);
+}
+
+// ── Activity renderers ────────────────────────────────────────────────
+
+/**
+ * Hook returning the **first** activity renderer whose `entryKind`
+ * matches the event AND whose `appliesTo` predicate passes. Returns
+ * `null` if no biome handles this entry kind — the host then falls
+ * back to its generic renderer.
+ *
+ * Ties broken by `id` so biome authors can predict which renderer
+ * wins. To force a specific biome to win, use a lexicographically
+ * smaller id (e.g. `'00-debug/…'`).
+ */
+export function useActivityRenderer(
+  session: SessionContext,
+  event: SessionActivityEvent,
+): ActivityRendererContribution | null {
+  const revision = useBiomeRegistryRevision();
+  return useMemo(() => {
+    const candidates: ActivityRendererContribution[] = [];
+    for (const biome of biomeRegistry.list()) {
+      for (const r of biome.session?.activityRenderers ?? []) {
+        if (r.entryKind !== event.kind) continue;
+        if (!applies(r, [{ session, event }])) continue;
+        candidates.push(r);
+      }
+    }
+    if (candidates.length === 0) return null;
+    return sortByWeight(candidates)[0] ?? null;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revision, session, event]);
+}
+
+// ── Tool-call renderers ───────────────────────────────────────────────
+
+type ToolMatch = 'exact' | 'glob' | 'none';
+
+function matchToolName(toolName: string, eventName: string): ToolMatch {
+  if (toolName === eventName) return 'exact';
+  if (toolName.endsWith('.*') && eventName.startsWith(toolName.slice(0, -1))) return 'glob';
+  return 'none';
+}
+
+function collectToolCallCandidates(
+  session: SessionContext,
+  event: SessionToolCallEvent,
+): { exact: ToolCallRendererContribution[]; glob: ToolCallRendererContribution[] } {
+  const exact: ToolCallRendererContribution[] = [];
+  const glob: ToolCallRendererContribution[] = [];
+  for (const biome of biomeRegistry.list()) {
+    for (const r of biome.session?.toolCallRenderers ?? []) {
+      const match = matchToolName(r.toolName, event.name);
+      if (match === 'none') continue;
+      if (!applies(r, [{ session, event }])) continue;
+      if (match === 'exact') exact.push(r);
+      else glob.push(r);
+    }
+  }
+  return { exact, glob };
+}
+
+/**
+ * Tool-call renderer resolution. Exact `toolName` matches outrank glob
+ * (`'<prefix>.*'`) matches; ties broken by `weight`, then `id`. Returns
+ * `null` if no biome handles this tool — host falls back to its
+ * generic key-value renderer.
+ */
+export function useToolCallRenderer(
+  session: SessionContext,
+  event: SessionToolCallEvent,
+): ToolCallRendererContribution | null {
+  const revision = useBiomeRegistryRevision();
+  return useMemo(() => {
+    const { exact, glob } = collectToolCallCandidates(session, event);
+    if (exact.length > 0) return sortByWeight(exact)[0] ?? null;
+    if (glob.length > 0) return sortByWeight(glob)[0] ?? null;
+    return null;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revision, session, event]);
+}
+
+// ── Mutation bars ─────────────────────────────────────────────────────
+
+export function useSessionMutationBars(
+  session: SessionContext,
+): readonly MutationBarContribution[] {
+  const revision = useBiomeRegistryRevision();
+  return useMemo(() => {
+    const out: MutationBarContribution[] = [];
+    for (const biome of biomeRegistry.list()) {
+      for (const bar of biome.session?.mutationBars ?? []) {
+        if (!applies(bar, [session])) continue;
+        out.push(bar);
+      }
+    }
+    return Object.freeze(sortByWeight(out));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revision, session]);
+}
+
+// ── Header chips ──────────────────────────────────────────────────────
+
+export function useSessionHeaderChips(
+  session: SessionContext,
+): readonly HeaderChipContribution[] {
+  const revision = useBiomeRegistryRevision();
+  return useMemo(() => {
+    const out: HeaderChipContribution[] = [];
+    for (const biome of biomeRegistry.list()) {
+      for (const chip of biome.session?.headerChips ?? []) {
+        if (!applies(chip, [session])) continue;
+        out.push(chip);
+      }
+    }
+    return Object.freeze(sortByWeight(out));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revision, session]);
+}
+
+// ── Attachment classes ────────────────────────────────────────────────
+
+export function useSessionAttachmentClasses(
+  session: SessionContext,
+): readonly AttachmentClassContribution[] {
+  const revision = useBiomeRegistryRevision();
+  return useMemo(() => {
+    const out: AttachmentClassContribution[] = [];
+    for (const biome of biomeRegistry.list()) {
+      for (const cls of biome.session?.attachmentClasses ?? []) {
+        if (!applies(cls, [session])) continue;
+        out.push(cls);
+      }
+    }
+    return Object.freeze(sortByWeight(out));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revision, session]);
+}

package/src/session/comments/CommentRail.tsx

@@ -0,0 +1,164 @@
+import type { ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+/**
+ * Generic, data-layer-agnostic comment shape. Host surfaces map their
+ * own DTOs (KB `DocumentCommentResponseDto`, workflow `InquiryReply`,
+ * …) into this before handing the array to `CommentRail`.
+ */
+export interface RailComment {
+  readonly id: string;
+  readonly body: string;
+  /** Anchored quote text shown above the body. Omit for whole-doc comments. */
+  readonly quotedText?: string;
+  /** `true` once the comment is resolved/closed. */
+  readonly resolved: boolean;
+  /** Optional author label (name / "Agent" / …). */
+  readonly authorLabel?: string;
+}
+
+/**
+ * Headless anchored-comment rail shared by every interactive-session
+ * surface (Document Buddy today; workflow review once `ReviewRail`
+ * migrates). It owns ONLY layout + rendering — no data fetching, no
+ * mutations. The host passes:
+ *
+ *   • `comments`      — already-mapped `RailComment[]`
+ *   • `onResolve`     — resolve callback (host owns the mutation)
+ *   • `composerSlot`  — the host's composer node (host owns its state)
+ *   • `headerSlot`    — optional extra header content
+ *
+ * Keeping it headless is what lets the same component render both KB
+ * document comments and workflow review threads without either data
+ * stack leaking into the package layer.
+ */
+export function CommentRail({
+  comments,
+  title = 'Comments',
+  emptyHint,
+  composerSlot,
+  headerSlot,
+  onResolve,
+  resolvingId,
+  renderResolveIcon,
+  renderResolvedIcon,
+}: {
+  readonly comments: readonly RailComment[];
+  readonly title?: string;
+  readonly emptyHint?: ReactNode;
+  readonly composerSlot?: ReactNode;
+  readonly headerSlot?: ReactNode;
+  readonly onResolve?: (id: string) => void;
+  readonly resolvingId?: string | null;
+  /** Host supplies the icon set so the package carries no icon dep. */
+  readonly renderResolveIcon?: (busy: boolean) => ReactNode;
+  readonly renderResolvedIcon?: () => ReactNode;
+}) {
+  const open = comments.filter((c) => !c.resolved);
+  const resolved = comments.filter((c) => c.resolved);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-2 bg-paper p-3 text-[12px]">
+      <div className="flex items-center gap-2">
+        <span className="font-medium text-ink">{title}</span>
+        {open.length > 0 && (
+          <span className="rounded-full bg-ink/10 px-2 py-0.5 text-[11px] text-ink-2">
+            {open.length}
+          </span>
+        )}
+        {headerSlot}
+      </div>
+
+      {composerSlot}
+
+      {comments.length === 0 && !composerSlot && emptyHint && (
+        <div className="text-ink-3">{emptyHint}</div>
+      )}
+
+      <div className="flex min-h-0 flex-1 flex-col gap-2 overflow-auto pr-1">
+        {open.map((comment) => (
+          <CommentRow
+            key={comment.id}
+            comment={comment}
+            onResolve={onResolve}
+            busy={resolvingId === comment.id}
+            renderResolveIcon={renderResolveIcon}
+            renderResolvedIcon={renderResolvedIcon}
+          />
+        ))}
+        {resolved.length > 0 && (
+          <div className="mt-1 text-[11px] uppercase tracking-wide text-ink-3">
+            Resolved
+          </div>
+        )}
+        {resolved.map((comment) => (
+          <CommentRow
+            key={comment.id}
+            comment={comment}
+            onResolve={onResolve}
+            busy={resolvingId === comment.id}
+            renderResolveIcon={renderResolveIcon}
+            renderResolvedIcon={renderResolvedIcon}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function CommentRow({
+  comment,
+  onResolve,
+  busy,
+  renderResolveIcon,
+  renderResolvedIcon,
+}: {
+  readonly comment: RailComment;
+  readonly onResolve?: ((id: string) => void) | undefined;
+  readonly busy: boolean;
+  readonly renderResolveIcon?: ((busy: boolean) => ReactNode) | undefined;
+  readonly renderResolvedIcon?: (() => ReactNode) | undefined;
+}) {
+  return (
+    <div
+      className={cn(
+        'rounded-md border p-2',
+        comment.resolved
+          ? 'border-rule/60 bg-paper-elev/30 opacity-70'
+          : 'border-rule/70 bg-paper-elev/40',
+      )}
+    >
+      {comment.quotedText && (
+        <div className="mb-1 border-l-2 border-[hsl(var(--comment-anchor))] pl-2 text-[11px] italic text-ink-3">
+          “{comment.quotedText.slice(0, 120)}
+          {comment.quotedText.length > 120 ? '…' : ''}”
+        </div>
+      )}
+      <div className="flex items-start justify-between gap-2">
+        <div className="flex flex-col gap-0.5">
+          {comment.authorLabel && (
+            <span className="text-[11px] font-medium text-ink-2">
+              {comment.authorLabel}
+            </span>
+          )}
+          <span className="whitespace-pre-wrap text-ink">{comment.body}</span>
+        </div>
+        {!comment.resolved && onResolve && (
+          <button
+            type="button"
+            title="Resolve"
+            disabled={busy}
+            onClick={() => onResolve(comment.id)}
+            className="flex h-6 w-6 shrink-0 items-center justify-center rounded text-ink-3 hover:bg-ink/5 hover:text-ink disabled:opacity-50"
+          >
+            {renderResolveIcon ? renderResolveIcon(busy) : busy ? '…' : '✓'}
+          </button>
+        )}
+        {comment.resolved && renderResolvedIcon && (
+          <span className="shrink-0 text-ink-3">{renderResolvedIcon()}</span>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/session/index.ts

@@ -0,0 +1,3 @@
+export { cn } from './lib/cn';
+export { SessionWorkspaceShell } from './shell/SessionWorkspaceShell';
+export { CommentRail, type RailComment } from './comments/CommentRail';

package/src/session/lib/cn.ts

@@ -0,0 +1,11 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Tailwind-aware class merge. Local copy so this package stays
+ * self-contained (no `@/lib/utils` host import) — the host shell has
+ * its own identical `cn`, and the duplication is one trivial line.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/session/shell/SessionWorkspaceShell.tsx

@@ -0,0 +1,141 @@
+import type { ReactNode, MouseEvent, RefObject } from 'react';
+
+import { cn } from '../lib/cn';
+
+interface SessionWorkspaceShellProps {
+  /**
+   * Container ref from `useHorizontalSplit`. The shell forwards mouse
+   * coordinates to the hook through this ref.
+   */
+  readonly splitContainerRef: RefObject<HTMLDivElement>;
+  /** Width of the left (chat) pane as a percentage 0-100. */
+  readonly chatPanePercent: number;
+  /** True while the resize handle is being dragged — applies cursor styling. */
+  readonly isResizing: boolean;
+  /** Mouse-down handler for the resize handle. */
+  readonly startResize: (event: MouseEvent<HTMLElement>) => void;
+
+  /** Mount for the Chat surface in the left pane. */
+  readonly chatSlot: ReactNode;
+  /**
+   * Mount for the right (preview) pane. Pass `null` for sessions that
+   * have no preview surface — the shell hides the right pane entirely
+   * (and the resize handle along with it) so chat takes the full
+   * width. Used by Document Buddy sessions, whose mechanic is a
+   * file-backed sync loop, not a previewed project.
+   */
+  readonly previewSlot: ReactNode;
+
+  /**
+   * Optional header strip at the top of the RIGHT pane. Used for
+   * preview-pane toolbars (KB references, attachments, actions menu).
+   */
+  readonly rightHeaderSlot?: ReactNode;
+
+  /**
+   * Optional content rendered *below* the chat surface, inside the left
+   * pane. Used for things like Brainstorming's `PendingCommentsBar`.
+   */
+  readonly chatFooterSlot?: ReactNode;
+
+  /**
+   * When true, the left pane and resize handle are hidden — the preview
+   * occupies the full width. Pages own this state.
+   */
+  readonly previewFullscreen?: boolean;
+
+  /** Optional override for the minimum left pane width (default 320px). */
+  readonly minLeftPaneWidth?: number;
+}
+
+/**
+ * Two-pane workspace layout shared by interactive session-like pages
+ * (sessions, design-system-builds, document buddy, …). The left pane renders
+ * the chat surface; the right pane always renders the preview slot.
+ *
+ * Auxiliary surfaces (Activity, Files, …) are no longer panes — they are
+ * surfaced through the floating `InspectorDock` and the right-pane
+ * overflow menu, so the shell stays a clean chat ⇄ preview split.
+ *
+ * Lives in `@xemahq/ui-kernel/session` so every session-like
+ * surface composes the identical layout. Biome extensibility lands
+ * inside the slot content (chat, preview) via the host's
+ * `HostExtensionSlots` SDK plumbing — the shell itself stays free of
+ * biome coupling.
+ */
+export function SessionWorkspaceShell({
+  splitContainerRef,
+  chatPanePercent,
+  isResizing,
+  startResize,
+  chatSlot,
+  previewSlot,
+  rightHeaderSlot,
+  chatFooterSlot,
+  previewFullscreen = false,
+  minLeftPaneWidth = 320,
+}: SessionWorkspaceShellProps) {
+  // `previewSlot === null` means the session declared no preview
+  // surface (Document Buddy). Hide the right pane + resize handle and
+  // let the chat pane occupy the full width.
+  const hasPreviewSlot = previewSlot !== null;
+  return (
+    <div
+      ref={splitContainerRef}
+      className={cn(
+        'relative flex h-full w-full overflow-hidden',
+        isResizing && 'cursor-col-resize',
+      )}
+    >
+      {!previewFullscreen && (
+        <div
+          className={cn(
+            'flex h-full w-full flex-col overflow-hidden bg-paper',
+            hasPreviewSlot ? 'lg:flex-none' : '',
+          )}
+          style={
+            hasPreviewSlot
+              ? {
+                  minWidth: `${minLeftPaneWidth}px`,
+                  width: `${chatPanePercent}%`,
+                }
+              : undefined
+          }
+        >
+          <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+            <div className="relative min-h-0 flex-1">{chatSlot}</div>
+            {chatFooterSlot}
+          </div>
+        </div>
+      )}
+
+      {!previewFullscreen && hasPreviewSlot && (
+        <div className="relative hidden w-px shrink-0 bg-rule/30 lg:block">
+          {/* Invisible 8px hot-environment for easier grabbing; visible divider
+              stays a single hair-line. On hover we tint only a 1px
+              accent column so the cursor change is the primary signal,
+              not a fat coloured strip. */}
+          <button
+            type="button"
+            onMouseDown={startResize}
+            aria-label="Resize chat and preview panels"
+            title="Drag to resize"
+            className="group absolute inset-y-0 left-1/2 w-2 -translate-x-1/2 cursor-col-resize"
+          >
+            <span
+              aria-hidden
+              className="absolute inset-y-0 left-1/2 w-px -translate-x-1/2 bg-transparent transition-colors group-hover:bg-primary/40"
+            />
+          </button>
+        </div>
+      )}
+
+      {hasPreviewSlot && (
+        <div className="flex min-w-0 flex-1 flex-col overflow-hidden bg-paper">
+          {rightHeaderSlot}
+          <div className="min-h-0 flex-1 overflow-hidden">{previewSlot}</div>
+        </div>
+      )}
+    </div>
+  );
+}