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/useShadeState.ts

@@ -0,0 +1,75 @@
+import { useEffect, useState, useCallback } from 'react';
+import { useShadeContext } from './ShadeProvider.js';
+
+export interface ShadeState {
+  identity: {
+    fingerprint: string | null;
+    registrationId: number | null;
+    lastInitialized: number | null;
+    lastRotated: number | null;
+  };
+  sessions: Array<{
+    address: string;
+    remoteIdentityKeyHash: string;
+    messageCountSent: number;
+    messageCountReceived: number;
+    lastActivity: number;
+    dhRatchetSteps: number;
+  }>;
+  prekeys: {
+    oneTimeRemaining: number;
+    lastGenerated: number | null;
+    lastConsumed: number | null;
+    signedPreKeyId: number | null;
+    signedPreKeyLastRotated: number | null;
+  };
+  retiredIdentities: number;
+  server: {
+    registeredIdentities: string[];
+    totalBundleFetches: number;
+    totalReplenishes: number;
+    totalDeleted: number;
+    totalRateLimited: number;
+  };
+}
+
+export interface UseShadeStateResult {
+  state: ShadeState | null;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Hook that polls the observer's /api/state endpoint at the configured interval.
+ */
+export function useShadeState(): UseShadeStateResult {
+  const ctx = useShadeContext();
+  const [state, setState] = useState<ShadeState | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchState = useCallback(async () => {
+    try {
+      const res = await fetch(`${ctx.observerUrl}/api/state`, {
+        headers: { Authorization: `Bearer ${ctx.token}` },
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const json = (await res.json()) as ShadeState;
+      setState(json);
+      setError(null);
+    } catch (err) {
+      setError(err as Error);
+    } finally {
+      setLoading(false);
+    }
+  }, [ctx.observerUrl, ctx.token]);
+
+  useEffect(() => {
+    fetchState();
+    const interval = setInterval(fetchState, ctx.pollIntervalMs);
+    return () => clearInterval(interval);
+  }, [fetchState, ctx.pollIntervalMs]);
+
+  return { state, loading, error, refresh: fetchState };
+}