@unoverse-platform/studio 0.1.103 → 0.1.104

package/vendor/sdk/lib/dom/primitives.ts

@@ -0,0 +1,689 @@
+/**
+ * EVERY PRIMITIVE, IN PLAIN DOM. The closed set of leaf elements: Box, Text, Image, Button,
+ * Select, Input, Icon, Skeleton, Orb and the Unknown fallback (Markdown is in ./markdown).
+ * The dispatcher (./render) walks the tree and hands each node to one of these.
+ *
+ * A primitive is built once and updated in place: `update(node, data, kids?)` writes only what
+ * changed, `destroy()` stops whatever it started. It renders ONE generic element and nothing
+ * about a specific UX, and authors no style values: every value is served (theme.*).
+ */
+import type { ResolvedTheme, UnoverseNode } from "../core/types";
+import { styleToCss, type CssStyle } from "../style";
+import { nodeAction, type ActionHandler } from "../actions";
+import { startOrb, type OrbState, type OrbTheme } from "../orb/canvas";
+import { nodeChrome, styleEls } from "./chrome";
+import { setAttr, setChildren, setStyle, textOf } from "./element";
+import type { Data, RenderCtx } from "./types";
+
+export interface Prim {
+  readonly nodes: Node[];
+  update(node: UnoverseNode, data: Data, kids?: Node[]): void;
+  destroy(): void;
+}
+
+const bound = (field: string | undefined, data: Data): unknown => (field ? data[field] : undefined);
+
+/** INSPECTABILITY: a node carrying `$id` stamps it on its element, for authoring tools. */
+const inspectId = (node: UnoverseNode): string | undefined => {
+  const id = (node as { $id?: unknown }).$id;
+  return typeof id === "string" ? id : undefined;
+};
+
+/** A change the element makes itself (a picked selection, a scale), applied once on the page. */
+type Behaviour = (el: HTMLElement) => () => void;
+
+/** Runs at most one behaviour on an element, restarting it only when it changes. */
+function behaviourSlot(ctx: RenderCtx) {
+  let name: string | null = null;
+  let stop: (() => void) | null = null;
+  let alive = true;
+  return {
+    set(next: string | null, el: HTMLElement | null, run?: Behaviour) {
+      if (next === name) return;
+      stop?.();
+      stop = null;
+      name = next;
+      if (!next || !el || !run) return;
+      const mine = next;
+      ctx.mounted(() => {
+        if (alive && name === mine) stop = run(el);
+      });
+    },
+    destroy() {
+      alive = false;
+      stop?.();
+      stop = null;
+    },
+  };
+}
+
+// The selection chip's look: a SERVED recipe (`theme.selection.chip`) when the org styles one;
+// else this neutral fallback of token NAMES resolved against the same theme.
+const SELECTION_CHIP_BUILTIN: Record<string, unknown> = {
+  background: "action.primary",
+  color: "text.inverse",
+  font: "body.sm",
+  radius: "full",
+  padding: ["1", "3"],
+  shadow: "lg",
+  border: "none",
+  cursor: "pointer",
+};
+
+/**
+ * `Box`/`Stack`/`Row`/`Column` (and the container of `Each`): the generic `<div>`. Its
+ * children are rendered by the dispatcher and handed in. Behaviours, each opt-in by data:
+ * a STAGE (`style.stage: 1280x720`, drawn at that size and scaled as one piece), `autoScroll`
+ * (stick to the newest content), `revealOnStick` (a sticky bar shown once the element before it
+ * scrolls away) and `selection` (a chip that fires an action with the selected text).
+ */
+export function boxView(ctx: RenderCtx): Prim {
+  const doc = ctx.doc;
+  let node: UnoverseNode;
+  let data: Data;
+  let kids: Node[] = [];
+  let host: HTMLDivElement | null = null;
+  let stageEl: HTMLDivElement | null = null;
+  let stageSize: [number, number] | null = null;
+  let scale = 1;
+  let hostStyle: CssStyle = {};
+  let pick: { text: string; top: number; left: number } | null = null;
+  let chip: HTMLButtonElement | null = null;
+  let rules: string[] = [];
+  const styles = styleEls(doc);
+  const behaviour = behaviourSlot(ctx);
+  const stageWatch = behaviourSlot(ctx);
+
+  const fill = () => {
+    if (!host) return;
+    const sel = (node as { selection?: { label?: string; action?: unknown } }).selection;
+    if (!stageSize && sel && pick) {
+      if (!chip) {
+        chip = doc.createElement("button");
+        chip.addEventListener("mousedown", (e) => e.preventDefault()); // keep the selection alive through the click
+        chip.addEventListener("click", () => {
+          const s = (node as { selection?: { action?: unknown } }).selection;
+          if (!pick) return;
+          ctx.onAction?.((s?.action as Parameters<ActionHandler>[0]) ?? "select", { ...data, selection: pick.text });
+          pick = null;
+          fill();
+        });
+      }
+      const recipe = ((ctx.theme as { selection?: { chip?: Record<string, unknown> } }).selection?.chip ?? SELECTION_CHIP_BUILTIN) as Record<string, unknown>;
+      setStyle(chip, { position: "absolute", top: pick.top, left: pick.left, transform: "translate(-50%, -100%)", zIndex: 40, whiteSpace: "nowrap", ...styleToCss(recipe, ctx.theme) });
+      chip.textContent = sel.label ?? "Comment";
+    }
+    setChildren(host, [...styles(rules), ...kids, ...(!stageSize && sel && pick && chip ? [chip] : [])]);
+  };
+
+  const applyStage = () => {
+    if (!host || !stageSize) return;
+    setStyle(host, { ...hostStyle, position: "absolute", top: 0, left: 0, width: stageSize[0], height: stageSize[1], transform: `scale(${scale})`, transformOrigin: "0 0" });
+  };
+
+  const selection: Behaviour = (el) => {
+    const read = () => {
+      const root = el.getRootNode() as Document | ShadowRoot;
+      const s = (root as unknown as { getSelection?: () => Selection | null }).getSelection?.() ?? window.getSelection();
+      const clear = () => {
+        if (pick) {
+          pick = null;
+          fill();
+        }
+      };
+      if (!s || s.isCollapsed || s.rangeCount === 0) return clear();
+      const range = s.getRangeAt(0);
+      if (!el.contains(range.commonAncestorContainer)) return clear();
+      const text = s.toString().trim();
+      if (!text) return clear();
+      const r = range.getBoundingClientRect();
+      const box = el.getBoundingClientRect();
+      pick = { text, top: r.top - box.top, left: Math.min(Math.max(0, r.left - box.left + r.width / 2), box.width) };
+      fill();
+    };
+    const up = () => window.setTimeout(read, 0); // after the browser settles the selection
+    // On the DOCUMENT: a drag-select often ends outside the host, and mouse events cross the
+    // shadow boundary. `read` still only raises the chip for a selection inside this host.
+    const d = el.ownerDocument;
+    d.addEventListener("mouseup", up);
+    return () => d.removeEventListener("mouseup", up);
+  };
+
+  const autoScroll: Behaviour = (el) => {
+    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
+    const ro = new ResizeObserver(stick); // 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();
+      stick();
+    });
+    mo.observe(el, { childList: true, subtree: true });
+    return () => {
+      ro.disconnect();
+      mo.disconnect();
+    };
+  };
+
+  const revealOnStick: Behaviour = (el) => {
+    const sentinel = el.previousElementSibling;
+    // Overlay, not push: the bar's own height is cancelled so content sits under it.
+    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) {
+      show();
+      return () => {};
+    }
+    const io = new IntersectionObserver(([e]) => (e.isIntersecting ? hide() : show()), { threshold: 0 });
+    io.observe(sentinel);
+    return () => io.disconnect();
+  };
+
+  return {
+    get nodes() {
+      return stageEl ? [stageEl] : host ? [host] : [];
+    },
+    update(n, d, k = []) {
+      node = n;
+      data = d;
+      kids = k;
+      const chrome = nodeChrome(n, d, ctx.theme);
+      rules = chrome.rules;
+      const sel = (n as { selection?: unknown }).selection;
+      hostStyle = sel && !chrome.style.position ? { ...chrome.style, position: "relative" } : chrome.style;
+      const m = /^(\d+)x(\d+)$/.exec(String((n.style as { stage?: unknown } | undefined)?.stage ?? ""));
+      const size: [number, number] | null = m ? [Number(m[1]), Number(m[2])] : null;
+      if (!host || !!size !== !!stageSize) {
+        behaviour.set(null, null);
+        stageWatch.set(null, null);
+        host = doc.createElement("div");
+        stageEl = size ? doc.createElement("div") : null;
+        if (stageEl) stageEl.appendChild(host);
+        scale = 1;
+      }
+      stageSize = size;
+      setAttr(host, "class", chrome.className);
+      setAttr(host, "data-unoverse-id", inspectId(n));
+      if (stageEl && size) {
+        setStyle(stageEl, { position: "relative", width: "100%", aspectRatio: `${size[0]} / ${size[1]}` });
+        applyStage();
+        const outer = stageEl;
+        stageWatch.set(`stage:${size[0]}`, outer, (el) => {
+          const ro = new ResizeObserver(() => {
+            scale = el.clientWidth / (stageSize?.[0] ?? 1);
+            applyStage();
+          });
+          ro.observe(el);
+          return () => ro.disconnect();
+        });
+      } else {
+        setStyle(host, hostStyle);
+        // One behaviour per element, in this order (the element can carry only one).
+        const which = n.autoScroll === true ? "autoScroll" : n.revealOnStick === true ? "revealOnStick" : sel ? "selection" : null;
+        behaviour.set(which, host, which === "autoScroll" ? autoScroll : which === "revealOnStick" ? revealOnStick : selection);
+        if (!sel) pick = null;
+      }
+      fill();
+    },
+    destroy() {
+      behaviour.destroy();
+      stageWatch.destroy();
+    },
+  };
+}
+
+/** `Text`: a bound or literal string (`<span>`). */
+export function textView(ctx: RenderCtx): Prim {
+  const el = ctx.doc.createElement("span");
+  return {
+    nodes: [el],
+    update(node, data) {
+      setStyle(el, styleToCss(node.style, ctx.theme, data));
+      setAttr(el, "data-unoverse-id", inspectId(node));
+      const t = textOf(bound(node.bind?.value, data) ?? node.value);
+      if (el.textContent !== t) el.textContent = t;
+    },
+    destroy() {},
+  };
+}
+
+/** `Image`: a bound or literal src (`<img>`). */
+export function imageView(ctx: RenderCtx): Prim {
+  const el = ctx.doc.createElement("img");
+  return {
+    nodes: [el],
+    update(node, data) {
+      setAttr(el, "data-unoverse-id", inspectId(node));
+      setStyle(el, styleToCss(node.style, ctx.theme, data));
+      setAttr(el, "src", (bound(node.bind?.src, data) as string | undefined) ?? node.src);
+      setAttr(el, "alt", (bound(node.bind?.alt, data) as string | undefined) ?? node.alt ?? "");
+    },
+    destroy() {},
+  };
+}
+
+/** `Button`: fires the node's action. Content is a bound label OR its composed children. */
+export function buttonView(ctx: RenderCtx): Prim {
+  const el = ctx.doc.createElement("button");
+  const styles = styleEls(ctx.doc);
+  const label = ctx.doc.createTextNode("");
+  let node: UnoverseNode;
+  let data: Data;
+  el.addEventListener("click", () => ctx.onAction?.(nodeAction(node, "click"), data));
+  return {
+    nodes: [el],
+    update(n, d, kids = []) {
+      node = n;
+      data = d;
+      const { className, rules, style, disabled } = nodeChrome(n, d, ctx.theme);
+      setAttr(el, "class", className);
+      setStyle(el, style);
+      setAttr(el, "disabled", disabled);
+      setAttr(el, "data-unoverse-id", inspectId(n));
+      let content: Node[] = kids;
+      if (!n.children?.length) {
+        label.data = textOf(bound(n.bind?.label, d));
+        content = label.data ? [label] : [];
+      }
+      setChildren(el, [...styles(rules), ...content]);
+    },
+    destroy() {},
+  };
+}
+
+/** Unknown node type: its children, so the tree does not break. */
+export function unknownView(ctx: RenderCtx): Prim {
+  const el = ctx.doc.createElement("div");
+  return {
+    nodes: [el],
+    update(node, _data, kids = []) {
+      setStyle(el, styleToCss(node.style, ctx.theme));
+      setAttr(el, "data-unoverse-unknown", node.type);
+      setChildren(el, kids);
+    },
+    destroy() {},
+  };
+}
+
+// React's camelCase SVG presentation names, as the attributes the browser reads.
+const SVG_CAMEL = /^(stroke|fill|clip|stop|font|text|marker|flood|lighting|color|dominant|vector|shape|paint|pointer|alignment|baseline|glyph|letter|word|writing|unicode|overline|underline|strikethrough|image|enable|horiz|vert)[A-Z]/;
+const svgAttr = (k: string) => (k === "className" ? "class" : k === "xlinkHref" ? "xlink:href" : SVG_CAMEL.test(k) ? k.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()) : k);
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+type Glyph = { viewBox?: string; attrs?: Record<string, unknown>; children?: [string, Record<string, unknown>][] };
+
+/** A served glyph as an `<svg>` (theme.icons); the SDK bundles no icon pack. */
+export function svgOf(doc: Document, ic: Glyph, style: CssStyle | undefined): SVGSVGElement {
+  const svg = doc.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("viewBox", ic.viewBox ?? "0 0 24 24");
+  for (const [k, v] of Object.entries(ic.attrs ?? {})) setAttr(svg, svgAttr(k), v);
+  svg.setAttribute("aria-hidden", "true");
+  setStyle(svg, style);
+  for (const [tag, attrs] of Array.isArray(ic.children) ? ic.children : []) {
+    const child = doc.createElementNS(SVG_NS, tag);
+    for (const [k, v] of Object.entries(attrs ?? {})) setAttr(child, svgAttr(k), v);
+    svg.appendChild(child);
+  }
+  return svg;
+}
+
+/** `Icon`: a named glyph whose drawing is served. Name is literal or bound (`bind.name`). */
+export function iconView(ctx: RenderCtx): Prim {
+  let svg: SVGSVGElement | null = null;
+  let drawn: Glyph | undefined;
+  return {
+    get nodes() {
+      return svg ? [svg] : [];
+    },
+    update(node, data) {
+      const name = node.bind?.name ? (data[node.bind.name] as string) : (node.icon ?? node.name);
+      const ic = name ? ((ctx.theme.icons ?? {}) as Record<string, Glyph>)[name] : undefined;
+      if (!ic) {
+        svg = null;
+        drawn = undefined;
+        return;
+      }
+      if (ic !== drawn || !svg) {
+        svg = svgOf(ctx.doc, ic, styleToCss(node.style ?? {}, ctx.theme));
+        drawn = ic;
+      } else setStyle(svg, styleToCss(node.style ?? {}, ctx.theme));
+    },
+    destroy() {},
+  };
+}
+
+/**
+ * `Skeleton`: the loading placeholder. Every dimension is served (theme.skeleton); the motion
+ * is the primitive's own, overridable by a served `skeleton.shimmer` and off when it is false.
+ * DEFENSIVE BY LAW: a missing token leaves that dimension unset, never a crash.
+ */
+export function skeletonView(ctx: RenderCtx): Prim & { variant(v: string | undefined): void } {
+  const doc = ctx.doc;
+  let nodes: Node[] = [];
+  let built: { variant: string; theme: ResolvedTheme } | null = null;
+  let variant = "text";
+  const build = () => {
+    const theme = ctx.theme;
+    if (built && built.variant === variant && built.theme === theme) return;
+    built = { variant, theme };
+    const sk = (theme.skeleton ?? {}) as Record<string, any>;
+    const SHIMMER_BUILTIN: CssStyle = {
+      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: CssStyle = sk.shimmer === false ? {} : typeof sk.shimmer === "object" ? (sk.shimmer as CssStyle) : SHIMMER_BUILTIN;
+    const keyframes = () => {
+      const s = doc.createElement("style");
+      s.textContent = "@keyframes uno-skeleton-shimmer{0%{background-position:200% 0}100%{background-position:-200% 0}}";
+      return s;
+    };
+    const div = (style: CssStyle, kids: Node[] = []) => {
+      const d = doc.createElement("div");
+      setStyle(d, style);
+      setChildren(d, kids);
+      return d;
+    };
+    const bar = (spec: string) => {
+      const [w, h] = String(spec).split(" ");
+      return div({ width: w, height: h, background: sk.fill, borderRadius: sk.barRadius, ...shimmer });
+    };
+    const kf = sk.shimmer === false ? [] : [keyframes()];
+    if (variant === "image") nodes = [...kf, div({ width: "100%", height: "100%", minHeight: sk.image?.minHeight, background: sk.fill, borderRadius: sk.radius, ...shimmer })];
+    else if (variant === "card")
+      nodes = [
+        ...kf,
+        div(
+          {
+            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),
+        ),
+      ];
+    else nodes = [div({ display: "flex", flexDirection: "column", gap: sk.gap }, [...kf, ...(Array.isArray(sk.text?.bars) ? (sk.text.bars as string[]) : []).map(bar)])];
+  };
+  return {
+    get nodes() {
+      return nodes;
+    },
+    variant(v) {
+      variant = v ?? "text";
+      build();
+    },
+    update(node) {
+      variant = (node.variant as string | undefined) ?? "text";
+      build();
+    },
+    destroy() {},
+  };
+}
+
+/**
+ * `Select`: the irreducible `<select>`. It reports a change as a controlled Input does,
+ * `("input", { field, text })`. The options are data (`bind.options` or literal `options`).
+ */
+export function selectView(ctx: RenderCtx): Prim {
+  const doc = ctx.doc;
+  const el = doc.createElement("select");
+  let field: string | undefined;
+  let value = "";
+  el.addEventListener("change", () => {
+    if (field != null) ctx.onAction?.("input", { text: el.value, field });
+    if (el.value !== value && Array.from(el.options).some((o) => o.value === value)) el.value = value;
+  });
+  return {
+    nodes: [el],
+    update(node, data) {
+      field = node.bind?.value;
+      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 Data).value ?? (o as Data).label ?? ""), label: String((o as Data).label ?? (o as Data).value ?? "") }
+          : { value: String(o), label: String(o) },
+      );
+      const { style, disabled } = nodeChrome(node, data, ctx.theme);
+      setStyle(el, style);
+      setAttr(el, "disabled", disabled);
+      setAttr(el, "data-unoverse-id", inspectId(node));
+      // The placeholder is CONTENT: an unanswered select says what it wants.
+      const want = [...(node.placeholder != null ? [{ value: "", label: String(node.placeholder), placeholder: true }] : []), ...options.map((o) => ({ ...o, placeholder: false }))];
+      const opts = Array.from(el.options);
+      want.forEach((w, i) => {
+        const o = opts[i] ?? doc.createElement("option");
+        setAttr(o, "value", w.value);
+        setAttr(o, "disabled", w.placeholder);
+        if (o.textContent !== w.label) o.textContent = w.label;
+        if (!opts[i]) el.appendChild(o);
+      });
+      for (const o of opts.slice(want.length)) o.remove();
+      // A value no option holds shows the first enabled option, as it always has.
+      const shown = want.some((w) => w.value === value) ? value : (want.find((w) => !w.placeholder)?.value ?? "");
+      if (el.value !== shown) el.value = shown;
+    },
+    destroy() {},
+  };
+}
+
+/**
+ * `Input`: the irreducible `<input>` (or `<textarea>` with `multiline`). CONTROLLED when
+ * `bind.value` is set: the value comes from the data and each change is reported as
+ * `("input", { text, field })`. Otherwise it keeps its own draft. Enter submits; with
+ * `multiline`, Cmd/Ctrl+Enter does. Generic constraints only (`maxLength`, numeric
+ * `inputMode`, `autoComplete`, `inputType`, `advanceOnFill`); no chrome, no UX shape.
+ */
+export function inputView(ctx: RenderCtx): Prim {
+  const doc = ctx.doc;
+  let el: HTMLInputElement | HTMLTextAreaElement | null = null;
+  let multiline = false;
+  let node: UnoverseNode;
+  let data: Data;
+  let local = "";
+  const field = () => node.bind?.value;
+  const value = () => (field() != null ? String(data[field()!] ?? "") : local);
+  const maxLength = () => (node as { maxLength?: number }).maxLength;
+  const numeric = () => (node as { inputMode?: string }).inputMode === "numeric";
+  const inputType = () => (node as { inputType?: string }).inputType;
+  const advanceOnFill = () => (node as { advanceOnFill?: boolean }).advanceOnFill === true;
+  const accept = (t: string) => {
+    const kept = numeric() ? t.replace(/[^0-9]/g, "") : t;
+    const max = maxLength();
+    return max != null ? kept.slice(0, max) : kept;
+  };
+  // Scoped to this render's ROOT: the SDK renders inside a shadow root.
+  const stepFocus = (dir: 1 | -1) => {
+    const self = el as HTMLInputElement | null;
+    if (!self || multiline) return;
+    const root = self.getRootNode() as Document | ShadowRoot;
+    const peers = Array.from(root.querySelectorAll<HTMLInputElement>("input[data-uno-advance]"));
+    const next = peers[peers.indexOf(self) + dir];
+    if (!next) return;
+    next.focus();
+    next.select();
+  };
+  // Show the value the data holds (a controlled field reverts a change the data refused).
+  const show = () => {
+    if (!el || inputType() === "file") return;
+    const v = value();
+    if (el.value !== v) el.value = v;
+  };
+  const setValue = (raw: string) => {
+    const t = accept(raw);
+    const max = maxLength();
+    // Focus moves BEFORE the store round-trip, so a fast typist's next key lands next door.
+    if (advanceOnFill() && max != null && t.length >= max) stepFocus(1);
+    if (field() != null) ctx.onAction?.("input", { text: t, field: field() });
+    else local = t;
+    show();
+  };
+  const submit = () => {
+    const t = value().trim();
+    if (!t) return;
+    ctx.onAction?.(nodeAction(node, "submit"), { text: t });
+    if (field() == null) {
+      local = "";
+      show();
+    }
+  };
+  const build = () => {
+    if (multiline) {
+      const ta = doc.createElement("textarea");
+      ta.addEventListener("input", () => setValue(ta.value));
+      ta.addEventListener("keydown", (e) => {
+        if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault();
+          submit();
+        }
+      });
+      return ta;
+    }
+    const input = doc.createElement("input");
+    input.addEventListener("input", () => {
+      // A FILE FIELD REPORTS ITS FILES, not its value (a fake path); the bytes are the host's.
+      if (inputType() === "file") {
+        const picked = Array.from(input.files ?? []).map((f) => ({ name: f.name, size: f.size, type: f.type }));
+        if (field() != null) ctx.onAction?.("input", { text: picked.map((f) => f.name).join(", "), field: field(), files: picked });
+        return;
+      }
+      setValue(input.value);
+    });
+    input.addEventListener("keydown", (e) => {
+      // Backspace in an already-empty field of a sequence steps back.
+      if (advanceOnFill() && e.key === "Backspace" && value() === "") {
+        e.preventDefault();
+        stepFocus(-1);
+        return;
+      }
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        submit();
+      }
+    });
+    return input;
+  };
+  return {
+    get nodes() {
+      return el ? [el] : [];
+    },
+    update(n, d) {
+      node = n;
+      data = d;
+      const ml = (n as { multiline?: boolean }).multiline === true;
+      if (!el || ml !== multiline) {
+        multiline = ml;
+        el = build();
+      }
+      const { style, disabled } = nodeChrome(n, d, ctx.theme);
+      setStyle(el, style);
+      setAttr(el, "disabled", disabled);
+      setAttr(el, "placeholder", n.placeholder);
+      setAttr(el, "maxlength", maxLength());
+      if (multiline) {
+        setAttr(el, "rows", (n as { rows?: number }).rows ?? 3);
+        if (el.textContent !== value()) el.textContent = value();
+      } else {
+        const file = inputType() === "file";
+        // A file input is never controlled: assigning its value is a security error.
+        setAttr(el, "value", file ? undefined : value());
+        setAttr(el, "type", inputType());
+        setAttr(el, "inputmode", numeric() ? "numeric" : undefined);
+        setAttr(el, "autocomplete", (n as { autoComplete?: string }).autoComplete);
+        setAttr(el, "data-uno-advance", advanceOnFill() ? "" : undefined);
+      }
+      show();
+    },
+    destroy() {},
+  };
+}
+
+const ORB_STATES = new Set(["working", "searching", "solving", "listening", "connecting", "weaving", "composing", "breathing", "shaping", "halo", "sonar", "shimmer", "pulse"]);
+const ORB_LABELS: Record<string, string> = {
+  working: "Working…",
+  searching: "Searching…",
+  solving: "Solving…",
+  listening: "Listening…",
+  connecting: "Connecting…",
+  weaving: "Weaving…",
+  composing: "Composing…",
+  breathing: "Thinking…",
+  shaping: "Shaping…",
+  halo: "Waiting…",
+  sonar: "Listening…",
+  shimmer: "Thinking…",
+  pulse: "Responding…",
+};
+
+/** #rgb / #rrggbb / rgb()/rgba() → an rgb tuple; anything else → 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;
+}
+
+/**
+ * `Orb`: the procedural "the assistant is doing something" animation on a 2D canvas (../orb).
+ * Every knob is data or literal (`bind.<knob>` wins). An unknown state degrades to the calm
+ * `halo`, never the loud sphere. Brand ink comes from the style's `color` token.
+ */
+export function orbView(ctx: RenderCtx): Prim {
+  const el = ctx.doc.createElement("canvas");
+  let drawn = "";
+  let stop: (() => void) | null = null;
+  let alive = true;
+  return {
+    nodes: [el],
+    update(node, data) {
+      const n = node as UnoverseNode & { state?: string; size?: number | string; speed?: number | string; theme?: string };
+      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;
+      const state = (raw && ORB_STATES.has(raw) ? raw : "halo") as OrbState;
+      const size = Number(knob("size")) > 0 ? Number(knob("size")) : 64;
+      const speed = Number(knob("speed")) > 0 ? Number(knob("speed")) : 1;
+      const theme: OrbTheme = n.theme === "dark" || n.theme === "light" ? n.theme : "auto";
+      const css = styleToCss(node.style ?? {}, ctx.theme, data);
+      const ink = cssColorToRgb(css.color as string | undefined);
+      setAttr(el, "role", "img");
+      setAttr(el, "aria-label", ORB_LABELS[state]);
+      setStyle(el, { width: size, height: size, display: "block", ...css });
+      const key = JSON.stringify([state, size, speed, theme, ink]);
+      if (key === drawn) return;
+      drawn = key;
+      stop?.();
+      stop = null;
+      ctx.mounted(() => {
+        if (alive && drawn === key) stop = startOrb(el, { state, size, speed, theme, ink });
+      });
+    },
+    destroy() {
+      alive = false;
+      stop?.();
+    },
+  };
+}