@unoverse-platform/studio 0.1.0

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

@@ -0,0 +1,194 @@
+/**
+ * @unoverse/core — shared neutral types.
+ *
+ * The neutral definition shape, the interaction vocabulary, and the resolved-theme
+ * SHAPE (values live on the server). Pure types — no runtime, no imports.
+ */
+
+// ---- The neutral definition shape (mirrors apps/unoverse/definitions/*.json) ----
+
+export interface UnoverseNode {
+  type: string; // Box | Stack | Row | Column | Text | Image | Button | ComponentSlot | Skeleton | ...
+  style?: Record<string, unknown>;
+  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)
+  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
+   *  scroll-container behavior, opt-in via data (e.g. the conversation state's scroll box). */
+  autoScroll?: boolean;
+  /** Box: a sticky bar (its own `position: sticky` + `top` in rx) that stays HIDDEN while
+   *  the element before it (its previous sibling — e.g. a hero image) is on screen, then
+   *  fades in once that sibling scrolls away. Overlays the content (no flow gap). Generic
+   *  scroll-reveal behavior, opt-in via data. */
+  revealOnStick?: boolean;
+  /** THE PROTOCOL'S LOADING SEMANTIC: while this node's bound field carries no data yet,
+   *  render its Skeleton ghost in place (variant inferred from the node type; look fully
+   *  theme-driven). One word gives any progressively-composed page (briefed components)
+   *  honest loading states — each platform SDK realizes it with its native idiom. */
+  skeleton?: boolean;
+  /** TEMPLATE LAYOUT ROOT ONLY — the guest-control law: a pinned layout, once active,
+   *  changes only by a GUEST write (tap, its ✕) — background arrivals cannot displace
+   *  it. Yields also when its component leaves the view or the template swaps. */
+  pinned?: boolean;
+  children?: UnoverseNode[];
+  // --- template primitives (UNOVERSE_SPEC.md §2e) ---
+  /** ComponentSlot: which components to pull from the store timeline.
+   *  `where` selects by COMPONENT STATE (the reaction contract, STATE_MODEL §5b): any
+   *  component whose slice matches, newest state-write first — NEVER by type/id (a
+   *  template naming a component type was the violation; the vocabulary has no way to
+   *  say it). The field/value are the template author's data; core knows no state names. */
+  select?: { from?: "latest" | "all"; limit?: number; where?: { field: string; eq?: unknown; ne?: unknown } };
+  /** ComponentSlot: rendered when the slot resolves to zero components. */
+  fallback?: UnoverseNode;
+  /** ComponentSlot: chrome rendered AROUND the matches — only when the slot resolved
+   *  (the non-empty twin of `fallback`). Inside it, a bare `{ "type": "ComponentSlot" }`
+   *  (no select) receives the outer slot's matches. This is how a template surface
+   *  EXISTS only while a component is in its state (§5b: derived, not stored) — e.g. a
+   *  focus overlay that appears because something is focused and vanishes when it isn't. */
+  frame?: UnoverseNode;
+  /** Skeleton: placeholder variant. */
+  variant?: "text" | "card" | "image";
+  /** Timeline: data sub-tree rendered for a user turn (binds `text`). ALL bubble UX lives here, not the SDK. */
+  user?: UnoverseNode;
+  /** Timeline: data sub-tree rendered for an assistant turn (its ComponentSlot is scoped to that turn). */
+  assistant?: UnoverseNode;
+  /** Each: the per-item subtree, rendered once per element of the bound array (`bind.items`),
+   *  with that element as its data scope. The node's own `style` is the list container. */
+  template?: UnoverseNode;
+  /** Literal content — components are microapps: static copy/lists/images are HARDCODED
+   *  in the def; props exist only for state (UNOVERSE_AUTHORING.md). `bind` wins when set. */
+  value?: unknown; // Text
+  items?: unknown[]; // Each
+  src?: string; // Image
+  alt?: string; // Image
+  /** Timeline: static author data merged into every assistant turn's data scope
+   *  (e.g. avatarUrl, thinkingText). The SDK forwards it verbatim — it interprets
+   *  nothing chat-specific; the turn STATE flags (streaming/thinking) are added on top. */
+  assistantData?: Record<string, unknown>;
+  /** Timeline: static author data merged into every user turn's data scope. */
+  userData?: Record<string, unknown>;
+  /** Icon: the served glyph NAME (literal) — or bind a data field via `bind.name`. */
+  icon?: string;
+  /** Disable the element (Input/Button) when this data field is truthy; the node's
+   *  `style.disabled` is merged while disabled. */
+  disabledWhen?: string;
+  /** Switch: the data field whose value selects which `cases` branch renders. */
+  on?: string;
+  /** Switch: a value→branch map (string-keyed). The branch for `data[on]` renders;
+   *  if none matches, `cases.default` renders; if neither, nothing renders. The
+   *  declarative whole-view swap (a wizard step, inline↔focused) — one place, mutually
+   *  exclusive, instead of a `visibleWhen` repeated on every branch. Each branch is a
+   *  normal subtree (commonly a `{ "$include": "step-x" }`, expanded at load). */
+  cases?: Record<string, UnoverseNode>;
+}
+
+export interface UnoverseDefinition {
+  unoverse: string;
+  kind: "component" | "template";
+  name: string;
+  /** For a TEMPLATE: the client org it belongs to (server-injected). Names the org's
+   *  theme (`unoverse://theme/{org}/light`). Universal components carry no org. */
+  org?: string;
+  description?: string;
+  /** EXTERNAL contract — the rare workflow-fed inputs (`input: true`). A contained
+   *  microapp has an EMPTY (or absent) props block. */
+  props?: Record<string, unknown>;
+  /** INTERNAL state + initial values — the keys the component's own actions write
+   *  (step, phase, its defaultState signal). Never external, never workbench controls;
+   *  merged into the render scope beneath the live slice. */
+  state?: Record<string, unknown>;
+  root: UnoverseNode;
+  /** TEMPLATE LAYOUTS (name-sync, docs/design/05): present only when the template
+   *  ships multiple layouts/ files. Each is a full arrangement; the active one is
+   *  the layout whose NAME matches the latest surfaced component view, falling back
+   *  to `defaultLayout`. Absent → classic single-layout behavior via `root`. */
+  layouts?: Record<string, UnoverseNode>;
+  defaultLayout?: string;
+}
+
+// ---- The interaction vocabulary (UNOVERSE_SPEC.md §2e-3) ----
+//
+// A small, declarative layer — NOT a programming language. Stac-inspired
+// (set_value + Multi Action + visible-if): an `action` is a bare string (→ the
+// workflow) or a `setValue` envelope (a LOCAL store write, the ported `updateData`);
+// `visibleWhen` is a truthy field name or an equality test.
+
+/** One `setValue` patch. `value` is a literal OR a `{{field}}` / `{{a.b}}` binding
+ *  resolved against the action's data scope (e.g. the tapped item inside an `Each`). */
+export interface ActionValue {
+  key: string;
+  value: unknown;
+}
+
+/** A declarative action. `setValue` merges `values` into THIS component's
+ *  `chatId:nodeId` slice (no round-trip); any other `type` routes to the workflow
+ *  (optionally narrowed by `send`). `then` chains a follow-up (Stac Multi Action). */
+export interface ActionSpec {
+  // The SDK hardcodes no UI concept — only generic writes + a server route:
+  type: string; // "setValue" (component slice) | "setTemplateValue" (template state) | "input" | "submit"/custom (→ server)
+  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
+}
+
+/** A data condition, evaluated against the render data scope. Pick ONE test:
+ *  `eq` (equals), `ne` (not-equals), `in` (one of a list) — or, with none of them, a
+ *  truthy test on `field`. Shared by `visibleWhen`, the `Switch` node, and `style.when`,
+ *  so the three "react to state" mechanisms speak ONE predicate. NOT a programming
+ *  language — no `and`/`or`/arithmetic; derive anything richer in the producing node. */
+export type Condition = { field: string; eq?: unknown; ne?: unknown; in?: unknown[] };
+
+/** `visibleWhen`: a data field name (truthy; an empty array counts as empty) OR a
+ *  `Condition`. The element renders only when it holds. */
+export type VisibleWhen = string | Condition;
+
+/** A data-driven style variant — the generalization of `style.disabled`. When its
+ *  `Condition` holds against the data scope, `apply` (ordinary style vocab) is merged
+ *  OVER the base style (later variants win). Authored as `style.when: StyleVariant[]`.
+ *  This is render-time (data) styling; interaction styling (hover/active/disabled) stays
+ *  in the injected pseudo-state keys. Lets one element restyle by state instead of
+ *  cloning it under opposite `visibleWhen`s. */
+export type StyleVariant = Condition & { apply: Record<string, unknown> };
+
+// ---- The resolved theme (SHAPE only — values live on the server) ----
+//
+// The MCP server OWNS THE VISUAL: it resolves the design tokens (apps/unoverse/
+// rx/styles) live and serves this shape at `unoverse://theme/{name}`. This is the
+// token SHAPE, never the token VALUES — the SDK fetches the values (readTheme),
+// it does NOT bundle them. A brand change in rx/styles is therefore refresh-only,
+// exactly like a definition change (UNOVERSE_SPEC §2d-1).
+export interface ResolvedTheme {
+  color: Record<string, string>;
+  /** Webfont stylesheet URLs (served `fonts.stylesheets` data) — injected into
+   *  document.head by the SDK (shadow roots can't register @font-face). */
+  fonts?: string[];
+  /** Dimension scale (theme.space ← rx/styles/base/spacing.json) — used for BOTH spacing
+   *  (gap/padding/margin) AND element sizes (width/height), Tailwind-style. */
+  space: Record<string, string>;
+  radius: Record<string, string>;
+  shadow: Record<string, string>;
+  borderWidth: Record<string, string>;
+  /** Line-height tokens (theme.lineHeight ← font.lineHeight) — tight/snug/normal/relaxed. */
+  lineHeight: Record<string, string | number>;
+  text: Record<string, Record<string, string | number>>;
+  skeleton: Record<string, unknown>;
+  prose: Record<string, unknown>;
+  /** STANDARD APP SIZES (theme.appSize ← rx/styles/semantic/app-sizes.json) — the named
+   *  width blocks `appWidth` references ("chat"/"rail"/"panel" → raw host-facing CSS).
+   *  Resolved by the SDK like every other token — one pipeline. */
+  appSize?: Record<string, string>;
+  /** Named keyframes (theme.keyframes ← rx/styles/semantic/keyframes.json), injected
+   *  once per render root. Lets any definition animate via `style.animation` — no SDK edit. */
+  keyframes: Record<string, Record<string, Record<string, string>>>;
+  /** Named icon glyphs as SERVED DATA. The SERVER sources these from an icon pack
+   *  (control plane) → `{ viewBox, attrs, children }` where children are raw SVG
+   *  elements `[tag, attrs]`. The generic `Icon` leaf renders them, sized/coloured by
+   *  node.style. The SDK never bundles the pack — icons are served like any token. */
+  icons: Record<string, { viewBox?: string; attrs?: Record<string, unknown>; children?: [string, Record<string, unknown>][] }>;
+  /** Base render-root settings (theme.root ← rx/styles/semantic/root.json) — a CSS
+   *  object the SDK spreads onto its outermost wrapper (e.g. font-smoothing). Served,
+   *  not authored: a whole-tree rendering normalization, like legacy styles/base.css. */
+  root: Record<string, unknown>;
+}

package/vendor/sdk/lib/index.ts

@@ -0,0 +1,59 @@
+export { UnoverseComponent } from "./UnoverseComponent";
+export type { UnoverseComponentProps } from "./UnoverseComponent";
+export { StreamedUnoverseComponent, useUnoverseInstance } from "./streamed";
+export type { StreamedUnoverseComponentProps } from "./streamed";
+export { StreamedUnoverseTemplate, selectPointers, computeAppWidth, resolveActiveLayout } from "./template";
+export type { StreamedUnoverseTemplateProps } from "./template";
+export { renderNode, styleToCss, keyframesCss } from "./render";
+export type { ActionHandler, SlotResolver } from "./render";
+export { useUnoverseTheme } from "./theme";
+export { IsolatedRoot } from "./isolate";
+export { useUnoverseConnection } from "./connection";
+export type { UnoverseConnectionConfig, UnoverseSessionParams, UnoverseConnection } from "./connection";
+// The `voice` native service (UNOVERSE_SPEC §2e-1 Tier-3). Channel-instantiated; its
+// neutral state is spread into a `service: "voice"` template's scope, its actions
+// dispatched from the template. Audio rides the /ws/gravity WS lane (§5), not MCP.
+export { useVoiceService } from "./voice";
+export type { UseVoiceServiceConfig, VoiceService, VoiceServiceState, VoiceSession, VoiceConnectionStatus } from "./voice";
+// Re-export core's FULL public API. core is BUNDLED into this package (tsup noExternal), so
+// consumers import EVERYTHING from `@unoverse/sdk` and never depend on a
+// separate `-core` install — eliminating react↔core version/export drift entirely. EXPLICIT
+// named re-exports (NOT `export *`): tsup's .d.ts bundler inlines `export *` from a bundled
+// dep as LOCAL declarations WITHOUT re-exporting them, so consumers' type imports break
+// ("declares X locally, but it is not exported"). Named re-exports emit correctly.
+export {
+  ComponentStore,
+  UnoverseClient,
+  applyServerMessage,
+  dispatchAction,
+  resolveValue,
+  matches,
+  visible,
+  selectCase,
+} from "./core";
+export type {
+  ResolvedTheme,
+  UnoverseDefinition,
+  UnoverseNode,
+  ActionSpec,
+  ActionValue,
+  ActionContext,
+  Condition,
+  VisibleWhen,
+  StyleVariant,
+  LifecycleState,
+  Pointer,
+  Turn,
+  UserTurn,
+  AssistantTurn,
+  UnoverseEvent,
+  ComponentInitEvent,
+  ComponentDataEvent,
+  UnoverseClientOptions,
+  ServerMessage,
+  ServerComponentInit,
+  ServerComponentData,
+  ServerWorkflowState,
+  ServerTemplateData,
+  ServerSessionReady,
+} from "./core";

package/vendor/sdk/lib/isolate.tsx

@@ -0,0 +1,70 @@
+/**
+ * <IsolatedRoot> — mounts `children` inside an open Shadow DOM for complete CSS isolation.
+ *
+ * The SDK is the renderer for EVERY consumer (the canvas node preview, the live channel,
+ * the workbench, external host apps), so the isolation boundary lives HERE — once — rather
+ * than being bolted onto each host (today only the canvas wraps; the channel renders
+ * unprotected, so page styles and component styles leak both ways).
+ *
+ * Why a portal, not a nested React root: `createPortal` renders into the shadow root while
+ * keeping the SAME React tree/context, so the SDK's client/store/theme context still flows
+ * to the rendered components. A separate `createRoot` would sever that.
+ *
+ * Web-only — this file lives in `unoverse-react`, never in the framework-agnostic core
+ * (Flutter/Swift have no DOM). Token VALUES are already resolved inline by the renderer, so
+ * concrete styles work unchanged inside the shadow root; only inherited typography needs the
+ * reset below, after which the served `theme.root` is the sole typographic baseline.
+ */
+import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+// Shadow DOM blocks style SELECTORS but NOT inheritance: inherited properties (font, colour,
+// line-height, letter-spacing) still pierce the boundary, and <button>/<input> fall back to
+// the UA font. `:host { all: initial }` neutralizes the inherited cascade; `display: contents`
+// keeps the host out of layout (the consumer owns the outer box). The themed child the SDK
+// passes in (theme.root) then re-establishes the design-system typography.
+const RESET_CSS = `
+  :host { all: initial; display: contents; }
+  .uno-isolate-root { box-sizing: border-box; }
+  .uno-isolate-root *, .uno-isolate-root *::before, .uno-isolate-root *::after { box-sizing: border-box; }
+  .uno-isolate-root button, .uno-isolate-root input, .uno-isolate-root textarea, .uno-isolate-root select {
+    font: inherit; letter-spacing: inherit; color: inherit; margin: 0;
+  }
+  /* Scrollbars hidden by default across every scroll container — scrolling still works,
+     the bar is just not painted. Generic chrome that rx can't author per-node (pseudo-
+     elements), so it lives with the structural reset. */
+  .uno-isolate-root * { scrollbar-width: none; }
+  .uno-isolate-root *::-webkit-scrollbar { width: 0; height: 0; display: none; }
+`;
+
+export function IsolatedRoot({ children, rootStyle }: { children: ReactNode; rootStyle?: CSSProperties }) {
+  const hostRef = useRef<HTMLDivElement>(null);
+  const [shadow, setShadow] = useState<ShadowRoot | null>(null);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    // Reuse an existing shadow root across re-mounts (attachShadow throws if called twice).
+    setShadow(host.shadowRoot ?? host.attachShadow({ mode: "open" }));
+  }, []);
+
+  return (
+    <div ref={hostRef} style={{ display: "contents" }}>
+      {shadow &&
+        createPortal(
+          <>
+            <style>{RESET_CSS}</style>
+            {/* Apply the served DS render-root (theme.root: font family/size/weight/line-height/
+                colour + smoothing) DIRECTLY to this REAL container — not a `display:contents`
+                wrapper, whose inherited-font cascade is unreliable inside a shadow root. This is
+                the Unoverse equivalent of the legacy `.gravity-component` baseline, so every node
+                in the tree inherits the design-system typography. */}
+            <div className="uno-isolate-root" style={rootStyle}>
+              {children}
+            </div>
+          </>,
+          shadow as unknown as Element,
+        )}
+    </div>
+  );
+}