Merge pull request #974 from nteract/intelligence-2

Add useConversationArc hook and docs

Author: emeeks

.clinerules

@@ -326,19 +326,35 @@ function SuggestedChart({ data, intent }) {
 ```
 
 ### Conversation-arc telemetry (`semiotic/ai`)
-Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
+Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`, plus `interrogation-asked` / `interrogation-answered` for chat-with-chart sessions. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
 - **`enableConversationArc({ capacity?, sessionId? })`** → enables recording. Bounded ring buffer (default 1000 events). Safe to call multiple times; reuses the existing session unless `sessionId` is overridden.
 - **`disableConversationArc()`** → stops recording without dropping buffered events.
-- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op).
-- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`).
+- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op). `getEvents()` returns a referentially stable snapshot until the next mutation — safe for `useSyncExternalStore`.
+- **`subscribeToConversationArcChange(fn)`** → fires on any state mutation (record / clear / flush / reset / enable). Used by the React hook for snapshot tracking; sinks should use `subscribe()` (event-typed) instead.
+- **`useConversationArc({ enableOnMount?, disableOnUnmount?, capacity?, sessionId? })`** → React hook returning `{ history, summary, enabled, sessionId, record, clear }`. `summary` is the live `ConversationArcSummary` (per-type counts, components seen, audiences seen, duration, latestArcId). Subscribes via `useSyncExternalStore` for tear-free re-renders.
+- **`summarizeArc(events)`** → pure reducer producing the same `ConversationArcSummary`. Server-safe, replay-safe.
+- **`recordAudienceChange(audience, previous?, { arcId?, meta? }?)`** → sugar over `record({ type: "audience-set", ... })`. Call from your audience-picker's `onChange`.
+- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`; `InterrogationAnsweredEvent` has `answer`, `annotationCount`, `latencyMs`, `error`).
+- **Auto-instrumented sources**: `useChartSuggestions` emits `suggestion-shown` whenever the suggestion list changes (dedup by component-list + intent signature); `useChartInterrogation` emits `interrogation-asked` on `ask()` and `interrogation-answered` (with `latencyMs`) when the response returns. Zero-overhead when arc store is disabled.
 
 ```ts
-import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
+// React surface
+import { useConversationArc } from "semiotic/ai"
+
+function ArcInspector() {
+  const { history, summary, record, clear } = useConversationArc()
+  return (
+    <>
+      <header>{summary.total} events · {summary.byType["chart-exported"] ?? 0} exports</header>
+      <EventList events={history} />
+    </>
+  )
+}
 
+// Non-React surface (sinks, replay)
+import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
 enableConversationArc()
-const store = getConversationArcStore()
-const unsub = store.subscribe((event) => console.log(event.type, event))
-store.record({ type: "suggestion-shown", components: ["LineChart"], intent: "trend" })
+const unsub = getConversationArcStore().subscribe((event) => sendToAnalytics(event))
 ```
 
 ### Annotation provenance + lifecycle (`semiotic/ai`, types also re-exported from `semiotic`)

.cursorrules

@@ -326,19 +326,35 @@ function SuggestedChart({ data, intent }) {
 ```
 
 ### Conversation-arc telemetry (`semiotic/ai`)
-Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
+Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`, plus `interrogation-asked` / `interrogation-answered` for chat-with-chart sessions. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
 - **`enableConversationArc({ capacity?, sessionId? })`** → enables recording. Bounded ring buffer (default 1000 events). Safe to call multiple times; reuses the existing session unless `sessionId` is overridden.
 - **`disableConversationArc()`** → stops recording without dropping buffered events.
-- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op).
-- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`).
+- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op). `getEvents()` returns a referentially stable snapshot until the next mutation — safe for `useSyncExternalStore`.
+- **`subscribeToConversationArcChange(fn)`** → fires on any state mutation (record / clear / flush / reset / enable). Used by the React hook for snapshot tracking; sinks should use `subscribe()` (event-typed) instead.
+- **`useConversationArc({ enableOnMount?, disableOnUnmount?, capacity?, sessionId? })`** → React hook returning `{ history, summary, enabled, sessionId, record, clear }`. `summary` is the live `ConversationArcSummary` (per-type counts, components seen, audiences seen, duration, latestArcId). Subscribes via `useSyncExternalStore` for tear-free re-renders.
+- **`summarizeArc(events)`** → pure reducer producing the same `ConversationArcSummary`. Server-safe, replay-safe.
+- **`recordAudienceChange(audience, previous?, { arcId?, meta? }?)`** → sugar over `record({ type: "audience-set", ... })`. Call from your audience-picker's `onChange`.
+- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`; `InterrogationAnsweredEvent` has `answer`, `annotationCount`, `latencyMs`, `error`).
+- **Auto-instrumented sources**: `useChartSuggestions` emits `suggestion-shown` whenever the suggestion list changes (dedup by component-list + intent signature); `useChartInterrogation` emits `interrogation-asked` on `ask()` and `interrogation-answered` (with `latencyMs`) when the response returns. Zero-overhead when arc store is disabled.
 
 ```ts
-import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
+// React surface
+import { useConversationArc } from "semiotic/ai"
+
+function ArcInspector() {
+  const { history, summary, record, clear } = useConversationArc()
+  return (
+    <>
+      <header>{summary.total} events · {summary.byType["chart-exported"] ?? 0} exports</header>
+      <EventList events={history} />
+    </>
+  )
+}
 
+// Non-React surface (sinks, replay)
+import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
 enableConversationArc()
-const store = getConversationArcStore()
-const unsub = store.subscribe((event) => console.log(event.type, event))
-store.record({ type: "suggestion-shown", components: ["LineChart"], intent: "trend" })
+const unsub = getConversationArcStore().subscribe((event) => sendToAnalytics(event))
 ```
 
 ### Annotation provenance + lifecycle (`semiotic/ai`, types also re-exported from `semiotic`)

.github/copilot-instructions.md

@@ -326,19 +326,35 @@ function SuggestedChart({ data, intent }) {
 ```
 
 ### Conversation-arc telemetry (`semiotic/ai`)
-Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
+Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`, plus `interrogation-asked` / `interrogation-answered` for chat-with-chart sessions. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
 - **`enableConversationArc({ capacity?, sessionId? })`** → enables recording. Bounded ring buffer (default 1000 events). Safe to call multiple times; reuses the existing session unless `sessionId` is overridden.
 - **`disableConversationArc()`** → stops recording without dropping buffered events.
-- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op).
-- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`).
+- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op). `getEvents()` returns a referentially stable snapshot until the next mutation — safe for `useSyncExternalStore`.
+- **`subscribeToConversationArcChange(fn)`** → fires on any state mutation (record / clear / flush / reset / enable). Used by the React hook for snapshot tracking; sinks should use `subscribe()` (event-typed) instead.
+- **`useConversationArc({ enableOnMount?, disableOnUnmount?, capacity?, sessionId? })`** → React hook returning `{ history, summary, enabled, sessionId, record, clear }`. `summary` is the live `ConversationArcSummary` (per-type counts, components seen, audiences seen, duration, latestArcId). Subscribes via `useSyncExternalStore` for tear-free re-renders.
+- **`summarizeArc(events)`** → pure reducer producing the same `ConversationArcSummary`. Server-safe, replay-safe.
+- **`recordAudienceChange(audience, previous?, { arcId?, meta? }?)`** → sugar over `record({ type: "audience-set", ... })`. Call from your audience-picker's `onChange`.
+- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`; `InterrogationAnsweredEvent` has `answer`, `annotationCount`, `latencyMs`, `error`).
+- **Auto-instrumented sources**: `useChartSuggestions` emits `suggestion-shown` whenever the suggestion list changes (dedup by component-list + intent signature); `useChartInterrogation` emits `interrogation-asked` on `ask()` and `interrogation-answered` (with `latencyMs`) when the response returns. Zero-overhead when arc store is disabled.
 
 ```ts
-import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
+// React surface
+import { useConversationArc } from "semiotic/ai"
+
+function ArcInspector() {
+  const { history, summary, record, clear } = useConversationArc()
+  return (
+    <>
+      <header>{summary.total} events · {summary.byType["chart-exported"] ?? 0} exports</header>
+      <EventList events={history} />
+    </>
+  )
+}
 
+// Non-React surface (sinks, replay)
+import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
 enableConversationArc()
-const store = getConversationArcStore()
-const unsub = store.subscribe((event) => console.log(event.type, event))
-store.record({ type: "suggestion-shown", components: ["LineChart"], intent: "trend" })
+const unsub = getConversationArcStore().subscribe((event) => sendToAnalytics(event))
 ```
 
 ### Annotation provenance + lifecycle (`semiotic/ai`, types also re-exported from `semiotic`)

.windsurfrules

@@ -326,19 +326,35 @@ function SuggestedChart({ data, intent }) {
 ```
 
 ### Conversation-arc telemetry (`semiotic/ai`)
-Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
+Opt-in event store that records the arc of an AI-assisted session: `suggestion-shown → suggestion-chosen → audience-set → chart-rendered → chart-edited → chart-replaced → chart-exported | chart-abandoned`, plus `interrogation-asked` / `interrogation-answered` for chat-with-chart sessions. Module-scoped, no React provider needed. Default surface is a no-op — call `enableConversationArc()` to start recording.
 - **`enableConversationArc({ capacity?, sessionId? })`** → enables recording. Bounded ring buffer (default 1000 events). Safe to call multiple times; reuses the existing session unless `sessionId` is overridden.
 - **`disableConversationArc()`** → stops recording without dropping buffered events.
-- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op).
-- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`).
+- **`getConversationArcStore()`** → returns `{ enabled, sessionId, capacity, record(input), flush(), getEvents(), subscribe(listener), clear(), reset() }`. Methods are safe to call when disabled (no-op). `getEvents()` returns a referentially stable snapshot until the next mutation — safe for `useSyncExternalStore`.
+- **`subscribeToConversationArcChange(fn)`** → fires on any state mutation (record / clear / flush / reset / enable). Used by the React hook for snapshot tracking; sinks should use `subscribe()` (event-typed) instead.
+- **`useConversationArc({ enableOnMount?, disableOnUnmount?, capacity?, sessionId? })`** → React hook returning `{ history, summary, enabled, sessionId, record, clear }`. `summary` is the live `ConversationArcSummary` (per-type counts, components seen, audiences seen, duration, latestArcId). Subscribes via `useSyncExternalStore` for tear-free re-renders.
+- **`summarizeArc(events)`** → pure reducer producing the same `ConversationArcSummary`. Server-safe, replay-safe.
+- **`recordAudienceChange(audience, previous?, { arcId?, meta? }?)`** → sugar over `record({ type: "audience-set", ... })`. Call from your audience-picker's `onChange`.
+- **Events**: `ConversationArcEvent` discriminated union with `type`, `timestamp`, `sessionId`, optional `arcId` + `meta`. Each variant carries its own payload (e.g. `SuggestionShownEvent` has `components`, `intent`, `topScore`, `audience`; `InterrogationAnsweredEvent` has `answer`, `annotationCount`, `latencyMs`, `error`).
+- **Auto-instrumented sources**: `useChartSuggestions` emits `suggestion-shown` whenever the suggestion list changes (dedup by component-list + intent signature); `useChartInterrogation` emits `interrogation-asked` on `ask()` and `interrogation-answered` (with `latencyMs`) when the response returns. Zero-overhead when arc store is disabled.
 
 ```ts
-import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
+// React surface
+import { useConversationArc } from "semiotic/ai"
+
+function ArcInspector() {
+  const { history, summary, record, clear } = useConversationArc()
+  return (
+    <>
+      <header>{summary.total} events · {summary.byType["chart-exported"] ?? 0} exports</header>
+      <EventList events={history} />
+    </>
+  )
+}
 
+// Non-React surface (sinks, replay)
+import { enableConversationArc, getConversationArcStore } from "semiotic/ai"
 enableConversationArc()
-const store = getConversationArcStore()
-const unsub = store.subscribe((event) => console.log(event.type, event))
-store.record({ type: "suggestion-shown", components: ["LineChart"], intent: "trend" })
+const unsub = getConversationArcStore().subscribe((event) => sendToAnalytics(event))
 ```
 
 ### Annotation provenance + lifecycle (`semiotic/ai`, types also re-exported from `semiotic`)