@unoverse-platform/studio 0.1.96 → 0.1.98

package/vendor/base/src/agent-mcp/types.ts

@@ -25,11 +25,12 @@
  *
  * THE ONE-WIRE-CALL RULE — where our code ends and native MCP begins. Everything here
  * is pure interpretation/routing and never touches the MCP wire, EXCEPT
- * `invokeComponentAppNative` — the single function that opens an MCP client and makes a
+ * `invokeTaskNative` — the single function that opens an MCP client and makes a
  * real `tools/call`. From that call onward it is all native MCP (the server renders +
- * elicits; the answers resolve the call). Node-MCP rows and path-A workflow apps route
- * in-process via the caller's `api.callService` because they have a node/workflow to run;
- * only path-B component apps (nothing local to call) ride the wire. Full map:
+ * elicits, or runs an Agent and holds until it completes; the answers resolve the call).
+ * Node-MCP rows route in-process via the caller's `api.callService` because they have a node
+ * to run; component apps and WORKFLOW TASKS (every task is a native MCP tool, 2026-09-06)
+ * ride the wire. Full map:
  * docs/MCP_COMPLETE_GUIDE.md → "where YOUR code ends and native MCP begins".
  */
 
@@ -54,7 +55,7 @@ export interface DiscoveredMCP {
   /**
    * PATH B (UNOVERSE_MCP_APP_PROTOCOL §0.1 / §4b): a self-contained component app —
    * an `app` URI but NO workflow. Holds the app-tool id the adapter hands to
-   * `invokeComponentAppNative` (the held native `/mcp` call) instead of firing
+   * `invokeTaskNative` (the held native `/mcp` call) instead of firing
    * `workflow@trigger`; `workflowId`/`nodeId` are empty. Undefined for node-MCP + path-A apps.
    */
   component?: string;
@@ -62,6 +63,33 @@ export interface DiscoveredMCP {
    *  schema handle. The tool's input schema is read LIVE from `<appUri>/schema` at mint
    *  time (`resolveToolDefNative`); spatial rows carry no schema copy. */
   appUri?: string;
+  /**
+   * A WORKFLOW TASK (2026-09-06): a task-augmented native tool on the platform's /mcp. The
+   * value is the tool's identity (`<org>/<name>`), spelled dotted on the wire. Calling it
+   * holds until the Agent's run completes and returns the terminal node's output.
+   */
+  taskTool?: string;
+  /**
+   * MINTED FROM A TASK ROW (object_type `task`): an outcome with a door, whichever door it
+   * has. The bridge reports a call to it as a `task` step, so the execution timeline draws
+   * it as a task and not as one more tool.
+   */
+  task?: true;
+}
+
+/**
+ * A FUNCTION THE ROWS OF A SEARCH RESULT OFFER (docs/unoverse/data/spatial/objects-in-spatial.md,
+ * "Found objects' functions as tools"): the engine names, once per NAME across the result, every
+ * public function the found rows' objects declare in api/service.yaml. The harness mints one tool
+ * per name, its input the function's own plus the row's universal_id, and a call runs that row's
+ * own object's function through the engine's one function door.
+ */
+export interface OfferedFunction {
+  name: string;
+  description: string;
+  input?: Record<string, unknown>;
+  /** The objects in the result that offer it, by title. */
+  objects: string[];
 }
 
 /** A neutral function-tool definition; each family maps this to its wire format. */
@@ -69,6 +97,8 @@ export interface AgentToolDef {
   name: string;
   description: string;
   parameters: Record<string, unknown>;
+  /** What the tool returns, from a component's `outputs` block (MCP `outputSchema`). */
+  outputSchema?: Record<string, unknown>;
 }
 
 /** Mint the model-facing tool definition for a discovered MCP. */
@@ -91,10 +121,17 @@ export interface AppInvocationContext {
   /** Deliver the component's SHELL only: render it in its declared state and return
    *  at once — never collect its outputs (§12e "Discovery delivers; it never invokes"). */
   shell?: boolean;
+  /** The row's relevance as the search scored it — the director's ordering. */
+  rank?: number;
   /** The delivery batch this render belongs to (UNOVERSE_TEMPLATE_MODEL §12e): the
    *  server's director judges the WHOLE batch before anything renders. `size` is how
    *  many siblings to wait for; `index` is this render's arrival position. */
   batch?: { id: string; size: number; index: number };
+  /**
+   * A WORKFLOW TASK's own arguments (2026-09-06), as the model wrote them against the task's
+   * input schema. Spread into the call beside the identity; the server shapes the run from them.
+   */
+  args?: Record<string, unknown>;
   /** Forwarded as a Bearer token so the internal `/mcp` call rides the gated lane too. */
   accessToken?: string;
   /** Internal MCP base; defaults to UNOVERSE_SERVICE_URL or http://localhost:4106. */
@@ -130,9 +167,9 @@ export interface RowComponent {
   component: string;
   /** The row's content AS-IS — the component's state (binds resolve by name). */
   props: Record<string, unknown>;
-  /** A SHELL delivery (TEMPLATE_MODEL §12e "One ladder, one delivery"): the row is a
-   *  component that takes input (a manifest, no workflow). It arrives in the same
-   *  delivery as the cards, in its declared state, with its own defaults and NO row
-   *  props; it is never invoked here — its form opens only on the model's call. */
-  shell?: boolean;
+  /** THE ROW'S RELEVANCE, as the search scored it (`similarity_score`, else `similarity`,
+   *  else `-distance`, read exactly as `routes/dictionary/search/ranking.ts` ranks). Carried
+   *  as a NUMBER because arrival position is not rank: renders dispatch in parallel. Rows
+   *  within one delivery come from one search call, so their numbers compare. */
+  rank?: number;
 }

package/vendor/base/src/definitions/load/compile/component.ts

@@ -28,6 +28,8 @@ export function compileComponentTree(def: UnoverseDefinition): void {
   const initial = typeof tree.initial === "string" ? tree.initial : names[0];
   def.publicStates = names;
   def.initialView = initial;
+  const statePlaces = placesOfStates(tree.states);
+  if (statePlaces) def.statePlaces = statePlaces;
   // The nested projection viewers render from (never scan layouts for it).
   def.stateTree = names.map((n) => {
     const s = (tree.states as Record<string, { layout?: unknown; on?: unknown; initial?: unknown; states?: Record<string, { layout?: unknown } | null> } | null>)[n];
@@ -35,6 +37,7 @@ export function compileComponentTree(def: UnoverseDefinition): void {
     if (s && typeof s === "object") {
       if (typeof s.layout === "string") entry.layout = s.layout;
       if (typeof s.on === "string") entry.on = s.on;
+      else if (s.states && typeof s.states === "object" && Object.keys(s.states).length) entry.on = STEP;
       if (typeof s.initial === "string") entry.initial = s.initial;
       if (s.states && typeof s.states === "object")
         entry.states = Object.entries(s.states).map(([k, v]) => ({
@@ -70,11 +73,63 @@ export function compileComponentTree(def: UnoverseDefinition): void {
   // READ where a def has not been swept, and lint-forbidden in rx.
   const flat: Record<string, unknown> = { ...authored, state: initial };
   delete (def as unknown as Record<string, unknown>).states; // the tree compiled; the raw block never rides the served def
-  for (const s of Object.values(tree.states))
-    if (s && typeof s === "object" && typeof s.on === "string") {
-      const subs = s.states && typeof s.states === "object" ? Object.keys(s.states) : [];
-      const step = typeof s.initial === "string" ? s.initial : subs[0];
+  const steps = new Set<string>();
+  for (const s of Object.values(tree.states)) {
+    if (!s || typeof s !== "object") continue;
+    const subs = s.states && typeof s.states === "object" ? Object.keys(s.states) : [];
+    const step = typeof s.initial === "string" ? s.initial : subs[0];
+    if (typeof s.on === "string") {
       if (step) flat[s.on] = step;
+    } else if (subs.length) {
+      // ONE WORD (UNOVERSE_STATE_MODEL §5, "One word: `state`"): a face's steps carry no second
+      // name. They start on the first declared and live in the hidden step value.
+      subs.forEach((n) => steps.add(n));
+      if (step && !(STEP in flat)) flat[STEP] = step;
     }
+  }
   def.state = flat;
+  if (steps.size) {
+    if (def.root) def.root = pointStepsAtStep(def.root, steps);
+    if (def.layouts) for (const n of Object.keys(def.layouts)) def.layouts[n] = pointStepsAtStep(def.layouts[n], steps);
+  }
+}
+
+/** The hidden value a face's steps live in. The author writes `state`; only the compiler says this. */
+export const STEP = "step";
+
+/**
+ * ONE WORD (UNOVERSE_STATE_MODEL §5): the author writes `state` for a face and for its steps alike.
+ * Wherever `state` names one of this component's STEPS, it means the step value: a `Switch on:
+ * state` whose cases are steps, a condition on `field: state` against steps, and a write of
+ * `key: state` to a step. Everything else about `state` (the face) is left untouched.
+ */
+export function pointStepsAtStep<T>(node: T, steps: Set<string>): T {
+  const isStep = (v: unknown): boolean => typeof v === "string" && steps.has(v);
+  const walk = (n: unknown): unknown => {
+    if (Array.isArray(n)) return n.map(walk);
+    if (!n || typeof n !== "object") return n;
+    const o: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(n as Record<string, unknown>)) o[k] = walk(v);
+    if (o.type === "Switch" && o.on === "state" && o.cases && typeof o.cases === "object") {
+      const keys = Object.keys(o.cases as object).filter((k) => k !== "default");
+      if (keys.length && keys.every(isStep)) o.on = STEP;
+    }
+    if (o.field === "state") {
+      const vals = [o.eq, o.ne, ...(Array.isArray(o.in) ? o.in : [])].filter((v) => v !== undefined);
+      if (vals.length && vals.every(isStep)) o.field = STEP;
+    }
+    if (o.key === "state" && isStep(o.value)) o.key = STEP;
+    return o;
+  };
+  return walk(node) as T;
+}
+
+/** The place each state names, or undefined when none names one (UNOVERSE_SCREEN.md §2.3). */
+export function placesOfStates(states: Record<string, unknown>): Record<string, string> | undefined {
+  const out: Record<string, string> = {};
+  for (const [name, s] of Object.entries(states)) {
+    const place = s && typeof s === "object" ? (s as { place?: unknown }).place : undefined;
+    if (typeof place === "string" && place) out[name] = place;
+  }
+  return Object.keys(out).length ? out : undefined;
 }

package/vendor/base/src/definitions/load/compile/sections.ts

@@ -80,6 +80,13 @@ export function expandTemplateSections(
           `template "${templateName}": an items place nests its search words INSIDE items: (each ITEM searches) — items: { min, max, type, include, pick }`,
         );
       const src = items ?? d;
+      // THE INCLUDE WORDS ARE CLOSED: products, images, needs. An unknown word used to
+      // pass through and match NOTHING at fill time (or everything, with no filter), which
+      // is a page drawn wrong with no error anywhere. `services` is retired (2026-09-07).
+      if (Array.isArray(src.include))
+        for (const w of src.include)
+          if (!["products", "images", "needs"].includes(String(w)))
+            throw new Error(`template "${templateName}": include: [${String(w)}] is not a kind a place can hold — the words are products, images, needs${String(w) === "services" ? " (services was renamed products, 2026-09-07)" : ""}`);
       out.push({
         kind: "director",
         face,
@@ -116,7 +123,6 @@ export function expandTemplateSections(
       face,
       ...(typeof d.state === "string" ? { state: d.state } : {}),
       ...(typeof d.pick === "number" ? { pick: d.pick } : {}),
-      ...(typeof d.rules === "string" ? { rules: d.rules } : {}),
       ...(Array.isArray(d.preview) ? { preview: d.preview.map(String) } : {}),
     });
     const { director: _d, ...rest } = n;

package/vendor/base/src/definitions/load/compile/template.ts

@@ -9,6 +9,7 @@ import type { UnoverseDefinition } from "../../model.js";
 import { loadDefinition } from "../load.js";
 import { composeIncludes } from "../expand/index.js";
 import { expandTemplateSections } from "./sections.js";
+import { placesOfStates } from "./component.js";
 
 /**
  * ONE PREVIEWED INSTANCE'S SEED — `preview ?? default` per prop, the same values the
@@ -108,19 +109,8 @@ export function synthesizeTemplateRoot(def: UnoverseDefinition, folderDir?: stri
   const layouts: Record<string, unknown> = {};
   const sections: NonNullable<UnoverseDefinition["sections"]> = {};
   const compiledPreview: Record<string, string[]> = {};
-  // THE LATCH IS A FACT ABOUT A STATE (MCP guide §The Component Latch). Collected on the
-  // same pass as the layouts and stamped as `def.latches`, because `states` is deleted
-  // below: a state that says nothing here can never be addressed, and an instance moving
-  // between states gains and loses the pill with no eviction and nothing to unregister.
-  const latches: NonNullable<UnoverseDefinition["latches"]> = {};
   for (const name of shapeNames) {
     const st = (states[name] ?? {}) as Record<string, unknown>;
-    const latch = st.latch as { title?: unknown; icon?: unknown } | undefined;
-    // TITLE OR NOTHING: the pill's whole content is the title, so a latch without one
-    // draws a nameless pill the guest cannot read. Declared but empty is an authoring
-    // slip, and taking it literally is what makes the slip visible.
-    if (latch && typeof latch === "object" && typeof latch.title === "string" && latch.title.trim())
-      latches[name] = { title: latch.title, ...(typeof latch.icon === "string" ? { icon: latch.icon } : {}) };
     if (typeof st.layout !== "string") continue;
     const secs: NonNullable<UnoverseDefinition["sections"]>[string] = [];
     layouts[name] = expandTemplateSections(composeIncludes({ $include: st.layout }, folderDir), name, def.name, secs);
@@ -143,11 +133,25 @@ export function synthesizeTemplateRoot(def: UnoverseDefinition, folderDir?: stri
   // same contract: states are the interface, the first declared one is arrival.
   def.publicStates = shapeNames;
   def.initialView = shapeNames[0];
-  if (Object.keys(latches).length) def.latches = latches;
+  const statePlaces = placesOfStates(states);
+  if (statePlaces) def.statePlaces = statePlaces;
   if (Object.keys(sections).length) def.sections = sections;
   if (Object.keys(compiledPreview).length) def.preview = { ...(def.preview ?? {}), ...compiledPreview };
   delete (def as unknown as Record<string, unknown>).states;
-  // The base arrangement, wrapped in a container so responsive columns can
-  // query their surface width in any host.
-  def.root = { type: "Box", style: { width: "full", container: "inline-size" }, children: [layouts[shapeNames[0]]] };
+  // THE TREE IS THE MACHINE, for templates too (ruled 2026-09-06, §5d). A template that
+  // STREAMS IN is an INSTANCE that draws itself, and the renderer draws `root`; served as
+  // the base layout alone, the instance's own face was read by nobody, so a task could
+  // never retract to its inline face (the ✕ wrote `inline` and the flow drew the whole
+  // page). A component's root is synthesized as a Switch on `state` over its declared
+  // layouts (load.ts, 2026-08-29); the same root here, one case per state, default = the
+  // base. `layouts` / `defaultLayout` are unchanged, so a MOUNT — which reads `layouts`
+  // by the faces of what it holds — is untouched. Wrapped in a container so responsive
+  // columns can query their surface width in any host.
+  const cases: Record<string, unknown> = { ...layouts };
+  if (!("default" in cases)) cases.default = layouts[shapeNames[0]];
+  def.root = {
+    type: "Box",
+    style: { width: "full", container: "inline-size" },
+    children: [shapeNames.length > 1 ? { type: "Switch", on: "state", cases } : layouts[shapeNames[0]]],
+  } as UnoverseDefinition["root"];
 }

package/vendor/base/src/definitions/load/expand/inherit.ts

@@ -110,7 +110,11 @@ export function inheritProps(
   // Day's moments the day `chapter` stopped restating the tile's contract: `required` was
   // still `["ref"]`, but `title` and `description` were back among the properties a model
   // could send, which is exactly the venue-renaming this flag exists to prevent.
-  const CONTRACT = ["type", "description", "maxLength", "minItems", "maxItems", "items", "hydrate", "optional", "override", "preview"] as const;
+  // `input` TRAVELS TOO (2026-09-15). An atom that marks a field `input: false` (the button's
+  // `icon` and `link`) says nobody outside fills it; without the word here the host inherited
+  // the field as fillable and the tool asked the model for it (SAB transfer: four fields it
+  // could not honestly write). Same failure as `override` above, one word later.
+  const CONTRACT = ["type", "description", "maxLength", "minItems", "maxItems", "items", "hydrate", "optional", "override", "preview", "input"] as const;
   // AN ATOM INSIDE AN `Each` DESCRIBES THE ITEM, not the page. The scope is the chain of
   // array props the Ref sits inside, so a `prose` atom drawn once per section lands on
   // `sections.items.body` — where a brief on its node used to land by being there.

package/vendor/base/src/definitions/load/expand/referenced.ts

@@ -11,6 +11,7 @@ import type { UnoverseDefinition } from "../../model.js";
 import { loadDefinition } from "../load.js";
 import { inheritState } from "./inherit.js";
 import type { AnyNode } from "./refs.js";
+import { composeRef, composesAxis } from "./walk.js";
 
 export function referencedDefinition(def: UnoverseDefinition, contextOrg?: string): UnoverseDefinition {
   const defs: Record<string, AnyNode> = {};
@@ -21,6 +22,22 @@ export function referencedDefinition(def: UnoverseDefinition, contextOrg?: strin
   const collect = (node: AnyNode | undefined): void => {
     if (!node || typeof node !== "object") return;
     if (Array.isArray(node)) return node.forEach(collect);
+    // A REF THAT CHOOSES A KIND IS COMPOSED HERE, NOT SHIPPED BY NAME. An org's component
+    // with a private axis (`sab/button`, `with: {kind: link}`) is specialised per use: the
+    // host picks the kind, the Ref's action/style land on the real node. Shipping its
+    // whole root once and letting the client resolve it drew the arrival kind with no
+    // words (the studio's comparison template, 2026-09-07). The composed node keeps its
+    // own inner atom references, which the client resolves from `defs` as ever.
+    if (node.type === "Ref" && typeof node.ref === "string" && composesAxis(node, contextOrg ?? def.org)) {
+      const composed = composeRef(node, contextOrg ?? def.org, "referenced");
+      if (composed) {
+        inheritState(inherit, composed.piece);
+        for (const [k, v] of Object.entries((composed.piece.defs ?? {}) as Record<string, AnyNode>)) if (!(k in defs)) defs[k] = v;
+        for (const k of Object.keys(node)) delete node[k];
+        Object.assign(node, composed.root);
+        return collect(node);
+      }
+    }
     if (node.type === "Ref" && typeof node.ref === "string") {
       const name = node.ref;
       if (!(name in defs)) {
@@ -30,8 +47,10 @@ export function referencedDefinition(def: UnoverseDefinition, contextOrg?: strin
         // EXPANDED instead was the difference between product-card costing 17 KB + 173 KB
         // and 17 KB + a handful: it references `document`, and an expanded document drags
         // in every copy this exists to remove.
-        const piece =
-          loadDefinition(name, "atom", "referenced") ?? loadDefinition(name, "component", "referenced", contextOrg ?? def.org);
+        // Qualified names are an org's piece, never a marketplace atom (see composeRef).
+        const piece = name.includes("/")
+          ? (loadDefinition(name, "component", "referenced", contextOrg ?? def.org) ?? loadDefinition(name, "atom", "referenced"))
+          : (loadDefinition(name, "atom", "referenced") ?? loadDefinition(name, "component", "referenced", contextOrg ?? def.org));
         if (piece?.root) {
           defs[name] = piece.root as AnyNode;
           // Same inheritance as the expanded form. The client resolves the Ref itself here,

package/vendor/base/src/definitions/load/expand/refs.ts

@@ -82,6 +82,20 @@ function applyStyleLiterals(style: unknown, lits: Record<string, unknown>): void
 }
 
 export function applyLiterals(node: AnyNode, lits: Record<string, unknown>): void {
+  // A NESTED REF FORWARDS THE LITERAL. A piece whose kind is itself a Ref to an atom
+  // (SAB's button: primary = the marketplace `button` atom with `props: {label: label}`)
+  // hands its host's literal on as that Ref's `with`, so the atom draws the words whether
+  // the tree is expanded here or resolved by name on the client (referenced form).
+  if (node.type === "Ref" && node.props && typeof node.props === "object") {
+    for (const k of Object.keys(node.props as AnyNode)) {
+      const field = (node.props as AnyNode)[k];
+      if (typeof field === "string" && field in lits) {
+        (node.with ??= {})[k] = lits[field];
+        delete (node.props as AnyNode)[k];
+      }
+    }
+    if (Object.keys(node.props as AnyNode).length === 0) delete node.props;
+  }
   if (node.bind) {
     for (const attr of Object.keys(node.bind)) {
       const field = node.bind[attr];

package/vendor/base/src/definitions/load/expand/walk.ts

@@ -13,44 +13,11 @@ import { inheritState, inheritProps, mergeInheritedProps } from "./inherit.js";
 
 export function expandNode(node: AnyNode, contextOrg?: string, inherit?: Record<string, unknown>, props?: Record<string, Record<string, unknown>>, scope: string[] = []): AnyNode {
   if (node?.type === "Ref") {
-    // A Ref inlines an ATOM (the usual case, rx/atoms). It also resolves a COMPONENT
-    // as a fallback, so a template can embed a shared flat component (e.g. the
-    // ComposerBar chrome) the same way it embeds an atom — the one mechanism for fixed,
-    // always-present chrome. (A component's root is inlined as-is; flat components only.)
-    // The parent definition's org rides along so a bare ref inside an org's own tree
-    // resolves to that org's component when two orgs share the name.
-    //
-    // AND A BLOCK (2026-08-31) — a flat TEMPLATE with no manifest: `pair`, `feature`,
-    // `single`, `rail`, `stack`. §2 always said "a rich template may compose basic ones
-    // inside itself", and this is that sentence, by the mechanism already here rather than
-    // a new one. Inlining is exactly right for it: the block's `director:` places arrive in
-    // the composing page's tree BEFORE its sections compile, so they become real slots and
-    // the page addresses them by position along with its own. Nothing is mounted, nothing
-    // is nested at runtime — the page ends up with the tree it would have had if someone
-    // had drawn the block by hand, which is the point.
-    //
-    // Last in the chain deliberately: atoms and components are the common case, and a
-    // template sharing a name with either keeps the old resolution.
-    const atom =
-      loadDefinition(String(node.ref), "atom") ??
-      loadDefinition(String(node.ref), "component", "expanded", contextOrg) ??
-      loadDefinition(String(node.ref), "template", "expanded", contextOrg);
-    if (!atom?.root) return node; // unknown ref — leave the Ref (renders as a no-op)
-    inheritState(inherit ?? {}, atom);
-    if (props) inheritProps(props, atom, (node.props ?? {}) as Record<string, string>, (node.with ?? {}) as Record<string, unknown>, scope);
-    const root = JSON.parse(JSON.stringify(atom.root)) as AnyNode;
-    remapFields(root, (node.props ?? {}) as Record<string, string>);
-    if (node.with && typeof node.with === "object") applyLiterals(root, node.with as Record<string, unknown>);
-    if (node.visibleWhen) root.visibleWhen = node.visibleWhen;
-    // A Ref may override the atom's `action` — the per-host behaviour the atom can't carry
-    // (e.g. each wizard step's option sets different fields). Parallel to style/visibleWhen.
-    if (node.action) root.action = node.action;
-    if (node.style) root.style = { ...(root.style ?? {}), ...node.style };
-    // THE BLOCK'S OPENING (2026-09-02, blocks returned): a Ref carrying `children:` fills
-    // the inlined root with the CALLER's children — a `band` or `two-column` block styles
-    // the frame, the composing layout says what sits inside. Same override family as
-    // style/action above; a Ref without children keeps the block's own (a complete block).
-    if (Array.isArray(node.children) && node.children.length) root.children = node.children;
+    const composed = composeRef(node, contextOrg, "expanded");
+    if (!composed) return node; // unknown ref — leave the Ref (renders as a no-op)
+    const { piece, root } = composed;
+    inheritState(inherit ?? {}, piece);
+    if (props) inheritProps(props, piece, (node.props ?? {}) as Record<string, string>, (node.with ?? {}) as Record<string, unknown>, scope);
     return expandNode(root, contextOrg, inherit, props, scope); // expand nested refs too
   }
   if (Array.isArray(node?.children)) node.children = node.children.map((c: AnyNode) => expandNode(c, contextOrg, inherit, props, scope));
@@ -75,6 +42,89 @@ export function expandNode(node: AnyNode, contextOrg?: string, inherit?: Record<
 }
 
 
+/**
+ * RESOLVE ONE REF INTO THE NODE IT COMPOSES — shared by the expanded form (which then
+ * recurses) and the referenced form (which keeps the inner atom references for the client).
+ *
+ * A Ref inlines an ATOM (the usual case, rx/atoms). It also resolves a COMPONENT as a
+ * fallback, so a template can embed a shared flat component (e.g. the ComposerBar chrome)
+ * the same way it embeds an atom — the one mechanism for fixed, always-present chrome.
+ * AND A BLOCK (2026-08-31) — a flat TEMPLATE with no manifest: `pair`, `feature`, `single`,
+ * `rail`, `stack`. Last in the chain deliberately: atoms and components are the common
+ * case, and a template sharing a name with either keeps the old resolution.
+ *
+ * AN ORG-QUALIFIED REF (`sab/button`) NAMES THAT ORG'S PIECE. Atoms are the marketplace's
+ * (no org), and the atom lookup strips the org from a qualified name — so `sab/button`
+ * silently resolved to the marketplace `button` atom and the org's own button component
+ * was never reached (2026-09-07). A bare name keeps the old order: atom first.
+ *
+ * AN EMBEDDED PIECE'S PRIVATE AXIS IS CHOSEN WHERE IT IS COMPOSED (2026-09-07, the SAB
+ * button: kinds primary/secondary/outline/link on a private `kind` axis). Its root is the
+ * compiled surface shell around the switches on that axis. Inlined, the piece has no slice
+ * of its own, so the host's `with` names the kind, and a host that names none gets the
+ * arrival kind (the first declared, def.state). Resolved HERE, statically, because the
+ * Ref's action/style/visibleWhen overrides must land on the real node, not on a Switch —
+ * and two buttons of different kinds in one host cannot share one runtime key.
+ */
+export function composeRef(node: AnyNode, contextOrg: string | undefined, mode: "expanded" | "referenced"): { piece: UnoverseDefinition; root: AnyNode } | null {
+  const ref = String(node.ref);
+  const qualified = ref.includes("/");
+  const piece = qualified
+    ? (loadDefinition(ref, "component", mode, contextOrg) ?? loadDefinition(ref, "template", mode, contextOrg) ?? loadDefinition(ref, "atom", mode))
+    : (loadDefinition(ref, "atom", mode) ?? loadDefinition(ref, "component", mode, contextOrg) ?? loadDefinition(ref, "template", mode, contextOrg));
+  if (!piece?.root) return null;
+  let root = JSON.parse(JSON.stringify(piece.root)) as AnyNode;
+  const lits = (node.with && typeof node.with === "object" ? node.with : {}) as Record<string, unknown>;
+  const axes = (piece.state ?? {}) as Record<string, unknown>;
+  const isAxisSwitch = (n: AnyNode | undefined): boolean => n?.type === "Switch" && typeof n.on === "string" && !!n.cases && (n.on in lits || n.on in axes);
+  const shared = (piece.defs ?? {}) as Record<string, AnyNode>;
+  for (let guard = 0; guard < 8; guard++) {
+    // The referenced form hoists a repeated subtree into a `shared:` chunk and leaves a
+    // parameterless reference to it (the kind switch sits under two cases, so it is one).
+    // Resolving the axis has to read through that reference.
+    if (root?.type === "Ref" && typeof root.ref === "string" && root.ref.startsWith("shared:") && shared[root.ref]) {
+      root = JSON.parse(JSON.stringify(shared[root.ref])) as AnyNode;
+      continue;
+    }
+    if (isAxisSwitch(root)) {
+      const pick = String(root.on in lits ? lits[root.on] : axes[root.on]);
+      const chosen = (root.cases as AnyNode)[pick] ?? (root.cases as AnyNode).default;
+      if (!chosen) break;
+      root = JSON.parse(JSON.stringify(chosen)) as AnyNode;
+      continue;
+    }
+    // The compiled SURFACE SHELL (a Box around the state switch) belongs to a piece standing
+    // on its own; a piece inlined into another is the node its kind resolves to.
+    if (root?.type === "Box" && Array.isArray(root.children) && root.children.length === 1 && isAxisSwitch(root.children[0] as AnyNode)) {
+      root = root.children[0] as AnyNode;
+      continue;
+    }
+    break;
+  }
+  remapFields(root, (node.props ?? {}) as Record<string, string>);
+  if (node.with && typeof node.with === "object") applyLiterals(root, node.with as Record<string, unknown>);
+  if (node.visibleWhen) root.visibleWhen = node.visibleWhen;
+  // A Ref may override the atom's `action` — the per-host behaviour the atom can't carry
+  // (e.g. each wizard step's option sets different fields). Parallel to style/visibleWhen.
+  if (node.action) root.action = node.action;
+  if (node.style) root.style = { ...(root.style ?? {}), ...node.style };
+  // THE BLOCK'S OPENING (2026-09-02, blocks returned): a Ref carrying `children:` fills
+  // the inlined root with the CALLER's children — a `band` or `two-column` block styles
+  // the frame, the composing layout says what sits inside. Same override family as
+  // style/action above; a Ref without children keeps the block's own (a complete block).
+  if (Array.isArray(node.children) && node.children.length) root.children = node.children;
+  return { piece, root };
+}
+
+/** Does this Ref compose a piece whose kind the host chooses (a component with a private
+ *  axis), rather than a shared atom the client can resolve by name? */
+export function composesAxis(node: AnyNode, contextOrg: string | undefined): boolean {
+  const ref = String(node.ref ?? "");
+  if (!ref.includes("/")) return false; // bare names are atoms first — the shared case
+  const piece = loadDefinition(ref, "component", "referenced", contextOrg) ?? loadDefinition(ref, "template", "referenced", contextOrg);
+  return !!piece?.root && Object.keys((piece.state ?? {}) as Record<string, unknown>).length > 0;
+}
+
 export function expandRefs(def: UnoverseDefinition, contextOrg?: string): UnoverseDefinition {
   // Whatever the tree embeds declares its own starting values; this is where they land on
   // the slice those inlined nodes actually read (see `inheritState`). Merged AFTER the

package/vendor/base/src/definitions/load/load.ts

@@ -82,7 +82,14 @@ export function loadDefinition(
         // expanding, because the parsed object is shared and expansion mutates in place.
         if (k === "atom") {
           const sig = `${path}:${statSync(path).mtimeMs};${dirSignature([SHARED_DIR.atom])}`;
-          return cachedBySignature(`def:atom:${lower}${suffix}`, sig, () => form(structuredClone(raw)));
+          // `type: atom` → `kind`, exactly as every other kind below. The 2026-08-30 refactor
+          // skipped it here, and from 2026-09-01 the atom resource refused a def with no
+          // `kind`, so every Studio atom preview said "Unknown Unoverse atom" (seen 2026-09-07).
+          return cachedBySignature(`def:atom:${lower}${suffix}`, sig, () => {
+            const d = structuredClone(raw) as UnoverseDefinition;
+            normalizeDeclaredKind(d);
+            return form(d);
+          });
         }
         const sig = `${path}:${statSync(path).mtimeMs};${dirSignature([SHARED_DIR.atom, SHARED_DIR.component])}`;
         // The org is stamped BEFORE form so expansion knows whose tree it is walking
@@ -181,11 +188,13 @@ export function loadDefinition(
             // nothing and the registry row is the whole opt-in (default OFF).
             def.spatial = true;
           }
-          // COMPONENT manifest (OPTIONAL — its PRESENCE means "spatial-capable"; a basic
-          // component has none and is never discovered). It is the single home for the
-          // discovery meta (description/whenToUse/title): merged over the def so every
-          // consumer (nodegen, workbench, catalog) reads one merged shape. `spatial: true`
-          // is the projected capability flag — derived from presence, never authored.
+          // COMPONENT manifest (OPTIONAL — its PRESENCE means "offerable to the map"; a basic
+          // component has none and is never a task). It is the single home for the discovery
+          // meta (description/whenToUse/title): merged over the def so every consumer reads
+          // one merged shape. `spatial: true` is the projected capability flag — derived from
+          // presence, never authored. The envelope's own `whenToUse` is palette text and
+          // does NOT make a component a task (observed 2026-09-06: every marketplace card
+          // listed in the Tasks lane).
           if (k === "component" && manifestPath) {
             const m = readDefCached<ComponentManifest>(manifestPath);
             keepComposition(def, m.description);
@@ -220,7 +229,7 @@ export function loadDefinition(
           // folders, exactly like `kind:`/`defaultState`.
           type AppStatesRecord = Record<
             string,
-            { layout?: unknown; preview?: unknown; latch?: unknown; states?: Record<string, unknown> } | null
+            { layout?: unknown; preview?: unknown; states?: Record<string, unknown> } | null
           >;
           const appStates: AppStatesRecord | undefined =
             k === "app"
@@ -240,11 +249,7 @@ export function loadDefinition(
           // Sources (`workflow`/`query`/`autoTrigger`) ride along as data until
           // per-container routing lands.
           if (k === "app" && manifestPath) {
-            const man = readDefCached<{ templates?: unknown; states?: Record<string, unknown> }>(manifestPath);
             const merged: Record<string, unknown> = {};
-            // The legacy container form (deal-workspace): a top-level `templates:` block.
-            if (man.templates && typeof man.templates === "object" && !Array.isArray(man.templates))
-              Object.assign(merged, man.templates as Record<string, unknown>);
             // A STATE ENTRY CARRIES ONLY WHAT SEEDS IT (owner ruling 2026-08-28
             // evening): its `preview`. What a place holds and the judgment granted to
             // it live on the PLACED NODE in the state's layout — projected below,
@@ -412,23 +417,6 @@ export function loadDefinition(
           //    by compilation. (Identified by structural equality: the composed
           //    states/<name> file IS the inlined node.)
           if (k === "app" && appStates) {
-            // THE LATCH IS A FACT ABOUT A STATE (MCP guide §The Component Latch, moved off
-            // the manifest 2026-08-31). Projected here for the same reason `preview` is:
-            // the raw states block never rides the served def, so anything a state declares
-            // has to become a projection or it is lost. `def.latches` is what the SDK's
-            // `resolveLatch` looks the wearer's face up in — a state that says nothing here
-            // can never be addressed, and an instance retracting out of an addressable
-            // state drops the pill with nothing to unregister.
-            const latches: NonNullable<UnoverseDefinition["latches"]> = {};
-            for (const [sname, sentry] of Object.entries(appStates)) {
-              const l = (sentry as { latch?: { title?: unknown; icon?: unknown } } | null)?.latch;
-              // TITLE OR NOTHING: the pill's whole content is its title, so a latch without
-              // one draws a nameless pill the guest cannot read. Taking a declared-but-empty
-              // block literally is what makes the authoring slip visible.
-              if (l && typeof l === "object" && typeof l.title === "string" && l.title.trim())
-                latches[sname] = { title: l.title, ...(typeof l.icon === "string" ? { icon: l.icon } : {}) };
-            }
-            if (Object.keys(latches).length) def.latches = latches;
             // The tree COMPILES into projections; the raw block never rides the
             // served def (stateTree is the viewers' shape).
             delete (def as unknown as Record<string, unknown>).states;
@@ -475,6 +463,10 @@ export function loadDefinition(
           //   - def.initialView  = the declared initial (the retract/fallback base)
           //   - def.state.view   → the scalar initial (the render scope reads a value)
           //   - a nested `on` + `initial` pair → its scalar initial (the substep key)
+          if (k === "app") {
+            const places = placesIn(def.layouts ?? { base: def.root });
+            if (places.length) def.places = places;
+          }
           if (k === "component") compileComponentTree(def);
           if (k === "template") synthesizeTemplateRoot(def, folderDir);
           return k === "atom" ? def : form(def);
@@ -485,3 +477,20 @@ export function loadDefinition(
   return null;
 }
 
+
+/** Every `Place` an app's layouts declare, first drawing first, each name once
+ *  (docs/unoverse/design/screen/UNOVERSE_SCREEN.md §2.2). */
+function placesIn(trees: Record<string, unknown>): { name: string; holds: "one" | "many" }[] {
+  const out = new Map<string, "one" | "many">();
+  const walk = (n: unknown): void => {
+    if (Array.isArray(n)) return n.forEach(walk);
+    if (!n || typeof n !== "object") return;
+    const node = n as Record<string, unknown>;
+    if (node.type === "Place" && typeof node.name === "string" && !out.has(node.name))
+      out.set(node.name, node.holds === "one" ? "one" : "many");
+    for (const key of ["children", "frame", "fallback", "item"]) walk(node[key]);
+    if (node.cases && typeof node.cases === "object") Object.values(node.cases).forEach(walk);
+  };
+  Object.values(trees).forEach(walk);
+  return [...out].map(([name, holds]) => ({ name, holds }));
+}