@unoverse-platform/studio 0.1.0

package/vendor/sdk/lib/primitives.tsx

@@ -0,0 +1,453 @@
+/**
+ * ════════════════════════════════════════════════════════════════════════════
+ *  EVERY PRIMITIVE LIVES HERE — render.tsx is the dispatcher and renders NONE.
+ * ════════════════════════════════════════════════════════════════════════════
+ *
+ *  This file is the CLOSED set of leaf primitives — the web realization of the
+ *  irreducible neutral elements: Box, Text, Image, Button, Icon, Skeleton, Input,
+ *  Markdown (+ the Unknown fallback). If you are writing a `<div>`, `<button>`,
+ *  `<span>`, `<img>`, `<input>`, `<svg>` … it goes HERE, never in render.tsx.
+ *  render.tsx ONLY dispatches `node.type` → one of these components. (A build
+ *  guard, test/dispatcher-only.test.mjs, fails if a raw element appears in
+ *  render.tsx — so this separation can't silently rot again.)
+ *
+ *  ⛔ A primitive renders ONE generic element and NOTHING about a specific UX.
+ *     No icons-in-the-input, no send buttons, no pills, no cards, no loaders.
+ *     Those are LAYOUTS — compose them in a DEFINITION from generic primitives.
+ *     Every style VALUE is served (theme.*); this file authors none. The bar to
+ *     ADD a primitive is high — it must be an irreducible element at the tier of
+ *     Text/Image (see FRAMEWORK.md), never a composite.
+ * ════════════════════════════════════════════════════════════════════════════
+ */
+import { createElement, useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import Markdown from "markdown-to-jsx";
+import type { ResolvedTheme, UnoverseNode } from "./core";
+import { styleToCss, cssDecls } from "./style";
+import type { ActionHandler } from "./render";
+
+/** Read a bound data field as a string (for Text/Image/Button content). */
+function bound(field: string | undefined, data: Record<string, unknown>): string | undefined {
+  return field ? (data[field] as string | undefined) : undefined;
+}
+
+/** Stable class name from a string (identical state specs share one injected rule). */
+function hashStr(s: string): string {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+// Interaction states are CSS pseudo-classes — inline styles can't express them, so we
+// resolve each state's tokens → a scoped rule and inject it (deduped by class hash).
+// Generic vocab (any element), values served; the SDK authors none. Add a state here.
+const INTERACTION_STATES: [string, string][] = [
+  ["hover", ":hover"],
+  ["active", ":active"],
+];
+
+// A state rule is a pure function of (spec object, theme) — and spec objects come from
+// cached defs, so they're referentially stable. Resolve + serialize + hash once, not
+// per element per render.
+const stateRuleCache = new WeakMap<ResolvedTheme, WeakMap<object, { cls: string; rule: string }>>();
+function stateRule(theme: ResolvedTheme, spec: Record<string, unknown>, key: string, pseudo: string): { cls: string; rule: string } {
+  let bySpec = stateRuleCache.get(theme);
+  if (!bySpec) {
+    bySpec = new WeakMap();
+    stateRuleCache.set(theme, bySpec);
+  }
+  let hit = bySpec.get(spec);
+  if (!hit) {
+    // !important — the base style is inline, which beats a class selector otherwise.
+    const decls = cssDecls(styleToCss(spec, theme), true);
+    const cls = `uno-${key}-${hashStr(decls)}`;
+    hit = { cls, rule: `.${cls}${pseudo}{${decls}}` };
+    bySpec.set(spec, hit);
+  }
+  return hit;
+}
+
+/**
+ * Resolve the generic per-element "chrome" shared by interactive primitives:
+ * the base inline style, hover/active rules (injected as <style>), and the
+ * data-driven `disabled` state (known at render via `disabledWhen` → merges the
+ * `disabled` style + sets the attr). All values are served; this authors none.
+ */
+function nodeChrome(node: UnoverseNode, data: Record<string, unknown>, theme: ResolvedTheme) {
+  const base = styleToCss(node.style, theme, data);
+  const disabled = node.disabledWhen ? !!data[node.disabledWhen] : false;
+  const style = disabled && node.style?.disabled ? { ...base, ...styleToCss(node.style.disabled as Record<string, unknown>, theme) } : base;
+  const classes: string[] = [];
+  const styleEls: ReactNode[] = [];
+  const s = node.style as Record<string, unknown> | undefined;
+  for (const [key, pseudo] of INTERACTION_STATES) {
+    const spec = s?.[key];
+    if (!spec) continue;
+    const { cls, rule } = stateRule(theme, spec as Record<string, unknown>, key, pseudo);
+    classes.push(cls);
+    styleEls.push(<style key={key}>{rule}</style>);
+  }
+  // `hideBelow` — responsive visibility via a CONTAINER query (inline styles can't express
+  // one): hides the element when its nearest container ancestor (an element with the
+  // `container` style) is narrower than a SERVED width token — e.g. drop a side image when
+  // the COMPONENT (not the viewport) is mobile-width. Correct for SDUI: a component reacts to
+  // its slot, not the page. Generic vocab, value served; the SDK authors none.
+  if (s?.hideBelow) {
+    const w = theme.space[s.hideBelow as string] ?? (s.hideBelow as string);
+    const cls = `uno-hidebelow-${hashStr(String(w))}`;
+    classes.push(cls);
+    styleEls.push(<style key="hideBelow">{`@container (max-width:${w}){.${cls}{display:none !important}}`}</style>);
+  }
+  // `hideAbove` — the mirror: hide when the container is WIDER than the width. Together
+  // these are the whole layout-switch mechanism for space-responsive components: the
+  // compact layout carries hideAbove, the full layout hideBelow, and the container's
+  // width (granted by the template's surface) picks the rendering — never a state key.
+  if (s?.hideAbove) {
+    const w = theme.space[s.hideAbove as string] ?? (s.hideAbove as string);
+    const cls = `uno-hideabove-${hashStr(String(w))}`;
+    classes.push(cls);
+    styleEls.push(<style key="hideAbove">{`@container (min-width:${w}){.${cls}{display:none !important}}`}</style>);
+  }
+  return { className: classes.join(" ") || undefined, styleEls, style, disabled };
+}
+
+/** `Box`/`Stack`/`Row`/`Column` — the generic container (`<div>`). Children are
+ *  pre-rendered by the dispatcher; layout/look come entirely from node.style. */
+export function BoxView({ node, data, theme, children }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; children?: ReactNode }): ReactNode {
+  const { className, styleEls, style } = nodeChrome(node, data, theme);
+  const scrollRef = useAutoScrollToEnd(node.autoScroll === true);
+  const revealRef = useRevealWhenStuck(node.revealOnStick === true);
+  return (
+    <div ref={scrollRef ?? revealRef} className={className} style={style}>
+      {styleEls}
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Generic "stick to the newest content" behavior for a scroll container (opt-in via
+ * `node.autoScroll`). Smooth-scrolls to the bottom whenever content grows — a new turn
+ * (childList change) OR streaming text (a child resizing) — but only while the user is
+ * already near the bottom, so scrolling up to read history is never yanked back down.
+ * NOT chat-specific: any `overflow:auto` Box can opt in. The SDK owns behaviour, never
+ * styles — the scroll container itself is defined in `rx/` (the conversation state box).
+ */
+function useAutoScrollToEnd(enabled: boolean) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (!enabled) return;
+    const el = ref.current;
+    if (!el) return;
+    const nearBottom = () => el.scrollHeight - el.scrollTop - el.clientHeight < 140;
+    const stick = () => {
+      if (nearBottom()) el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+    };
+    el.scrollTop = el.scrollHeight; // land at the end on mount (no animation)
+    const ro = new ResizeObserver(stick); // catches streaming text growing a turn's height
+    const observeKids = () => {
+      for (const kid of Array.from(el.children)) ro.observe(kid);
+    };
+    observeKids();
+    const mo = new MutationObserver(() => {
+      observeKids(); // new turns → observe them too
+      stick();
+    });
+    mo.observe(el, { childList: true, subtree: true });
+    return () => {
+      ro.disconnect();
+      mo.disconnect();
+    };
+  }, [enabled]);
+  return enabled ? ref : undefined;
+}
+
+/**
+ * Generic "sticky bar that reveals only once you've scrolled past the element before it"
+ * (opt-in via `node.revealOnStick`). Pins the bar at the top (its own `position: sticky`
+ * + `top` in `rx/`) and, using an IntersectionObserver on the bar's PREVIOUS sibling as
+ * the sentinel (e.g. a hero image), keeps it hidden while that sibling is on screen and
+ * fades it in once the sibling scrolls away. A negative margin removes the bar's flow
+ * footprint so it OVERLAYS the content (no gap at the top). NOT card-specific: any sticky
+ * bar can opt in. The SDK owns behaviour, never styles — the bar's look lives in `rx/`.
+ */
+function useRevealWhenStuck(enabled: boolean) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (!enabled) return;
+    const el = ref.current;
+    if (!el) return;
+    const sentinel = el.previousElementSibling; // reveal the bar once THIS scrolls away
+    // Overlay, not push: cancel the bar's own height so content sits under it, bar pins on top.
+    el.style.marginBottom = `-${el.offsetHeight}px`;
+    el.style.transition = "opacity 200ms ease, transform 200ms ease";
+    const hide = () => {
+      el.style.opacity = "0";
+      el.style.transform = "translateY(-8px)";
+      el.style.pointerEvents = "none";
+    };
+    const show = () => {
+      el.style.opacity = "1";
+      el.style.transform = "translateY(0)";
+      el.style.pointerEvents = "auto";
+    };
+    hide();
+    if (!sentinel) return void show(); // no sentinel to hide behind → just show
+    const io = new IntersectionObserver(([e]) => (e.isIntersecting ? hide() : show()), { threshold: 0 });
+    io.observe(sentinel);
+    return () => io.disconnect();
+  }, [enabled]);
+  return enabled ? ref : undefined;
+}
+
+/** `Text` — a bound string (`<span>`). */
+export function TextView({ node, data, theme }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme }): ReactNode {
+  // Literal `value` fallback: components are microapps — static copy is HARDCODED in the
+  // def, props exist only for state (UNOVERSE_AUTHORING.md). bind wins when present.
+  return <span style={styleToCss(node.style, theme, data)}>{bound(node.bind?.value, data) ?? (node.value as ReactNode)}</span>;
+}
+
+/** `Image` — a bound OR literal src (`<img>`). */
+export function ImageView({ node, data, theme }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme }): ReactNode {
+  return <img style={styleToCss(node.style, theme, data)} src={bound(node.bind?.src, data) ?? node.src} alt={bound(node.bind?.alt, data) ?? node.alt ?? ""} />;
+}
+
+/** `Button` — fires `onAction(node.action, data)`. Content is a bound label OR composed
+ *  children (so an Icon can sit in a button). The SDK authors no button styling. */
+export function ButtonView({ node, data, theme, onAction, children }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; onAction?: ActionHandler; children?: ReactNode }): ReactNode {
+  const { className, styleEls, style, disabled } = nodeChrome(node, data, theme);
+  return (
+    <button className={className} style={style} disabled={disabled} onClick={() => onAction?.(node.action ?? "click", data)}>
+      {styleEls}
+      {node.children?.length ? children : bound(node.bind?.label, data)}
+    </button>
+  );
+}
+
+/** Unknown node type — render children so the tree doesn't break (degenerate fallback). */
+export function UnknownView({ node, theme, children }: { node: UnoverseNode; theme: ResolvedTheme; children?: ReactNode }): ReactNode {
+  return (
+    <div style={styleToCss(node.style, theme)} data-unoverse-unknown={node.type}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * `Icon` — leaf primitive (the irreducible SVG, like Text→<span>/Image→<img>).
+ * Renders a named glyph whose element DATA is SERVED (theme.icons): the server sources
+ * it from an icon pack (control plane) and serves `{ viewBox, attrs, children }`, where
+ * children are raw SVG elements `[tag, attrs]`. The SDK NEVER bundles a pack — it's
+ * pack-agnostic, just rendering served elements. Size = node.style width/height, colour
+ * = node.style color (→ `currentColor`). Name is literal (`node.icon`) or bound
+ * (`bind.name`). NOT a composite — one glyph, no buttons/chrome.
+ */
+export function IconView({ name, style, theme }: { name?: string; style?: Record<string, unknown>; theme: ResolvedTheme }): ReactNode {
+  const set = (theme.icons ?? {}) as Record<string, { viewBox?: string; attrs?: Record<string, unknown>; children?: [string, Record<string, unknown>][] }>;
+  const ic = name ? set[name] : undefined;
+  if (!ic) return null;
+  const children = Array.isArray(ic.children) ? ic.children : [];
+  return (
+    <svg viewBox={ic.viewBox ?? "0 0 24 24"} {...(ic.attrs ?? {})} aria-hidden="true" style={styleToCss(style ?? {}, theme)}>
+      {children.map(([tag, attrs], i) => createElement(tag, { key: i, ...attrs }))}
+    </svg>
+  );
+}
+
+/**
+ * `Skeleton` — built-in loading placeholder. ALL dimensions are DATA, fetched
+ * from the theme (theme.skeleton ← rx/styles/semantic/skeleton.json). The SDK
+ * authors nothing here but structure (flex/full). `bars` are 'width height' pairs.
+ */
+export function SkeletonView({ variant = "text", theme }: { variant?: string; theme: ResolvedTheme }): ReactNode {
+  // DEFENSIVE BY LAW: a loading GHOST must never crash the app. Every token read
+  // tolerates absence (missing token = that dimension simply unset — we still author
+  // no values); a theme without a skeleton recipe renders inert placeholders, never
+  // a TypeError that unmounts the whole tree (observed live: blank panel).
+  const sk = (theme.skeleton ?? {}) as Record<string, any>;
+  // SELF-CONTAINED shimmer: the loading ghost is generic chrome, so its motion lives
+  // WITH the primitive — no cross-file dependency on an org's keyframes recipe that
+  // silently breaks when absent. The sweep is a neutral white-alpha overlay (brand
+  // colors still come from the served `fill`); a served `skeleton.shimmer` object
+  // overrides it, and `skeleton.shimmer: false` disables motion entirely.
+  const SHIMMER_BUILTIN: CSSProperties = {
+    backgroundImage: "linear-gradient(90deg, rgba(255,255,255,0) 0%, rgba(255,255,255,0.55) 50%, rgba(255,255,255,0) 100%)",
+    backgroundSize: "200% 100%",
+    animation: "uno-skeleton-shimmer 1.4s ease-in-out infinite",
+  };
+  const shimmer: CSSProperties = sk.shimmer === false ? {} : typeof sk.shimmer === "object" ? (sk.shimmer as CSSProperties) : SHIMMER_BUILTIN;
+  const shimmerKeyframes =
+    sk.shimmer === false ? null : (
+      <style>{"@keyframes uno-skeleton-shimmer{0%{background-position:200% 0}100%{background-position:-200% 0}}"}</style>
+    );
+  const bar = (spec: string, i: number): ReactNode => {
+    const [w, h] = String(spec).split(" ");
+    return <div key={i} style={{ width: w, height: h, background: sk.fill, borderRadius: sk.barRadius, ...shimmer }} />;
+  };
+  if (variant === "image")
+    return (
+      <>
+        {shimmerKeyframes}
+        <div style={{ width: "100%", height: "100%", minHeight: sk.image?.minHeight, background: sk.fill, borderRadius: sk.radius, ...shimmer }} />
+      </>
+    );
+  if (variant === "card")
+    return (
+      <>
+        {shimmerKeyframes}
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: sk.gap,
+          padding: sk.card?.padding,
+          border: theme.borderWidth?.thin && sk.fill ? `${theme.borderWidth.thin} solid ${sk.fill}` : undefined,
+          borderRadius: sk.radius,
+        }}
+      >
+        {(Array.isArray(sk.card?.bars) ? (sk.card.bars as string[]) : []).map(bar)}
+      </div>
+      </>
+    );
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: sk.gap }}>
+      {shimmerKeyframes}
+      {(Array.isArray(sk.text?.bars) ? (sk.text.bars as string[]) : []).map(bar)}
+    </div>
+  );
+}
+
+/**
+ * `Input` — single-line composer (the irreducible `<input>`, like Text→<span>).
+ * Holds its own draft text (local, not store state); on Enter it fires
+ * `onAction(node.action, { text })` and clears. The SDK authors NO styling here —
+ * look comes entirely from `node.style` (data), exactly like Button. `placeholder`
+ * is copy (content), not a style value.
+ *
+ * ⛔ DO NOT add icons, send buttons, pills, or any composer chrome here. That is
+ *    UX — compose it in a DEFINITION from generic primitives (Box + Icon + Input).
+ *    A primitive renders ONE generic element; it never encodes a specific layout.
+ */
+export function InputView({ node, data, theme, onAction }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; onAction?: ActionHandler }): ReactNode {
+  // CONTROLLED when `bind.value` is set: value comes from shared data and changes are
+  // emitted as an "input" action (the channel writes it to the store). This is what lets
+  // a sibling send button submit the draft. Otherwise the field keeps its own local text.
+  const field = node.bind?.value;
+  const [local, setLocal] = useState("");
+  const value = field != null ? String(data[field] ?? "") : local;
+  // CONTROLLED: report the change as an "input" event carrying WHICH field changed.
+  // The component dispatcher writes that field into this instance's slice (local two-way
+  // binding, §2e-3); the template composer's channel reads `text` and ignores `field`
+  // (its bound field is the shared `draft`). The SDK authors no UX — just the fact.
+  const setValue = (t: string) => (field != null ? onAction?.("input", { text: t, field }) : setLocal(t));
+  const submit = () => {
+    const t = value.trim();
+    if (!t) return;
+    onAction?.(node.action ?? "submit", { text: t });
+    if (field == null) setLocal("");
+  };
+  const { style, disabled } = nodeChrome(node, data, theme);
+  return (
+    <input
+      style={style}
+      disabled={disabled}
+      value={value}
+      placeholder={node.placeholder}
+      onChange={(e) => setValue(e.target.value)}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" && !e.shiftKey) {
+          e.preventDefault();
+          submit();
+        }
+      }}
+    />
+  );
+}
+
+/**
+ * markdown-to-jsx overrides for the `Markdown` primitive.
+ *
+ * ⛔ AUTHORS ZERO STYLE VALUES. Every element style is read verbatim from the
+ *    SERVED prose recipe (`theme.prose` ← rx/styles/semantic/prose.json). The SDK
+ *    only maps element → recipe key and supplies BEHAVIOUR (target=_blank, image
+ *    error-fallback). No hex, no px/rem, no weights here — they live in rx/.
+ *
+ * Built once per theme (stable component identities so streaming re-renders don't
+ * remount images and drop their broken-state).
+ */
+function buildMarkdownOverrides(theme: ResolvedTheme, inheritLinkColor = false) {
+  const p = theme.prose as Record<string, CSSProperties | Record<string, string> | string>;
+  const s = (k: string) => (p[k] as CSSProperties | undefined) ?? {};
+  // Heading element → served text-style NAME (the map lives in the recipe, not here).
+  const headings = (p.heading as Record<string, string>) ?? {};
+  const head = (tag: string) => (theme.text[headings[tag]] as CSSProperties | undefined) ?? {};
+
+  // Served external-link glyph (theme.icons.externalLink), styled by served prose.linkIcon.
+  // The icon inherits the link's colour via `currentColor`. The SDK authors no geometry.
+  const li = (theme.icons?.externalLink ?? {}) as { viewBox?: string; attrs?: Record<string, unknown>; children?: [string, Record<string, unknown>][] };
+  const linkArrow = li.children?.length ? (
+    <svg viewBox={li.viewBox ?? "0 0 24 24"} {...(li.attrs ?? {})} aria-hidden="true" style={s("linkIcon")}>
+      {li.children.map(([tag, attrs], i) => createElement(tag, { key: i, ...attrs }))}
+    </svg>
+  ) : null;
+  // A definition that declares `color` on its Markdown node owns its anchors'
+  // color too (`inherit` — no value authored here); the served recipe stays the
+  // default for undeclared nodes (chat prose).
+  const ExternalLink = ({ children, ...a }: React.AnchorHTMLAttributes<HTMLAnchorElement>) => (
+    <a {...a} target="_blank" rel="noopener noreferrer" style={inheritLinkColor ? { ...s("link"), color: "inherit" } : s("link")}>
+      {children}
+      {linkArrow}
+    </a>
+  );
+  // Wide tables scroll instead of crushing columns (legacy ScrollableTable).
+  const ScrollableTable = (a: React.TableHTMLAttributes<HTMLTableElement>) => (
+    <div style={s("tableWrap")}>
+      <table {...a} style={s("table")} />
+    </div>
+  );
+  // Broken external image URLs degrade to alt text, not a broken-image icon.
+  const MarkdownImage = ({ src, alt, title }: React.ImgHTMLAttributes<HTMLImageElement>) => {
+    const [broken, setBroken] = useState(false);
+    if (!src || broken) return <span style={s("imageFallback")}>{alt || "Image unavailable"}</span>;
+    return (
+      <img src={src as string} alt={alt || ""} title={title} loading="lazy" decoding="async" onError={() => setBroken(true)} style={s("image")} />
+    );
+  };
+
+  return {
+    p: { props: { style: s("paragraph") } },
+    a: { component: ExternalLink },
+    table: { component: ScrollableTable },
+    img: { component: MarkdownImage },
+    th: { props: { style: { ...s("cell"), ...s("headerCell") } } },
+    td: { props: { style: s("cell") } },
+    ul: { props: { style: { ...s("list"), listStyleType: p.bulletStyle as string } } },
+    ol: { props: { style: { ...s("list"), listStyleType: p.orderedStyle as string } } },
+    li: { props: { style: s("listItem") } },
+    h1: { props: { style: head("h1") } },
+    h2: { props: { style: head("h2") } },
+    h3: { props: { style: head("h3") } },
+    h4: { props: { style: head("h4") } },
+    h5: { props: { style: head("h5") } },
+    h6: { props: { style: head("h6") } },
+  };
+}
+
+/**
+ * `Markdown` leaf primitive (SPEC §2d:197). Renders a bound markdown string; the
+ * web impl is markdown-to-jsx (a per-platform primitive impl, like Text→<span>).
+ * Container takes node.style (tokens); elements map to served theme tokens via
+ * buildMarkdownOverrides. The SDK authors ZERO style values.
+ */
+export function MarkdownView({ node, data, theme }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme }): ReactNode {
+  const value = (node.bind?.value ? (data[node.bind.value] as string) : "") ?? "";
+  // Explicit opt-in ONLY (a CTA pill whose label must match its declared color):
+  // `inheritLinkColor: true` on the node. Declaring a body color alone never
+  // hijacks anchors — chat prose keeps the served link recipe.
+  const inheritLink = (node as { inheritLinkColor?: boolean }).inheritLinkColor === true;
+  const overrides = useMemo(() => buildMarkdownOverrides(theme, inheritLink), [theme, inheritLink]);
+  return (
+    <div style={styleToCss(node.style, theme, data)}>
+      <Markdown options={{ overrides, forceBlock: true }}>{value}</Markdown>
+    </div>
+  );
+}

package/vendor/sdk/lib/realtime/audioUtils.ts

@@ -0,0 +1,40 @@
+/**
+ * Audio utility functions for PCM conversion and processing.
+ * Ported verbatim from gravity-client/src/realtime/audioUtils.ts (the proven,
+ * live implementation). Only the two helpers the continuous-capture path uses.
+ */
+
+/**
+ * Convert Float32Array audio (range -1..1, from the Web Audio API) to Int16Array
+ * PCM (16-bit signed).
+ */
+export function float32ToInt16(float32Audio: Float32Array): Int16Array {
+  const int16Data = new Int16Array(float32Audio.length);
+  for (let i = 0; i < float32Audio.length; i++) {
+    const s = Math.max(-1, Math.min(1, float32Audio[i]));
+    int16Data[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+  }
+  return int16Data;
+}
+
+/**
+ * Downsample a Float32 PCM frame from `fromRate` to `toRate` using linear
+ * interpolation. Returns the source frame unchanged if rates already match.
+ *
+ * Mic capture picks the native device rate (typically 44100 / 48000 Hz) and the
+ * realtime LLM expects 16000 Hz.
+ */
+export function downsampleFloat32(input: Float32Array, fromRate: number, toRate: number): Float32Array {
+  if (fromRate === toRate || input.length === 0) return input;
+  const ratio = fromRate / toRate;
+  const outLen = Math.floor(input.length / ratio);
+  const out = new Float32Array(outLen);
+  for (let i = 0; i < outLen; i++) {
+    const srcIdx = i * ratio;
+    const i0 = Math.floor(srcIdx);
+    const i1 = Math.min(i0 + 1, input.length - 1);
+    const frac = srcIdx - i0;
+    out[i] = input[i0] * (1 - frac) + input[i1] * frac;
+  }
+  return out;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Shared types for realtime audio streaming.
+ *
+ * Ported verbatim from gravity-client/src/realtime/types.ts (the proven, live
+ * implementation) — the Unoverse `voice` native service reuses the same audio
+ * lane (`/ws/gravity`) and the same control-channel AUDIO_STATE vocabulary, so
+ * the contract is identical. See docs/VOICE_STREAMING_GUIDE.md.
+ */
+
+export type ConnectionStatus = "idle" | "connecting" | "connected" | "error" | "ended";
+
+/**
+ * Control-channel audio state events emitted by the server, in lockstep with the
+ * audio frames on the SAME WS lane (they are the control half of the live-audio
+ * conversation — NOT component/UI data; they never ride the MCP stream).
+ */
+export type AudioState =
+  | "SESSION_READY"
+  | "SESSION_ENDED"
+  | "SPEECH_STARTED"
+  | "SPEECH_ENDED"
+  | "USER_SPEECH_STARTED"
+  | "USER_SPEECH_ENDED"
+  | "TOOL_USE"
+  | "TOOL_USE_COMPLETED";
+
+export interface AudioStateMessage {
+  type: "audioState";
+  state: AudioState;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ControlMessage {
+  type: string;
+  state?: AudioState;
+  audioState?: AudioState;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface AudioStateEvent {
+  state: AudioState;
+  metadata?: Record<string, unknown>;
+  message?: string;
+}