@archznn/crewloop-skills 0.5.0 → 0.7.0

package/servers/dashboard/ui/src/components/views/Overview.tsx

@@ -0,0 +1,135 @@
+import { useMemo } from 'react';
+import type { ClientSession } from '../../../../src/types';
+import { ActiveSkillPanel } from '../ActiveSkillPanel';
+import { TelemetryPanel } from '../TelemetryPanel';
+import { ActivityGraph } from '../ActivityGraph';
+import { ViewHeader } from '../ViewHeader';
+import { usePinnedSessions } from '../../contexts/PinnedSessionsContext';
+import { sourceIcon } from '../../../../src/lib/constants';
+import { Icon } from '../ui/Icon';
+import { truncate } from '../../../../src/lib/format';
+
+interface Props {
+  sessions: Map<string, ClientSession>;
+  selectedSession: ClientSession | undefined;
+  onSelectSession: (id: string) => void;
+}
+
+export function Overview({ sessions, selectedSession, onSelectSession }: Props) {
+  const { pins } = usePinnedSessions();
+  const allSessions = useMemo(() => Array.from(sessions.values()), [sessions]);
+  const activeCount = useMemo(
+    () => allSessions.filter((s) => s.lifecycle === 'running').length,
+    [allSessions]
+  );
+
+  const topSkills = useMemo(() => {
+    const counts = new Map<string, number>();
+    for (const s of allSessions) {
+      const name = s.activeSkill?.name || s.skill;
+      if (name) counts.set(name, (counts.get(name) || 0) + 1);
+    }
+    return Array.from(counts.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+  }, [allSessions]);
+
+  const topTools = useMemo(() => {
+    const counts = new Map<string, number>();
+    for (const s of allSessions) {
+      for (const e of s.events) {
+        if (e.tool) counts.set(e.tool, (counts.get(e.tool) || 0) + 1);
+      }
+    }
+    return Array.from(counts.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+  }, [allSessions]);
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      <ViewHeader title="Overview" icon="House" />
+      <div className="flex-1 overflow-y-auto p-5">
+        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
+          <ActiveSkillPanel session={selectedSession} />
+          <TelemetryPanel session={selectedSession} />
+          <ActivityGraph session={selectedSession} />
+
+          <section className="panel p-5">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Sessions
+            </h2>
+            <div className="pt-4 grid grid-cols-2 gap-3">
+              <div className="flex flex-col gap-1">
+                <span className="font-display text-4xl text-accent">{allSessions.length}</span>
+                <span className="text-[11px] uppercase tracking-widest text-text-muted">Total</span>
+              </div>
+              <div className="flex flex-col gap-1">
+                <span className="font-display text-4xl text-running">{activeCount}</span>
+                <span className="text-[11px] uppercase tracking-widest text-text-muted">Active</span>
+              </div>
+              <div className="flex flex-col gap-1">
+                <span className="font-display text-4xl text-accent">{pins.length}</span>
+                <span className="text-[11px] uppercase tracking-widest text-text-muted">Pinned</span>
+              </div>
+            </div>
+          </section>
+
+          <section className="panel p-5">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Top Skills
+            </h2>
+            <div className="pt-3 flex flex-col gap-2">
+              {topSkills.length === 0 && <p className="text-sm text-text-muted">No skills observed.</p>}
+              {topSkills.map(([name, count]) => (
+                <div key={name} className="flex items-center justify-between text-sm">
+                  <span className="text-text-primary">{name}</span>
+                  <span className="text-text-muted tabular">{count}</span>
+                </div>
+              ))}
+            </div>
+          </section>
+
+          <section className="panel p-5">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Top Tools
+            </h2>
+            <div className="pt-3 flex flex-col gap-2">
+              {topTools.length === 0 && <p className="text-sm text-text-muted">No tools observed.</p>}
+              {topTools.map(([name, count]) => (
+                <div key={name} className="flex items-center justify-between text-sm">
+                  <span className="font-mono text-text-primary">{name}</span>
+                  <span className="text-text-muted tabular">{count}</span>
+                </div>
+              ))}
+            </div>
+          </section>
+
+          <section className="panel p-5 md:col-span-2 xl:col-span-3">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Recent Sessions
+            </h2>
+            <div className="pt-3 grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
+              {allSessions.slice(0, 6).map((s) => (
+                <button
+                  key={s.id}
+                  onClick={() => onSelectSession(s.id)}
+                  className="flex items-center gap-3 p-3 rounded-lg border border-border-default bg-elevated hover:border-accent transition-colors text-left"
+                >
+                  <Icon name={sourceIcon(s.source)} className="w-5 h-5 text-text-secondary" />
+                  <div className="flex flex-col min-w-0">
+                    <span className="text-sm text-text-primary font-mono truncate">
+                      {truncate(s.activeSkill?.name || 'No active skill', 24)}
+                    </span>
+                    <span className="text-[11px] text-text-muted uppercase">{s.source}</span>
+                  </div>
+                </button>
+              ))}
+              {allSessions.length === 0 && <p className="text-sm text-text-muted">No sessions yet.</p>}
+            </div>
+          </section>
+        </div>
+      </div>
+    </div>
+  );
+}

package/servers/dashboard/ui/src/components/views/SessionsView.tsx

@@ -0,0 +1,84 @@
+import type { ClientSession } from '../../../../src/types';
+import { usePinnedSessions } from '../../contexts/PinnedSessionsContext';
+import { ViewHeader } from '../ViewHeader';
+import { FilterBar } from '../FilterBar';
+import { Icon } from '../ui/Icon';
+import { formatDuration, formatTime, truncate } from '../../../../src/lib/format';
+import type { FilterOptions } from '../../lib/types';
+
+interface Props {
+  sessions: ClientSession[];
+  selectedSessionId: string | null;
+  filterOptions: FilterOptions;
+  onSelectSession: (id: string) => void;
+}
+
+function lifecycleColor(lifecycle: string): string {
+  switch (lifecycle) {
+    case 'starting':
+      return 'bg-warning';
+    case 'running':
+      return 'bg-running';
+    case 'ended':
+      return 'bg-text-muted';
+    default:
+      return 'bg-text-muted';
+  }
+}
+
+export function SessionsView({ sessions, selectedSessionId, filterOptions, onSelectSession }: Props) {
+  const { togglePin, isPinned } = usePinnedSessions();
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      <ViewHeader title="Sessions" icon="Rows" />
+      <FilterBar options={filterOptions} resultCount={sessions.length} />
+      <div className="flex-1 overflow-y-auto p-5">
+        <div className="flex flex-col gap-2">
+          {sessions.map((s) => {
+            const duration = s.endedAt
+              ? formatDuration(s.endedAt - s.startTime)
+              : formatDuration(Date.now() - s.startTime);
+            const active = s.id === selectedSessionId;
+            const pinned = isPinned(s.id);
+            return (
+              <button
+                key={s.id}
+                onClick={() => onSelectSession(s.id)}
+                className={`group flex items-center gap-3 w-full text-left p-3 rounded-lg border transition-colors ${
+                  active
+                    ? 'bg-elevated border-accent'
+                    : 'bg-surface border-border-default hover:bg-elevated'
+                }`}
+              >
+                <button
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    togglePin(s.id);
+                  }}
+                  aria-label={pinned ? 'Unpin session' : 'Pin session'}
+                  className={`p-1 rounded hover:bg-base transition-colors ${
+                    pinned ? 'text-accent' : 'text-text-muted group-hover:text-text-secondary'
+                  }`}
+                >
+                  <Icon name={pinned ? 'PushPinSlash' : 'PushPin'} className="w-4 h-4" />
+                </button>
+                <span className={`w-2.5 h-2.5 rounded-full ${lifecycleColor(s.lifecycle)}`} />
+                <div className="flex flex-col min-w-0 flex-1">
+                  <span className="text-sm text-text-primary font-mono truncate">
+                    {truncate(s.activeSkill?.name || s.id, 40)}
+                  </span>
+                  <span className="text-[11px] text-text-muted">
+                    {formatTime(s.startTime)} · {duration} · {s.events.length} events
+                  </span>
+                </div>
+                <span className="text-[11px] uppercase text-text-muted">{s.source}</span>
+              </button>
+            );
+          })}
+          {sessions.length === 0 && <p className="text-sm text-text-muted text-center py-8">No sessions match the filters.</p>}
+        </div>
+      </div>
+    </div>
+  );
+}

package/servers/dashboard/ui/src/components/views/SettingsView.tsx

@@ -0,0 +1,138 @@
+import { useSettings } from '../../contexts/SettingsContext';
+import { ViewHeader } from '../ViewHeader';
+import { Icon } from '../ui/Icon';
+
+export function SettingsView() {
+  const { settings, setSettings, reducedMotion } = useSettings();
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      <ViewHeader title="Settings" icon="Gear" />
+      <div className="flex-1 overflow-y-auto p-5">
+        <div className="max-w-2xl flex flex-col gap-4">
+          <section className="panel p-5">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Appearance
+            </h2>
+            <div className="pt-4 flex flex-col gap-4">
+              <div className="flex items-center justify-between">
+                <div>
+                  <div className="text-sm text-text-primary">Theme</div>
+                  <div className="text-xs text-text-muted">Choose your preferred color scheme.</div>
+                </div>
+                <select
+                  value={settings.theme}
+                  onChange={(e) => setSettings((s) => ({ ...s, theme: e.target.value as typeof s.theme }))}
+                  className="h-9 px-3 rounded-lg bg-elevated border border-border-default text-sm text-text-primary outline-none focus:border-accent"
+                >
+                  <option value="system">System</option>
+                  <option value="dark">Dark</option>
+                  <option value="light">Light</option>
+                </select>
+              </div>
+
+              <div className="flex items-center justify-between">
+                <div>
+                  <div className="text-sm text-text-primary">Density</div>
+                  <div className="text-xs text-text-muted">Control how compact lists appear.</div>
+                </div>
+                <div className="flex items-center gap-2">
+                  <button
+                    onClick={() => setSettings((s) => ({ ...s, density: 'comfortable' }))}
+                    className={`flex items-center gap-1.5 px-3 py-1.5 rounded-lg border text-xs transition-colors ${
+                      settings.density === 'comfortable'
+                        ? 'border-accent text-accent bg-accent/10'
+                        : 'border-border-default text-text-secondary hover:bg-elevated'
+                    }`}
+                  >
+                    <Icon name="ArrowsOutLineVertical" className="w-4 h-4" />
+                    Comfortable
+                  </button>
+                  <button
+                    onClick={() => setSettings((s) => ({ ...s, density: 'compact' }))}
+                    className={`flex items-center gap-1.5 px-3 py-1.5 rounded-lg border text-xs transition-colors ${
+                      settings.density === 'compact'
+                        ? 'border-accent text-accent bg-accent/10'
+                        : 'border-border-default text-text-secondary hover:bg-elevated'
+                    }`}
+                  >
+                    <Icon name="ArrowsInLineVertical" className="w-4 h-4" />
+                    Compact
+                  </button>
+                </div>
+              </div>
+
+              <div className="flex items-center justify-between">
+                <div>
+                  <div className="text-sm text-text-primary">Reduced motion</div>
+                  <div className="text-xs text-text-muted">Disable animations throughout the dashboard.</div>
+                </div>
+                <button
+                  onClick={() => setSettings((s) => ({ ...s, reducedMotion: !s.reducedMotion }))}
+                  className={`relative w-11 h-6 rounded-full transition-colors ${
+                    settings.reducedMotion ? 'bg-accent' : 'bg-border-strong'
+                  }`}
+                  aria-pressed={settings.reducedMotion}
+                >
+                  <span
+                    className={`absolute top-1 left-1 w-4 h-4 rounded-full bg-white transition-transform ${
+                      settings.reducedMotion ? 'translate-x-5' : 'translate-x-0'
+                    }`}
+                  />
+                </button>
+              </div>
+              {reducedMotion && (
+                <p className="text-xs text-text-muted">OS reduced-motion preference is also enabled.</p>
+              )}
+            </div>
+          </section>
+
+          <section className="panel p-5">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Behavior
+            </h2>
+            <div className="pt-4 flex flex-col gap-4">
+              <div className="flex items-center justify-between">
+                <div>
+                  <div className="text-sm text-text-primary">Auto-follow active session</div>
+                  <div className="text-xs text-text-muted">Automatically select the running session.</div>
+                </div>
+                <button
+                  onClick={() => setSettings((s) => ({ ...s, autoFollowActive: !s.autoFollowActive }))}
+                  className={`relative w-11 h-6 rounded-full transition-colors ${
+                    settings.autoFollowActive ? 'bg-accent' : 'bg-border-strong'
+                  }`}
+                  aria-pressed={settings.autoFollowActive}
+                >
+                  <span
+                    className={`absolute top-1 left-1 w-4 h-4 rounded-full bg-white transition-transform ${
+                      settings.autoFollowActive ? 'translate-x-5' : 'translate-x-0'
+                    }`}
+                  />
+                </button>
+              </div>
+
+              <div className="flex items-center justify-between">
+                <div>
+                  <div className="text-sm text-text-primary">Max events per session</div>
+                  <div className="text-xs text-text-muted">Limit how many events are kept in memory.</div>
+                </div>
+                <input
+                  type="number"
+                  min={10}
+                  max={1000}
+                  value={settings.maxEvents}
+                  onChange={(e) => {
+                    const n = parseInt(e.target.value, 10);
+                    if (!Number.isNaN(n)) setSettings((s) => ({ ...s, maxEvents: Math.max(10, Math.min(1000, n)) }));
+                  }}
+                  className="w-24 h-9 px-3 rounded-lg bg-elevated border border-border-default text-sm text-text-primary outline-none focus:border-accent"
+                />
+              </div>
+            </div>
+          </section>
+        </div>
+      </div>
+    </div>
+  );
+}

package/servers/dashboard/ui/src/components/views/SkillsView.tsx

@@ -0,0 +1,92 @@
+import { useMemo } from 'react';
+import type { ToolInvocation } from '../../../../src/lib/invocations';
+import { operationType } from '../../../../src/lib/invocations';
+import { resolvePath } from '../../../../src/lib/paths';
+import { ViewHeader } from '../ViewHeader';
+import { FilterBar } from '../FilterBar';
+import type { FilterOptions } from '../../lib/types';
+import { Icon } from '../ui/Icon';
+
+interface Props {
+  invocations: ToolInvocation[];
+  filterOptions: FilterOptions;
+}
+
+export function SkillsView({ invocations, filterOptions }: Props) {
+  const stats = useMemo(() => {
+    const skills = new Map<string, number>();
+    const tools = new Map<string, number>();
+    const files = new Set<string>();
+    for (const inv of invocations) {
+      if (inv.skill) skills.set(inv.skill, (skills.get(inv.skill) || 0) + 1);
+      tools.set(inv.tool, (tools.get(inv.tool) || 0) + 1);
+      const path = resolvePath(inv.input, inv.output);
+      if (path) files.add(path);
+    }
+    return {
+      skills: Array.from(skills.entries()).sort((a, b) => b[1] - a[1]),
+      tools: Array.from(tools.entries()).sort((a, b) => b[1] - a[1]),
+      reads: invocations.filter((i) => operationType(i.tool) === 'read').length,
+      edits: invocations.filter((i) => operationType(i.tool) === 'edit').length,
+      fileCount: files.size,
+    };
+  }, [invocations]);
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      <ViewHeader title="Skills" icon="ChartPie" />
+      <FilterBar options={filterOptions} resultCount={invocations.length} />
+      <div className="flex-1 overflow-y-auto p-5">
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-4 mb-4">
+          <div className="panel p-4 flex flex-col gap-1">
+            <span className="font-display text-4xl text-accent">{stats.skills.length}</span>
+            <span className="text-[11px] uppercase tracking-widest text-text-muted">Skills</span>
+          </div>
+          <div className="panel p-4 flex flex-col gap-1">
+            <span className="font-display text-4xl text-accent">{stats.tools.length}</span>
+            <span className="text-[11px] uppercase tracking-widest text-text-muted">Tools</span>
+          </div>
+          <div className="panel p-4 flex flex-col gap-1">
+            <span className="font-display text-4xl text-accent">{stats.fileCount}</span>
+            <span className="text-[11px] uppercase tracking-widest text-text-muted">Files touched</span>
+          </div>
+        </div>
+
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+          <section className="panel p-5">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Skill usage
+            </h2>
+            <div className="pt-3 flex flex-col gap-2">
+              {stats.skills.length === 0 && <p className="text-sm text-text-muted">No skills observed.</p>}
+              {stats.skills.map(([name, count]) => (
+                <div key={name} className="flex items-center justify-between text-sm">
+                  <div className="flex items-center gap-2">
+                    <Icon name="Circle" className="w-2 h-2 text-accent" />
+                    <span className="text-text-primary">{name}</span>
+                  </div>
+                  <span className="text-text-muted tabular">{count}</span>
+                </div>
+              ))}
+            </div>
+          </section>
+
+          <section className="panel p-5">
+            <h2 className="text-xs font-medium text-text-muted uppercase tracking-widest pb-3 border-b border-border-default">
+              Tool usage
+            </h2>
+            <div className="pt-3 flex flex-col gap-2">
+              {stats.tools.length === 0 && <p className="text-sm text-text-muted">No tools observed.</p>}
+              {stats.tools.map(([name, count]) => (
+                <div key={name} className="flex items-center justify-between text-sm">
+                  <span className="font-mono text-text-primary">{name}</span>
+                  <span className="text-text-muted tabular">{count}</span>
+                </div>
+              ))}
+            </div>
+          </section>
+        </div>
+      </div>
+    </div>
+  );
+}

package/servers/dashboard/ui/src/components/views/TimelineView.tsx

@@ -0,0 +1,46 @@
+import { useState } from 'react';
+import type { ToolInvocation } from '../../../../src/lib/invocations';
+import { ViewHeader } from '../ViewHeader';
+import { FilterBar } from '../FilterBar';
+import { Timeline } from '../Timeline';
+import { toJson, download, filename, toExportableEvent } from '../../lib/export';
+import type { FilterOptions } from '../../lib/types';
+
+interface Props {
+  invocations: ToolInvocation[];
+  filterOptions: FilterOptions;
+  onMouseEnter?: () => void;
+  onMouseLeave?: () => void;
+}
+
+export function TimelineView({ invocations, filterOptions, onMouseEnter, onMouseLeave }: Props) {
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(new Set());
+
+  function toggleExpanded(id: string) {
+    setExpandedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }
+
+  function handleExport() {
+    const events = invocations.map(toExportableEvent);
+    download(toJson(events), filename('json'));
+  }
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      <ViewHeader title="Timeline" icon="Clock" />
+      <FilterBar options={filterOptions} resultCount={invocations.length} onExport={handleExport} />
+      <Timeline
+        invocations={invocations}
+        expandedIds={expandedIds}
+        onToggle={toggleExpanded}
+        onMouseEnter={onMouseEnter}
+        onMouseLeave={onMouseLeave}
+      />
+    </div>
+  );
+}

package/servers/dashboard/ui/src/contexts/FilterContext.tsx

@@ -0,0 +1,41 @@
+import { createContext, useCallback, useContext, useState, type ReactNode } from 'react';
+import type { FilterState } from '../lib/types';
+import { DEFAULT_FILTER_STATE } from '../lib/types';
+
+interface FilterContextValue {
+  filters: FilterState;
+  setFilters: (updater: Partial<FilterState> | ((prev: FilterState) => FilterState)) => void;
+  resetFilters: () => void;
+}
+
+const FilterContext = createContext<FilterContextValue | null>(null);
+
+export function FilterProvider({ children }: { children: ReactNode }) {
+  const [filters, setFiltersState] = useState<FilterState>(DEFAULT_FILTER_STATE);
+
+  const setFilters = useCallback(
+    (updater: Partial<FilterState> | ((prev: FilterState) => FilterState)) => {
+      setFiltersState((prev) => {
+        if (typeof updater === 'function') {
+          return (updater as (prev: FilterState) => FilterState)(prev);
+        }
+        return { ...prev, ...updater };
+      });
+    },
+    []
+  );
+
+  const resetFilters = useCallback(() => setFiltersState(DEFAULT_FILTER_STATE), []);
+
+  return (
+    <FilterContext.Provider value={{ filters, setFilters, resetFilters }}>
+      {children}
+    </FilterContext.Provider>
+  );
+}
+
+export function useFilters(): FilterContextValue {
+  const ctx = useContext(FilterContext);
+  if (!ctx) throw new Error('useFilters must be used within FilterProvider');
+  return ctx;
+}

package/servers/dashboard/ui/src/contexts/PinnedSessionsContext.tsx

@@ -0,0 +1,80 @@
+import { createContext, useCallback, useContext, useState, type ReactNode } from 'react';
+import type { PinnedSession } from '../lib/types';
+
+interface PinnedSessionsContextValue {
+  pins: PinnedSession[];
+  addPin: (id: string) => void;
+  removePin: (id: string) => void;
+  togglePin: (id: string) => void;
+  isPinned: (id: string) => boolean;
+}
+
+const STORAGE_KEY = 'crewloop-dashboard-pins';
+
+const PinnedSessionsContext = createContext<PinnedSessionsContextValue | null>(null);
+
+function loadPins(): PinnedSession[] {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed.filter((p): p is PinnedSession => p && typeof p.id === 'string' && typeof p.pinnedAt === 'number');
+  } catch {
+    // ignore
+  }
+  return [];
+}
+
+function savePins(pins: PinnedSession[]): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(pins));
+  } catch {
+    // ignore
+  }
+}
+
+export function PinnedSessionsProvider({ children }: { children: ReactNode }) {
+  const [pins, setPins] = useState<PinnedSession[]>(() => loadPins());
+
+  const addPin = useCallback((id: string) => {
+    setPins((prev) => {
+      if (prev.some((p) => p.id === id)) return prev;
+      const next = [...prev, { id, pinnedAt: Date.now() }];
+      savePins(next);
+      return next;
+    });
+  }, []);
+
+  const removePin = useCallback((id: string) => {
+    setPins((prev) => {
+      const next = prev.filter((p) => p.id !== id);
+      savePins(next);
+      return next;
+    });
+  }, []);
+
+  const togglePin = useCallback(
+    (id: string) => {
+      if (pins.some((p) => p.id === id)) removePin(id);
+      else addPin(id);
+    },
+    [pins, addPin, removePin]
+  );
+
+  const isPinned = useCallback(
+    (id: string) => pins.some((p) => p.id === id),
+    [pins]
+  );
+
+  return (
+    <PinnedSessionsContext.Provider value={{ pins, addPin, removePin, togglePin, isPinned }}>
+      {children}
+    </PinnedSessionsContext.Provider>
+  );
+}
+
+export function usePinnedSessions(): PinnedSessionsContextValue {
+  const ctx = useContext(PinnedSessionsContext);
+  if (!ctx) throw new Error('usePinnedSessions must be used within PinnedSessionsProvider');
+  return ctx;
+}