@unoverse-platform/studio 0.1.115 → 0.1.116

package/vendor/sdk/pageInterfaces.ts

@@ -18,6 +18,7 @@
  * The frame shares the page's origin (EMBED_CLIENT.md §1), so the page's document is reachable
  * from here, and a part drawn into the page is as live as one drawn in the frame.
  */
+import { taskUri, taskUriOf } from "../../../../../packages/base/src/definitions/registry/taskUri.js";
 import { ComponentStore } from "./lib/core/store";
 import type { UnoverseDefinition } from "./lib/core/types";
 import type { ActionHandler, ActionMeta } from "./lib/actions";
@@ -25,6 +26,20 @@ import { mountComponent, type ComponentMount, type DefinitionSource } from "./li
 import type { VoiceService } from "./lib/voiceService";
 
 const MARK = "data-unoverse-interface";
+/** WHAT THE PAGE HANDS A TEMPLATE'S TASK (docs/design/lifecycle-hooks.md): a JSON object on the
+ *  marked element, such as the id in the page's address. Its task reads it as `props.input`;
+ *  the page hands values, never calls. */
+const INPUT = "data-unoverse-input";
+function inputOf(el: HTMLElement): Record<string, unknown> | undefined {
+  const raw = el.getAttribute(INPUT);
+  if (!raw) return undefined;
+  try {
+    const v = JSON.parse(raw);
+    return v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
 const CHAT = "page";
 const TEMPLATE_NODE = "~template";
 
@@ -60,6 +75,17 @@ function keyOwner(doc: Document): HTMLElement | null {
 
 /** A page template's address, from the name its element is marked with. */
 const uriOf = (name: string) => (name.includes("://") ? name : `unoverse://templates/${name}`);
+/**
+ * THE TASK A PAGE TEMPLATE IS, by its one URI (docs/mcp/MCP_TASKS.md § 2a): the template's own
+ * address (`unoverse://templates/<org>/<name>`, what draws it) names the task
+ * `unoverse://tasks/<org>/<name>`, which is what starts it (`metadata.task`) and what its progress
+ * is published under (`tasks.<uri>`). The shared parser, bundled, so the page and the platform
+ * read a task's name one way.
+ */
+const taskOf = (uri: string): string => {
+  const short = uri.replace(/^unoverse:\/\/templates\//, "");
+  return taskUri(short) ?? taskUriOf(null, short) ?? uri;
+};
 
 /** THE AVATARS: page templates whose steps are the call's phases (`listening`, `speaking`).
  *  They are how the page is spoken to, so they are never the task in view; they follow the call. */
@@ -67,7 +93,7 @@ const avatars = new Set<HTMLElement>();
 const CALL_PHASES = ["listening", "speaking"];
 
 /** The workflow a template names in its manifest (UNOVERSE_HOST_PAGE.md rule 4). */
-export type Binding = { workflow?: string; trigger?: string; pipeline?: string };
+export type Binding = { workflow?: string; trigger?: string; pipeline?: string; autoTrigger?: boolean };
 
 /** THE TASK IN VIEW: the marked template, not an avatar, spanning the middle of the screen. */
 function taskInView(doc: Document): HTMLElement | null {
@@ -121,6 +147,8 @@ interface PageTemplateOptions {
   waiting: () => boolean;
   onBinding: (uri: string, binding: Binding) => void;
   onCall: ActionHandler;
+  /** Run the task this template carries (its lifecycle hook) as the viewer; its fields come back. */
+  runTask: (uri: string, phase: "onStart", input?: Record<string, unknown>) => Promise<Record<string, unknown>>;
 }
 
 /** One marked template: read it, give it its parts, draw it. */
@@ -132,6 +160,12 @@ function mountPageTemplate(o: PageTemplateOptions): { refresh(): void; destroy()
   let def: { stateTree?: StateTree } | null = null;
   let comp: ComponentMount | null = null;
   let alive = true;
+  // THE TASK IT CARRIES, ASKED AT ONCE (docs/design/lifecycle-hooks.md): in parallel with reading
+  // the template, not after it. A template without an `onStart` hook answers `{}` and is ignored.
+  const early = o.runTask(uri, "onStart", inputOf(el)).catch((e) => {
+    console.warn(`[unoverse] page template "${uri}" task failed:`, e);
+    return {} as Record<string, unknown>;
+  });
 
   // Where the template draws: its element, or the dock while a fullscreen template holds one
   // and this template is an avatar.
@@ -142,10 +176,14 @@ function mountPageTemplate(o: PageTemplateOptions): { refresh(): void; destroy()
   };
 
   const ready = () => {
-    comp = mountComponent({ client, store, chatId: CHAT, nodeId: TEMPLATE_NODE, onAction: o.onCall, place: () => [dock.slot], appStore, doc: el.ownerDocument, arrowKeys: false });
-    place();
-    stops.push(dock.watch(place), store.subscribe(() => dock.check()));
-    dock.check();
+    // DRAWN WHEN ITS DATA IS IN: a template with a task shows nothing until the task answers, so
+    // its sample values (the preview a studio draws) never flash on a live page.
+    const show = () => {
+      comp = mountComponent({ client, store, chatId: CHAT, nodeId: TEMPLATE_NODE, onAction: o.onCall, place: () => [dock.slot], appStore, doc: el.ownerDocument, arrowKeys: false });
+      place();
+      stops.push(dock.watch(place), store.subscribe(() => dock.check()));
+      dock.check();
+    };
 
     // A TEMPLATE FOLLOWS ITS TASK. Whatever runs the task publishes where it is as
     // `tasks.<its URI>` in the app state (SIGNAL.md 6c): this template moves to that step, and its
@@ -161,6 +199,47 @@ function mountPageTemplate(o: PageTemplateOptions): { refresh(): void; destroy()
         for (const nodeId of parts.filter((id) => id.startsWith(`${part}~`))) store.mergeComponentState(CHAT, nodeId, values as Record<string, unknown>);
       }
     };
+    // A TASK'S VALUES THAT NAME NO PART are the template's own props (a list it holds, a line
+    // above it): they fill the template itself, as a part's fill its part.
+    const fillOwn = (byPart: Record<string, unknown>) => {
+      const own = Object.fromEntries(Object.entries(byPart).filter(([key]) => key !== "state" && !parts.some((id) => id.startsWith(`${key}~`))));
+      if (!Object.keys(own).length) return;
+      syncHeld({ ...((store.get(CHAT, TEMPLATE_NODE) ?? {}) as Record<string, unknown>), ...own });
+      store.mergeComponentState(CHAT, TEMPLATE_NODE, own);
+    };
+
+    // WHAT THE TEMPLATE HOLDS (docs/design/templates.md "Holding a component"): one instance of
+    // the held component per item of the template's own data, keyed as the server keys it in an
+    // app (server runtime/screen/held.ts) and as `heldPointer` looks it up, so each card draws in
+    // its spot and keeps its own state. Re-sent only when an item changes. MADE BEFORE the data
+    // that names them reaches the template: a spot looks for its instance as it draws, once.
+    const heldSpecs = Object.values(((def as { held?: Record<string, { component: string; items: string[] }[]> } | null)?.held) ?? {}).flat();
+    const lastHeld = new Map<string, string>();
+    const syncHeld = (data: Record<string, unknown>) => {
+      if (!heldSpecs.length) return;
+      for (const spec of heldSpecs) {
+        if (!(spec.items[0] in data)) continue;
+        let level: unknown[] = [data];
+        for (const field of spec.items)
+          level = level.flatMap((o) => {
+            const list = o && typeof o === "object" ? (o as Record<string, unknown>)[field] : undefined;
+            return Array.isArray(list) ? list : [];
+          });
+        level.forEach((item, index) => {
+          if (!item || typeof item !== "object" || Array.isArray(item)) return;
+          const row = item as Record<string, unknown>;
+          const id = row.universal_id ?? row.ref ?? row.id;
+          const key = typeof id === "string" || typeof id === "number" ? String(id) : String(index);
+          const nodeId = `${TEMPLATE_NODE}:${spec.component}:${key}`;
+          const next = JSON.stringify(row);
+          if (lastHeld.get(nodeId) === next) return;
+          lastHeld.set(nodeId, next);
+          if (!store.getType(CHAT, nodeId)) store.apply({ type: "COMPONENT_INIT", chatId: CHAT, nodeId, component: { type: spec.component, props: row } });
+          else store.apply({ type: "COMPONENT_DATA", chatId: CHAT, nodeId, data: row });
+        });
+      }
+    };
+    syncHeld((store.get(CHAT, TEMPLATE_NODE) ?? {}) as Record<string, unknown>);
     const moveTo = (at: unknown) => {
       if (typeof at !== "string") return;
       const tree = def?.stateTree?.find((t) => t.on && t.states?.some((x) => x.name === at));
@@ -169,12 +248,13 @@ function mountPageTemplate(o: PageTemplateOptions): { refresh(): void; destroy()
       if (tpl?.[tree.on] !== at) store.mergeComponentState(CHAT, TEMPLATE_NODE, { [tree.on]: at });
     };
     const follow = () => {
-      const task = ((appStore.getAppState().tasks ?? {}) as Record<string, { step?: string; props?: Record<string, unknown> }>)[uri];
+      const task = ((appStore.getAppState().tasks ?? {}) as Record<string, { step?: string; props?: Record<string, unknown> }>)[taskOf(uri)];
       if (task?.props && typeof task.props === "object") {
         const next = JSON.stringify(task.props);
         if (next !== lastProps) {
           lastProps = next;
           fillParts(task.props);
+          fillOwn(task.props);
         }
       }
       // A NEW STEP MOVES IT, once. A step the person took since (Enter) stands until the task
@@ -214,6 +294,18 @@ function mountPageTemplate(o: PageTemplateOptions): { refresh(): void; destroy()
     follow();
     stops.push(appStore.subscribe(follow));
 
+    // THE TASK IT CARRIES (docs/design/lifecycle-hooks.md): a template whose manifest has an
+    // `onStart` hook asks the server to run it as it loads, as the viewer, and fills its own
+    // fields with the answer, its held cards made first, as a workflow's fill does.
+    const hooks = (def as { lifecycle?: Array<{ phase?: string }> } | null)?.lifecycle ?? [];
+    if (hooks.some((h) => h.phase === "onStart"))
+      void early.then((fields) => {
+        if (!alive) return;
+        if (fields && Object.keys(fields).length) fillOwn(fields);
+        show();
+      });
+    else show();
+
     const doc = pageDocument();
     if (doc) {
       // THE ARROW KEYS STEP IT, on the PAGE (the keys are the page's), when its state says
@@ -336,6 +428,7 @@ export interface PageInterfacesOptions {
   appStore: ComponentStore;
   toServer: (t: string, data: Record<string, unknown>, meta?: ActionMeta) => void;
   startTask: (binding: Binding, task: string, submit?: Record<string, unknown>) => void;
+  runTask: (uri: string, phase: "onStart", input?: Record<string, unknown>) => Promise<Record<string, unknown>>;
 }
 
 /**
@@ -374,7 +467,7 @@ export function mountPageInterfaces(o: PageInterfacesOptions): { destroy(): void
     if (action === "submit" || action === "cancel") {
       o.toServer(action, data, meta);
       const state = (meta?.state ?? data) as Record<string, unknown> | undefined;
-      if (action === "submit" && (bindings[uri]?.workflow || bindings[uri]?.pipeline) && state && typeof state === "object") o.startTask(bindings[uri], uri, state);
+      if (action === "submit" && (bindings[uri]?.workflow || bindings[uri]?.pipeline) && state && typeof state === "object") o.startTask(bindings[uri], taskOf(uri), state);
     } else if (action === "startCall") {
       const t = target();
       if (!t || started.has(t)) return;
@@ -382,7 +475,7 @@ export function mountPageInterfaces(o: PageInterfacesOptions): { destroy(): void
       refreshAll();
       // The press is the click the browser needs before it plays a voice the workflow may have.
       o.voice.unlock();
-      o.startTask(bindings[t], t);
+      o.startTask(bindings[t], taskOf(t));
     } else if (action === "endCall") void o.voice.endCall();
     else if (action === "toggleMute") o.voice.toggleMute();
     // Another app on the page, opened or closed by its `<org>/<app>` (its own tag, EMBED_CLIENT.md).
@@ -425,9 +518,17 @@ export function mountPageInterfaces(o: PageInterfacesOptions): { destroy(): void
           onBinding: (u, b) => {
             if (bindings[u]) return;
             bindings[u] = b;
+            // A TASK THAT STARTS ITSELF (UNOVERSE_HOST_PAGE.md rule 4b): a binding that says
+            // `autoTrigger: true` starts its task once, as the page draws the template, the way
+            // an app's does on load. Nothing to press, and never twice on one page.
+            if (b.autoTrigger && !started.has(u)) {
+              started.add(u);
+              o.startTask(b, u);
+            }
             refreshAll();
           },
           onCall: onCallFor(uri),
+          runTask: o.runTask,
         }),
       );
     }