@unoverse-platform/studio 0.1.103 → 0.1.104

package/vendor/sdk/lib/render.tsx

@@ -1,244 +0,0 @@
-/**
- * ════════════════════════════════════════════════════════════════════════════
- *  THE DISPATCHER: UnoverseNode → React.   ⛔ READ BEFORE EDITING ⛔
- * ════════════════════════════════════════════════════════════════════════════
- *
- *  THIS FILE RENDERS NOTHING. It only WALKS the tree and DISPATCHES `node.type`
- *  to a primitive component in ./primitives. There is NOT A SINGLE raw element
- *  here — no `<div>`, `<span>`, `<button>`, `<img>`, `<input>`, `<svg>`. If you
- *  are about to write one, STOP: it belongs in ./primitives. This is enforced by
- *  test/dispatcher-only.test.mjs (the build fails if a raw element appears here),
- *  so the engine/primitive split can't silently rot — which is exactly how
- *  `Button` (and its styling logic) kept leaking back into the dispatcher.
- *
- *  THE FRAMEWORK IN ONE SENTENCE: this SDK is a FIXED, GENERIC interpreter. ALL
- *  UX is built in DATA (design/ definitions + the served theme) — an author creates
- *  ANY interface WITHOUT editing this SDK. (See FRAMEWORK.md.)
- *
- *  WHERE THINGS LIVE:
- *    • ./render     — this dispatcher (control flow: visibleWhen, Each, slots) ONLY.
- *    • ./primitives — EVERY primitive (Box/Text/Image/Button/Icon/Skeleton/Input/
- *                     Markdown/Unknown) + the shared per-element chrome.
- *    • ./style      — the style + animation interpreter (styleToCss/keyframesCss).
- *
- *  Two laws (govern all three files + the whole package):
- *    LAW 1 — OWN ZERO STYLE VALUES. No hex/px/rem/em/recipes; resolve token NAMES
- *            against the SERVED theme. Enforced by test/golden-rule.test.mjs.
- *    LAW 2 — OWN ZERO UX SHAPE. A primitive renders ONE generic element, nothing
- *            about a specific UX. A composer/card/loader is a LAYOUT — compose it
- *            in a DEFINITION. Never a per-UX primitive or per-UX config.
- *
- *  Need something the vocab can't express? Prefer extending the generic interpreter
- *  ONCE (a new style-vocab key in ./style, a new model projection) over a primitive.
- *  You almost never need to touch this file — build it in design/ first.
- * ════════════════════════════════════════════════════════════════════════════
- */
-import type { ReactNode } from "react";
-import type { ActionSpec, ResolvedTheme, UnoverseNode } from "./core";
-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".
-export { styleToCss, keyframesCss } from "./style";
-
-// An action is a bare string (→ workflow) or a declarative envelope (§2e-3). The
-// binding layer (streamed.tsx) interprets it; primitives just forward node.action.
-/** Instance context riding with a bubbled server action — WHICH component fired and its
- *  current slice, so the channel can forward the submitted state (e.g. a wizard's answers)
- *  without reaching into the store. Pure transport metadata; the SDK interprets none of it. */
-export interface ActionMeta {
-  chatId?: string;
-  nodeId?: string;
-  /** Which component this instance is — so the server needs no registry to find out. */
-  type?: string;
-  state?: Record<string, unknown>;
-}
-
-export type ActionHandler = (action: string | ActionSpec, data: Record<string, unknown>, meta?: ActionMeta) => void;
-
-/**
- * A leaf's action, with the node's declared `analytics` attached (UNOVERSE_ANALYTICS.md).
- *
- * Authors write `analytics:` beside `action:` on the node, where the data it reports is
- * already in scope. The two travel together from here so `dispatchAction` remains the ONE
- * place an interaction is understood: leaves stay dumb, and no leaf can forget to report.
- * A node with no `analytics` block passes its action through untouched, unallocated.
- */
-export function nodeAction(node: UnoverseNode, fallback: string): string | ActionSpec {
-  const action = node.action ?? fallback;
-  if (!node.analytics?.event) return action;
-  return typeof action === "string"
-    ? { type: action, analytics: node.analytics }
-    : { ...action, analytics: node.analytics };
-}
-
-/**
- * Resolves a `ComponentSlot` node against the store (provided by the template
- * renderer). Returns the rendered leaves (or the slot's fallback). Components
- * don't use slots, so this is undefined on the component render path.
- */
-export type SlotResolver = (node: UnoverseNode, key?: React.Key) => ReactNode;
-
-// cssWidth moved to core/apps.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,
-  data: Record<string, unknown>,
-  onAction: ActionHandler | undefined,
-  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
-  // one field can drive tabs/wizard steps without a boolean per state. The predicate is
-  // shared with `Switch` and `style.when` (core/conditions.ts) — one state semantics.
-  if (node.visibleWhen != null && !visible(node.visibleWhen, data)) return null;
-
-  // `skeleton: true` — the protocol's LOADING semantic: while the node's bound field has
-  // no data yet, render its Skeleton ghost IN PLACE (inside the node's own styled box, so
-  // the ghost occupies exactly the space the content will). Variant inferred from the
-  // node type; the ghost's entire look is theme data (LAW 1). This is a generic BEHAVIOR
-  // (no data yet → ghost), not a style or a UX shape — the one judgment only the
-  // renderer can make, since only it watches binds resolve over time.
-  if (node.skeleton) {
-    const field = node.bind?.value ?? node.bind?.src ?? node.bind?.items;
-    if (field && !visible(field, data)) {
-      const variant = node.type === "Image" ? "image" : node.type === "Each" ? "card" : "text";
-      return (
-        <BoxView key={key} node={{ type: "Box", style: node.style }} data={data} theme={theme}>
-          <SkeletonView variant={variant} theme={theme} />
-        </BoxView>
-      );
-    }
-  }
-
-  // STATE-OWNED SIZING (docs/design/05): a plain node's `appWidth` = an ALWAYS-OPEN
-  // panel (e.g. the core chat column). The ONE declared value both grows the app
-  // (computeAppWidth) and fixes the panel's box here — they can never disagree, and
-  // nothing elastic remains for a resize to land on. Slot panels are injected at their
-  // frame (template.tsx); a layout root never carries appWidth (guard-enforced).
-  const panelW = (node as { appWidth?: string }).appWidth;
-  // ComponentSlot AND Template keep their appWidth: both are slot-dispatched places
-  // whose width applies to their FRAME (app.tsx), not to a box of their own —
-  // consuming it here left the mount frame width-less (measured live 2026-08-28).
-  if (panelW && node.type !== "ComponentSlot" && node.type !== "Template" && node.type !== "Place") {
-    const w = cssWidth(theme.appSize?.[panelW] ?? panelW);
-    if (w) node = { ...node, appWidth: undefined, style: { ...(node.style ?? {}), width: w, flex: "0 0 auto" } } as UnoverseNode;
-  }
-
-  // Store-backed / leaf primitives → dispatch to ./primitives.
-  if (node.type === "Skeleton") return <SkeletonView key={key} variant={node.variant} theme={theme} />;
-  // Icon: DATA path reads `bind.name`; LITERAL path reads the `icon` attribute. `name` is
-  // read as a literal too, because an atom that binds `name` (the only spelling the data
-  // path reads) has that bind turned INTO a `name` attribute when a Ref supplies the glyph
-  // 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} onAction={onAction} />;
-  if (node.type === "ComponentSlot" || node.type === "Timeline" || node.type === "Template" || node.type === "Place") 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, defs) : null;
-  }
-
-  // `Each` — control flow: map a bound array (bind.items) → the `item` subtree once
-  // per item (that item as the data scope), inside the node's own container (a Box).
-  // A PRIMITIVE item (string/number — e.g. a `string[]` of follow-up questions) is exposed
-  // as `{ value: item }`, so the item binds `value` like any field; object items pass
-  // through unchanged. This is what lets an `Each` iterate a plain list of strings.
-  if (node.type === "Each") {
-    // Literal `items` fallback: a microapp component hardcodes its static option lists
-    // in the def (props exist only for state — UNOVERSE_AUTHORING.md). bind wins.
-    const src = node.bind?.items ? data[node.bind.items] : node.items;
-    const items = Array.isArray(src) ? src : [];
-    // `item` is the Each's repeated drawing (renamed from `template` 2026-09-01: one word for
-    // a holder NAME (string) on Template, which this branch never sees. Narrow rather than
-    // assert, so a definition that puts the wrong one here renders nothing instead of
-    // throwing inside the map.
-    const tpl = typeof node.item === "object" ? node.item : undefined;
-    // WHERE AN ITEM SITS is something only the renderer knows, and a numbered list cannot
-    // be authored without it: the data carries no ordinal, and a template cannot count.
-    // `index` is 0-based for logic, `position` 1-based because that is what a reader sees.
-    // The item's own fields always win, so data that carries either name is untouched.
-    // AN ARRAY ITEM IS THE VALUE. `typeof [] === "object"`, so an array took the spread
-    // branch and its INDICES became scope keys ({0: "London", 1: "+44…"}) while `value` was
-    // never set. A nested Each bound to `value` — a table's row of cells — then found
-    // nothing, and every table rendered its headers over empty rows.
-    const scopeOf = (item: unknown, i: number): Record<string, unknown> => {
-      const base = { index: i, position: i + 1 };
-      return item != null && typeof item === "object" && !Array.isArray(item)
-        ? { ...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, defs)) : null;
-    return (
-      <BoxView key={key} node={node} data={data} theme={theme}>
-        {rendered}
-      </BoxView>
-    );
-  }
-
-  // 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, defs));
-  switch (node.type) {
-    case "Box":
-    case "Stack":
-    case "Row":
-    case "Column":
-      return (
-        <BoxView key={key} node={node} data={data} theme={theme} onAction={onAction}>
-          {kids}
-        </BoxView>
-      );
-    case "Text":
-      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}>
-          {kids}
-        </ButtonView>
-      );
-    default:
-      return (
-        <UnknownView key={key} node={node} theme={theme}>
-          {kids}
-        </UnknownView>
-      );
-  }
-}

package/vendor/sdk/lib/streamed.tsx

@@ -1,30 +0,0 @@
-/**
- * DEPRECATED ALIAS. `UnoverseComponent` now renders from either a plain `data` object or a
- * live store, so the streamed variant is the same component with the store props filled in.
- *
- * Kept so existing channels keep working while their call sites move over. Nothing here
- * decides anything: it forwards.
- */
-import { UnoverseComponent, useUnoverseInstance } from "./UnoverseComponent";
-import type { ComponentStore, ResolvedTheme, UnoverseClient } from "./core";
-import type { ActionHandler } from "./render";
-
-export { useUnoverseInstance };
-
-export interface StreamedUnoverseComponentProps {
-  client: UnoverseClient;
-  store: ComponentStore;
-  chatId: string;
-  nodeId: string;
-  onAction?: ActionHandler;
-  theme?: ResolvedTheme;
-  /** Neutral turn state merged into the component's data scope (e.g. `streaming`). */
-  extraData?: Record<string, unknown>;
-  /** A surface's single occupant fills the surface — see UnoverseComponent.fill. */
-  fill?: boolean;
-}
-
-/** @deprecated Render `UnoverseComponent` with `store`, `chatId` and `nodeId`. */
-export function StreamedUnoverseComponent(props: StreamedUnoverseComponentProps) {
-  return <UnoverseComponent {...props} />;
-}

package/vendor/sdk/lib/theme.ts

@@ -1,55 +0,0 @@
-/**
- * useUnoverseTheme — fetch the RESOLVED theme from the MCP server by name.
- *
- * The SDK owns ZERO token values. The server owns the visual (apps/unoverse/
- * design/styles, resolved live) and serves it at `unoverse://theme/{name}`; this hook
- * fetches it (cached in the client). A brand change in design/styles is refresh-only
- * — there is no baked theme in this bundle to rebuild (UNOVERSE_SPEC §2d-1).
- */
-import { useEffect, useState } from "react";
-import type { ResolvedTheme, UnoverseClient } from "./core";
-
-/**
- * Ensure the theme's webfont stylesheets are loaded ONCE in the document head.
- * `theme.fonts` is SERVED DATA (`fonts.stylesheets` in an org's styles) — the SDK
- * authors no font choices, it just registers what the server serves. Fonts must live
- * at document level: a shadow root cannot register @font-face, but faces declared in
- * the document apply inside shadow trees via the font cascade.
- */
-export function ensureFontStylesheets(theme: ResolvedTheme | null): void {
-  if (!theme?.fonts?.length || typeof document === "undefined") return;
-  for (const href of theme.fonts) {
-    if (document.head.querySelector(`link[data-unoverse-font="${CSS.escape(href)}"]`)) continue;
-    const link = document.createElement("link");
-    link.rel = "stylesheet";
-    link.href = href;
-    link.setAttribute("data-unoverse-font", href);
-    document.head.appendChild(link);
-  }
-}
-
-/** Returns the resolved theme (null until the first fetch resolves).
- *  `name: null` = don't fetch yet (the caller is still deriving the name — e.g. waiting
- *  for the definition whose `org` names its pack's theme). An unknown name falls back to
- *  the neutral `light` so a pack without a theme still renders. */
-export function useUnoverseTheme(client: UnoverseClient, name: string | null = "light"): ResolvedTheme | null {
-  const [theme, setTheme] = useState<ResolvedTheme | null>(null);
-  useEffect(() => {
-    if (!name) return;
-    let alive = true;
-    client
-      .readTheme(name)
-      .then((t) => alive && setTheme(t))
-      .catch(() => {
-        if (!alive || name === "light") return;
-        client
-          .readTheme("light")
-          .then((t) => alive && setTheme(t))
-          .catch(() => {});
-      });
-    return () => {
-      alive = false;
-    };
-  }, [client, name]);
-  return theme;
-}

package/vendor/sdk/lib/transition/MountArrangement.tsx

@@ -1,71 +0,0 @@
-/**
- * The double-buffered mount (UNOVERSE_TEMPLATE_MODEL §13.3): renders its LAST
- * COMMITTED arrangement and commits the next one only when the decision allows —
- * so a data ripple can never move the shelf, and the boundary commit is the one
- * designed (and, with theme motion, animated) change. Content inside held
- * instances stays live automatically: the render closure reads slices from the
- * store at render time; only membership and order are buffered here.
- *
- * Fail open (§13.5): a "hold" with no boundary inside the grace window commits
- * anyway — the screen never pays for machinery failure.
- *
- * RENDER-LAYER state, deliberately: the portable core stays frozen and "no UI
- * state in the store" holds.
- */
-
-import React, { useEffect, useRef, useState } from "react";
-import type { ReactNode } from "react";
-import { decideCommit, type Arrangement } from "./decide";
-import { commitArrangement } from "./viewTransition";
-
-/** A held-back change commits anyway after this long without a boundary. */
-const GRACE_MS = 4000;
-
-export function MountArrangement({
-  next,
-  directed,
-  motion,
-  render,
-}: {
-  /** The arrangement the store derives RIGHT NOW. */
-  next: Arrangement;
-  /** The placement grants a director — every delivery settles, so membership
-   *  waits for the settle (decide.ts). */
-  directed: boolean;
-  /** Theme-requested motion (§13.4) — absent theme word = instant commits. */
-  motion: boolean;
-  /** Build the tree for an arrangement; slices are read live inside. */
-  render: (arrangement: Arrangement) => ReactNode;
-}) {
-  const [committed, setCommitted] = useState<Arrangement | null>(null);
-  const graceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const decision = decideCommit(committed, next, directed);
-
-  useEffect(() => {
-    if (decision === "none") return;
-    if (decision === "hold") {
-      if (!graceTimer.current) {
-        graceTimer.current = setTimeout(() => {
-          graceTimer.current = null;
-          setCommitted(next);
-        }, GRACE_MS);
-      }
-      return;
-    }
-    if (graceTimer.current) {
-      clearTimeout(graceTimer.current);
-      graceTimer.current = null;
-    }
-    if (decision === "transition") commitArrangement(() => setCommitted(next), motion);
-    else setCommitted(next);
-  });
-
-  useEffect(
-    () => () => {
-      if (graceTimer.current) clearTimeout(graceTimer.current);
-    },
-    [],
-  );
-
-  return <>{render(committed ?? next)}</>;
-}

package/vendor/sdk/lib/transition/index.ts

@@ -1,9 +0,0 @@
-/**
- * The Transition Model (UNOVERSE_TEMPLATE_MODEL §13) — the render layer's
- * designed way of moving interfaces in and out of a mounted template:
- * `decide.ts` (the pure commit decision), `MountArrangement.tsx` (the
- * double-buffer), `viewTransition.ts` (the theme-gated animated commit).
- */
-export { decideCommit, type Arrangement, type CommitDecision } from "./decide";
-export { MountArrangement } from "./MountArrangement";
-export { commitArrangement } from "./viewTransition";

package/vendor/sdk/lib/transition/viewTransition.ts

@@ -1,29 +0,0 @@
-/**
- * The commit IS the animation (UNOVERSE_TEMPLATE_MODEL §13.4): when the theme
- * asks for motion, the boundary commit is wrapped in the browser's View
- * Transitions API — the browser diffs old and new and animates; the THEME's CSS
- * owns every duration and ease. The SDK contributes only this generic behaviour
- * and NO styles. Engines without the API, and themes that author no motion, get
- * the instant commit — today's behaviour, gracefully.
- */
-
-import { flushSync } from "react-dom";
-
-type WithViewTransition = { startViewTransition?: (cb: () => void) => unknown };
-
-export function commitArrangement(commit: () => void, motion: boolean): void {
-  const doc = typeof document !== "undefined" ? (document as unknown as WithViewTransition) : undefined;
-  if (!motion || typeof doc?.startViewTransition !== "function") {
-    commit();
-    return;
-  }
-  // From a microtask, outside React's lifecycle, so flushSync is legal: the
-  // API snapshots, the commit flushes the new DOM, the browser animates.
-  queueMicrotask(() => {
-    try {
-      doc.startViewTransition!(() => flushSync(commit));
-    } catch {
-      commit(); // fail open — the change lands even if the ceremony breaks
-    }
-  });
-}