feat(observer): M-Obs 4-7 — widgets, dashboard, docs, integration example

M-Obs 4: @shade/widgets React library
- ShadeProvider context with observer URL + token + theme
- useShadeState (polling) + useShadeEvents (SSE) hooks
- 7 widgets: IdentityCard, SessionList, PrekeyStock, RecentActivity,
  ServerStatus, FingerprintCompare, WidgetCatalog (meta-widget for
  user-selectable layout with localStorage persistence)
- Self-contained CSS via inline styles, no external CSS conflicts
- Light/dark/auto theme via tokens

M-Obs 5: @shade/dashboard standalone SPA
- Vite + React app composing all widgets into a full debugger layout
- Login screen with token persistence to localStorage
- Build script copies dist/ to @shade/observer/dist/ for embedded serving
- 211 KB JS bundle (66 KB gzipped)

M-Obs 6: Documentation + integration example
- READMEs for @shade/observer and @shade/widgets
- examples/06-observer-dashboard runnable demo: spins up prekey server +
  observer, runs Alice ↔ Bob conversation loop, dashboard at :3901
- Updated root README and docker-compose.yml with observer integration

M-Obs 7: End-to-end verification
- StateAggregator now drains buffered events on subscription, so
  identity.initialized fires before observer construction are still seen
- Verified live: snapshot endpoint returns full state, dashboard serves,
  401 without auth, sessions/messages/ratchet steps all tracked

220 tests passing, 0 failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/shade-widgets/src/useShadeEvents.ts

@@ -0,0 +1,62 @@
+import { useEffect, useState, useRef } from 'react';
+import { useShadeContext } from './ShadeProvider.js';
+
+export interface ShadeEventEnvelope {
+  source: 'client' | 'server';
+  seq: number;
+  timestamp: number;
+  name: string;
+  data: Record<string, any>;
+}
+
+export interface UseShadeEventsResult {
+  events: ShadeEventEnvelope[];
+  connected: boolean;
+  error: Error | null;
+}
+
+/**
+ * Hook that subscribes to /api/events SSE stream and accumulates events.
+ *
+ * @param maxBuffer Max number of events to keep in memory (default: 200).
+ *                  Older events are dropped.
+ */
+export function useShadeEvents(maxBuffer = 200): UseShadeEventsResult {
+  const ctx = useShadeContext();
+  const [events, setEvents] = useState<ShadeEventEnvelope[]>([]);
+  const [connected, setConnected] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const eventSourceRef = useRef<EventSource | null>(null);
+
+  useEffect(() => {
+    const url = `${ctx.observerUrl}/api/events?token=${encodeURIComponent(ctx.token)}`;
+    const es = new EventSource(url);
+    eventSourceRef.current = es;
+
+    es.addEventListener('open', () => setConnected(true));
+    es.addEventListener('error', () => {
+      setConnected(false);
+      setError(new Error('SSE connection error'));
+    });
+
+    es.addEventListener('shade', (msg) => {
+      try {
+        const event = JSON.parse((msg as MessageEvent).data) as ShadeEventEnvelope;
+        setEvents((prev) => {
+          const next = [...prev, event];
+          return next.length > maxBuffer ? next.slice(-maxBuffer) : next;
+        });
+      } catch (err) {
+        console.error('[Shade] Failed to parse event:', err);
+      }
+    });
+
+    return () => {
+      es.close();
+      eventSourceRef.current = null;
+      setConnected(false);
+    };
+  }, [ctx.observerUrl, ctx.token, maxBuffer]);
+
+  return { events, connected, error };
+}