@unoverse-platform/studio 0.1.0

package/vendor/sdk/lib/connection.tsx

@@ -0,0 +1,302 @@
+/**
+ * useUnoverseConnection — the CHANNEL's data-plane connector (MCP stream).
+ *
+ * Opens the live workflow connection to the Unoverse server's `/stream` MCP endpoint
+ * (Streamable-HTTP SSE) for the inbound component stream, and REST `…/execute` for
+ * sending messages. Inbound `notifications/unoverse/event` messages feed the single
+ * `ComponentStore` via the pure `applyServerMessage` mapper.
+ *
+ * Per UNOVERSE_MCP_TEMPLATE_PROTOCOL.md §5/§5a/§5b: the component stream rides MCP
+ * (NOT the legacy `/ws/gravity` WS — that's reserved for live audio). The node
+ * executes in the same Unoverse process that serves this stream, so there's no
+ * gateway relay and no Redis in the component path.
+ */
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { applyServerMessage, type ComponentStore, type ServerMessage } from "./core";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+// Interpreter-based JSON-schema validator (no `new Function`). The SDK's default Ajv
+// provider compiles schemas with `new Function`, which ChatGPT's widget CSP (no
+// unsafe-eval) blocks — that crashed the in-iframe MCP client on boot and left the
+// widget blank. CfWorker is the SDK's own edge/no-eval provider.
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
+import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+export interface UnoverseConnectionConfig {
+  /** Gravity API base, e.g. "http://localhost:4100". REST execute lives here. */
+  apiUrl: string;
+  /** Unoverse server base, e.g. "http://localhost:4105" (or the workbench origin in
+   *  dev). The `/stream` MCP data-plane endpoint (§5b) is appended. */
+  streamUrl: string;
+  /** Optional JWT provider — the token rides the MCP transport fetch + REST Authorization header. */
+  getAccessToken?: () => Promise<string | null>;
+}
+
+export interface UnoverseSessionParams {
+  workflowId: string;
+  targetTriggerNode: string;
+  userId: string;
+  conversationId: string;
+  /** Groups one request→response turn. Defaults to conversationId if omitted. */
+  chatId?: string;
+}
+
+export interface UnoverseConnection {
+  isConnected: boolean;
+  isReady: boolean;
+  /** Composer target: optimistic user turn + REST workflow trigger. */
+  sendMessage: (text: string) => void;
+  /** Fire the bound workflow WITHOUT a user turn — the "load → run the workflow" ping
+   *  (its component streams back into the shell). `input` shapes the execute payload per
+   *  the app's `inputSchema`; omit for a bare trigger. (§5b REST `/execute`; the future
+   *  MCP-native form is a `tools/call` on the InputTrigger tool, same call site.) */
+  trigger: (input?: Record<string, unknown>) => void;
+  /** Other component actions (button clicks, etc.) → MCP `user_action` tool. */
+  sendAction: (action: string, data: Record<string, unknown>) => void;
+  /** Answer a pending ELICITATION with the submitted component state (the native
+   *  collection path — §3.3). Returns false when no elicitation is pending (the
+   *  channel then falls back to `sendAction`). */
+  resolveElicitation: (state: Record<string, unknown>) => boolean;
+  /** The workflow-selected template (MCP app) name, or null. The channel renders
+   *  `unoverse://templates/{activeTemplate}` when set — the official resources/read load. */
+  activeTemplate: string | null;
+}
+
+/** The data-plane endpoint on the Unoverse server (§5b). */
+const STREAM_ENDPOINT = "/stream";
+/** Custom notification carrying one ServerMessage as `params` (§5b). */
+const UNOVERSE_EVENT = "notifications/unoverse/event";
+
+/**
+ * Guest identity — CONTAINED HERE so hosts never write guest logic. A token-less
+ * session is a GUEST to the platform's public-entry gate, which only admits
+ * `guest-`-prefixed ids (Run Authorization, AUTH_TOKEN_FLOW.md). Minted once per
+ * browser and persisted so the visitor's conversation and memory cohere across
+ * reloads. A host that supplies its own guest id wins (two apps in one page share
+ * one visitor); a host with a token is untouched.
+ */
+const GUEST_KEY = "unoverse:guestId";
+function resolveGuestId(): string {
+  let id: string | null = null;
+  try {
+    id = localStorage.getItem(GUEST_KEY);
+  } catch {
+    /* storage blocked → per-load guest below */
+  }
+  if (!id || !/^guest[-:]/.test(id)) {
+    id = `guest-${crypto.randomUUID()}`;
+    try {
+      localStorage.setItem(GUEST_KEY, id);
+    } catch {
+      /* fine: the id just won't survive a reload */
+    }
+  }
+  return id;
+}
+
+export function useUnoverseConnection(
+  config: UnoverseConnectionConfig,
+  session: UnoverseSessionParams,
+  store: ComponentStore,
+  options: { enabled?: boolean } = {},
+): UnoverseConnection {
+  const enabled = options.enabled ?? true;
+  const { streamUrl, getAccessToken } = config;
+  const { workflowId, targetTriggerNode, conversationId } = session;
+  // No token ⇒ the platform sees a GUEST session and requires a guest-prefixed id —
+  // supply one automatically (host-supplied guest ids win; with a token the host's
+  // real userId passes through untouched). This is the whole guest story for a host.
+  const userId = getAccessToken || /^guest[-:]/.test(session.userId ?? "") ? session.userId : resolveGuestId();
+  const chatId = session.chatId ?? conversationId;
+
+  const [isConnected, setIsConnected] = useState(false);
+  const [isReady, setIsReady] = useState(false);
+  const clientRef = useRef<Client | null>(null);
+  // First-seen component keys for this connection (repeat INIT → props merge).
+  const seenRef = useRef<Set<string>>(new Set());
+  // The pending elicitation's resolver (one at a time per session) — set while the
+  // server is asking this session for structured input; the channel's submit branch
+  // answers it via `resolveElicitation`.
+  const pendingElicitRef = useRef<((state: Record<string, unknown>) => void) | null>(null);
+
+  // ---- connection lifecycle (MCP stream) ----
+  useEffect(() => {
+    if (!enabled) return; // mock mode — no live stream
+    if (!workflowId || !userId || !conversationId) {
+      console.warn("[unoverse] connection missing workflowId/userId/conversationId");
+      return;
+    }
+    let cancelled = false;
+    seenRef.current = new Set();
+
+    // Declare the ELICITATION capability (form mode) — the native collection path
+    // (UNOVERSE_MCP_TEMPLATE_PROTOCOL §3.3): the server pauses inside an app tool
+    // call and asks THIS session for the user's structured input. The interactive
+    // component already on screen IS the form; its `submit` answers the elicitation.
+    const client = new Client(
+      { name: "unoverse-channel", version: "0.0.1" },
+      { capabilities: { elicitation: {} }, jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
+    );
+    client.setRequestHandler(ElicitRequestSchema, async (req) => {
+      // Pend until the user submits the component (the channel calls resolveElicitation
+      // from its submit branch). The branded UI renders the request — never a generic form.
+      // The accept content MUST match the requestedSchema (spec: flat primitives only) —
+      // project the submitted component state to the REQUESTED keys, or the SDK rejects
+      // the response (view-state like a `courses` array fails the primitive union).
+      const requested =
+        (req.params as unknown as { requestedSchema?: { properties?: Record<string, unknown> } }).requestedSchema?.properties ?? {};
+      return await new Promise((resolve) => {
+        pendingElicitRef.current = (state: Record<string, unknown>) => {
+          pendingElicitRef.current = null;
+          const content: Record<string, unknown> = {};
+          for (const k of Object.keys(requested)) if (state[k] !== undefined) content[k] = state[k];
+          resolve({ action: "accept", content } as never);
+        };
+      });
+    });
+    clientRef.current = client;
+
+    // The server pushes the live stream as `notifications/unoverse/event` over the
+    // GET SSE channel. Custom notification methods land on the fallback handler —
+    // route their `params` (one ServerMessage) into the store.
+    client.fallbackNotificationHandler = async (notification) => {
+      if (notification.method !== UNOVERSE_EVENT) return;
+      const msg = (notification.params ?? {}) as unknown as ServerMessage;
+      if ((msg as { type?: string }).type === "SESSION_READY") {
+        setIsReady(true);
+        return;
+      }
+      applyServerMessage(store, msg, seenRef.current);
+    };
+
+    (async () => {
+      // Inject the bearer on every underlying request (fresh per call → refresh-safe).
+      const authFetch = getAccessToken
+        ? async (url: string | URL, init?: RequestInit): Promise<Response> => {
+            const token = await getAccessToken();
+            const headers = new Headers(init?.headers);
+            if (token) headers.set("Authorization", `Bearer ${token}`);
+            return fetch(url, { ...init, headers });
+          }
+        : undefined;
+      try {
+        const transport = new StreamableHTTPClientTransport(
+          new URL(`${streamUrl}${STREAM_ENDPOINT}`),
+          authFetch ? { fetch: authFetch } : undefined,
+        );
+        await client.connect(transport);
+        if (cancelled) {
+          await client.close().catch(() => {});
+          return;
+        }
+        setIsConnected(true);
+        // Bind this stream to the session — the server then pushes the live component
+        // stream and an immediate SESSION_READY.
+        const bind = await client.callTool({
+          name: "register_session",
+          arguments: { userId, conversationId, workflowId, targetTriggerNode, chatId },
+        });
+        // A refusal (public-entry gate, requires.role, …) is an isError tool RESULT,
+        // not a thrown error — surface it, or the session is an eternal silent
+        // "Connecting…" (the server logs the same refusal as REFUSED:).
+        if ((bind as { isError?: boolean }).isError) {
+          const c = (bind as { content?: Array<{ type?: string; text?: string }> }).content;
+          console.error("[unoverse] session refused:", c?.[0]?.text ?? "unauthorized");
+        }
+      } catch (e) {
+        if (!cancelled) console.error("[unoverse] stream connect failed", e);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      setIsConnected(false);
+      setIsReady(false);
+      void clientRef.current?.close().catch(() => {});
+      clientRef.current = null;
+    };
+  }, [enabled, streamUrl, workflowId, targetTriggerNode, userId, conversationId, chatId, getAccessToken, store]);
+
+  // ---- turn identity ----
+  // `conversationId` names the CONVERSATION (session addressing, agent memory,
+  // elicitation); `chatId` names ONE TURN (the store's response identity — every
+  // component of a turn keys `chatId:nodeId`). The channel MINTS a fresh turn id per
+  // outbound send; the `<conversationId>:t…` prefix keeps conversation-scoped waiter
+  // resolution (elicitation accept) matching turn-scoped node waiters.
+  const mintTurn = useCallback(
+    () => `${chatId}:t${Date.now().toString(36)}${Math.floor(Math.random() * 1296).toString(36)}`,
+    [chatId],
+  );
+
+  // ---- outbound: fire the bound workflow over REST (§5b /execute) ----
+  // No user turn — this is the raw trigger. `sendMessage` layers a user turn on top.
+  const trigger = useCallback(
+    (input?: Record<string, unknown>, turnId?: string) => {
+      const turn = turnId ?? mintTurn();
+      (async () => {
+        // NATIVE MCP: fire the run via a `tools/call` on the live /stream session — NOT
+        // the retired REST `/api/workflows/:id/execute` (UNOVERSE_MCP_TEMPLATE_PROTOCOL
+        // §0.3). Fire-and-forget: the run's UI streams back over this same session; the
+        // caller's token rides the connection (server reads it from extra.authInfo).
+        const client = clientRef.current;
+        if (!client) {
+          console.error("[unoverse] trigger dropped — MCP stream not connected yet");
+          return;
+        }
+        // Same `input` envelope the REST route received (server unwraps it 1:1).
+        const inputEnvelope = { chatId: turn, conversationId, userId, providerId: "gravity-ds", metadata: { targetTriggerNode }, ...input };
+        try {
+          await client.callTool({ name: "trigger", arguments: { workflowId, conversationId, input: inputEnvelope } });
+        } catch (e) {
+          console.error("[unoverse] trigger failed", e);
+        }
+      })();
+    },
+    [workflowId, targetTriggerNode, userId, conversationId, mintTurn],
+  );
+
+  // ---- outbound: send a message (optimistic user turn + trigger) ----
+  const sendMessage = useCallback(
+    (text: string) => {
+      const message = text.trim();
+      if (!message) return;
+      const turn = mintTurn(); // ONE turn id shared by the user message, the assistant response, and the run
+      store.addUserMessage(turn, message); // optimistic user turn
+      // Optimistically open the assistant turn too, so the avatar + thinking dots
+      // appear IMMEDIATELY on send instead of waiting for the backend's
+      // WORKFLOW_STARTED. startResponse is idempotent — the later WORKFLOW_STARTED
+      // (and the first COMPONENT_INIT) reuse this same turn (responseFor by chatId).
+      store.startResponse(turn);
+      trigger({ message }, turn);
+    },
+    [mintTurn, store, trigger],
+  );
+
+  // ---- outbound: generic component action → MCP `user_action` tool ----
+  const sendAction = useCallback(
+    (action: string, data: Record<string, unknown>) => {
+      void clientRef.current
+        ?.callTool({ name: "user_action", arguments: { action, data, userId, conversationId, chatId } })
+        .catch((e) => console.error("[unoverse] user_action failed", e));
+    },
+    [userId, conversationId, chatId],
+  );
+
+  // The workflow-selected template, reactively (a primitive snapshot so the store
+  // subscription doesn't loop). The channel renders it via resources/read.
+  // Stable subscribe fn — an inline arrow re-subscribes every render.
+  const activeTemplate = useSyncExternalStore(
+    useCallback((cb) => store.subscribe(cb), [store]),
+    useCallback(() => store.getActiveTemplate().name, [store]),
+  );
+
+  // Answer a pending elicitation with the submitted component state (native path).
+  const resolveElicitation = useCallback((state: Record<string, unknown>): boolean => {
+    const pending = pendingElicitRef.current;
+    if (!pending) return false;
+    pending(state);
+    return true;
+  }, []);
+
+  return { isConnected, isReady, sendMessage, trigger, sendAction, resolveElicitation, activeTemplate };
+}

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

@@ -0,0 +1,84 @@
+/**
+ * The action interpreter (UNOVERSE_SPEC.md §2e-3) — pure state logic, no React,
+ * no DOM. Turns a node's `action` (a bare string or a `setValue` envelope) into
+ * a store write and/or a server route. This is the ported `updateData`: a LOCAL
+ * write into a component's own `chatId:nodeId` slice via the store's existing
+ * merge — the generalisation of the composer's `setDraft`.
+ *
+ * Shape taken from Stac (set_value + Multi Action): `values:[{key,value}]` with
+ * `{{binding}}` resolution, an optional chained `then`, and a hard split between
+ * LOCAL `setValue` and a server route for anything computed/transactional.
+ */
+import type { ComponentStore } from "./store";
+import type { ActionSpec } from "./types";
+
+export interface ActionContext {
+  store: ComponentStore;
+  chatId: string;
+  nodeId: string;
+  /** Route a non-`setValue` action to the workflow (channel-provided, e.g. USER_ACTION). */
+  sendToServer?: (type: string, data: Record<string, unknown>) => void;
+}
+
+/** Resolve a value: a `"{{path}}"` template reads from `scope` (dot-path); anything
+ *  else is a literal. Mirrors Stac's `{{response}}` / `order.status` references. */
+export function resolveValue(value: unknown, scope: Record<string, unknown>): unknown {
+  if (typeof value !== "string") return value;
+  const m = value.match(/^\{\{\s*([\w.]+)\s*\}\}$/);
+  if (!m) return value;
+  return m[1]
+    .split(".")
+    .reduce<unknown>((acc, k) => (acc == null ? undefined : (acc as Record<string, unknown>)[k]), scope);
+}
+
+/**
+ * Interpret an action (bare string or envelope) against the data scope at the
+ * interaction site. `setValue` → local store merge into this `chatId:nodeId`;
+ * any other type → the workflow (narrowed by `send`). `then` chains.
+ */
+export function dispatchAction(
+  action: string | ActionSpec | undefined,
+  scope: Record<string, unknown>,
+  ctx: ActionContext,
+): void {
+  if (action == null) return;
+  const spec: ActionSpec = typeof action === "string" ? { type: action } : action;
+
+  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
+    // `visibleWhen`. Same merge inbound COMPONENT_DATA uses; no server round-trip.
+    const patch: Record<string, unknown> = {};
+    for (const { key, value } of spec.values ?? []) patch[key] = resolveValue(value, scope);
+    // 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);
+  } 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
+    // (openPanel, focusMode, …) and reads it via `visibleWhen`. The SDK hardcodes NO UI
+    // concept — only "write a key to component state" and "write a key to template state".
+    const patch: Record<string, unknown> = {};
+    for (const { key, value } of spec.values ?? []) patch[key] = resolveValue(value, scope);
+    ctx.store.mergeTemplateState(patch);
+  } else if (spec.type === "input") {
+    // A controlled Input changed — write its bound field back into the state bag that
+    // OWNS this tree (local two-way binding; every keystroke is local, never a server
+    // round-trip). `scope.field` names the bound field, `scope.text` the new value
+    // (InputView). Component scope (real nodeId) → its own slice; template chrome
+    // (empty ids) → template state — the composer's `draft` lives there, and writing
+    // the slice for an empty id swallows the keystroke (the type-nothing-appears bug).
+    // This is the only special-cased event name.
+    const field = typeof scope.field === "string" ? scope.field : undefined;
+    if (field) {
+      if (ctx.nodeId) ctx.store.apply({ type: "COMPONENT_DATA", chatId: ctx.chatId, nodeId: ctx.nodeId, data: { [field]: scope.text } });
+      else ctx.store.mergeTemplateState({ [field]: scope.text });
+    }
+  } else {
+    // SERVER — narrow the payload by `send` if given, else forward the whole scope.
+    const payload = spec.send ? Object.fromEntries(spec.send.map((k) => [k, scope[k]])) : scope;
+    ctx.sendToServer?.(spec.type, payload);
+  }
+
+  if (spec.then) dispatchAction(spec.then, scope, ctx);
+}

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

@@ -0,0 +1,134 @@
+/**
+ * @unoverse/core — the MCP client.
+ *
+ * Reads neutral definitions + the resolved theme from the Unoverse MCP server
+ * (resources/read), with a per-request bearer for secured servers. Caches both.
+ * No UI framework here.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+// CSP-safe (no `new Function`) validator — the default Ajv provider's eval is blocked by
+// ChatGPT's widget CSP. See connection.tsx for the full rationale.
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
+import type { UnoverseDefinition, ResolvedTheme } from "./types";
+
+export interface UnoverseClientOptions {
+  /**
+   * Returns a fresh bearer token per request (e.g. an OIDC access_token). The token
+   * rides the `Authorization` header on every MCP call so a secured server (default-deny)
+   * accepts it. Omit for anonymous/dev (server with AUTH_ENABLED=false). Called per
+   * request, so it can return a refreshed token transparently.
+   */
+  getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
+}
+
+export class UnoverseClient {
+  private client: Client;
+  private connected = false;
+  private connecting: Promise<void> | null = null;
+  private cache = new Map<string, UnoverseDefinition>();
+  private themeCache = new Map<string, ResolvedTheme>();
+
+  constructor(
+    private readonly url: string,
+    private readonly options: UnoverseClientOptions = {},
+  ) {
+    this.client = new Client(
+      { name: "unoverse-core", version: "0.0.1" },
+      { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
+    );
+  }
+
+  /** The server ORIGIN this client talks to — `this.url` without the trailing `/mcp`.
+   *  The one true source for any other lane on the same server (e.g. the audio
+   *  `/ws/gravity` WS): the SDK derives it HERE so no host has to pass a URL that can be
+   *  wrong (a sandboxed srcdoc iframe's `location.origin` is the string "null"). */
+  get serverOrigin(): string {
+    return this.url.replace(/\/mcp\/?$/, "");
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+    // Single shared connect — concurrent readDefinition() calls must not each
+    // open a transport ("Already connected to a transport").
+    if (!this.connecting) {
+      this.connecting = (async () => {
+        const getToken = this.options.getAccessToken;
+        // Inject the bearer on every underlying request (fresh per call → refresh-safe).
+        const authFetch = getToken
+          ? async (url: string | URL, init?: RequestInit): Promise<Response> => {
+              const token = await getToken();
+              const headers = new Headers(init?.headers);
+              if (token) headers.set("Authorization", `Bearer ${token}`);
+              return fetch(url, { ...init, headers });
+            }
+          : undefined;
+        const transport = new StreamableHTTPClientTransport(
+          new URL(this.url),
+          authFetch ? { fetch: authFetch } : undefined,
+        );
+        await this.client.connect(transport);
+        this.connected = true;
+      })().catch((err) => {
+        // Don't cache a FAILED connect (e.g. a 401 before sign-in) — clearing
+        // `connecting` lets a later call retry fresh once a token is available.
+        this.connecting = null;
+        throw err;
+      });
+    }
+    return this.connecting;
+  }
+
+  /** Generic tools/call passthrough (e.g. `user_action` component submissions). */
+  async callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+    await this.connect();
+    return this.client.callTool({ name, arguments: args });
+  }
+
+  /** 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;
+    await this.connect();
+    const res = await this.client.readResource({ uri });
+    const first = res.contents[0] as { text?: string };
+    if (!first?.text) throw new Error(`No definition content for ${uri}`);
+    const def = JSON.parse(first.text) as UnoverseDefinition;
+    this.cache.set(uri, def);
+    return def;
+  }
+
+  /**
+   * resources/read the RESOLVED theme by name (e.g. "light"). The server owns the
+   * values (rx/styles); the SDK only fetches — it bundles no tokens. Cached.
+   */
+  async readTheme(name = "light"): Promise<ResolvedTheme> {
+    const cached = this.themeCache.get(name);
+    if (cached) return cached;
+    await this.connect();
+    const res = await this.client.readResource({ uri: `unoverse://theme/${name}` });
+    const first = res.contents[0] as { text?: string };
+    if (!first?.text) throw new Error(`No theme content for ${name}`);
+    const theme = JSON.parse(first.text) as ResolvedTheme;
+    this.themeCache.set(name, theme);
+    return theme;
+  }
+
+  /** List available theme names (e.g. ["light", "dark"]) from the server. */
+  async listThemes(): Promise<string[]> {
+    await this.connect();
+    const res = await this.client.listResources();
+    return res.resources
+      .filter((r) => r.uri.startsWith("unoverse://theme/"))
+      .map((r) => r.uri.replace("unoverse://theme/", ""));
+  }
+
+  /** List available component definitions (resources/templates + list). */
+  async listComponents(): Promise<{ uri: string; name?: string }[]> {
+    await this.connect();
+    const res = await this.client.listResources();
+    return res.resources
+      .filter((r) => r.uri.startsWith("unoverse://components/"))
+      .map((r) => ({ uri: r.uri, name: r.name }));
+  }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * The ONE predicate behind every "react to state" mechanism — `visibleWhen`, the
+ * `Switch` node, and `style.when`. Keeping it here (pure, framework-agnostic) means the
+ * three share identical semantics and there is a single place to test them.
+ *
+ * This is a SMALL declarative layer, NOT a programming language: a `Condition` picks one
+ * of `eq` / `ne` / `in`, or (with none) a truthy test. There is deliberately no
+ * `and`/`or`/arithmetic — anything richer is DERIVED in the producing node and sent as a
+ * plain field (see UNOVERSE_AUTHORING.md / FRAMEWORK.md).
+ */
+import type { Condition, VisibleWhen, UnoverseNode } from "./types";
+
+/** Does a `Condition` hold against the data scope? `eq`/`ne`/`in`, else a truthy test. */
+export function matches(cond: Condition, data: Record<string, unknown>): boolean {
+  const v = data[cond.field];
+  if ("eq" in cond) return v === cond.eq;
+  if ("ne" in cond) return v !== cond.ne;
+  if ("in" in cond) return Array.isArray(cond.in) && cond.in.includes(v);
+  return v != null && v !== "" && v !== false;
+}
+
+/** `visibleWhen` semantics: a bare field name is a "has data" test (an empty array counts
+ *  as empty, so an `Each`-driven section disappears when its list is `[]`); an object is a
+ *  `Condition`. Returns whether the node should render. */
+export function visible(vw: VisibleWhen, data: Record<string, unknown>): boolean {
+  if (typeof vw === "string") {
+    const v = data[vw];
+    return !(v == null || v === "" || v === false || (Array.isArray(v) && v.length === 0));
+  }
+  return matches(vw, data);
+}
+
+/** `Switch` resolution: the branch keyed by `data[on]` (stringified), else `cases.default`,
+ *  else `undefined` (render nothing). Pure so it is unit-testable without React. */
+export function selectCase(
+  node: { on?: string; cases?: Record<string, UnoverseNode> },
+  data: Record<string, unknown>,
+): UnoverseNode | undefined {
+  const cases = node.cases;
+  if (!cases) return undefined;
+  const key = node.on != null ? String(data[node.on] ?? "") : "";
+  return cases[key] ?? cases.default;
+}