@unoverse-platform/studio 0.1.0

package/vendor/sdk/lib/core/connection.ts

@@ -0,0 +1,142 @@
+/**
+ * The data-plane translation layer (pure, no React, no DOM).
+ *
+ * The CHANNEL owns the live workflow connection (WS + REST execute); this file
+ * is the thin mapping it feeds: one inbound server message → one mutation of the
+ * single `ComponentStore`. Keeping it pure makes it unit-testable and lets the
+ * React hook (react/src/connection.tsx) own only socket lifecycle.
+ *
+ * The Unoverse MCP server is NOT involved here — it's the control plane
+ * (definitions + theme). See UNOVERSE_MCP_TEMPLATE_PROTOCOL.md §5a.
+ */
+import type { ComponentStore } from "./store";
+
+// ---- Inbound server messages (the subset this rung handles) ----
+// Mirrors the legacy gravity-client contract (core/types.ts). nodeId is
+// SERVER-ASSIGNED per emitted component — never minted by the client.
+
+export interface ServerComponentInit {
+  type: "COMPONENT_INIT";
+  chatId: string;
+  nodeId: string;
+  component: { type: string; componentUrl?: string; props?: Record<string, unknown> };
+  /** Marks a TEMPLATE directive (legacy emits a fake COMPONENT_INIT with nodeId
+   *  `<name>_template`). Templates are SERVED apps, loaded via resources/read — never
+   *  rendered as components — so we route these to the template plane, not the timeline. */
+  metadata?: { isTemplate?: boolean; [k: string]: unknown };
+}
+export interface ServerComponentData {
+  type: "COMPONENT_DATA" | "OBJECT_DATA";
+  chatId: string;
+  nodeId: string;
+  data: Record<string, unknown>;
+}
+export interface ServerWorkflowState {
+  type: "WORKFLOW_STATE";
+  state: string; // WORKFLOW_STARTED | WORKFLOW_COMPLETED | ...
+  chatId: string;
+  workflowId?: string;
+  workflowRunId?: string | null;
+  /** Template SELECTION rides here (SPEC §5b: `{ template, templateMode }`) — the
+   *  OFFICIAL signal for which MCP-app shell to load via resources/read. */
+  metadata?: { template?: string; templateMode?: string; [k: string]: unknown };
+}
+export interface ServerSessionReady {
+  type: "SESSION_READY";
+}
+/** Generic write into TEMPLATE STATE — the template-state twin of COMPONENT_DATA. The
+ *  producer names the keys (e.g. the Suggestions node sends `{ faqs }`); core stays generic. */
+export interface ServerTemplateData {
+  type: "TEMPLATE_DATA";
+  data: Record<string, unknown>;
+}
+export type ServerMessage =
+  | ServerComponentInit
+  | ServerComponentData
+  | ServerWorkflowState
+  | ServerSessionReady
+  | ServerTemplateData
+  | { type: string; [k: string]: unknown }; // forward-compat: unknown types ignored
+
+// Track first-seen components per `chatId:nodeId` so a repeated COMPONENT_INIT
+// is applied as a props merge (legacy behaviour), not a second timeline placement.
+// Caller passes a Set it owns (per connection), so this stays pure.
+
+/**
+ * Apply one inbound server message to the single store. Out-of-scope message types
+ * (NODE_EXECUTION, audio) are ignored here; audio-state rides the WS lane, not this stream.
+ *
+ * @param seen  per-connection set of already-initialised `chatId:nodeId` keys.
+ */
+export function applyServerMessage(store: ComponentStore, msg: ServerMessage, seen: Set<string>): void {
+  switch (msg.type) {
+    case "COMPONENT_INIT": {
+      const m = msg as ServerComponentInit;
+      if (!m.chatId || !m.nodeId) return;
+      // TEMPLATE DIRECTIVE — a template is a SERVED MCP app (protocol §0.1), loaded via
+      // resources/read unoverse://templates/{name}; it is NEVER a streamed component. Record
+      // WHICH app to load (the channel reads it); do not place it in the component timeline
+      // (that produced "Unknown Unoverse component: <Template>"). The legacy componentUrl
+      // .js bundle is ignored — Unoverse loads the neutral definition, not a React bundle.
+      if (m.metadata?.isTemplate === true || m.nodeId.endsWith("_template")) {
+        if (m.component?.type) store.setActiveTemplate(m.component.type, m.component.props ?? {});
+        return;
+      }
+      const key = `${m.chatId}:${m.nodeId}`;
+      if (seen.has(key)) {
+        // Already placed — treat a repeat INIT as a props merge (no re-placement).
+        const props = m.component?.props;
+        if (props && Object.keys(props).length > 0) {
+          store.apply({ type: "COMPONENT_DATA", chatId: m.chatId, nodeId: m.nodeId, data: props });
+        }
+        return;
+      }
+      seen.add(key);
+      store.apply({ type: "COMPONENT_INIT", chatId: m.chatId, nodeId: m.nodeId, component: m.component });
+      return;
+    }
+    case "COMPONENT_DATA":
+    case "OBJECT_DATA": {
+      const m = msg as ServerComponentData;
+      if (!m.chatId || !m.nodeId) return;
+      store.apply({ type: "COMPONENT_DATA", chatId: m.chatId, nodeId: m.nodeId, data: m.data ?? {} });
+      return;
+    }
+    case "WORKFLOW_STATE": {
+      const m = msg as ServerWorkflowState;
+      // OFFICIAL template selection (SPEC §5b): the workflow names the app shell in
+      // metadata.template; the channel loads it via resources/read. (templateMode
+      // switch/stack/replace is future — default "switch".)
+      if (m.metadata?.template) store.setActiveTemplate(m.metadata.template);
+      // Open an EMPTY streaming turn so the timeline shows a thinking state BEFORE the
+      // first component (legacy processWorkflowState.ts; aiContext treats these as
+      // streaming). COMPONENT_INIT then reuses it. Without this, the assistant turn is
+      // born WITH its first component, so the streaming-and-empty window never exists.
+      if (m.state === "WORKFLOW_STARTED" || m.state === "THINKING" || m.state === "RESPONDING" || m.state === "WAITING") {
+        if (m.chatId) store.startResponse(m.chatId);
+      } else if (m.state === "WORKFLOW_COMPLETED" || m.state === "COMPLETE") {
+        store.completeResponse(m.chatId);
+      }
+      // Lifecycle machine — the global turn status (projected for visibleWhen).
+      if (m.state === "WORKFLOW_STARTED" || m.state === "THINKING") store.setLifecycle("thinking");
+      else if (m.state === "RESPONDING" || m.state === "WAITING") store.setLifecycle("streaming");
+      else if (m.state === "WORKFLOW_COMPLETED" || m.state === "COMPLETE") store.setLifecycle("complete");
+      else if (m.state === "ERROR" || m.state === "WORKFLOW_ERROR") store.setLifecycle("error");
+      return;
+    }
+    // No AUDIO_STATE case: voice is a NATIVE SERVICE on the WS audio lane (useVoiceService),
+    // NOT the structured MCP stream. Audio-state events never arrive here (UNOVERSE_SPEC §2e-1).
+    case "TEMPLATE_DATA": {
+      // Generic write into TEMPLATE STATE (the template-state twin of COMPONENT_DATA). The
+      // PRODUCER names the keys (the Suggestions node sends `{ faqs }`); the template picks
+      // them up. Core knows NO key names — fully generic (UNOVERSE_STATE_MODEL §2/§8).
+      const data = ((msg as { data?: Record<string, unknown> }).data ?? {}) as Record<string, unknown>;
+      store.mergeTemplateState(data);
+      return;
+    }
+    default:
+      // SESSION_READY is handled by the hook (it may send initialQuery); everything
+      // else (NODE_EXECUTION, audio) is out of scope this rung.
+      return;
+  }
+}

package/vendor/sdk/lib/core/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @unoverse/core — framework-agnostic brain. Public barrel.
+ *
+ * The implementation is split into focused modules:
+ *   - ./types       neutral definition shape + interaction vocab + resolved-theme shape
+ *   - ./client      the MCP client (reads definitions + theme)
+ *   - ./store       the single shared state + interaction state machines
+ *   - ./connection  data-plane translation (server message → store)
+ *   - ./actions     the action interpreter (§2e-3)
+ * No UI framework here; the React binding lives in @unoverse/sdk.
+ */
+
+export * from "./types";
+export * from "./client";
+export * from "./store";
+
+// Data-plane translation layer (pure event→store mapping; channel-owned connection).
+export {
+  applyServerMessage,
+  type ServerMessage,
+  type ServerComponentInit,
+  type ServerComponentData,
+  type ServerWorkflowState,
+  type ServerSessionReady,
+  type ServerTemplateData,
+} from "./connection";
+
+// The action interpreter (§2e-3) — local `setValue` store write + server route.
+export { dispatchAction, resolveValue, type ActionContext } from "./actions";
+
+// The shared "react to state" predicate (visibleWhen / Switch / style.when).
+export { matches, visible, selectCase } from "./conditions";

package/vendor/sdk/lib/core/store.ts

@@ -0,0 +1,455 @@
+/**
+ * @unoverse/core — the single shared state (UNOVERSE_SPEC.md §2e-0).
+ *
+ * ONE store, ONE subscribe. Framework-agnostic (NO Zustand/XState) so it ports to
+ * every platform; the React binding is `useSyncExternalStore` in the react package.
+ * Two facets of the same object:
+ *
+ *   1. DATA     — every component instance keyed `${chatId}:${nodeId}`,
+ *                 MERGE-not-replace. The live, high-frequency plane.
+ *   2. TIMELINE — the conversation: an ordered list of turns. An assistant
+ *                 turn holds POINTERS (the `chatId:nodeId` keys) into the data
+ *                 plane — never copies. This is what templates read.
+ *
+ * Plus a generic TEMPLATE-STATE bag (`templateState`) + `lifecycle` (derived from the
+ * conversation) + `draft` (the shared composer buffer). The SDK hardcodes NO UI concept —
+ * disclosure/focus/etc. are keys the dev writes via the `setValue` (component) or
+ * `setTemplateValue` (template) actions and reads via `visibleWhen`. (Voice is a native
+ * SERVICE — WS audio lane, react package — whose call state a producer merges into
+ * template state, per UNOVERSE_SPEC §2e-1. The store holds structured state only.)
+ *
+ * The split that makes template-swapping safe: COMPONENT_INIT *places a pointer* in
+ * the timeline (structure changes once); COMPONENT_DATA only merges into the data
+ * plane (the timeline never moves). A template reads structure, never the stream — so
+ * you can swap templates mid-stream and the conversation + live data are untouched.
+ */
+
+/** A pointer into the data plane — the `${chatId}:${nodeId}` key. */
+export type Pointer = string;
+
+export interface UserTurn {
+  role: "user";
+  id: string;
+  chatId: string;
+  text: string;
+  /** Epoch ms when the turn was created — the renderer formats it (e.g. "just now"). */
+  createdAt: number;
+}
+export interface AssistantTurn {
+  role: "assistant";
+  id: string;
+  chatId: string;
+  streamingState: "streaming" | "complete";
+  /** Pointers into the data plane (`chatId:nodeId`), in arrival order. NOT copies. */
+  components: Pointer[];
+  /** Epoch ms when the response opened — the renderer formats it (e.g. "just now"). */
+  createdAt: number;
+}
+export type Turn = UserTurn | AssistantTurn;
+
+export interface ComponentInitEvent {
+  type: "COMPONENT_INIT";
+  chatId: string;
+  nodeId: string;
+  component: { type: string; componentUrl?: string; props?: Record<string, unknown> };
+}
+export interface ComponentDataEvent {
+  type: "COMPONENT_DATA";
+  chatId: string;
+  nodeId: string;
+  data: Record<string, unknown>;
+}
+export type UnoverseEvent = ComponentInitEvent | ComponentDataEvent;
+
+/** Lifecycle machine states (the workflow turn's status). */
+export type LifecycleState = "idle" | "thinking" | "streaming" | "complete" | "error";
+
+/** Stable empty slice for missing keys — never mutate. */
+const EMPTY_SLICE: Record<string, unknown> = Object.freeze({});
+
+export class ComponentStore {
+  // --- data plane ---
+  private data = new Map<string, Record<string, unknown>>();
+  private types = new Map<string, string>();
+  // --- timeline plane (pointers only) ---
+  private timeline: Turn[] = [];
+  // --- write recency per slice (monotonic seq stamped on every merge) — powers
+  //     ComponentSlot.select.where's "most recent state-write wins" ordering (§5b).
+  //     Generic bookkeeping: core stamps WHEN a slice changed, never reads WHAT. ---
+  private touches = new Map<string, number>();
+  /** Slices whose LATEST write was a guest interaction (`mergeComponentState`) — value is
+   *  that write's touch seq. Powers `pinned` layouts: guest writes move them, arrivals don't. */
+  private interactionTouches = new Map<string, number>();
+  private touchSeq = 0;
+  // --- shared ---
+  private listeners = new Set<() => void>();
+  private version = 0;
+  private structureVersion = 0;
+  private notifyScheduled = false;
+  private seq = 0;
+  // --- active template (the workflow-selected MCP app shell; §0.1) ---
+  private activeTemplateName: string | null = null;
+  private activeTemplateProps: Record<string, unknown> = {};
+  // --- template state: the active template's OWN generic bag (UNOVERSE_STATE_MODEL §2).
+  //     draft / suggestions / openPanel / focusedId / voice call state all live here as
+  //     plain keys — core knows NO key names. Replace/merge only (O(1), never append). ---
+  private templateState: Record<string, unknown> = {};
+  // --- history cap (UNOVERSE_STATE_MODEL §6a): hold at most N turns, oldest-out-first. ---
+  private maxTurns: number;
+
+  /** @param opts.maxTurns history cap (default 100; §6a). Channels may raise/lower it. */
+  constructor(opts?: { maxTurns?: number }) {
+    this.maxTurns = opts?.maxTurns ?? 100;
+  }
+
+  // ============ writes ============
+
+  /** The current composer draft (a key in template state). */
+  getDraft(): string {
+    return (this.templateState.draft as string) ?? "";
+  }
+  /** Set the composer draft (input onChange writes here; a send button reads it). */
+  setDraft(text: string): void {
+    if (this.getDraft() === text) return;
+    this.mergeTemplateState({ draft: text });
+  }
+
+  /** The workflow-selected template (MCP app shell) + its props, or null if the channel picks. */
+  getActiveTemplate(): { name: string | null; props: Record<string, unknown> } {
+    return { name: this.activeTemplateName, props: this.activeTemplateProps };
+  }
+  /**
+   * Switch the active template (a workflow "render this app" directive — a COMPONENT_INIT
+   * marked isTemplate). Templates are SERVED apps, never streamed components (protocol
+   * §0.1); this records WHICH app the channel should load, never a timeline component.
+   */
+  setActiveTemplate(name: string, props: Record<string, unknown> = {}): void {
+    if (this.activeTemplateName === name && JSON.stringify(this.activeTemplateProps) === JSON.stringify(props)) return;
+    // TEMPLATE SWAP = the hard refresh boundary: a NEW shell starts with every surface
+    // retired — every instance (durable ones included) returns to inline; the new
+    // template derives its base state. Conversation data stays untouched (turns +
+    // slices persist; only the active VIEW resets) — swapping back re-presents nothing
+    // until something surfaces again.
+    if (this.activeTemplateName !== null && this.activeTemplateName !== name) {
+      for (const [key, slice] of this.data) {
+        if (typeof slice.defaultState === "string" && slice.defaultState !== "inline") {
+          this.data.set(key, { ...slice, defaultState: "inline" });
+          this.touches.set(key, ++this.touchSeq);
+        }
+      }
+    }
+    this.activeTemplateName = name;
+    this.activeTemplateProps = props;
+    this.bump();
+  }
+
+  /**
+   * GUEST CLOSE — un-surface the active view: every non-inline slice returns to `inline`,
+   * so a name-synced layout retracts to its base (the ✕ on a rail/panel the guest didn't
+   * open a single card from). This is EXACTLY the new-turn reset (`beginExchange`), just
+   * triggered by a template close button instead of an arriving turn — same durable
+   * (`lifetime: "conversation"`) opt-out, no new vocabulary, nothing stored. The renderer
+   * calls this when a template-chrome `setValue defaultState:"inline"` fires (a card that
+   * closes ITSELF still uses the plain component write; template chrome has no card to hit).
+   */
+  closeSurfaces(): void {
+    let changed = false;
+    for (const [key, slice] of this.data) {
+      if (slice.lifetime === "conversation") continue;
+      if (typeof slice.defaultState === "string" && slice.defaultState !== "inline") {
+        this.data.set(key, { ...slice, defaultState: "inline" });
+        this.touches.set(key, ++this.touchSeq);
+        changed = true;
+      }
+    }
+    if (changed) this.bump();
+  }
+
+  /** The active template's state bag (templates read this into their root scope). */
+  getTemplateState(): Readonly<Record<string, unknown>> {
+    return this.templateState;
+  }
+  /** Merge a patch into template state (replace/merge — never append, stays O(1)). */
+  mergeTemplateState(patch: Record<string, unknown>): void {
+    this.templateState = { ...this.templateState, ...patch };
+    this.bump();
+  }
+
+  // ════════════════════════════════════════════════════════════════════════════
+  //  STATE HAS TWO HOMES, BY SCOPE (UNOVERSE_STATE_MODEL §2) — and the SDK hardcodes
+  //  NO UI concept (no panel / focus / faq / voice). The dev picks the key and the home:
+  //   • COMPONENT state — a component's own data + view state (tab / edit / wizard-step /
+  //     displayState / …), keyed by its id, written via the `setValue` action (data plane).
+  //   • TEMPLATE state — the active template's own bag (`templateState`), written via the
+  //     `setTemplateValue` action (or `mergeTemplateState` from a producer). Just keys.
+  //  `lifecycle` is the one thing that is NEITHER: it's READ OFF the conversation (the turn's
+  //  streaming/complete status), so it stays a tiny derived machine here. `draft` is the one
+  //  named convenience (the shared composer buffer the channel reads to send).
+  //  (Voice is a NATIVE SERVICE — WS audio lane, react package — whose call state a producer
+  //   merges into template state. Not a store machine.)
+  //  ⛔ Do NOT add a UI-pattern method here (togglePanel/openFocus/…). It's a key the dev
+  //     writes via setValue / setTemplateValue and reads via `visibleWhen`. Removed twice.
+  // ════════════════════════════════════════════════════════════════════════════
+
+  // --- lifecycle: the workflow turn's status (derived from WORKFLOW_STATE) ---
+  private lifecycleState: LifecycleState = "idle";
+
+  /** The conversation lifecycle status. */
+  getLifecycle(): LifecycleState {
+    return this.lifecycleState;
+  }
+  /** Move the lifecycle machine to a status (idempotent). */
+  setLifecycle(s: LifecycleState): void {
+    if (this.lifecycleState === s) return;
+    this.lifecycleState = s;
+    this.bump();
+  }
+
+  /** Apply a streamed event (COMPONENT_INIT or COMPONENT_DATA). */
+  apply(event: UnoverseEvent): void {
+    const key = `${event.chatId}:${event.nodeId}`;
+    if (event.type === "COMPONENT_INIT") {
+      this.types.set(key, event.component.type);
+      this.placeInTimeline(event.chatId, key); // structure: place the pointer ONCE
+      this.merge(key, event.component.props ?? {}); // data: seed
+    } else {
+      // NEW ACTIVITY reads newest-at-the-bottom: if this component is no longer the
+      // LAST pointer in its turn (something was placed after it), fresh server data
+      // moves it back to the end — e.g. answer text resuming AFTER an interactive
+      // component the workflow placed mid-turn. At most ONE structure bump per
+      // overtake; the streaming hot path (already last) stays data-only.
+      const resp = this.responseFor(event.chatId);
+      if (resp && resp.components.length > 1 && resp.components[resp.components.length - 1] !== key && resp.components.includes(key)) {
+        resp.components.splice(resp.components.indexOf(key), 1);
+        resp.components.push(key);
+        this.bump();
+      }
+      this.merge(key, event.data);
+    }
+  }
+
+  /** Append a user message turn. Response identity = its chatId. */
+  addUserMessage(chatId: string, text: string): void {
+    this.timeline.push({ role: "user", id: `u${this.seq++}`, chatId, text, createdAt: Date.now() });
+    this.beginExchange();
+    this.evict();
+    this.bump();
+  }
+
+  /**
+   * TWO LIFETIMES, ONE STORE (docs/design/04): CONVERSATION state (turns + each
+   * instance's data — durable, append-only, the stream owns it) vs CHAT state (the
+   * present interaction: each instance's active VIEW, the template's chrome). A new
+   * user turn advances the conversation, so the chat layer returns to its universal
+   * default: every instance goes back to `inline` — surfaces empty, the template
+   * derives its base state, panels retract. Data is untouched; history keeps every
+   * card. (A future durable, conversation-scoped component — a cart, an itinerary —
+   * will opt out of this explicitly; today nothing does.)
+   */
+  private beginExchange(): void {
+    for (const [key, slice] of this.data) {
+      // DURABLE conversation-scoped surface (docs/design/04 §Two lifetimes): the
+      // producer marked the slice `lifetime: "conversation"` (a cart, an itinerary,
+      // a composed page) — it opted out of the new-turn reset and stays surfaced
+      // until replaced, closed, or the template swaps. Generic: a key the producer
+      // wrote, not a UI concept.
+      if (slice.lifetime === "conversation") continue;
+      if (typeof slice.defaultState === "string" && slice.defaultState !== "inline") {
+        this.data.set(key, { ...slice, defaultState: "inline" });
+        this.touches.set(key, ++this.touchSeq);
+      }
+    }
+  }
+
+  /**
+   * Open (or re-open) the assistant response for chatId in streaming state, WITHOUT
+   * attaching a component. Mirrors legacy WORKFLOW_STARTED (processWorkflowState.ts):
+   * it creates the EMPTY streaming turn so the timeline shows a "thinking" state in
+   * the window BEFORE the first component arrives. The first COMPONENT_INIT then
+   * reuses this same turn (responseFor matches by chatId). Idempotent.
+   */
+  startResponse(chatId: string): void {
+    const resp = this.responseFor(chatId);
+    if (!resp) {
+      this.timeline.push({ role: "assistant", id: `a${this.seq++}`, chatId, streamingState: "streaming", components: [], createdAt: Date.now() });
+      this.evict();
+      this.bump();
+    } else if (resp.streamingState !== "streaming") {
+      resp.streamingState = "streaming";
+      this.bump();
+    }
+  }
+
+  /** Mark the assistant response for this chatId complete (e.g. on workflow-completed). */
+  completeResponse(chatId: string): void {
+    const resp = this.responseFor(chatId);
+    if (resp && resp.streamingState !== "complete") {
+      resp.streamingState = "complete";
+      this.bump();
+    }
+  }
+
+  /** Place a component pointer into the open assistant turn for chatId (lazily creating it). */
+  private placeInTimeline(chatId: string, key: Pointer): void {
+    let resp = this.responseFor(chatId);
+    if (!resp) {
+      // Born COMPLETE: only lifecycle events (startResponse) open a STREAMING turn. A
+      // turn lazily created just to hold an arriving component (e.g. a conversation-keyed
+      // durable render) is not a spoken reply — no completion event will ever match its
+      // chatId, so born-streaming left it as an eternal thinking bubble. If a real
+      // lifecycle start for this id follows, startResponse flips it to streaming.
+      resp = { role: "assistant", id: `a${this.seq++}`, chatId, streamingState: "complete", components: [], createdAt: Date.now() };
+      this.timeline.push(resp);
+      this.evict();
+    }
+    if (!resp.components.includes(key)) resp.components.push(key);
+    this.bump();
+  }
+
+  private responseFor(chatId: string): AssistantTurn | undefined {
+    // Response identity is the chatId — all components of one turn share it.
+    for (let i = this.timeline.length - 1; i >= 0; i--) {
+      const t = this.timeline[i];
+      if (t.role === "assistant" && t.chatId === chatId) return t;
+    }
+    return undefined;
+  }
+
+  /** Trim the timeline to the last `maxTurns`, deleting the component slices the dropped
+   *  turns pointed at so the data/types maps can't leak (UNOVERSE_STATE_MODEL §6a). */
+  private evict(): void {
+    while (this.timeline.length > this.maxTurns) {
+      const dropped = this.timeline.shift();
+      if (dropped?.role === "assistant") {
+        for (const ptr of dropped.components) {
+          this.data.delete(ptr);
+          this.types.delete(ptr);
+          this.touches.delete(ptr);
+          this.interactionTouches.delete(ptr);
+        }
+      }
+    }
+  }
+
+  private merge(key: string, patch: Record<string, unknown>): void {
+    // merge-not-replace. Fresh object identity per merge = the per-slice snapshot
+    // React bindings key on (useSyncExternalStore bails out for untouched slices).
+    this.data.set(key, { ...(this.data.get(key) ?? {}), ...patch });
+    this.touches.set(key, ++this.touchSeq);
+    this.bumpData();
+  }
+
+  /**
+   * LOCAL interaction write into a component's own slice (the `setValue` action).
+   * Same merge as inbound COMPONENT_DATA, but STRUCTURE-bumps: slot selection
+   * (`ComponentSlot.select.where`) reads component state, and templates subscribe to
+   * structure only — a click that changes a component's state must re-resolve the
+   * template's slots. Low-frequency (a click, not a token stream), so the synchronous
+   * notify is fine.
+   */
+  mergeComponentState(chatId: string, nodeId: string, patch: Record<string, unknown>): void {
+    const key = `${chatId}:${nodeId}`;
+    this.data.set(key, { ...(this.data.get(key) ?? {}), ...patch });
+    this.touches.set(key, ++this.touchSeq);
+    // Remember that this slice's LATEST write came through the guest's hand — the one
+    // fact `pinned` layouts need: a pinned layout yields to guest writes, never to
+    // background arrivals (which land via `merge` and don't stamp this).
+    this.interactionTouches.set(key, this.touchSeq);
+    this.bump();
+  }
+
+  /** The touch seq of this slice's last GUEST write (`setValue`), or -1 if the latest
+   *  activity was a server arrival. Compare with `touchOf`: equal ⇒ the guest wrote last. */
+  interactionTouchOf(pointer: string): number {
+    return this.interactionTouches.get(pointer) ?? -1;
+  }
+
+  /**
+   * STRUCTURE bump — timeline placement, template state, lifecycle. Low-frequency
+   * and often interaction-driven (composer draft), so listeners fire synchronously.
+   */
+  private bump(): void {
+    this.version++;
+    this.structureVersion++;
+    this.notify();
+  }
+
+  /**
+   * DATA bump — COMPONENT_DATA merges, the per-chunk streaming hot path. A token
+   * stream can deliver hundreds of events/sec; notifying per event drives one React
+   * render pass each. State is updated synchronously (reads are always fresh) but
+   * listener notification coalesces to once per animation frame (display rate),
+   * falling back to a macrotask outside the DOM. useSyncExternalStore is safe with
+   * deferred notify — it re-reads the snapshot when the notification lands.
+   */
+  private bumpData(): void {
+    this.version++;
+    if (this.notifyScheduled) return;
+    this.notifyScheduled = true;
+    const flush = () => {
+      this.notifyScheduled = false;
+      this.notify();
+    };
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(flush);
+    else setTimeout(flush, 0);
+  }
+
+  private notify(): void {
+    this.listeners.forEach((l) => l());
+  }
+
+  // ============ reads — data plane (unchanged API; streamed.tsx depends on these) ============
+
+  get(chatId: string, nodeId: string): Record<string, unknown> {
+    // EMPTY (module-stable) for missing keys — a fresh {} per call would make a
+    // snapshot-based useSyncExternalStore loop forever.
+    return this.data.get(`${chatId}:${nodeId}`) ?? EMPTY_SLICE;
+  }
+  getType(chatId: string, nodeId: string): string | undefined {
+    return this.types.get(`${chatId}:${nodeId}`);
+  }
+  getVersion(): number {
+    return this.version;
+  }
+  /** Bumped only by timeline/template-state/lifecycle changes — what templates subscribe to.
+   *  COMPONENT_DATA merges don't touch it, so streaming chunks never re-render the template. */
+  getStructureVersion(): number {
+    return this.structureVersion;
+  }
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+
+  // ============ reads — timeline plane (what templates iterate) ============
+
+  /** The full conversation, in order. */
+  getTimeline(): readonly Turn[] {
+    return this.timeline;
+  }
+  /** Just the assistant responses, in order. */
+  getResponses(): AssistantTurn[] {
+    return this.timeline.filter((t): t is AssistantTurn => t.role === "assistant");
+  }
+  /** The most recent assistant response (KeyService-style single-response layouts). */
+  latestResponse(): AssistantTurn | undefined {
+    const r = this.getResponses();
+    return r[r.length - 1];
+  }
+  /** Resolve a pointer back to its parts (for handing to the leaf renderer). */
+  split(pointer: Pointer): { chatId: string; nodeId: string } {
+    const i = pointer.indexOf(":");
+    return { chatId: pointer.slice(0, i), nodeId: pointer.slice(i + 1) };
+  }
+  /** Type of the component a pointer refers to (for filter-by-type in templates). */
+  typeOf(pointer: Pointer): string | undefined {
+    return this.types.get(pointer);
+  }
+  /** Write-recency of a slice (monotonic seq; 0 = never written). Powers the
+   *  `select.where` most-recent-wins ordering — last writer wins, like any store. */
+  touchOf(pointer: Pointer): number {
+    return this.touches.get(pointer) ?? 0;
+  }
+}