@unoverse-platform/studio 0.1.26 → 0.1.28

package/vendor/sdk/lib/orb/theme.ts

@@ -0,0 +1,83 @@
+// Theme resolution: explicit prop → ancestor data-theme/.dark|.light
+// class (watched live) → prefers-color-scheme (subscribed live).
+// SSR-safe: everything runs in effects; the pre-mount fallback is dark.
+
+import type { RefObject } from 'react';
+import { useEffect, useState } from 'react';
+import type { OrbTheme } from './types';
+
+function ancestorTheme(el: Element | null): boolean | null {
+  let node: Element | null = el;
+  while (node) {
+    const attr = node.getAttribute('data-theme');
+    if (attr === 'dark') return true;
+    if (attr === 'light') return false;
+    if (node.classList.contains('dark')) return true;
+    if (node.classList.contains('light')) return false;
+    node = node.parentElement;
+  }
+  return null;
+}
+
+function systemDark(): boolean {
+  return typeof matchMedia === 'undefined' || matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+/** Resolve the effective dark/light substrate for a mounted element. */
+export function useResolvedDark(theme: OrbTheme, hostRef: RefObject<Element | null>): boolean {
+  const [dark, setDark] = useState(true);
+
+  useEffect(() => {
+    if (theme === 'dark') {
+      setDark(true);
+      return;
+    }
+    if (theme === 'light') {
+      setDark(false);
+      return;
+    }
+
+    const resolve = () => {
+      const fromTree = ancestorTheme(hostRef.current);
+      setDark(fromTree ?? systemDark());
+    };
+    resolve();
+
+    // live OS/browser theme switches
+    const mq = typeof matchMedia !== 'undefined' ? matchMedia('(prefers-color-scheme: dark)') : null;
+    const onMq = () => resolve();
+    mq?.addEventListener('change', onMq);
+
+    // live app-level toggles: watch class/data-theme flips on ancestors
+    let mo: MutationObserver | null = null;
+    if (typeof MutationObserver !== 'undefined' && hostRef.current) {
+      mo = new MutationObserver(resolve);
+      mo.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['class', 'data-theme'],
+        subtree: true
+      });
+    }
+
+    return () => {
+      mq?.removeEventListener('change', onMq);
+      mo?.disconnect();
+    };
+  }, [theme, hostRef]);
+
+  return dark;
+}
+
+/** Live `prefers-reduced-motion` — reduced users get a static frame. */
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    if (typeof matchMedia === 'undefined') return;
+    const mq = matchMedia('(prefers-reduced-motion: reduce)');
+    setReduced(mq.matches);
+    const on = (e: MediaQueryListEvent) => setReduced(e.matches);
+    mq.addEventListener('change', on);
+    return () => mq.removeEventListener('change', on);
+  }, []);
+  return reduced;
+}

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

@@ -0,0 +1,84 @@
+import type { CSSProperties, CanvasHTMLAttributes } from 'react';
+
+/**
+ * The nine shipped states — each a hand-tuned animation:
+ * - `working`    — particles on tilted orbits
+ * - `searching`  — a scan meridian sweeps a dotted globe
+ * - `solving`    — bands scramble in quarter turns, then click back
+ * - `listening`  — a waveform rolls through latitude rings
+ * - `connecting` — a constellation wires itself, packets running the edges
+ * - `weaving`    — three strands plait around the sphere
+ * - `composing`  — an undulating multi-band sash
+ * - `breathing`  — a face-on ring slowly morphing
+ * - `shaping`    — a dotted outline morphs circle → triangle → square
+ *
+ * Plus the LOCAL (Unoverse) ANNULAR set — drawn only in a ring with the centre left
+ * empty, for framing an avatar's face rather than colliding with it (engine/rings.ts):
+ * - `halo`       — a soft aura breathing, its form drifting off-circle
+ * - `sonar`      — soft rings of light arriving inward, the shape of sound reaching you
+ * - `shimmer`    — luminance sweeping through a still ring, a thought being turned over
+ * - `pulse`      — rings of light leaving outward, the shape of a voice carrying
+ */
+export type OrbState =
+  | 'working'
+  | 'searching'
+  | 'solving'
+  | 'listening'
+  | 'connecting'
+  | 'weaving'
+  | 'composing'
+  | 'breathing'
+  | 'shaping'
+  | 'halo'
+  | 'sonar'
+  | 'shimmer'
+  | 'pulse';
+
+/**
+ * Rendered size in CSS pixels. Exactly two tuned presets ship:
+ * 64 (chat-avatar scale) and 20 (inline-text scale). Each size carries
+ * its own dot count, dot size and speed tuning — they are separate
+ * designs, not a scale factor.
+ */
+export type OrbSize = 64 | 20;
+
+/**
+ * Theme mode.
+ *
+ * - `auto` (default) resolves in three layers, live-updating on change:
+ *   1. a `data-theme="dark|light"` attribute or `dark`/`light` class on
+ *      any ancestor (the Tailwind / shadcn convention), watched via
+ *      `MutationObserver`;
+ *   2. otherwise `matchMedia('(prefers-color-scheme: dark)')`,
+ *      subscribed for live OS/browser theme switches;
+ *   3. during SSR (no DOM) the first client render resolves the theme
+ *      before anything is painted — the canvas is client-only.
+ * - `dark` / `light` pin the palette regardless of context.
+ *
+ * Dark renders light ink on the transparent canvas (for dark
+ * backgrounds); light renders dark ink (for light backgrounds).
+ */
+export type OrbTheme = 'auto' | 'dark' | 'light';
+
+/** Props for the ThinkingOrb React component. */
+export interface ThinkingOrbProps extends Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'style'> {
+  /** Which animation to show. @default 'working' */
+  state?: OrbState;
+
+  /** Tuned size preset — 64 or 20 CSS px. @default 64 */
+  size?: OrbSize;
+
+  /** Theme mode; `auto` detects from the host project. @default 'auto' */
+  theme?: OrbTheme;
+
+  /**
+   * Animation speed multiplier on top of the preset's baked speed.
+   * @default 1
+   */
+  speed?: number;
+
+  /** Freeze the animation on the current frame. @default false */
+  paused?: boolean;
+
+  style?: CSSProperties;
+}

package/vendor/sdk/lib/primitives.tsx

@@ -24,6 +24,7 @@ import Markdown from "markdown-to-jsx";
 import type { ResolvedTheme, UnoverseNode } from "./core";
 import { styleToCss, cssDecls } from "./style";
 import { nodeAction, type ActionHandler } from "./render";
+import { ThinkingOrb, type OrbState, type OrbSize, type OrbTheme } from "./orb";
 
 /** Read a bound data field as a string (for Text/Image/Button content). */
 function bound(field: string | undefined, data: Record<string, unknown>): string | undefined {
@@ -339,6 +340,49 @@ export function ButtonView({ node, data, theme, onAction, children }: { node: Un
   );
 }
 
+/**
+ * `Orb` — a procedural "the assistant is doing something" animation, drawn
+ * per-frame on a 2D canvas (see ./orb — vendored thinking-orbs, MIT). This is
+ * the ONE class of motion keyframe data cannot express (per-frame math, depth
+ * occlusion), so like Skeleton's shimmer the drawing lives WITH the primitive;
+ * every authoring decision stays data: `state` (which of the nine animations —
+ * bindable), `size` (64 avatar / 20 inline), `speed`, `theme` override.
+ * Unknown/unbound state degrades to "working", never a crash.
+ */
+const ORB_STATES = new Set(["working", "searching", "solving", "listening", "connecting", "weaving", "composing", "breathing", "shaping", "halo", "sonar", "shimmer", "pulse"]);
+export function OrbView({ node, data, theme }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme }): ReactNode {
+  const n = node as UnoverseNode & { state?: string; size?: number | string; speed?: number | string; theme?: string };
+  // Every knob is data-driven OR literal, like Icon: `bind.<knob>` wins, the attribute is the fallback.
+  const knob = (name: "state" | "size" | "speed") =>
+    (node.bind?.[name] ? (data[node.bind[name] as string] as string | number | undefined) : undefined) ?? n[name];
+  const raw = knob("state") as string | undefined;
+  // UNKNOWN NAME → the calm ANNULAR fallback, never the sphere. A bad/stale name is an
+  // authoring or version mismatch, and the orb most often sits behind a face: degrading
+  // to `working` threw 3-D particles across the portrait (the loudest mode in the set) to
+  // signal a problem the viewer cannot act on. `halo` is quiet, ring-shaped, and wrong in
+  // no context — a mismatch should look calm, not broken.
+  const state = raw && ORB_STATES.has(raw) ? (raw as OrbState) : "halo";
+  const size = Number(knob("size")) > 0 ? Number(knob("size")) : 64;
+  const speed = Number(knob("speed")) > 0 ? Number(knob("speed")) : 1;
+  const orbTheme: OrbTheme = n.theme === "dark" || n.theme === "light" ? n.theme : "auto";
+  // Brand ink comes from the STYLE vocabulary (`color: <token>`), never a prop — LAW 1:
+  // a definition names a token, the theme serves the value, the engine tints toward it.
+  const css = styleToCss(node.style ?? {}, theme, data);
+  return <ThinkingOrb state={state} size={size as OrbSize} speed={speed} theme={orbTheme} ink={cssColorToRgb(css.color as string | undefined)} style={css} />;
+}
+
+/** #rgb / #rrggbb / rgb()/rgba() → an rgb tuple; anything else (gradients, names) → null (neutral ink). */
+function cssColorToRgb(c?: string): [number, number, number] | null {
+  if (!c) return null;
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(c.trim());
+  if (hex) {
+    const h = hex[1].length === 3 ? [...hex[1]].map((x) => x + x).join("") : hex[1];
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number];
+  }
+  const fn = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(c.trim());
+  return fn ? [Number(fn[1]), Number(fn[2]), Number(fn[3])] : null;
+}
+
 /** 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 (
@@ -432,6 +476,58 @@ export function SkeletonView({ variant = "text", theme }: { variant?: string; th
   );
 }
 
+/**
+ * `Select` — the irreducible `<select>`, like Text→<span> and Input→<input>.
+ *
+ * THE ONE CONTROL THAT CANNOT BE COMPOSED. Every other form field in this platform is
+ * built from Box, Text, Button and Input, as data. A closed set of two hundred countries
+ * is where that stops: laying them out is unusable, filtering them is logic a definition
+ * may not carry, and a hand-rolled menu forfeits the OS picker, type-to-search, keyboard
+ * navigation and screen-reader semantics that the real element gives for nothing.
+ *
+ * It reports a change exactly as a controlled Input does — `onAction("input", { field,
+ * text })` — so the bound field name IS the key the answer lands in, and a select needs no
+ * mechanism the platform does not already have.
+ *
+ * ⛔ NO CHROME HERE. No custom arrow, no popup, no styling: `node.style` is the whole look,
+ * and the options are DATA (`bind.options`, entries of `{ value, label }` or plain
+ * strings). A searchable picker is a different control and does not belong in this one.
+ */
+export function SelectView({ node, data, theme, onAction }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; onAction?: ActionHandler }): ReactNode {
+  const field = node.bind?.value;
+  const value = field != null ? String(data[field] ?? "") : "";
+  const raw = node.bind?.options ? data[node.bind.options] : (node as { options?: unknown }).options;
+  const options = (Array.isArray(raw) ? raw : []).map((o) =>
+    o != null && typeof o === "object"
+      ? { value: String((o as Record<string, unknown>).value ?? (o as Record<string, unknown>).label ?? ""), label: String((o as Record<string, unknown>).label ?? (o as Record<string, unknown>).value ?? "") }
+      : { value: String(o), label: String(o) },
+  );
+  const { style, disabled } = nodeChrome(node, data, theme);
+  return (
+    <select
+      style={style}
+      disabled={disabled}
+      value={value}
+      data-unoverse-id={inspectId(node)}
+      onChange={(e) => field != null && onAction?.("input", { text: e.target.value, field })}
+    >
+      {/* The placeholder is CONTENT, exactly as it is on an Input: an unanswered select
+          must say what it wants rather than pre-selecting the first option and claiming an
+          answer nobody gave. */}
+      {node.placeholder != null && (
+        <option value="" disabled>
+          {node.placeholder}
+        </option>
+      )}
+      {options.map((o) => (
+        <option key={o.value} value={o.value}>
+          {o.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+
 /**
  * `Input` — single-line composer (the irreducible `<input>`, like Text→<span>).
  * Holds its own draft text (local, not store state); on Enter it fires
@@ -463,6 +559,11 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
   // a postal code, "off") and the guess never happens. Generic pass-through: the SDK holds
   // no list of values and no idea what a one-time code is.
   const autoComplete = (node as { autoComplete?: string }).autoComplete;
+  // `type` — WHAT THE FIELD IS, passed to the platform: `date` gets the OS date picker,
+  // `tel` the phone keypad, `file` the file chooser. The same class of generic constraint
+  // as `maxLength` and `inputMode`, and the reason a definition never has to hand-roll a
+  // calendar out of Boxes. The SDK holds no list of types and no opinion about them.
+  const inputType = (node as { inputType?: string }).inputType;
   // `maxLength` is enforced by the element itself, but `inputMode` is only a HINT —
   // a desktop keyboard types straight past it — so the digit rule is applied here.
   const accept = (t: string) => {
@@ -538,13 +639,26 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
       ref={el}
       style={style}
       disabled={disabled}
-      value={value}
+      // A file input is never controlled: assigning its value is a security error in every
+      // browser, so the chosen name lives in the data and the element stays uncontrolled.
+      value={inputType === "file" ? undefined : value}
       placeholder={node.placeholder}
+      type={inputType}
       maxLength={maxLength}
       inputMode={numeric ? "numeric" : undefined}
       autoComplete={autoComplete}
       data-uno-advance={advanceOnFill ? "" : undefined}
-      onChange={(e) => setValue(e.target.value)}
+      onChange={(e) => {
+        // A FILE FIELD REPORTS ITS FILES, not its value: the DOM's value for one is a fake
+        // path, and the bytes are the host's business (an upload target, a stored
+        // reference) rather than the renderer's. The SDK states what was chosen and stops.
+        if (inputType === "file") {
+          const picked = Array.from(e.target.files ?? []).map((f) => ({ name: f.name, size: f.size, type: f.type }));
+          if (field != null) onAction?.("input", { text: picked.map((f) => f.name).join(", "), field, files: picked });
+          return;
+        }
+        setValue(e.target.value);
+      }}
       onKeyDown={(e) => {
         // Backspace in an ALREADY-empty field steps back, so correcting a sequence never
         // needs the mouse. A field with content just deletes it (the default).

package/vendor/sdk/lib/render.tsx

@@ -35,8 +35,9 @@
  */
 import type { ReactNode } from "react";
 import type { ActionSpec, ResolvedTheme, UnoverseNode } from "./core";
-import { visible, selectCase } from "./core";
-import { BoxView, TextView, ImageView, ButtonView, UnknownView, SkeletonView, InputView, MarkdownView, IconView } from "./primitives";
+import { visible, selectCase, cssWidth } from "./core";
+import { resolveRef } from "./core/refs";
+import { BoxView, TextView, ImageView, ButtonView, UnknownView, SkeletonView, InputView, SelectView, MarkdownView, IconView, OrbView } from "./primitives";
 
 // The style + animation interpreter lives in ./style; re-exported so consumers keep
 // importing it from "./render".
@@ -80,9 +81,9 @@ export function nodeAction(node: UnoverseNode, fallback: string): string | Actio
  */
 export type SlotResolver = (node: UnoverseNode, key?: React.Key) => ReactNode;
 
-/** A usable appWidth is CSS ("360px", "min(50vw, 760px)") — an UNRESOLVED size name
- *  has no digits; treat it as absent rather than emitting invalid CSS. */
-export const cssWidth = (w: unknown): string | undefined => (typeof w === "string" && /\d/.test(w) ? w : undefined);
+// cssWidth moved to core/templates.ts (computeAppWidth needs it and core imports
+// nothing from the React layer); re-exported to keep this import path working.
+export { cssWidth };
 
 export function renderNode(
   node: UnoverseNode,
@@ -91,6 +92,12 @@ export function renderNode(
   theme: ResolvedTheme,
   key?: React.Key,
   slot?: SlotResolver,
+  /**
+   * The shared pieces this definition REFERENCES, by name. Present only when the server
+   * sends references instead of inlining copies of them; absent for every definition
+   * served the old way, in which case no `Ref` reaches this function at all.
+   */
+  defs?: Record<string, UnoverseNode>,
 ): ReactNode {
   // visibleWhen — conditional visibility (§2e-3). A bare field name is a truthiness test
   // (an empty array counts as empty); an object is a `Condition` (eq/ne/in, or truthy) so
@@ -135,17 +142,32 @@ export function renderNode(
   // through `with` — so without this an atom can be data-driven or literal, never both.
   if (node.type === "Icon")
     return <IconView key={key} name={node.bind?.name ? (data[node.bind.name] as string) : (node.icon ?? node.name)} style={node.style} theme={theme} />;
+  // Orb: procedural thinking/working animation — state is a literal or bound (`bind.state`).
+  if (node.type === "Orb") return <OrbView key={key} node={node} data={data} theme={theme} />;
   if (node.type === "Input") return <InputView key={key} node={node} data={data} theme={theme} onAction={onAction} />;
   if (node.type === "Markdown") return <MarkdownView key={key} node={node} data={data} theme={theme} />;
   if (node.type === "ComponentSlot" || node.type === "Timeline") return slot ? slot(node, key) : null;
 
+  // `Ref` — REFERENCE, NOT COPY. The design system's shared pieces travel once and are
+  // cached; a definition names one and specialises it here (core/refs.ts: `props` remap,
+  // `with` literals, style/action/visibleWhen overrides). This is what stops a button
+  // being re-sent inside every definition that uses it.
+  //
+  // A Ref only arrives when the server sent references, so this branch is inert for
+  // anything served the old, inlined way. An unknown name renders NOTHING rather than a
+  // broken box: a hole is easier to diagnose than a mystery element.
+  if (node.type === "Ref") {
+    const resolved = resolveRef(node, defs?.[String((node as { ref?: string }).ref ?? "")]);
+    return resolved ? renderNode(resolved, data, onAction, theme, key, slot, defs) : null;
+  }
+
   // `Switch` — control flow: render EXACTLY ONE branch, the case matching `data[on]`
   // (else `cases.default`, else nothing). The declarative whole-view swap (wizard step,
   // inline↔focused) — mutually exclusive in one place, vs. a `visibleWhen` per branch. No
   // wrapper element: it is transparent, like an `if`, delegating straight to the branch.
   if (node.type === "Switch") {
     const branch = selectCase(node, data);
-    return branch ? renderNode(branch, data, onAction, theme, key, slot) : null;
+    return branch ? renderNode(branch, data, onAction, theme, key, slot, defs) : null;
   }
 
   // `Each` — control flow: map a bound array (bind.items) → the `template` subtree once
@@ -173,7 +195,7 @@ export function renderNode(
         ? { ...base, ...(item as Record<string, unknown>) }
         : { ...base, value: item };
     };
-    const rendered = tpl ? items.map((item, i) => renderNode(tpl, scopeOf(item, i), onAction, theme, i, slot)) : null;
+    const rendered = tpl ? items.map((item, i) => renderNode(tpl, scopeOf(item, i), onAction, theme, i, slot, defs)) : null;
     return (
       <BoxView key={key} node={node} data={data} theme={theme}>
         {rendered}
@@ -182,7 +204,7 @@ export function renderNode(
   }
 
   // Element primitives → dispatch. Children are rendered here (control flow) and handed down.
-  const kids = (node.children ?? []).map((c, i) => renderNode(c, data, onAction, theme, i, slot));
+  const kids = (node.children ?? []).map((c, i) => renderNode(c, data, onAction, theme, i, slot, defs));
   switch (node.type) {
     case "Box":
     case "Stack":
@@ -197,6 +219,8 @@ export function renderNode(
       return <TextView key={key} node={node} data={data} theme={theme} />;
     case "Image":
       return <ImageView key={key} node={node} data={data} theme={theme} />;
+    case "Select":
+      return <SelectView key={key} node={node} data={data} theme={theme} onAction={onAction} />;
     case "Button":
       return (
         <ButtonView key={key} node={node} data={data} theme={theme} onAction={onAction}>

package/vendor/sdk/lib/style.ts

@@ -223,17 +223,21 @@ export function cssDecls(css: CSSProperties, important = false): string {
  * into a CSS string, injected ONCE per render root (<style>). This authors zero values —
  * it only structures DATA into `@keyframes uno-<name>{ <stop>{ <prop>:<val> } }`. Adding a
  * new animation = adding a keyframe to rx/ + a `style.animation` ref in a definition. No
- * SDK edit, no new primitive. Keyframe decls use real CSS prop names (transform, opacity…).
+ * SDK edit, no new primitive. Keyframe decls use real CSS prop names, KEBAB-CASE
+ * (`box-shadow`, never `boxShadow`) — that is the canonical authored form, lint-enforced.
+ * Property keys are still kebab-normalized here, exactly as Studio's gallery serializer
+ * does, so the two renderers can never disagree on a key that slips past the lint.
  */
 export function keyframesCss(theme: ResolvedTheme): string {
   const hit = keyframesCache.get(theme);
   if (hit !== undefined) return hit;
   const kf = (theme.keyframes ?? {}) as Record<string, Record<string, Record<string, string>>>;
+  const kebab = (s: string) => s.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
   const css = Object.entries(kf)
     .map(
       ([name, stops]) =>
         `@keyframes uno-${name}{${Object.entries(stops)
-          .map(([stop, decls]) => `${stop}{${Object.entries(decls).map(([p, v]) => `${p}:${v}`).join(";")}}`)
+          .map(([stop, decls]) => `${stop}{${Object.entries(decls).map(([p, v]) => `${kebab(p)}:${v}`).join(";")}}`)
           .join("")}}`,
     )
     .join("");