@unoverse-platform/studio 0.1.86 → 0.1.88

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/screens/TemplatesLibraryView.tsx

@@ -94,6 +94,7 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
   const [templates, setTemplates] = useState<TemplateDef[]>([]);
   const [selected, setSelected] = usePersistentState<string>("wb:template", "");
   const [panelOpen, setPanelOpen] = useState(true);
+  const [metaOpen, setMetaOpen] = usePersistentState<boolean>("wb:templates:meta", false); // manifest meta panel
   const [panelHeight, setPanelHeight] = useState(200);
   const [stageWidth, setStageWidth] = useState<number | null>(768);
 
@@ -247,6 +248,24 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
                 label="Available"
               />
             )}
+            {/* META — the same disclosure Components and Apps carry, on the same
+                mandatory manifest (§9c: a template is discovered like everything
+                else, so what it is DISCOVERED BY must be readable where it is
+                designed). Disclosure only; it changes nothing. */}
+            {current?.spatial && (
+              <button
+                onClick={() => setMetaOpen((o) => !o)}
+                className="flex items-center gap-1 rounded border px-2 py-0.5 text-[11px] font-medium"
+                style={{
+                  borderColor: theme.color["border.subtle"],
+                  color: metaOpen ? theme.color["text.primary"] : theme.color["text.secondary"],
+                  background: metaOpen ? theme.color["surface.sunken"] : "transparent",
+                }}
+                title="Show the template's manifest (spatial discovery meta)"
+              >
+                ⓘ Meta <span className="opacity-60">{metaOpen ? "▴" : "▾"}</span>
+              </button>
+            )}
             {shapeNames.length > 1 && (
               <div className="flex items-center gap-1 rounded p-0.5 text-[11px]" style={{ background: theme.color["border.subtle"] }}>
                 {shapeNames.map((name, i) => {
@@ -312,6 +331,42 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
             </span>
           </div>
 
+          {/* MANIFEST META — identical anatomy to the Components and Apps panels:
+              title / category chip / muted tag, description, when-to-use callout. */}
+          {metaOpen && current?.spatial && (() => {
+            const accent = theme.color["action.primary"] ?? "#6366f1";
+            return (
+              <div className="border-b px-5 py-4" style={{ borderColor: theme.color["border.subtle"], background: theme.color["surface.base"] }}>
+                <div className="mx-auto flex max-w-5xl flex-col gap-1">
+                  <div className="flex flex-wrap items-center gap-2">
+                    <h2 className="text-[17px] font-semibold leading-tight tracking-tight" style={{ color: theme.color["text.primary"] }}>
+                      {current.title || current.name}
+                    </h2>
+                    {current.category && (
+                      <span className="rounded-full px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide" style={{ background: `${accent}14`, color: accent }}>
+                        {current.category}
+                      </span>
+                    )}
+                    <span className="font-mono text-[10px]" style={{ color: theme.color["text.tertiary"] }}>
+                      manifest.json
+                    </span>
+                  </div>
+                  {current.description && (
+                    <p className="mt-1 max-w-3xl text-[13px] leading-relaxed" style={{ color: theme.color["text.secondary"] }}>{current.description}</p>
+                  )}
+                  {current.whenToUse && (
+                    <div className="mt-2 max-w-3xl rounded-r py-1.5 pl-3" style={{ borderLeft: `3px solid ${accent}`, background: theme.color["surface.sunken"] }}>
+                      <div className="mb-0.5 text-[10px] font-semibold uppercase tracking-wider" style={{ color: accent }}>
+                        When to use
+                      </div>
+                      <p className="text-[15px] font-medium leading-relaxed" style={{ color: theme.color["text.primary"] }}>{current.whenToUse}</p>
+                    </div>
+                  )}
+                </div>
+              </div>
+            );
+          })()}
+
           <div className="flex-1 overflow-auto p-10">
             <div className="mx-auto max-w-full transition-[width] duration-200" style={{ width: stageWidth ?? "100%" }}>
               {uri && <StreamedUnoverseApp key={uri} client={client} store={store} uri={uri} theme={theme} />}

package/vendor/sdk/lib/app.tsx

@@ -331,11 +331,11 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
    */
   const tstate = store.getAppState() as Record<string, unknown>;
   const dismissedRaw = tstate.latchDismissed;
-  const held = def ? resolveLatch(def, store, typeof dismissedRaw === "string" ? dismissedRaw : undefined) : null;
+  const held = def ? resolveLatch(def, store, ladder.view, typeof dismissedRaw === "string" ? dismissedRaw : undefined) : null;
   useEffect(() => {
     if (dismissedRaw === true) {
       // Resolve the bare flag against whoever holds it RIGHT NOW, then re-derive.
-      const current = def ? resolveLatch(def, store) : null;
+      const current = def ? resolveLatch(def, store, ladder.view) : null;
       store.mergeAppState({ latchDismissed: current ? current.key : "" });
       return;
     }
@@ -353,6 +353,7 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
     held?.key,
     held?.latch,
     dismissedRaw,
+    ladder.view,
     def,
     store,
     tstate.latched,

package/vendor/sdk/lib/connection.tsx

@@ -13,7 +13,7 @@
  */
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { emitAnalytics } from "./core/analytics";
-import { applyServerMessage, resolveLatch, type ComponentStore, type ServerMessage } from "./core";
+import { applyServerMessage, viewOf, type ComponentStore, type ServerMessage } from "./core";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 // Interpreter-based JSON-schema validator (no `new Function`). The SDK's default Ajv
@@ -344,58 +344,59 @@ export function useUnoverseConnection(
     (text: string) => {
       const message = text.trim();
       if (!message) return;
-      const turn = mintTurn(); // ONE turn id shared by the user message, the assistant response, and the run
-      store.addUserMessage(turn, message); // optimistic user turn
-      // Optimistically open the assistant turn too, so the avatar + thinking dots
-      // appear IMMEDIATELY on send instead of waiting for the backend's
-      // WORKFLOW_STARTED. startResponse is idempotent — the later WORKFLOW_STARTED
-      // (and the first COMPONENT_INIT) reuse this same turn (responseFor by chatId).
-      store.startResponse(turn);
       /**
        * THE LATCH RIDES THE ORDINARY SEND (docs/MCP_COMPLETE_GUIDE.md §The Component Latch).
        *
-       * Resolved HERE rather than in a host, because both hosts call this one function and
+       * Handled HERE rather than in a host, because both hosts call this one function and
        * two hosts each deciding "what happens on send" is how the composer regression
-       * happened. The user turn is still minted normally — the guest said something and it
-       * belongs in the timeline; the latch only tells the workflow WHERE the answer lands.
+       * happened.
        *
-       * `state` is the component's live slice, so the workflow is told what the page
-       * currently holds without a round trip, and it stays right after local `setValue`
-       * writes the server never saw. Sent as one `latch` object so an unlatched send is
-       * byte-for-byte what it was before.
+       * READ, NOT RE-DERIVED. `app.tsx` runs `resolveLatch` every render and publishes
+       * `latched`/`latchKey` into app state for the composer's pill; this reads that same
+       * published fact. Deriving it again here is what left the send inert for two weeks:
+       * `resolveLatch` needs the app DEFINITION and this file holds a raw MCP `Client` with
+       * no definition cache, so the second derivation could never see `def.latches` and
+       * silently answered "not latched" on every send.
        */
+      const app = store.getAppState() as Record<string, unknown>;
+      const held =
+        app.latched === true && typeof app.latchKey === "string" && app.latchKey ? store.split(app.latchKey) : null;
       /**
-       * UNFINISHED, and deliberately shipped inert rather than guessed at.
-       *
-       * `peekDefinition` is the SYNCHRONOUS cached read the send path needs (a send cannot
-       * await a resources/read), and it lives on `UnoverseClient` — the wrapper holding the
-       * definition cache, constructed in appEngine.tsx. THIS file holds a raw MCP `Client`
-       * (line 137), which has no cache and no such method, so the lookup finds nothing here.
+       * THE RUN REUSES THE LATCHED TURN; the guest's message does not.
        *
-       * Optional-called through a narrow type so the shape is honest: null is already a
-       * legitimate answer meaning "no opinion", `resolveLatch` is not called for it, and an
-       * unlatched send is byte-for-byte what it was before. The day this ref carries the
-       * wrapper, latching starts working with no change here.
+       * The user turn is minted normally either way — the guest said something and it
+       * belongs in the timeline where they said it. What the latch changes is where the
+       * ANSWER opens: `startResponse` and the trigger both take the held component's own
+       * chatId, so every render in that run keys `chatId:nodeId` to what is already on
+       * screen, and a repeated COMPONENT_INIT on a seen key is already a props merge
+       * (applyServerMessage). Hydrate in place, by construction, with no new return path.
        */
-      const cache = clientRef.current as unknown as
-        | { peekDefinition?: (uri: string) => Parameters<typeof resolveLatch>[0] }
-        | null;
-      const tmpl = store.getActiveApp().name;
-      const def = tmpl ? (cache?.peekDefinition?.(`unoverse://apps/${tmpl}/definition`) ?? null) : null;
-      const held = def ? resolveLatch(def, store) : null;
+      const turn = mintTurn();
+      store.addUserMessage(turn, message); // optimistic user turn
+      const run = held ? held.chatId : turn;
+      // Optimistically open the assistant turn too, so the avatar + thinking dots
+      // appear IMMEDIATELY on send instead of waiting for the backend's
+      // WORKFLOW_STARTED. startResponse is idempotent — the later WORKFLOW_STARTED
+      // (and the first COMPONENT_INIT) reuse this same turn (responseFor by chatId), and
+      // while latched that turn is the page's own, which is exactly the point.
+      store.startResponse(run);
       trigger(
         held
           ? {
               message,
+              // `state` is the component's live slice, so the workflow is told what the page
+              // currently holds without a round trip, and it stays right after local
+              // `setValue` writes the server never saw. Sent as one `latch` object so an
+              // unlatched send is byte-for-byte what it was before.
               latch: {
                 chatId: held.chatId,
                 nodeId: held.nodeId,
-                view: held.view,
+                view: viewOf(store.get(held.chatId, held.nodeId) as Record<string, unknown>) ?? "",
                 state: store.get(held.chatId, held.nodeId) ?? {},
               },
             }
           : { message },
-        turn,
+        run,
       );
     },
     [mintTurn, store, trigger],

package/vendor/sdk/lib/core/apps.ts

@@ -271,17 +271,25 @@ export function resolveActiveView(
  * conversation is currently ADDRESSED AT, or none.
  *
  * DERIVED, never stored, for the same reason `lifecycle` is (STATE_MODEL §3): nothing
- * registers a latch and nothing unregisters one. A component becomes latchable by carrying
- * `latch` on its slice (seeded from its manifest with the render); it stops holding the
- * latch when its slice evicts or leaves the surface. There is no set, no stack, and no
- * "latch this one too" — this function returns ONE holder or null, so two latches are not
- * a bug to prevent but a state that cannot be represented.
+ * registers a latch and nothing unregisters one. THE STATE IS WHAT IS LATCHABLE, not the
+ * component (moved off the manifest 2026-08-31): an instance holds the latch while it is
+ * wearing a state the app declared a `latch` on, and stops the moment it wears one that
+ * says nothing — retracted inline, superseded, evicted, all the same answer with no code.
+ * There is no set, no stack, and no "latch this one too" — this function returns ONE
+ * holder or null, so two latches are not a bug to prevent but a state that cannot be
+ * represented.
  *
- * SAME WALK AS `resolveActiveView`, deliberately: the ladder is the ladder. A latchable
- * slice must be sitting in one of the template's declared states to hold the latch, and
- * the highest-ranked one wins, ties going to the most recent write. So a page retracted to
- * `inline` (superseded by an arrival, released by `cancelBelow`, closed by the guest)
- * silently stops holding it rather than leaving a pill pointing at something off-surface.
+ * THE HOLDER MUST BE THE STATE ON SCREEN, which is why `active` is a required argument
+ * rather than something derived again here. Being ON the ladder is not enough: an app whose
+ * ladder is [page, perfect-day] shows `page` the moment a card arrives wearing that face,
+ * and the composed page — still live, still ranked, just not showing — went on holding the
+ * latch. The guest then reads a pill naming a page that is nowhere on screen and types into
+ * it (observed live 2026-08-31: three search cards took the surface and "Your Perfect Day"
+ * stayed up over them). A pill is a promise about what the words will reach.
+ *
+ * SAME WALK AS `resolveActiveView` otherwise: the highest-ranked wins, ties going to the
+ * most recent write. So a page retracted to `inline` (superseded by an arrival, released by
+ * `cancelBelow`, closed by the guest) silently stops holding it too.
  *
  * Returns the FULL key. `chatId` alone reaches the turn, not the component inside it: a
  * turn carrying two components would hydrate the wrong one.
@@ -289,15 +297,23 @@ export function resolveActiveView(
 export function resolveLatch(
   def: UnoverseDefinition | null | undefined,
   store: ComponentStore,
+  /** The state the app is ACTUALLY showing (`resolveActiveView().view`). Empty = nothing is
+   *  surfaced, so nothing can be addressed. */
+  active: string,
   dismissed?: string,
-): { key: string; chatId: string; nodeId: string; latch: Record<string, unknown>; view: string } | null {
+): { key: string; chatId: string; nodeId: string; latch: { title: string; icon?: string }; view: string } | null {
   const order = def?.stateOrder?.length ? def.stateOrder : undefined;
   if (!order) return null; // no ladder, no ranking — abstain rather than guess a holder
+  const latches = def?.latches;
+  if (!latches || !Object.keys(latches).length) return null; // no state is addressable here
+  // WHAT IS ON SCREEN, first: an addressable state that is not the active one is not being
+  // shown, and a pill over someone else's surface points at nothing the guest can see.
+  if (!active || !latches[active]) return null;
   // `key` is the component key this candidate came from, carried so the return can name the
   // FULL key (line 269) rather than re-deriving it from chatId, which reaches the turn and
   // not the component inside it.
   let best:
-    | { key: string; chatId: string; nodeId: string; latch: Record<string, unknown>; view: string; rank: number; at: number }
+    | { key: string; chatId: string; nodeId: string; latch: { title: string; icon?: string }; view: string; rank: number; at: number }
     | null = null;
   for (const turn of store.getResponses())
     for (const p of turn.components) {
@@ -308,15 +324,20 @@ export function resolveLatch(
       if (dismissed && dismissed === p) continue;
       const { chatId, nodeId } = store.split(p);
       const slice = store.get(chatId, nodeId) as Record<string, unknown>;
-      const latch = slice?.latch;
-      if (!latch || typeof latch !== "object") continue;
       const view = viewOf(slice);
       if (!view) continue;
       const rank = order.indexOf(view);
       if (rank < 0) continue; // not on the surface (inline/retracted): holds nothing
+      // THE STATE DECIDES, and it must be the state SHOWING. Same lookup for every instance,
+      // so nothing has to be told it is addressable and nothing has to be untold — the face
+      // it currently wears is the whole question, and a face that is not the active one is
+      // not on screen to be addressed.
+      if (view !== active) continue;
+      const latch = latches[view];
+      if (!latch) continue;
       const at = store.touchOf(p);
       if (!best || rank < best.rank || (rank === best.rank && at > best.at))
-        best = { key: p, chatId, nodeId, latch: latch as Record<string, unknown>, view, rank, at };
+        best = { key: p, chatId, nodeId, latch, view, rank, at };
     }
   return best ? { key: best.key, chatId: best.chatId, nodeId: best.nodeId, latch: best.latch, view: best.view } : null;
 }

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

@@ -208,6 +208,14 @@ export interface UnoverseDefinition {
    *  ladder and arrival-scan order, served from the manifest. First entry outranks
    *  all below it; no name is special. Absent → legacy v1 recency semantics. */
   stateOrder?: string[];
+  /** THE LATCH, PER STATE (docs/MCP_COMPLETE_GUIDE.md §The Component Latch, moved off the
+   *  manifest 2026-08-31): the states whose wearer the conversation may be ADDRESSED AT,
+   *  keyed by state name, compiled from each state's own `latch:` block.
+   *
+   *  A state absent from this map can never hold the latch, so the SAME instance retracted
+   *  from its page state to an inline one drops the pill by construction. `resolveLatch`
+   *  reads this; nothing about the latch travels on the wire with a render. */
+  latches?: Record<string, { title: string; icon?: string }>;
 }
 
 // ---- The interaction vocabulary (UNOVERSE_SPEC.md §2e-3) ----