@unoverse-platform/studio 0.1.25 → 0.1.27

package/vendor/sdk/appEngine.tsx

@@ -17,6 +17,9 @@ import {
   useUnoverseTheme,
   computeAppWidth,
   resolveActiveLayout,
+  setAnalyticsSink,
+  setAnalyticsContext,
+  setAnalyticsDebug,
   type UseVoiceServiceConfig,
 } from "./lib";
 
@@ -27,12 +30,24 @@ export interface AppConfig {
   getAccessToken?: () => Promise<string | null> | string | null;
   userId?: string;
   conversationId: string;
+  /** Where this app is running, reported on every analytics event
+   *  (UNOVERSE_ANALYTICS.md §surfaces). Host-supplied: the app cannot know which frame
+   *  it was placed in. */
+  surface?: string;
+  /** Log each analytics event as it fires. Server-delivered with the rest of the tenant
+   *  config, never a client-side flag someone can turn on against a live site. */
+  analyticsDebug?: boolean;
 }
 
 export function AppEngine(cfg: AppConfig) {
-  const { serverUrl, apiUrl, templateId, getAccessToken, userId, conversationId } = cfg;
+  const { serverUrl, apiUrl, templateId, getAccessToken, userId, conversationId, surface, analyticsDebug } = cfg;
 
-  const store = useMemo(() => new ComponentStore(), []);
+  // ONE STORE PER CONVERSATION. The host may reuse this engine (the native-host
+  // iframe posts new config on app switch), and a template swap keeps the store by
+  // law (the template owns nothing) — but a CONVERSATION swap must not: carrying the
+  // old timeline across conversations rendered one app's history inside another's
+  // shell (observed live, 2026-08-08: one org's chat inside another org's app).
+  const store = useMemo(() => new ComponentStore(), [userId, conversationId]);
   const client = useMemo(
     () => new UnoverseClient(`${serverUrl}/mcp`, { getAccessToken: getAccessToken as any }),
     [serverUrl],
@@ -80,11 +95,26 @@ export function AppEngine(cfg: AppConfig) {
   // inbound `unoverse:config` channel), re-reporting whenever a panel surface opens or
   // closes: the app grows by the panel's declared width, then shrinks back. The host
   // animates the resize. Only posts on an ACTUAL width change (guard).
+  // ANALYTICS (UNOVERSE_ANALYTICS.md). The SDK produces events and knows no destination;
+  // this is the pipe out. Events cross to the HOST REALM, where the page's own analytics
+  // tag lives with the visitor's cookie and consent state already resolved — which is the
+  // whole reason measurement runs client-side rather than from a server that cannot read
+  // either. With no parent (a first-party page, an MCP app host) the post is a silent
+  // no-op, so a surface with nothing to report to costs nothing.
+  useEffect(() => {
+    setAnalyticsDebug(!!analyticsDebug);
+    setAnalyticsContext({ surface, conversation_id: conversationId, user_id: userId });
+    setAnalyticsSink((event) => {
+      window.parent?.postMessage({ type: "unoverse:event", ...event }, "*");
+    });
+    return () => setAnalyticsSink(null);
+  }, [surface, conversationId, userId, analyticsDebug]);
+
   useEffect(() => {
     const report = () => {
       // NAME-SYNC: width is computed off the ACTIVE layout (multi-layout templates
       // swap whole arrangements); single-layout defs resolve to their root.
-      const w = computeAppWidth(resolveActiveLayout(def as never, store), store, theme?.appSize);
+      const w = computeAppWidth(resolveActiveLayout(def as never, store), store, theme?.appSize, def as never);
       if (w && w !== lastWidthRef.current) {
         lastWidthRef.current = w;
         window.parent?.postMessage({ type: "unoverse:size", width: w }, "*");
@@ -111,6 +141,17 @@ export function AppEngine(cfg: AppConfig) {
     { enabled: !!userId && !!binding.workflow },
   );
 
+  // STATUS TO THE HOST. In native-host mode the iframe owns the only real
+  // connection, so a host badge watching its own (never-opened) in-page connection
+  // reads "offline" forever while this session streams (observed live). Report the
+  // truth the same way size is reported; hosts that don't listen lose nothing.
+  useEffect(() => {
+    window.parent?.postMessage(
+      { type: "unoverse:status", ready: !!conn.isReady, connected: !!conn.isConnected },
+      "*",
+    );
+  }, [conn.isReady, conn.isConnected]);
+
   // VOICE (§2e-1): a `service: "voice"` app runs the native voice service — which now lives
   // in the shared renderer (StreamedUnoverseTemplate), identical to Studio. The host only
   // supplies the connection identity it already holds; startCall/endCall/toggleMute are

package/vendor/sdk/lib/UnoverseComponent.tsx

@@ -38,7 +38,7 @@ export function useUnoverseInstance(store?: ComponentStore, chatId = "", nodeId
 
 export interface UnoverseComponentProps {
   client: UnoverseClient;
-  /** STATIC source: the definition to render, e.g. "unoverse://components/Card". */
+  /** STATIC source: the definition to render, e.g. "unoverse://components/card". */
   uri?: string;
   /** STATIC source: instance data bound into the definition. */
   data?: Record<string, unknown>;

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

@@ -9,6 +9,7 @@
  * `{{binding}}` resolution, an optional chained `then`, and a hard split between
  * LOCAL `setValue` and a server route for anything computed/transactional.
  */
+import { emitAnalytics, resolveAnalyticsParams } from "./analytics";
 import type { ComponentStore } from "./store";
 import type { ActionSpec } from "./types";
 
@@ -44,6 +45,15 @@ export function dispatchAction(
   if (action == null) return;
   const spec: ActionSpec = typeof action === "string" ? { type: action } : action;
 
+  // ANALYTICS FIRST, and unconditionally. Reporting must not depend on what the action
+  // then does, nor on it succeeding: an interaction that happened is news whether or not
+  // the write, the route or the chained `then` works out. This is also why it is here and
+  // not in a leaf — one interpreter sees every interaction, so an event cannot be missed
+  // by an author writing an unusual definition.
+  if (spec.analytics?.event) {
+    emitAnalytics(spec.analytics.event, resolveAnalyticsParams(spec.analytics, scope, resolveValue));
+  }
+
   if (spec.type === "setValue") {
     // Write the dev's chosen keys into THIS COMPONENT's OWN slice (chatId:nodeId) — its own
     // view state: tab / edit / wizard-step / displayState / anything. Read back via
@@ -53,12 +63,16 @@ export function dispatchAction(
     // Structure-bumping write (not the deferred COMPONENT_DATA path): templates re-resolve
     // their `select.where` slots the moment a component changes its own state (§5b).
     ctx.store.mergeComponentState(ctx.chatId, ctx.nodeId, patch);
-    // A CHANGED LAYOUT IS NEWS. `defaultState` is the view a component is showing, so a
-    // write to it means this instance just entered a different face — the moment an
-    // `onEnterView` hook exists for. Reported on the channel path every other server
-    // action already uses; the server decides whether any hook cares. Nothing to author:
-    // the setValue already carries the fact, so no component repeats it in a `then`.
-    if (ctx.nodeId && "defaultState" in patch) ctx.sendToServer?.("viewEntered", { layout: patch.defaultState });
+    // A CHANGED VIEW IS NEWS. The public axis (`view`, legacy alias `defaultState`) is
+    // the state a component is showing, so a write to it means this instance just
+    // entered a different state — the moment an `onEnterView` hook exists for. Reported
+    // on the channel path every other server action uses; the server decides whether
+    // any hook cares. The payload carries both spellings during the migration (the
+    // server's lifecycle scope historically read `layout`).
+    if (ctx.nodeId && ("view" in patch || "defaultState" in patch)) {
+      const entered = patch.view ?? patch.defaultState;
+      ctx.sendToServer?.("viewEntered", { layout: entered, view: entered });
+    }
   } else if (spec.type === "setTemplateValue") {
     // Write the dev's chosen keys into TEMPLATE state — the template-state twin of setValue.
     // No component scope. The dev builds disclosure / focus / etc. from a key THEY name

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

@@ -0,0 +1,89 @@
+/**
+ * Experience analytics — the emit side (docs/unoverse/UNOVERSE_ANALYTICS.md).
+ *
+ * The SDK produces events and knows NOTHING about where they go. No GA, no gtag, no
+ * dataLayer, no vendor of any kind appears here. A host registers a sink; without one
+ * every emit is a no-op, which is what makes a preview, a test, or an MCP app host with
+ * no page to report to cost nothing.
+ *
+ * Events are NEWS, never instruction: nothing downstream may branch on one. The trigger
+ * originates in a browser the visitor controls, so a path that could act on an event
+ * would be a path a visitor could drive.
+ */
+
+import type { AnalyticsSpec } from "./types";
+
+/** What a sink receives. `context` is the platform's own vocabulary, kept separate from
+ *  the author's `params` so the two can never collide on a key. */
+export interface AnalyticsEvent {
+  event: string;
+  params: Record<string, unknown>;
+  context: AnalyticsContext;
+}
+
+export interface AnalyticsContext {
+  /** Where this is running: `unoverse_assistant` | `unoverse_client` | `mcp_app_host`. */
+  surface?: string;
+  /** The journey key. The SAME id the chat, the session and agent memory use. */
+  conversation_id?: string;
+  user_id?: string;
+}
+
+export type AnalyticsSink = (event: AnalyticsEvent) => void;
+
+let sink: AnalyticsSink | null = null;
+let context: AnalyticsContext = {};
+let debug = false;
+
+/** Registered by the host (the channel), which owns identity and the destination.
+ *  Passing null removes it, so a torn-down host stops receiving. */
+export function setAnalyticsSink(next: AnalyticsSink | null): void {
+  sink = next;
+}
+
+/** Session facts, supplied once by the channel. The SDK never invents them. */
+export function setAnalyticsContext(next: AnalyticsContext): void {
+  context = { ...context, ...next };
+}
+
+/** Server-delivered, never a client-side flag: log each event as it fires. */
+export function setAnalyticsDebug(next: boolean): void {
+  debug = next;
+}
+
+/**
+ * Emit one event. Failure is SILENT and CLOSED: a throwing sink never breaks a render
+ * and never blocks the interaction that produced it.
+ */
+export function emitAnalytics(event: string, params?: Record<string, unknown>): void {
+  if (!event) return;
+  const payload: AnalyticsEvent = { event, params: params ?? {}, context: { ...context } };
+  // Matches the platform's existing log convention (`[unoverse:lifecycle] …`), so one
+  // console filter catches it among a host page's own noise.
+  if (debug) console.log(`[unoverse:analytics] ${event}`, payload.params, payload.context);
+  if (!sink) return;
+  try {
+    sink(payload);
+  } catch (err) {
+    console.warn(`[unoverse:analytics] sink failed for ${event}: ${(err as Error)?.message ?? err}`);
+  }
+}
+
+/**
+ * Resolve a declared `params` block against the data scope at the interaction site,
+ * using the SAME `{{path}}` binding an action's values already use. Keys resolving to
+ * `undefined` are dropped rather than sent as empty, so an absent field is absent in the
+ * report instead of arriving as a misleading blank.
+ */
+export function resolveAnalyticsParams(
+  spec: AnalyticsSpec | undefined,
+  scope: Record<string, unknown>,
+  resolve: (value: unknown, scope: Record<string, unknown>) => unknown,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(spec?.params ?? {})) {
+    const v = resolve(value, scope);
+    if (v !== undefined && v !== null && v !== "") out[key] = v;
+  }
+  return out;
+}

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

@@ -114,7 +114,7 @@ export class UnoverseClient {
     return this.withSession(() => this.client.callTool({ name, arguments: args }));
   }
 
-  /** resources/read a definition by URI (e.g. unoverse://components/Card). Cached. */
+  /** resources/read a definition by URI (e.g. unoverse://components/card). Cached. */
   async readDefinition(uri: string): Promise<UnoverseDefinition> {
     const cached = this.cache.get(uri);
     if (cached) return cached;

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

@@ -28,5 +28,35 @@ export {
 // The action interpreter (§2e-3) — local `setValue` store write + server route.
 export { dispatchAction, resolveValue, type ActionContext } from "./actions";
 
+// The pure template-tier derivations (STATE_MODEL v2: the stateOrder ladder, state-
+// owns-layout resolution, the pinned law, slot selection, claimed views, app width).
+// Framework-agnostic — the React binding (template.tsx) and every platform port call
+// these, never re-derive them.
+export {
+  collectSurfacedViews,
+  computeAppWidth,
+  cssWidth,
+  formatRelative,
+  isViewField,
+  orderedClaims,
+  propDefaults,
+  resolveActiveLayout,
+  resolveActiveView,
+  selectPointers,
+  viewOf,
+} from "./templates";
+
+// Experience analytics (UNOVERSE_ANALYTICS.md) — the SDK emits; the host decides where to.
+export {
+  emitAnalytics,
+  setAnalyticsSink,
+  setAnalyticsContext,
+  setAnalyticsDebug,
+  resolveAnalyticsParams,
+  type AnalyticsEvent,
+  type AnalyticsContext,
+  type AnalyticsSink,
+} from "./analytics";
+
 // The shared "react to state" predicate (visibleWhen / Switch / style.when).
 export { matches, visible, selectCase } from "./conditions";

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

@@ -102,6 +102,26 @@ export class ComponentStore {
     this.maxTurns = opts?.maxTurns ?? 100;
   }
 
+  /**
+   * RETRACT ONE SLICE to its declared base (STATE_MODEL v2 §8 item 6). The public
+   * axis is `view` with `defaultState` as the legacy alias; the retract target is the
+   * slice's declared initial (`initialView`, seeded at spawn) falling back to
+   * `"inline"` (the universal fallback). Returns true when the slice changed. This is
+   * the ONE home for the reset every boundary uses (new turn, guest close, template
+   * swap) — never re-hardcode `"inline"` at a call site.
+   */
+  private retractSlice(key: string, slice: Record<string, unknown>): boolean {
+    const current = (slice.view ?? slice.defaultState) as unknown;
+    const base = typeof slice.initialView === "string" ? slice.initialView : "inline";
+    if (typeof current !== "string" || current === base) return false;
+    const next: Record<string, unknown> = { ...slice };
+    if ("view" in next || !("defaultState" in next)) next.view = base;
+    if ("defaultState" in next) next.defaultState = base;
+    this.data.set(key, next);
+    this.touches.set(key, ++this.touchSeq);
+    return true;
+  }
+
   // ============ writes ============
 
   /** The current composer draft (a key in template state). */
@@ -131,12 +151,7 @@ export class ComponentStore {
     // 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);
-        }
-      }
+      for (const [key, slice] of this.data) this.retractSlice(key, slice);
     }
     this.activeTemplateName = name;
     this.activeTemplateProps = props;
@@ -152,15 +167,40 @@ export class ComponentStore {
    * 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).
    */
+  /**
+   * ARRIVALS REFRESH THEIR STATE (THE SEVEN RULES, 2026-08-09, rule 5): when a
+   * component ARRIVES into state X (a server placement — never a guest write),
+   * components from EARLIER turns sitting in X retract to inline. New cards
+   * replace the rail's old cards; a new wizard replaces the old wizard — latest
+   * wins, at every rung. Same-turn siblings coexist (one answer's card set is one
+   * delivery, so eviction is keyed by TURN, not by instance). Durable
+   * (`lifetime: "conversation"`) slices opt out, as with every retract. Whether a
+   * refresh is VISIBLE is the ladder's business alone (rule 4: higher states mask;
+   * lower states update silently underneath).
+   */
+  private supersede(arrivingChatId: string, view: unknown): void {
+    if (typeof view !== "string" || !view || view === "inline") return;
+    let changed = false;
+    for (const [key, slice] of this.data) {
+      if (key.startsWith(`${arrivingChatId}:`)) continue; // same turn = same delivery
+      if (slice.lifetime === "conversation") continue;
+      const v = (slice.view ?? slice.defaultState) as unknown;
+      if (v !== view) continue;
+      const next: Record<string, unknown> = { ...slice };
+      if ("view" in next || !("defaultState" in next)) next.view = "inline";
+      if ("defaultState" in next) next.defaultState = "inline";
+      this.data.set(key, next);
+      this.touches.set(key, ++this.touchSeq);
+      changed = true;
+    }
+    if (changed) this.bump();
+  }
+
   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 (this.retractSlice(key, slice)) changed = true;
     }
     if (changed) this.bump();
   }
@@ -212,6 +252,9 @@ export class ComponentStore {
       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
+      // Rule 5 — an arrival carrying a public state refreshes that state.
+      const seeded = event.component.props as Record<string, unknown> | undefined;
+      this.supersede(event.chatId, seeded?.view ?? seeded?.defaultState);
     } 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
@@ -225,42 +268,26 @@ export class ComponentStore {
         this.bump();
       }
       this.merge(key, event.data);
+      // Rule 5 — a server data-write that PLACES a component into a public state
+      // (the host's arrival placement rides COMPONENT_DATA) refreshes that state.
+      this.supersede(event.chatId, (event.data as Record<string, unknown> | undefined)?.view ?? (event.data as Record<string, unknown> | undefined)?.defaultState);
     }
   }
 
-  /** Append a user message turn. Response identity = its chatId. */
+  /** Append a user message turn. Response identity = its chatId.
+   *
+   *  RULE 7 (the seven rules, 2026-08-09): typing changes NOTHING by itself. The
+   *  old new-turn reset (`beginExchange`, the "two lifetimes" chat-layer wipe) is
+   *  GONE — only arrivals move the screen (rule 5's same-state refresh) and only
+   *  closings release it (rule 6's ladder re-look). A wizard mid-flow survives the
+   *  guest's next message; a stale rail is cleared by the cards that replace it,
+   *  never by the message that asked for them. */
   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):