@unoverse-platform/studio 0.1.25 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/screens/SourceView.tsx

@@ -432,7 +432,7 @@ export function SourceView({
         /**
          * TWO FILE SHAPES, TWO WAYS IN.
          *
-         * An ENVELOPE (`coursecard.yaml`) holds its tree under `root:`, and that tree IS
+         * An ENVELOPE (`course-card.yaml`) holds its tree under `root:`, and that tree IS
          * the composed root, so the file path maps by dropping one level. A PARTIAL (a
          * layout) is a bare node included somewhere inside the composed tree, so it has to
          * be found first. Treating everything as a partial meant an envelope never matched

package/screens/TemplatesView.tsx

@@ -112,7 +112,7 @@ interface Def {
     autoTrigger?: boolean;
     default?: boolean;
     inputSchema?: Record<string, unknown>;
-    // Per-STATE mock seeding: `{ "<state>": ["coursecard", "coursecard"] }` — the
+    // Per-STATE mock seeding: `{ "<state>": ["course-card", "course-card"] }` — the
     // author decides what each state's preview shows (a repeated name = several
     // instances). Supersedes the legacy flat `previewComponents`.
     // Per-state mock: an ARRAY seeds components; an OBJECT is authored template-state
@@ -468,7 +468,7 @@ export function TemplatesView({
   // what a real arrival-in-focus or a component's own expand button would do.
   function seed(comps: Def[]) {
     // nodeId is per-INSTANCE (`name-i`), so previewComponents may repeat a name to
-    // seed several instances — e.g. ["coursecard", "coursecard"] previews a rail of cards.
+    // seed several instances — e.g. ["course-card", "course-card"] previews a rail of cards.
     comps.forEach((c, i) =>
       store.apply({
         type: "COMPONENT_INIT",

package/src/PublishDialog.tsx

@@ -122,7 +122,7 @@ export function PublishDialog({
    * own status, and the statuses sort so the ones that will move sit at the top.
    *
    * The kind is singular here, because a row is one thing. `bpp` is a style set and
-   * `bppchatlayout` is an app; without that word they read as five apps, which is how a
+   * `bpp-chat-layout` is an app; without that word they read as five apps, which is how a
    * developer concludes their components were never collected when they were.
    */
   const KIND_LABEL: Record<string, string> = {

package/vendor/sdk/appEngine.tsx

@@ -17,6 +17,9 @@ import {
   useUnoverseTheme,
   computeAppWidth,
   resolveActiveLayout,
+  setAnalyticsSink,
+  setAnalyticsContext,
+  setAnalyticsDebug,
   type UseVoiceServiceConfig,
 } from "./lib";
 
@@ -27,10 +30,17 @@ 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(), []);
   const client = useMemo(
@@ -80,6 +90,21 @@ 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

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

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,17 @@ export {
 // The action interpreter (§2e-3) — local `setValue` store write + server route.
 export { dispatchAction, resolveValue, type ActionContext } from "./actions";
 
+// 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/types.ts

@@ -5,6 +5,17 @@
  * SHAPE (values live on the server). Pure types — no runtime, no imports.
  */
 
+/** Report an interaction to the host's analytics (UNOVERSE_ANALYTICS.md). Declared on a
+ *  node beside its `action`. The SDK produces the event and knows nothing about where it
+ *  goes: no vendor, no destination, no identity appears in this shape. */
+export interface AnalyticsSpec {
+  /** The event name. A GA4 standard name where one fits, else `unoverse_`-prefixed. */
+  event: string;
+  /** Sent with it. `{{path}}` resolves against the data scope at the interaction site,
+   *  the same binding an action's `values` already use. */
+  params?: Record<string, unknown>;
+}
+
 // ---- The neutral definition shape (mirrors apps/unoverse/definitions/*.json) ----
 
 export interface UnoverseNode {
@@ -13,6 +24,11 @@ export interface UnoverseNode {
   bind?: Record<string, string>; // target prop -> data field
   visibleWhen?: VisibleWhen; // render only when the condition holds (truthy field, or {field,eq/ne})
   action?: string | ActionSpec; // dispatched on interaction (bare string → server, or a setValue envelope)
+  /** Report this interaction to the host's analytics (UNOVERSE_ANALYTICS.md). Opt-in per
+   *  node: no block, no event. Sits beside `action` because each interaction carries its
+   *  own params, drawn from the data already in scope right here. The SDK only produces
+   *  the event; where it goes is the channel's business. */
+  analytics?: AnalyticsSpec;
   placeholder?: string; // Input: empty-field copy (content, not style)
   /** Box: keep the scroll pinned to the newest content — smooth-scroll to the end when
    *  content grows (new turn or streaming text), unless the user has scrolled up. Generic
@@ -136,6 +152,10 @@ export interface ActionSpec {
   values?: ActionValue[]; // setValue / setTemplateValue patches (the dev's chosen keys)
   send?: string[]; // server route: which scope fields to include (default: all)
   then?: ActionSpec | string; // optional chained follow-up
+  /** Carried here by the renderer, NOT authored on the action: a node declares
+   *  `analytics:` beside `action:`, and the leaf attaches it so the ONE interpreter
+   *  (`dispatchAction`) stays the only place an interaction is understood. */
+  analytics?: AnalyticsSpec;
 }
 
 /** A data condition, evaluated against the render data scope. Pick ONE test:

package/vendor/sdk/lib/index.ts

@@ -30,6 +30,11 @@ export {
   matches,
   visible,
   selectCase,
+  emitAnalytics,
+  setAnalyticsSink,
+  setAnalyticsContext,
+  setAnalyticsDebug,
+  resolveAnalyticsParams,
 } from "./core";
 export type {
   ResolvedTheme,
@@ -56,4 +61,8 @@ export type {
   ServerWorkflowState,
   ServerTemplateData,
   ServerSessionReady,
+  AnalyticsSpec,
+  AnalyticsEvent,
+  AnalyticsContext,
+  AnalyticsSink,
 } from "./core";

package/vendor/sdk/lib/primitives.tsx

@@ -23,7 +23,7 @@ import { createElement, useEffect, useMemo, useRef, useState, type CSSProperties
 import Markdown from "markdown-to-jsx";
 import type { ResolvedTheme, UnoverseNode } from "./core";
 import { styleToCss, cssDecls } from "./style";
-import type { ActionHandler } from "./render";
+import { nodeAction, type ActionHandler } from "./render";
 
 /** Read a bound data field as a string (for Text/Image/Button content). */
 function bound(field: string | undefined, data: Record<string, unknown>): string | undefined {
@@ -332,7 +332,7 @@ export function ImageView({ node, data, theme }: { node: UnoverseNode; data: Rec
 export function ButtonView({ node, data, theme, onAction, children }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; onAction?: ActionHandler; children?: ReactNode }): ReactNode {
   const { className, styleEls, style, disabled } = nodeChrome(node, data, theme);
   return (
-    <button className={className} style={style} disabled={disabled} data-unoverse-id={inspectId(node)} onClick={() => onAction?.(node.action ?? "click", data)}>
+    <button className={className} style={style} disabled={disabled} data-unoverse-id={inspectId(node)} onClick={() => onAction?.(nodeAction(node, "click"), data)}>
       {styleEls}
       {node.children?.length ? children : bound(node.bind?.label, data)}
     </button>
@@ -507,7 +507,7 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
   const submit = () => {
     const t = value.trim();
     if (!t) return;
-    onAction?.(node.action ?? "submit", { text: t });
+    onAction?.(nodeAction(node, "submit"), { text: t });
     if (field == null) setLocal("");
   };
   const { style, disabled } = nodeChrome(node, data, theme);

package/vendor/sdk/lib/render.tsx

@@ -57,6 +57,22 @@ export interface ActionMeta {
 
 export type ActionHandler = (action: string | ActionSpec, data: Record<string, unknown>, meta?: ActionMeta) => void;
 
+/**
+ * A leaf's action, with the node's declared `analytics` attached (UNOVERSE_ANALYTICS.md).
+ *
+ * Authors write `analytics:` beside `action:` on the node, where the data it reports is
+ * already in scope. The two travel together from here so `dispatchAction` remains the ONE
+ * place an interaction is understood: leaves stay dumb, and no leaf can forget to report.
+ * A node with no `analytics` block passes its action through untouched, unallocated.
+ */
+export function nodeAction(node: UnoverseNode, fallback: string): string | ActionSpec {
+  const action = node.action ?? fallback;
+  if (!node.analytics?.event) return action;
+  return typeof action === "string"
+    ? { type: action, analytics: node.analytics }
+    : { ...action, analytics: node.analytics };
+}
+
 /**
  * Resolves a `ComponentSlot` node against the store (provided by the template
  * renderer). Returns the rendered leaves (or the slot's fallback). Components

package/vendor/sdk/main.tsx

@@ -29,6 +29,13 @@ function render() {
       templateId={current.templateId}
       userId={current.userId}
       conversationId={current.conversationId}
+      // ANALYTICS (UNOVERSE_ANALYTICS.md). Host-supplied: the same bundle boots inside a
+      // customer's page, our own client, and an MCP app host, and it cannot tell which
+      // from in here. A host that says nothing gets `mcp_app_host`, the one surface with
+      // no parent page to report to, so an unconfigured boot reports as the surface where
+      // events go nowhere rather than mislabelling itself as a customer embed.
+      surface={current.surface ?? "mcp_app_host"}
+      analyticsDebug={current.analyticsDebug}
       // Only claim auth when the host actually sent a token. A fabricated accessor on a
       // tokenless boot made the SDK skip its guest-id substitution (connection.tsx), so
       // the session registered a non-guest id and the public-entry gate refused it.