@unoverse-platform/studio 0.1.103 → 0.1.105

package/vendor/sdk/appEngine.tsx

@@ -1,395 +0,0 @@
-/**
- * The native app ENGINE (§6d) — surface-agnostic. It:
- *   - reads its OWN workflow binding from its manifest (§4b: "App supplies workflow, trigger"),
- *   - opens the SDK's native connection (`/stream` register_session → store),
- *   - fires the workflow DIRECTLY via `conn.sendMessage` → REST `{apiUrl}/api/workflows/:id/execute`
- *     with the USER's token (§5a: "direct channel → Gravity backend — never brokered").
- *
- * The server tool only LOADS this app; it never fires or brokers a token. Uses the LOCAL
- * vendored SDK (./lib), not the npm package.
- */
-import { useEffect, useMemo, useRef, useState } from "react";
-import { postToEmbedHost } from "./mcpAppBridge";
-import { PageInterfaces, type Binding } from "./pageInterfaces";
-import {
-  UnoverseClient,
-  ComponentStore,
-  StreamedUnoverseApp,
-  INERT_VOICE,
-  useVoiceService,
-  useUnoverseConnection,
-  useUnoverseTheme,
-  computeAppWidth,
-  resolveActiveLayout,
-  setAnalyticsSink,
-  setAnalyticsContext,
-  setAnalyticsDebug,
-  type UseVoiceServiceConfig,
-  type UnoverseDefinition,
-  type ActionMeta,
-} from "./lib";
-
-export interface AppConfig {
-  serverUrl: string;
-  apiUrl?: string;
-  appId: string;
-  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, appId: configuredApp, getAccessToken, userId, conversationId, surface, analyticsDebug } = cfg;
-
-  // 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],
-  );
-  const [binding, setBinding] = useState<{ workflow?: string; trigger?: string; service?: string }>({});
-  // RENDER-TIME reset (React's derived-state-from-props pattern), not an effect: on an
-  // app switch the connection effect and a reset effect share one commit, and the
-  // connection runs first — so an effect-based reset still let one session open with the
-  // OLD app's trigger against the NEW app's conversation before correcting (observed
-  // live 2026-08-16, twice: first with no reset, then with the reset as an effect).
-  // Setting state during render makes React re-render BEFORE the commit, so the
-  // connection effect only ever sees either the old app intact or an empty binding —
-  // never the cross-app hybrid.
-  // WHICH APP IS RUNNING, and there are two ways it changes. The host re-posts its
-  // config (the native-host iframe's app switch), and the SERVER can now swap it mid
-  // conversation — an app discovered and called IS the surface, so opening one replaces
-  // what is mounted (owner ruling 2026-09-07). One piece of state either way, so the
-  // stale-binding guard below covers both rather than only the host's.
-  const [appId, setAppId] = useState(configuredApp);
-  const [boundFor, setBoundFor] = useState(configuredApp);
-  // The host's own switch WINS and resets: a new config is a new intent.
-  if (boundFor !== configuredApp) {
-    setBoundFor(configuredApp);
-    setAppId(configuredApp);
-    setBinding({});
-  }
-  // The server's switch, same reset: a different app is a different workflow and trigger,
-  // and the binding is read async from the incoming app's manifest (the effect below).
-  // Clearing it here is what stops a session opening on the OLD app's trigger against the
-  // new app — the hazard the render-time reset above exists for.
-  const switchApp = (next: string) => {
-    if (next === appId) return;
-    setAppId(next);
-    setBinding({});
-  };
-  // STATE-OWNED WIDTH (design data): the layout root's `appWidth` = the core surface's
-  // constant width; an occupied panel slot's `appWidth` adds to it (computeAppWidth).
-  // No declared width → the host keeps its own default. There is no other path.
-  // THE WHOLE DEFINITION, not a chosen four fields. This used to keep `{root, org, layouts,
-  // defaultLayout}` and drop everything else, which is a whitelist that silently loses each
-  // field the contract gains. It was dropping `stateOrder`, `publicStates`, `initialView`
-  // and `stateTree`, quietly running the v2 ladder in legacy mode, and it dropped `defs`
-  // too: with shared pieces unreachable, the core panel's `appWidth` went uncounted and the
-  // app's width collapsed to the open surface's remainder term, which is negative, so the
-  // app rendered 0 pixels wide and blank.
-  const [def, setDef] = useState<UnoverseDefinition | null>(null);
-  const lastWidthRef = useRef<string | undefined>(undefined);
-  // Named app sizes resolve via the served theme (theme.appSize), like every token.
-  // The theme's name is the template's org. When appId already carries it
-  // ("org/name" — every production boot), start the theme read IMMEDIATELY, in
-  // parallel with the template read; waiting for the definition just to learn an org
-  // we were handed serialized two round trips for nothing. Bare ids (dev) still wait.
-  const orgFromId = appId.includes("/") ? appId.split("/")[0] : null;
-  const theme = useUnoverseTheme(
-    client,
-    orgFromId ? `${orgFromId}/light` : def ? (def.org ? `${def.org}/light` : "light") : null,
-  );
-
-  // The app owns which workflow it runs — read it from its manifest (§4b), not from config.
-  useEffect(() => {
-    let alive = true;
-    // The stale-binding reset lives at RENDER time (boundFor, above) — resetting here,
-    // in an effect, ran too late: the connection effect had already opened a session on
-    // the previous app's trigger within the same commit.
-    client
-      .connect()
-      .then(() => (client as any).client.readResource({ uri: `unoverse://apps/${appId.toLowerCase()}` }))
-      .then((res: any) => {
-        const parsed = res?.contents?.[0]?.text ? JSON.parse(res.contents[0].text) : null;
-        const m = parsed?.manifest ?? parsed ?? {};
-        const b = m.binding ?? {};
-        // `service` (e.g. "voice") is the app's own declaration — it selects whether the
-        // renderer runs a native service. Read it here, next to the binding, and forward it.
-        if (alive) setBinding({ workflow: b.workflow, trigger: b.trigger, service: m.service });
-      })
-      .catch((e) => console.error("[app] manifest read failed:", e));
-    // The width lives in the template DATA (root/slot `appWidth`), so read the
-    // definition too — same resource the renderer loads.
-    client
-      .connect()
-      .then(() => client.readDefinition(`unoverse://apps/${appId}/definition`))
-      .then((d) => {
-        if (alive) setDef(d ?? null);
-      })
-      .catch((e) => console.error("[app] template read failed:", e));
-    return () => {
-      alive = false;
-    };
-  }, [client, appId]);
-
-  // Report the app's width UP to the embedding host (iframe boundary → the twin of the
-  // 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) => {
-      postToEmbedHost({ type: "unoverse:event", ...event });
-    });
-    return () => setAnalyticsSink(null);
-  }, [surface, conversationId, userId, analyticsDebug]);
-
-  useEffect(() => {
-    // A NEW APP RE-ANNOUNCES ITS WIDTH, ALWAYS. The native host keeps ONE iframe for every
-    // app (its srcdoc is keyed on the server, not the app — it just re-posts
-    // `unoverse:config` with a new appId) and this engine is re-rendered in place, so
-    // the change-guard below outlives the switch — while the host RESETS its frame to the
-    // default on it (NativeAppHost/TemplatesView). Two apps of the same declared width is
-    // the ordinary case (one org, one `chat` size), and the incoming app then reported
-    // nothing: its frame sat at the host default (100%) while its core panel held its
-    // declared width, leaving a dead band beside it (observed live 2026-08-13,
-    // bpp-voice). Clearing the guard here makes the first report after an app
-    // switch unconditional; the guard still suppresses repeats within one app.
-    lastWidthRef.current = undefined;
-    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, store), store, theme?.appSize, def);
-      if (w && w !== lastWidthRef.current) {
-        lastWidthRef.current = w;
-        postToEmbedHost({ type: "unoverse:size", width: w });
-      }
-    };
-    report();
-    return store.subscribe(report);
-  }, [store, def, theme]);
-
-  // VOICE (§2e-1): a `service: "voice"` app runs the native voice service — which now lives
-  // in the shared renderer (StreamedUnoverseApp), identical to Studio. The host only
-  // supplies the connection identity it already holds; startCall/endCall/toggleMute are
-  // answered inside the renderer, so this host wires NO voice buttons. Absent → inert.
-  const voiceConfig = useMemo<UseVoiceServiceConfig | undefined>(
-    () =>
-      // THE SERVICE NEEDS NO WORKFLOW OF ITS OWN. It is the page's microphone, speaker and
-      // audio lane; a call names the workflow it runs (a page template's binding,
-      // UNOVERSE_HOST_PAGE.md rule 4), and an app with a binding lends it as the default.
-      binding.service === "voice"
-        ? {
-            // START_CALL REST triggers the workflow on the gateway (user token). The audio
-            // WS lane is derived by the SDK from the client's server origin (see the renderer)
-            // — the host passes NO wsUrl (its srcdoc `location.origin` is "null").
-            apiUrl: apiUrl ?? serverUrl,
-            getAccessToken: getAccessToken as UseVoiceServiceConfig["getAccessToken"],
-            session: {
-              userId: userId ?? "",
-              conversationId,
-              chatId: conversationId,
-              workflowId: binding.workflow ?? "",
-              targetTriggerNode: binding.trigger ?? "",
-            },
-            // Producer: writes callState/isMuted into TEMPLATE STATE so the voice states switch.
-            store,
-          }
-        : undefined,
-    [binding.service, binding.workflow, binding.trigger, apiUrl, serverUrl, getAccessToken, userId, conversationId, store],
-  );
-
-  // ONE CALL FOR THE PAGE. The service runs here, once, so the app and the page's own
-  // templates (an avatar in the navigation) start, follow and end the same call.
-  const voice = useVoiceService(
-    voiceConfig ? { ...voiceConfig, wsUrl: client.serverOrigin.replace(/^http/, "ws") } : INERT_VOICE,
-  );
-
-  // CONNECTED TO THE TASK UNTIL THE PAGE CLOSES. The avatar is a button that starts a task's
-  // workflow; from that press the page is in the task (its steps, its submit) until the task
-  // closes or the visitor leaves. Whether the workflow has a voice is its own business, so
-  // nothing here waits on a call (UNOVERSE_HOST_PAGE.md rule 4).
-  const [inTask, setInTask] = useState(false);
-
-  // SDK's native connection: opens /stream, register_session, feeds the store. Outbound
-  // sendMessage fires the workflow DIRECTLY (REST, user token) — no server broker.
-  const conn = useUnoverseConnection(
-    { apiUrl: apiUrl ?? serverUrl, streamUrl: serverUrl, getAccessToken: getAccessToken as any },
-    {
-      workflowId: binding.workflow ?? "",
-      targetTriggerNode: binding.trigger ?? "",
-      userId: userId ?? "",
-      conversationId,
-      chatId: conversationId,
-      appId,
-    },
-    store,
-    // Open once the user is known AND there is something to hear from: the app's own workflow,
-    // or a task the page is in. An app with no workflow (a website's page app) connects when the
-    // avatar starts a task and stays connected to it; nothing is held open while the visitor
-    // only reads.
-    {
-      enabled: !!userId && (!!binding.workflow || voice.state.isCallActive || inTask),
-      onAppSwitch: switchApp,
-      // A voice in the running workflow asks the page in: join its call, never start one.
-      onJoinCall: (workflowId) => void voice.joinCall(workflowId),
-    },
-  );
-
-  // 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.
-  //
-  // `failure` is the last run's WORKFLOW_ERROR detail (which node, what error) —
-  // DEVELOPER information. A production embed host doesn't listen and its users see
-  // nothing; Studio's preview listens and shows it, so a dead run stops being a
-  // silence only the server logs could explain.
-  const [failure, setFailure] = useState(store.getLastFailure());
-  useEffect(() => store.subscribe(() => setFailure(store.getLastFailure())), [store]);
-  useEffect(() => {
-    // `refused` carries the server's terminal refusal text (register_session isError) —
-    // the one state a "Connecting…" badge must not sit on forever.
-    postToEmbedHost({
-      type: "unoverse:status",
-      ready: !!conn.isReady,
-      connected: !!conn.isConnected,
-      refused: conn.refusal ?? undefined,
-      failure: failure ?? undefined,
-    });
-  }, [conn.isReady, conn.isConnected, conn.refusal, failure]);
-
-  // THE SPEC'S ANSWERS, AND NOTHING ELSE (UNOVERSE_MCP_COMPLETE_GUIDE.md, "How the SDK answers an
-  // elicitation"): while the server is ELICITING on this session, a component's `submit` answers
-  // `accept` with its slice and its `cancel` answers `cancel`. Every other action (a state it
-  // enters, a step, a tab) is the component's own and goes to the server as usual. Without a
-  // pending elicitation, a submit falls back to the data-plane `user_action` waiter (a workflow
-  // node waiting on a component). One way for every component, the app's and the page's alike.
-  const toServer = (t: string, data: Record<string, unknown>, meta?: ActionMeta) => {
-    const state = (meta?.state ?? data) as Record<string, unknown>;
-    if ((t === "submit" || t === "cancel") && conn.resolveElicitation(state, t === "cancel" ? "cancel" : "accept")) return;
-    conn.sendAction(t, {
-      componentNodeId: meta?.nodeId,
-      componentType: meta?.type,
-      // The component's OWN chatId is the TURN id — the waiting node execution is
-      // keyed `<turn>:<nodeId>`, not the conversation-level chatId.
-      componentChatId: meta?.chatId,
-      componentState: state,
-    });
-  };
-
-  // A PAGE TEMPLATE'S TASK, called at its own workflow's trigger over REST with the user's
-  // token, as any request to a workflow (§5a). `metadata.task` names the task its Task Runner
-  // loads. The avatar's press is the first call; the task's submit is the last, carrying the
-  // answers as `metadata.submit`, and nothing waits for it (design/tasks.md, "The submit").
-  // From the first call the page is in the task.
-  const startTask = async (b: Binding, task: string, submit?: Record<string, unknown>) => {
-    if (!b.workflow) return;
-    setInTask(true);
-    const token = getAccessToken ? await getAccessToken() : null;
-    fetch(`${apiUrl ?? serverUrl}/api/workflows/${b.workflow}/execute`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
-      body: JSON.stringify({
-        input: {
-          message: submit ? "Submit" : "Start",
-          chatId: conversationId,
-          conversationId,
-          userId,
-          providerId: "gravity-ds",
-          metadata: { targetTriggerNode: b.trigger, workflowId: b.workflow, task, ...(submit ? { submit } : {}) },
-        },
-        conversationId,
-      }),
-    }).catch((e) => console.error("[unoverse] task start failed", e));
-  };
-
-  return (
-    <>
-    {/* The page's own templates, drawn into its elements by this one runtime (pageInterfaces.tsx). */}
-    <PageInterfaces org={appId.split("/")[0]} client={client} voice={voice} appStore={store} toServer={toServer} startTask={startTask} />
-    <StreamedUnoverseApp
-      client={client}
-      store={store}
-      uri={`unoverse://apps/${appId}/definition`}
-      voice={voiceConfig}
-      voiceService={voice}
-      onAction={(action, data, meta) => {
-        const t = typeof action === "string" ? action : (action as any)?.type;
-        if (t === "close") {
-          // The app owns its close chrome (its own top-right X). Tell the embedding host to
-          // dismiss the surface (twin of `unoverse:config`/`unoverse:size`). The host decides
-          // what "close" means for its frame (slide the drawer shut); we don't assume.
-          postToEmbedHost({ type: "unoverse:close" });
-          return;
-        }
-        if (t === "sendMessage") {
-          // A suggestion that NAMES AN APP launches it instead of sending its text: read
-          // that app's manifest (the binding lives there — §4b, never in template data)
-          // and fire its trigger. The `text` field stays as the fallback for channels
-          // without launch support. Same-workflow apps only for now: the connection
-          // posts to the BOUND workflow id, so a foreign-workflow app logs and falls
-          // through to its trigger on the bound workflow.
-          const app = typeof (data as any)?.app === "string" ? (data as any).app : "";
-          if (app) {
-            (client as any).client
-              .readResource({ uri: `unoverse://apps/${app.toLowerCase()}` })
-              .then((res: any) => {
-                const parsed = res?.contents?.[0]?.text ? JSON.parse(res.contents[0].text) : null;
-                const b = parsed?.manifest?.binding ?? parsed?.binding ?? {};
-                if (!b.trigger) return console.error("[app] launch failed: no binding on", app);
-                if (b.workflow && binding.workflow && b.workflow !== binding.workflow)
-                  console.warn("[app] launch:", app, "binds a different workflow — firing its trigger on the bound workflow");
-                // LOADING STATE: write the app's declared defaultState (open NAME; `mode` =
-                // pre-rename alias) into template state NOW — e.g. a "focus" app pre-opens
-                // the focus surface, whose slot shows its fallback (skeleton) until the
-                // workflow streams the component in. Same template-state key the node's
-                // APP_DATA emit writes; no new vocabulary. An "app" app IS the surface
-                // — nothing to write.
-                const declared = parsed?.manifest?.defaultState ?? parsed?.manifest?.mode ?? parsed?.defaultState ?? parsed?.mode;
-                if (declared && declared !== "app") store.mergeAppState({ defaultState: declared });
-                conn.trigger({ app, metadata: { targetTriggerNode: b.trigger, ...(def?.org ? { org: def.org } : {}) } });
-              })
-              .catch((e: any) => console.error("[app] launch failed:", e));
-            return;
-          }
-          // Composer submit is generic: Enter carries `text`; a send BUTTON carries none,
-          // so fall back to the shared draft the store already holds (same as Studio).
-          const text = (typeof (data as any)?.text === "string" && (data as any).text) || store.getDraft();
-          if (text.trim()) {
-            conn.sendMessage(text);
-            store.setDraft(""); // clear the composer after sending (the Input binds `draft`)
-          }
-          return;
-        }
-        // Controlled composer: the Input emits "input" on every keystroke → the shared
-        // draft (local, never a server round-trip). A send button / Enter emits "sendMessage".
-        if (t === "input") {
-          store.setDraft(typeof (data as any)?.text === "string" ? (data as any).text : "");
-          return;
-        }
-        if (t) toServer(t, data, meta);
-      }}
-    />
-    </>
-  );
-}