@unoverse-platform/studio 0.1.103 → 0.1.104

package/vendor/sdk/pageInterfaces.tsx

@@ -1,388 +0,0 @@
-/**
- * THE PAGE'S OWN TEMPLATES (docs/unoverse/design/sdk/UNOVERSE_HOST_PAGE.md rule 3).
- *
- * A website that is the app marks where its unoverse templates go:
- *
- *   <div data-unoverse-interface="unoverse/presence-avatar"></div>
- *
- * This runtime is already loaded (the embed started the app with no chrome). It reads each
- * marked template by URI over MCP, exactly as it reads the app, and draws it INTO the page's
- * element, in a shadow DOM (UnoverseComponent's own IsolatedRoot). One runtime, many shadow
- * roots: one client, one conversation, one sign-in for every part of the page.
- *
- * A template ARRIVES WITH ITS PAGE, as Studio previews it and as a delivery lands it: one
- * instance per linked part (`static:`), at its face, with the part's own values
- * (the served `sections` and their `seeds`), then the template itself. Drawn bare, its parts'
- * slots hold nothing and only the frame shows.
- *
- * The frame shares the page's origin (EMBED_CLIENT.md §1), so the page's document is
- * reachable from here; React portals listen for events on their own container, so a part
- * drawn into the page is as live as one drawn in the frame.
- */
-import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { createPortal } from "react-dom";
-import { ComponentStore, UnoverseComponent, type ActionHandler, type ActionMeta, type UnoverseClient, type UnoverseDefinition, type VoiceService } from "./lib";
-
-const MARK = "data-unoverse-interface";
-const CHAT = "page";
-const TEMPLATE_NODE = "~template";
-
-/** The page this runtime serves, or null when there is none it may reach (an MCP host). */
-function pageDocument(): Document | null {
-  try {
-    return window.parent !== window ? window.parent.document : null;
-  } catch {
-    return null; // a cross-origin host: there is no page of ours to draw into
-  }
-}
-
-/**
- * WHICH TEMPLATE THE ARROW KEYS BELONG TO: exactly one. The one the visitor last pressed in;
- * before any press, the one taking the most of the screen. Every template's state is its
- * own, so a key must never move two (the presentation's slides moved the avatar's steps).
- */
-let engaged: HTMLElement | null = null;
-function keyOwner(doc: Document): HTMLElement | null {
-  const full = doc.fullscreenElement as HTMLElement | null;
-  if (full?.hasAttribute(MARK)) return full; // a fullscreen template is the only one on screen
-  if (engaged && doc.contains(engaged)) return engaged;
-  const vh = doc.defaultView?.innerHeight ?? 0;
-  let best: HTMLElement | null = null;
-  let area = 0;
-  for (const el of doc.querySelectorAll<HTMLElement>(`[${MARK}]`)) {
-    const r = el.getBoundingClientRect();
-    const seen = Math.max(0, Math.min(r.bottom, vh) - Math.max(r.top, 0)) * r.width;
-    if (seen > area) (area = seen), (best = el);
-  }
-  return best;
-}
-
-/** A page template's address, from the name its element is marked with. */
-const uriOf = (name: string) => (name.includes("://") ? name : `unoverse://templates/${name}`);
-
-/** THE AVATARS: page templates whose steps are the call's phases (`listening`, `speaking`).
- *  They are how the page is spoken to, so they are never the task in view; they are the ones
- *  that follow the call. */
-const avatars = new Set<HTMLElement>();
-const CALL_PHASES = ["listening", "speaking"];
-
-/** The workflow a template names in its manifest (UNOVERSE_HOST_PAGE.md rule 4). */
-export type Binding = { workflow?: string; trigger?: string };
-
-/** THE TASK IN VIEW: the marked template, not an avatar, spanning the middle of the screen. */
-function taskInView(doc: Document): HTMLElement | null {
-  const mid = (doc.defaultView?.innerHeight ?? 0) / 2;
-  for (const el of doc.querySelectorAll<HTMLElement>(`[${MARK}]`)) {
-    if (avatars.has(el)) continue;
-    const r = el.getBoundingClientRect();
-    if (r.top <= mid && r.bottom >= mid) return el;
-  }
-  return null;
-}
-
-/**
- * THE AVATAR'S SPOT WHILE A TEMPLATE IS FULLSCREEN. The browser shows only the fullscreen
- * element, so the avatar's own element (in the site's navigation) is hidden. A fullscreen
- * state's layout carries a `Place`; it draws this element, and the page's avatar draws there
- * until the place goes. It is the same avatar, so it keeps following the call.
- */
-let dock: HTMLElement | null = null;
-const dockWatchers = new Set<() => void>();
-const setDock = (at: HTMLElement | null) => {
-  if (at === dock) return;
-  dock = at;
-  dockWatchers.forEach((f) => f());
-};
-const watchDock = (f: () => void) => {
-  dockWatchers.add(f);
-  return () => void dockWatchers.delete(f);
-};
-const drawDock = () => <div ref={setDock} />;
-
-type Section = { kind?: string; face?: string; ref?: string; preview?: string[]; seeds?: Record<string, Record<string, unknown>> };
-
-/** One marked template: read it, give it its parts, draw it. */
-function PageTemplate({ client, uri, el, voice, waiting, onBinding, onCall, appStore }: { client: UnoverseClient; uri: string; el: HTMLElement; voice: VoiceService; waiting: boolean; onBinding: (uri: string, binding: Binding) => void; onCall: ActionHandler; appStore: ComponentStore }) {
-  const store = useMemo(() => new ComponentStore(), [uri]);
-  const [ready, setReady] = useState(false);
-  const partsRef = useRef<string[]>([]);
-  const defRef = useRef<{ stateTree?: { name: string; on?: string; initial?: string; states?: { name: string }[]; fullscreen?: boolean }[] } | null>(null);
-
-  useEffect(() => {
-    let alive = true;
-    client
-      .readDefinition(uri)
-      .then((def) => {
-        if (!alive || !def) return;
-        const d = def as UnoverseDefinition & { defaultLayout?: string; layouts?: Record<string, unknown>; sections?: Record<string, Section[]>; binding?: Binding };
-        if (d.binding?.workflow) onBinding(uri, d.binding);
-        defRef.current = d as typeof defRef.current;
-        const base = d.defaultLayout ?? (d.layouts ? Object.keys(d.layouts)[0] : undefined);
-        partsRef.current = [];
-        for (const sec of (base && d.sections?.[base]) || []) {
-          const parts = sec.ref ? [sec.ref] : sec.kind === "director" ? sec.preview ?? [] : [];
-          parts.forEach((ref, i) => {
-            const nodeId = `${sec.face}~${ref}~${i}`;
-            partsRef.current.push(nodeId);
-            store.apply({ type: "COMPONENT_INIT", chatId: CHAT, nodeId, component: { type: ref, props: sec.seeds?.[ref] ?? {} } });
-            if (sec.face) store.mergeComponentState(CHAT, nodeId, { state: sec.face });
-          });
-        }
-        const ref = uri.replace(/^unoverse:\/\/templates\//, "");
-        store.apply({ type: "COMPONENT_INIT", chatId: CHAT, nodeId: TEMPLATE_NODE, component: { type: ref, componentUrl: uri, props: {} } });
-        if (base) store.mergeComponentState(CHAT, TEMPLATE_NODE, { state: base });
-        if ((d.stateTree ?? []).some((t) => CALL_PHASES.every((p) => t.states?.some((x) => x.name === p)))) avatars.add(el);
-        setReady(true);
-      })
-      .catch((e) => console.warn(`[unoverse] page template "${uri}" failed to load:`, e));
-    return () => {
-      alive = false;
-    };
-  }, [client, uri, store]);
-
-  // A TEMPLATE FOLLOWS ITS TASK. Whatever runs the task publishes where it is as
-  // `tasks.<its URI>` in the app state (SIGNAL.md 6c); this template moves to that step, the
-  // same write its own Next makes, whether the move came from a voice or a chat.
-  // Its `props` too, keyed by part: `{ <part>: values }` merges into that part (a template's
-  // content lives in its parts), once per change, so a template already on the page is
-  // hydrated in place.
-  //
-  // THE SAME TEMPLATE, STREAMED. When a run renders this template, it streams into the
-  // client's store like any interface. It is already on the page, so it is not drawn again:
-  // this copy hydrates from it, each part's values onto that part. A copy still on its first
-  // step (the wait, such as `finding`) moves to the next step as its values land; nothing
-  // outside the template moves it.
-  useEffect(() => {
-    if (!ready) return;
-    let lastProps = "";
-    let lastStreamed = "";
-    const fillParts = (parts: Record<string, unknown>) => {
-      for (const [part, values] of Object.entries(parts)) {
-        if (!values || typeof values !== "object" || Array.isArray(values)) continue;
-        for (const nodeId of partsRef.current.filter((id) => id.startsWith(`${part}~`))) store.mergeComponentState(CHAT, nodeId, values as Record<string, unknown>);
-      }
-    };
-    const moveTo = (at: unknown) => {
-      if (typeof at !== "string") return;
-      const tree = defRef.current?.stateTree?.find((t) => t.on && t.states?.some((x) => x.name === at));
-      if (!tree?.on) return;
-      const tpl = store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined;
-      if (tpl?.[tree.on] !== at) store.mergeComponentState(CHAT, TEMPLATE_NODE, { [tree.on]: at });
-    };
-    const follow = () => {
-      const task = ((appStore.getAppState().tasks ?? {}) as Record<string, { step?: string; props?: Record<string, unknown> }>)[uri];
-      if (task?.props && typeof task.props === "object") {
-        const next = JSON.stringify(task.props);
-        if (next !== lastProps) {
-          lastProps = next;
-          fillParts(task.props);
-        }
-      }
-      moveTo(task?.step);
-      for (const r of appStore.getResponses()) {
-        for (const pointer of r.components) {
-          const { chatId, nodeId } = appStore.split(pointer);
-          if ((appStore.getComponentUrl(chatId, nodeId) ?? "").split("#")[0] !== uri) continue;
-          const streamed = appStore.get(chatId, nodeId) ?? {};
-          const next = JSON.stringify(streamed);
-          if (next === lastStreamed) continue;
-          lastStreamed = next;
-          if (!streamed.state || typeof streamed.state !== "object") continue;
-          fillParts(streamed.state as Record<string, unknown>);
-          const tree = defRef.current?.stateTree?.find((t) => t.on && (t.states?.length ?? 0) > 1);
-          const tpl = store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined;
-          if (tree?.on && (tpl?.[tree.on] ?? tree.initial) === tree.initial) moveTo(tree.states![1].name);
-        }
-      }
-    };
-    follow();
-    return appStore.subscribe(follow);
-  }, [ready, appStore, store, uri]);
-
-  // THE ARROW KEYS STEP IT, on the PAGE. Left and Right move a template's steps (the served
-  // step tree: `on` + its substates), the same write its own Back and Next make. The keys are
-  // the page's, so they are heard on the page's document, not this frame's. Typing in a field
-  // never steps, and only the template that owns the keys moves (keyOwner).
-  useEffect(() => {
-    const doc = pageDocument();
-    if (!doc || !ready) return;
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key !== "ArrowRight" && e.key !== "ArrowLeft") return;
-      if (keyOwner(doc) !== el) return;
-      const t = e.target as HTMLElement | null;
-      if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
-      const tpl = store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined;
-      const def = defRef.current;
-      const face = String(tpl?.state ?? "");
-      const tree = def?.stateTree?.find((s) => s.name === face);
-      const steps = tree?.states?.map((s) => s.name) ?? [];
-      if (!tree?.on || steps.length < 2) return;
-      const cur = String(tpl?.[tree.on] ?? tree.initial ?? steps[0]);
-      const i = steps.indexOf(cur) + (e.key === "ArrowRight" ? 1 : -1);
-      if (i < 0 || i >= steps.length) return;
-      e.preventDefault();
-      store.mergeComponentState(CHAT, TEMPLATE_NODE, { [tree.on]: steps[i] });
-    };
-    doc.addEventListener("keydown", onKey);
-    return () => doc.removeEventListener("keydown", onKey);
-  }, [ready, store, el]);
-
-  // FULLSCREEN IS A STATE. Entering a state marked `fullscreen` takes this template's element
-  // fullscreen; leaving it hands the screen back. The request is made inside the store write
-  // the visitor's click made (setValue notifies synchronously), because a browser grants
-  // fullscreen only to a click. Refused, or left with Esc, the template goes back to the
-  // state it came from. The step is one value across states, so the slide stays put.
-  useEffect(() => {
-    const doc = pageDocument();
-    if (!doc || !ready) return;
-    const states = () => defRef.current?.stateTree ?? [];
-    const isFull = (name: string) => states().some((t) => t.name === name && t.fullscreen);
-    const face = () => String((store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined)?.state ?? "");
-    let from = isFull(face()) ? (states().find((t) => !t.fullscreen)?.name ?? "") : face();
-    let asking = false;
-    const back = () => store.mergeComponentState(CHAT, TEMPLATE_NODE, { state: from });
-    const sync = () => {
-      const now = face();
-      if (!isFull(now)) {
-        from = now;
-        if (doc.fullscreenElement === el) void doc.exitFullscreen();
-        return;
-      }
-      if (doc.fullscreenElement === el || asking) return;
-      asking = true;
-      el.requestFullscreen()
-        .catch(back)
-        .finally(() => (asking = false));
-    };
-    const onChange = () => {
-      if (doc.fullscreenElement !== el && !asking && isFull(face())) back();
-    };
-    const stop = store.subscribe(sync);
-    doc.addEventListener("fullscreenchange", onChange);
-    return () => {
-      stop();
-      doc.removeEventListener("fullscreenchange", onChange);
-    };
-  }, [ready, store, el]);
-
-  // WHILE A TEMPLATE IS FULLSCREEN, AN AVATAR DRAWS IN ITS PLACE (drawDock).
-  const docked = useSyncExternalStore(watchDock, () => dock);
-
-  // AN AVATAR FOLLOWS THE CALL: its steps are the call's phases, so its step is the call's
-  // state. `waiting` rides beside it, on any step: a task in view that the call is not working
-  // yet. The avatar draws it as a pulse, and a press on the pulse starts or moves the call.
-  const callState = voice.state.callState;
-  useEffect(() => {
-    if (!ready || !avatars.has(el)) return;
-    const tree = defRef.current?.stateTree?.find((t) => CALL_PHASES.every((p) => t.states?.some((x) => x.name === p)));
-    if (!tree?.on) return;
-    store.mergeComponentState(CHAT, TEMPLATE_NODE, { [tree.on]: callState, waiting });
-  }, [ready, store, el, callState, waiting]);
-
-  if (!ready) return null;
-  const drawn = <UnoverseComponent client={client} store={store} chatId={CHAT} nodeId={TEMPLATE_NODE} onAction={onCall} place={drawDock} appStore={appStore} />;
-  return docked && avatars.has(el) ? createPortal(drawn, docked) : drawn;
-}
-
-/**
- * ONE APP STATE FOR THE WHOLE PAGE. Each template keeps its own slice in its own store, and
- * all of them read and write the app's state in `appStore`, the store the call and the
- * workflow write to. A name one template saves is a name every other template can show.
- */
-export function PageInterfaces({ org, client, voice, appStore, toServer, startTask }: { org: string; client: UnoverseClient; voice: VoiceService; appStore: ComponentStore; toServer: (t: string, data: Record<string, unknown>, meta?: ActionMeta) => void; startTask: (binding: Binding, task: string, submit?: Record<string, unknown>) => void }) {
-  const [targets, setTargets] = useState<HTMLElement[]>([]);
-  // The task in view, by its URI, measured again as the page scrolls or resizes.
-  const [inView, setInView] = useState<string | null>(null);
-  // Each template's own workflow, as it loads; a template without one is never called.
-  const [bindings, setBindings] = useState<Record<string, Binding>>({});
-  const onBinding = useCallback((uri: string, b: Binding) => setBindings((prev) => (prev[uri] ? prev : { ...prev, [uri]: b })), []);
-  // The tasks this page has started. Each starts once: a second press starts nothing. The ref
-  // holds it at once, so two quick presses are still one; the state redraws the avatar.
-  const started = useRef(new Set<string>());
-  const [, setStarted] = useState(0);
-
-  // THE AVATAR STARTS THE TASK'S WORKFLOW (UNOVERSE_HOST_PAGE.md rule 4), like any button. The
-  // page connects to nothing until it is pressed. A task in view with a workflow, that is not
-  // already running, is WAITING: a press starts its workflow at the template's trigger. A voice
-  // in that workflow is the workflow's own. Nothing in view, or nothing bound: nothing.
-  const target = inView && bindings[inView]?.workflow ? inView : null;
-  const waiting = !!target && !started.current.has(target);
-  // A TEMPLATE'S OWN ACTIONS go where the app's go: its `submit` answers whoever opened the task,
-  // exactly as in the app (appEngine `toServer`). A template with its own workflow also has
-  // that workflow called with the answers: the submit is the task's last call, and its Task
-  // Runner finishes it (design/tasks.md, "The submit"). The call's three are the page's.
-  const onCallFor = (uri: string): ActionHandler => (spec, data, meta) => {
-    const action = typeof spec === "string" ? spec : spec?.type;
-    if (action === "submit" || action === "cancel") {
-      toServer(action, data, meta);
-      const state = (meta?.state ?? data) as Record<string, unknown> | undefined;
-      if (action === "submit" && bindings[uri]?.workflow && state && typeof state === "object") startTask(bindings[uri], uri, state);
-    } else if (action === "startCall") {
-      if (!target || started.current.has(target)) return;
-      started.current.add(target);
-      setStarted((n) => n + 1);
-      // The press is the click the browser needs before it plays a voice the workflow may have.
-      voice.unlock();
-      startTask(bindings[target], target);
-    } else if (action === "endCall") {
-      void voice.endCall();
-    } else if (action === "toggleMute") voice.toggleMute();
-    // Another app on the page, opened or closed by its `<org>/<app>` (its own tag, EMBED_CLIENT.md).
-    else if (action === "toggleApp") {
-      const app = (data as { app?: unknown } | undefined)?.app;
-      if (typeof app === "string") (pageDocument()?.defaultView as (Window & { unoverseApps?: Record<string, { toggle(): void }> }) | undefined)?.unoverseApps?.[app]?.toggle();
-    }
-  };
-
-  useEffect(() => {
-    const doc = pageDocument();
-    const win = doc?.defaultView;
-    if (!doc || !win) return;
-    const measure = () => {
-      const name = taskInView(doc)?.getAttribute(MARK);
-      setInView(name ? uriOf(name) : null);
-    };
-    measure();
-    win.addEventListener("scroll", measure, { passive: true });
-    win.addEventListener("resize", measure);
-    return () => {
-      win.removeEventListener("scroll", measure);
-      win.removeEventListener("resize", measure);
-    };
-  }, [targets]);
-
-  useEffect(() => {
-    const doc = pageDocument();
-    if (!doc) return;
-    const scan = () => {
-      // Only this app's own org's templates: another app on the page draws its own.
-      const found = [...doc.querySelectorAll<HTMLElement>(`[${MARK}]`)].filter((el) => el.getAttribute(MARK)?.startsWith(`${org}/`));
-      setTargets((prev) => (prev.length === found.length && prev.every((el, i) => el === found[i]) ? prev : found));
-    };
-    scan();
-    // The page may render its parts after this runtime starts (a client-rendered page),
-    // so it keeps looking; only a change in the marked set re-renders.
-    const watch = new MutationObserver(scan);
-    watch.observe(doc.body, { childList: true, subtree: true });
-    // A press anywhere inside a marked template makes it the one the keys move; a press
-    // outside every template hands the keys back to the one most in view.
-    const onPress = (e: Event) => {
-      engaged = (e.composedPath().find((n) => n instanceof HTMLElement && n.hasAttribute(MARK)) as HTMLElement | undefined) ?? null;
-    };
-    doc.addEventListener("pointerdown", onPress, true);
-    return () => {
-      watch.disconnect();
-      doc.removeEventListener("pointerdown", onPress, true);
-    };
-  }, []);
-
-  return (
-    <>
-      {targets.map((el) => {
-        const name = el.getAttribute(MARK) ?? "";
-        if (!name) return null;
-        return createPortal(<PageTemplate client={client} uri={uriOf(name)} el={el} voice={voice} waiting={waiting} onBinding={onBinding} onCall={onCallFor(uriOf(name))} appStore={appStore} />, el, name);
-      })}
-    </>
-  );
-}

package/vendor/sdk/responseView.tsx

@@ -1,82 +0,0 @@
-/**
- * THE RESPONSE VIEW — what an UNNAMED result renders (THE NAMING RULE,
- * docs/mcp/UNOVERSE_MCP_APP_PROTOCOL § THE NAMING RULE).
- *
- * An MCP Action's result carries `interface: { kind: "components", components }` —
- * the component events the run produced. This view renders EXACTLY those: seed a
- * fresh store with the events, resolve the theme, paint each instance with the
- * standard renderer. No app mount, no session registration, no home state, no
- * auto-trigger — an app mounts only when something NAMES it (a channel, a row, or
- * a result declaring `kind: "app"`).
- *
- * Definitions and theme still resolve over the result's serverUrl (`/mcp` reads) —
- * the response is data; the rendering vocabulary lives on the universe.
- */
-import { useMemo } from "react";
-import {
-  UnoverseClient,
-  ComponentStore,
-  StreamedUnoverseComponent,
-  useUnoverseTheme,
-  applyServerMessage,
-} from "./lib";
-
-export interface ResponseViewProps {
-  serverUrl: string;
-  /** The run's component events (COMPONENT_INIT / COMPONENT_DATA), as collected
-   *  server-side and carried in the result's `interface.components`. */
-  events: Record<string, unknown>[];
-}
-
-export function ResponseView({ serverUrl, events }: ResponseViewProps) {
-  const client = useMemo(() => new UnoverseClient(`${serverUrl}/mcp`, {}), [serverUrl]);
-
-  // Seed once per result: the same pure mapper the live stream uses, so a seeded
-  // component is indistinguishable from a streamed one (merge-not-replace and all).
-  const store = useMemo(() => {
-    const s = new ComponentStore();
-    const seen = new Set<string>();
-    for (const e of events) {
-      try {
-        applyServerMessage(s, e as never, seen);
-      } catch {
-        /* one malformed event must not blank the whole response */
-      }
-    }
-    return s;
-  }, [events]);
-
-  const theme = useUnoverseTheme(client);
-
-  // One card per INSTANCE, in arrival order (the events carry chatId+nodeId — the
-  // store's own keying — so no pointer parsing).
-  const instances = useMemo(() => {
-    const out: { chatId: string; nodeId: string }[] = [];
-    const seen = new Set<string>();
-    for (const e of events) {
-      const ev = e as { type?: string; chatId?: string; nodeId?: string };
-      if (ev.type !== "COMPONENT_INIT" || !ev.chatId || !ev.nodeId) continue;
-      const key = `${ev.chatId}:${ev.nodeId}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      out.push({ chatId: ev.chatId, nodeId: ev.nodeId });
-    }
-    return out;
-  }, [events]);
-
-  if (!instances.length) return null;
-  return (
-    <div style={{ display: "flex", flexDirection: "column", gap: 12, padding: 12 }}>
-      {instances.map((i) => (
-        <StreamedUnoverseComponent
-          key={`${i.chatId}:${i.nodeId}`}
-          client={client}
-          store={store}
-          chatId={i.chatId}
-          nodeId={i.nodeId}
-          theme={theme ?? undefined}
-        />
-      ))}
-    </div>
-  );
-}