@unoverse-platform/studio 0.1.102 → 0.1.104

package/vendor/sdk/lib/UnoverseComponent.tsx

@@ -1,325 +0,0 @@
-/**
- * <UnoverseComponent> — reads a definition by URI from the Unoverse MCP server
- * (via ./core) and renders it natively.
- *
- * ONE COMPONENT, TWO DATA SOURCES. A definition cannot tell which is rendering it, so the
- * SDK stopped pretending they were different things:
- *
- *   data source          give it                        state lives in
- *   a plain object       `uri` + `data`                 a local slice, here
- *   the live stream      `store` + `chatId` + `nodeId`  the store's slice
- *
- * The split used to be two exported components, and a host had to know which one it was
- * holding. It never mattered to the component: the same `renderNode` walks the same
- * definition, and `setValue` writes the same instance either way.
- */
-import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
-import { dispatchAction, matches, type ComponentStore, type ResolvedTheme, type UnoverseClient, type UnoverseDefinition } from "./core";
-import { renderNode, keyframesCss, type ActionHandler, type SlotResolver } from "./render";
-import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
-import { IsolatedRoot } from "./isolate";
-import { stateOfUri } from "./core/apps";
-
-/** Subscribe to an instance in the store, re-rendering when a merge lands. Snapshots THIS
- *  instance's slice (merge() gives it a fresh identity), so chunks for other components bail
- *  out in React instead of re-rendering everyone. Tolerates no store: the static path calls
- *  the same hook, because hooks cannot be conditional. */
-export function useUnoverseInstance(store?: ComponentStore, chatId = "", nodeId = "") {
-  const subscribe = useCallback((cb: () => void) => (store ? store.subscribe(cb) : () => {}), [store]);
-  const data = useSyncExternalStore(
-    subscribe,
-    useCallback(() => (store ? store.get(chatId, nodeId) : undefined), [store, chatId, nodeId]),
-  );
-  const type = useSyncExternalStore(
-    subscribe,
-    useCallback(() => (store ? store.getType(chatId, nodeId) : undefined), [store, chatId, nodeId]),
-  );
-  const componentUrl = useSyncExternalStore(
-    subscribe,
-    useCallback(() => (store ? store.getComponentUrl(chatId, nodeId) : undefined), [store, chatId, nodeId]),
-  );
-  return { type, data, componentUrl };
-}
-
-export interface UnoverseComponentProps {
-  client: UnoverseClient;
-  /** 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>;
-  /** LIVE source: the merge-state store. With it, `uri` and `data` come from the instance. */
-  store?: ComponentStore;
-  chatId?: string;
-  nodeId?: string;
-  /** Neutral turn state merged into the data scope (e.g. `streaming`), so a component can
-   *  reflect it. Live source only. */
-  extraData?: Record<string, unknown>;
-  onAction?: ActionHandler;
-  /**
-   * Resolved theme. Optional — if omitted, the SDK FETCHES it from the server
-   * (`unoverse://theme/light`). The SDK bundles no tokens. Pass one to override
-   * (e.g. the workbench's light/dark toggle); swap it to restyle, zero def changes.
-   */
-  theme?: ResolvedTheme;
-  /**
-   * Render inside a Shadow DOM for full CSS isolation (default true). The SDK owns the
-   * isolation boundary so every consumer is protected identically; the canvas/channel no
-   * longer wrap it themselves. Set false only for a host that manages its own isolation.
-   */
-  isolate?: boolean;
-  /**
-   * A SURFACE'S SINGLE OCCUPANT FILLS THE SURFACE (docs/design/05): set by a limit-1
-   * reaction surface so the instance wrapper takes the frame's full height. The
-   * component still owns its face — this only gives its `height: "full"` a definite
-   * container. Flow/rail instances stay content-sized (never set there).
-   */
-  fill?: boolean;
-  /**
-   * WHAT A `Place` IN THIS DEFINITION DRAWS. An app's places are filled by the screen
-   * (app.tsx); a place inside a component or template is filled by its host, which alone
-   * knows what belongs there (a fullscreen template's place holds the page's avatar).
-   * Without it a place draws nothing.
-   */
-  place?: (name: string) => ReactNode;
-  /**
-   * THE APP'S STATE, when it lives in another store (live source only). A template a website
-   * page draws keeps its own slice in its own store, and shares one app state with the rest
-   * of the page: it reads that state beneath its own values, and `setAppValue` writes there.
-   */
-  appStore?: ComponentStore;
-}
-
-export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, extraData, onAction, theme, isolate = true, fill = false, place, appStore }: UnoverseComponentProps) {
-  const [def, setDef] = useState<UnoverseDefinition | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  // A component's OWN view state (a tab, a step, an expanded face) moves by writing its own
-  // slice. That write is not a host concern: a tab click should work wherever a component
-  // renders, without every surface wiring a handler for it. So the renderer keeps the slice
-  // and applies `setValue` to it, and STILL forwards every action to `onAction` for hosts
-  // that care (a channel persisting state, a workflow answering a submit).
-  const [localSlice, setLocalSlice] = useState<Record<string, unknown>>({});
-  // LIVE SOURCE. The hook runs either way (hooks cannot be conditional) and no-ops without a
-  // store, so one component serves both paths without a wrapper deciding for it.
-  const live = useUnoverseInstance(store, chatId, nodeId);
-  const appState = useSyncExternalStore(
-    useCallback((cb: () => void) => (appStore ? appStore.subscribe(cb) : () => {}), [appStore]),
-    useCallback(() => appStore?.getAppState(), [appStore]),
-  );
-  // The SERVER-SENT address first: an org component's URI is org-qualified
-  // (`unoverse://components/<org>/<name>`) and the bare type cannot rebuild it once two
-  // orgs share a name. The rebuild-from-type stays as the fallback for events that
-  // carry no componentUrl. (Still the plain URI, never the withdrawn `@refs` form —
-  // that suffix broke Studio's local definition route.)
-  // THE HASH NAMES THE STATE (stateOfUri): the address is read without it, and it seeds the
-  // public `state` of a static instance that carries none, so `...#page` opens on the page.
-  const address = store ? (live.componentUrl ?? (live.type ? `unoverse://components/${live.type}` : null)) : (uri ?? null);
-  const { uri: resolvedUri, state: hashState } = address ? stateOfUri(address) : { uri: null as string | null };
-  const sourceData = store
-    ? (extraData ? { ...(live.data ?? {}), ...extraData } : live.data)
-    : (hashState && data?.state == null ? { state: hashState, ...(data ?? {}) } : data);
-  // No theme passed → fetch it from the server (the SDK owns zero token values). The
-  // theme REF comes from the definition itself: a template's `org` names its client's
-  // theme (`<org>/light`); a universal component previews under the default set
-  // ("light" — channels pass their org's theme explicitly). Wait for the def before
-  // fetching (null = no fetch) so the wrong theme never flashes.
-  const fetched = useUnoverseTheme(client, theme ? null : def ? (def.org ? `${def.org}/light` : "light") : null);
-  const activeTheme = theme ?? fetched;
-  // Register the theme's webfonts (served DATA) at document level — see ensureFontStylesheets.
-  useEffect(() => ensureFontStylesheets(activeTheme), [activeTheme]);
-
-  useEffect(() => {
-    let alive = true;
-    setDef(null);
-    setError(null);
-    setLocalSlice({});
-    if (!resolvedUri) return;
-    client
-      .readDefinition(resolvedUri)
-      .then((d) => alive && setDef(d))
-      .catch((e) => alive && setError(String(e?.message ?? e)));
-    return () => {
-      alive = false;
-    };
-  }, [client, resolvedUri]);
-
-  // Fill props the instance didn't provide from the definition's defaults; instance `data`
-  // overrides. This is what lets a partially-emitted component still render its declared
-  // baseline — e.g. StreamingText's `progressText` default ("Thinking…") shows while the node
-  // streams and hasn't emitted a progress line. IMPORTANT: a def `default` must therefore be
-  // a sensible RUNTIME fallback, NOT a demo placeholder — a demo-y default (e.g. a markdown
-  // showcase on `text`) would mask an empty stream. Keep demo content out of prop defaults.
-  // Memoized on the def — a streaming component re-renders per chunk; the defaults don't move.
-  const propDefaults = useMemo(
-    () =>
-      Object.fromEntries(
-        Object.entries((def?.props ?? {}) as Record<string, { default?: unknown }>).map(([k, v]) => [k, v?.default]),
-      ),
-    [def],
-  );
-
-  // ONE ACTION RULE, TWO OWNERS OF THE SLICE. `setValue` writes THIS instance's keys; where
-  // they land is the only difference between the two sources, and the component never knows.
-  const handleAction = useMemo<ActionHandler>(
-    () =>
-      store
-        ? (action, scope) =>
-            dispatchAction(action, scope, {
-              store,
-              chatId: chatId ?? "",
-              nodeId: nodeId ?? "",
-              appStore,
-              // Server actions carry the INSTANCE context (which component + its current
-              // slice) so the channel can forward the submitted state with the action.
-              sendToServer: onAction
-                ? (t, payload) =>
-                    onAction(t, payload, {
-                      chatId,
-                      nodeId,
-                      type: live.type,
-                      state: store.get(chatId ?? "", nodeId ?? ""),
-                    })
-                : undefined,
-            })
-        : (action, payload, meta) => {
-            // No store, so the slice is local. This is what makes a tab work in a preview,
-            // a content panel or an email-shaped host with no state code in between.
-            if (action && typeof action === "object" && (action as { type?: string }).type === "setValue") {
-              const values = ((action as { values?: { key: string; value: unknown }[] }).values ?? []).filter(
-                (v) => v && typeof v.key === "string",
-              );
-              if (values.length)
-                setLocalSlice((prev) => ({ ...prev, ...Object.fromEntries(values.map((v) => [v.key, v.value])) }));
-            }
-            onAction?.(action, payload, meta);
-          },
-    [store, chatId, nodeId, onAction, live.type, appStore],
-  );
-
-  // ARROW KEYS STEP A TEMPLATE. A template's steps (the served stateTree: `on` + its
-  // substates) move with Left and Right while it holds the main place, through the same
-  // setValue its own Back and Next make, so the step is saved and reported exactly as a
-  // click would be. Forms (components) are left alone: their steps are confirmations.
-  // Typing in a field never steps.
-  const slice = store ? sourceData : localSlice;
-  useEffect(() => {
-    const d = def as (UnoverseDefinition & {
-      kind?: string;
-      stateTree?: { name: string; on?: string; states?: { name: string }[] }[];
-      statePlaces?: Record<string, string>;
-    }) | null;
-    if (d?.kind !== "template") return;
-    const face = String((slice as Record<string, unknown> | undefined)?.state ?? d.state?.state ?? "");
-    const tree = (d.stateTree ?? []).find((s) => s.name === face);
-    const steps = tree?.states?.map((s) => s.name) ?? [];
-    if (!tree?.on || steps.length < 2 || d.statePlaces?.[face] !== "main") return;
-    const on = tree.on;
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key !== "ArrowRight" && e.key !== "ArrowLeft") return;
-      const t = e.target as HTMLElement | null;
-      if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
-      const cur = String((slice as Record<string, unknown> | undefined)?.[on] ?? d.state?.[on] ?? steps[0]);
-      const i = steps.indexOf(cur) + (e.key === "ArrowRight" ? 1 : -1);
-      if (i < 0 || i >= steps.length) return;
-      e.preventDefault();
-      handleAction({ type: "setValue", values: [{ key: on, value: steps[i] }] }, {});
-    };
-    document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
-  }, [def, slice, handleAction]);
-
-  // Loading/error hints carry NO styling — the SDK owns zero styles (tokens or hints).
-  if (error) return <div>Unoverse error: {error}</div>;
-  if (store && !live.type) return <div>waiting for COMPONENT_INIT…</div>;
-  if (!def || !activeTheme) return <div>Loading {resolvedUri ?? "component"}…</div>;
-  // Internal state initial values (def.state) sit beneath the live slice — the
-  // microapp's own keys (step/phase/…) start at their authored values and move only
-  // when its actions write them. Props stay the EXTERNAL contract.
-  // The local slice sits ON TOP: a value the component wrote itself is the current one.
-  const merged = store
-    ? { ...propDefaults, ...(appState ?? {}), ...(def?.state ?? {}), ...(sourceData ?? {}) }
-    : { ...propDefaults, ...(def?.state ?? {}), ...(sourceData ?? {}), ...localSlice };
-  // Inject the served keyframes + apply the SERVED base render-root (theme.root — DS typography
-  // + font-smoothing). When ISOLATED, theme.root is applied to the shadow-root container inside
-  // IsolatedRoot (a REAL box — reliable font cascade in the shadow tree). When NOT isolated the
-  // host owns isolation, so apply it here on a `display:contents` wrapper (out of layout while
-  // its inherited props cascade) — the design-system baseline either way.
-  const keyframes = <style>{keyframesCss(activeTheme)}</style>;
-  // The shared pieces this definition NAMES travel beside it and are threaded through
-  // every recursion, so a reference nested in a Switch branch or an Each item resolves too.
-  // A DEFINITION THAT CARRIES SLOTS RESOLVES THEM — the rule the SDK already applies to
-  // an app tree, applied here too. Without it a rendered TEMPLATE drew its frame and every
-  // section resolved to null (render.tsx: `slot ? slot(node) : null`), so a page that
-  // STREAMED IN rather than being mounted by an app came out blank. Mounted templates were
-  // fine because `app.tsx` hands that path a resolver; instances never got one, and a
-  // definition rendering its own parts nowhere is a renderer bug, not a design decision.
-  //
-  // Generic and dumb, like the rest of it: the slot's claim picks instances out of the
-  // SAME store by the face they wear, in the order the store holds them. It knows nothing
-  // about templates, days or cards — only "which instances match this claim".
-  //
-  // TEMPLATES ONLY, and the boundary matters: an ordinary component may carry the
-  // conversation's FLOW slot (`select: {}` inside a chat's assistant turn), and that one
-  // belongs to the app's timeline, which scopes it to a single turn's unclaimed
-  // components. Resolving it here too rendered every instance in the store a second time
-  // — the composed page appeared in its surface AND in the chat beside it.
-  const resolveSlot: SlotResolver | undefined = (store && (def as { sections?: unknown }).sections) || place
-    ? (node, key) => {
-        if (node.type === "Place") return place?.(String((node as { name?: unknown }).name ?? "")) ?? null;
-        if (!store) return null;
-        const claim = node.select?.where;
-        const pointers = store
-          .getResponses()
-          .flatMap((r) => r.components)
-          .filter((p) => {
-            const { chatId: c, nodeId: n } = store.split(p);
-            if (n === nodeId) return false; // never claim the instance drawing the slot
-            return claim ? matches(claim, (store.get(c, n) ?? {}) as Record<string, unknown>) : true;
-          })
-          .slice(0, node.select?.limit ?? undefined);
-        if (!pointers.length)
-          return node.fallback ? renderNode(node.fallback, {}, handleAction, activeTheme, key ?? "fb", undefined, def.defs) : null;
-        return pointers.map((p) => {
-          const { chatId: c, nodeId: n } = store.split(p);
-          return (
-            <UnoverseComponent
-              key={n}
-              client={client}
-              store={store}
-              chatId={c}
-              nodeId={n}
-              onAction={onAction}
-              theme={activeTheme}
-              appStore={appStore}
-            />
-          );
-        });
-      }
-    : undefined;
-  const tree = renderNode(def.root, merged, handleAction, activeTheme, undefined, resolveSlot, def.defs);
-  // The isolation container MIRRORS the component root's declared sizing intent (§4a:
-  // the component owns its size; the host responds). A root that declares
-  // `height: "full"` needs a definite chain — the container passes the host's height
-  // through (100%). Any other root keeps an auto container → fit-to-content, the §5a
-  // default (a card in a timeline must NOT fill). Without this, a full-height
-  // component's 100% resolves against an auto box and silently collapses.
-  const fillsHost = fill || ((def.root as { style?: Record<string, unknown> })?.style?.height ?? null) === "full";
-  const isolatedRootStyle = {
-    ...(activeTheme.root as CSSProperties),
-    ...(fillsHost ? { height: "100%" } : {}),
-    ...(fill ? { flex: "1 1 auto", minHeight: 0 } : {}),
-  };
-  if (isolate) {
-    return (
-      <IsolatedRoot rootStyle={isolatedRootStyle}>
-        {keyframes}
-        {tree}
-      </IsolatedRoot>
-    );
-  }
-  return (
-    <>
-      {keyframes}
-      <div style={{ display: "contents", ...(activeTheme.root as CSSProperties) }}>{tree}</div>
-    </>
-  );
-}