@unoverse-platform/studio 0.1.97 → 0.1.99

package/vendor/base/src/auth/auth.ts

@@ -41,11 +41,33 @@ const getIssuerCandidates = (): string[] => {
 };
 const getAudience = (): string | undefined => process.env.AUTH_AUDIENCE;
 
-let jwks: ReturnType<typeof createRemoteJWKSet> | null = null;
-function getJWKS() {
+// WHERE THE SIGNING KEYS ARE IS THE PROVIDER'S TO SAY, in its discovery document.
+//
+// This read `${issuer}/.well-known/jwks.json`, which is where Auth0 and Cognito happen to keep
+// them. Microsoft Entra keeps them under /discovery/v2.0/keys, Keycloak under
+// /protocol/openid-connect/certs, WorkOS AuthKit under /oauth2/jwks, so a bank's Entra or a
+// WorkOS login was refused on every request with a key that could not be found. OIDC
+// discovery names the place (`jwks_uri`). With no discovery document the old location is
+// used, and not remembered, so a transient failure is retried on the next request.
+type KeySet = ReturnType<typeof createRemoteJWKSet>;
+let jwks: Promise<KeySet> | null = null;
+async function loadJWKS(base: string): Promise<{ set: KeySet; discovered: boolean }> {
+  try {
+    const res = await fetch(`${base}/.well-known/openid-configuration`, { signal: AbortSignal.timeout(5000) });
+    const doc: any = res.ok ? await res.json() : null;
+    if (typeof doc?.jwks_uri === "string") return { set: createRemoteJWKSet(new URL(doc.jwks_uri)), discovered: true };
+  } catch {
+    // fall through to the conventional location
+  }
+  return { set: createRemoteJWKSet(new URL(`${base}/.well-known/jwks.json`)), discovered: false };
+}
+function getJWKS(): Promise<KeySet> | null {
   const base = getIssuerBase();
   if (!jwks && base) {
-    jwks = createRemoteJWKSet(new URL(`${base}/.well-known/jwks.json`));
+    jwks = loadJWKS(base).then(({ set, discovered }) => {
+      if (!discovered) jwks = null;
+      return set;
+    });
   }
   return jwks;
 }
@@ -69,6 +91,14 @@ function parseArrayClaim(payload: JWTPayload, claimName: string): string[] {
   return [];
 }
 
+/** Roles as a list. Most providers send a `roles` list (Auth0 namespaced, Entra app roles);
+ *  WorkOS sends one `role`, the role of the organization membership signed in with. */
+export function parseRoles(payload: JWTPayload): string[] {
+  const roles = parseArrayClaim(payload, "roles");
+  const one = payload.role;
+  return typeof one === "string" && one && !roles.includes(one) ? [...roles, one] : roles;
+}
+
 /** Parse a string claim, handling Auth0-style namespaced claims (e.g. https://…/email).
  *  Auth0 emits custom claims (email on the access token) ONLY namespaced, so a plain
  *  `payload.email` read returns undefined and silently no-ops every email-keyed feature
@@ -114,7 +144,7 @@ export async function validateJWT(token: string): Promise<AuthUser | null> {
 }
 
 async function verifyJWT(token: string): Promise<AuthUser | null> {
-  const jwksSet = getJWKS();
+  const jwksSet = await getJWKS();
   const issuers = getIssuerCandidates();
   if (!jwksSet || issuers.length === 0) {
     console.warn("[auth] OIDC not configured (AUTH_ISSUER missing)");
@@ -148,7 +178,7 @@ async function verifyJWT(token: string): Promise<AuthUser | null> {
     return {
       id: payload.sub || "unknown",
       email: parseStringClaim(payload, "email"),
-      roles: parseArrayClaim(payload, "roles"),
+      roles: parseRoles(payload),
       permissions: parseArrayClaim(payload, "permissions"),
       raw: payload,
     };

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

@@ -0,0 +1,37 @@
+/**
+ * AN ORG IS A WALL (docs/unoverse/UNOVERSE_ORGANISATION.md §11, part 1).
+ *
+ * Anything built from many orgs' definitions (an MCP session's tools, the spatial
+ * registry, the Studio lists) builds each item through here. One that throws is left
+ * out and named, `org/item: reason`, and every other org is still served. Observed live
+ * 2026-09-23: one org's stale template threw inside MCP session construction and every
+ * signed-in session, for every org, answered -32603.
+ *
+ * The one door, so no builder writes its own try and no builder forgets one.
+ */
+
+/** Name what was left out and why. The label is `org/item` (or `kind org/item`). */
+export function reportLeftOut(label: string, err: unknown): void {
+  const reason = err instanceof Error ? err.message : String(err);
+  console.warn(`[unoverse] left out ${label}: ${reason}`);
+}
+
+/** Build one item on its own. Undefined when it failed; the failure is reported. */
+export function isolated<T>(label: string, build: () => T): T | undefined {
+  try {
+    return build();
+  } catch (err) {
+    reportLeftOut(label, err);
+    return undefined;
+  }
+}
+
+/** The same, for a build that awaits. */
+export async function isolatedAsync<T>(label: string, build: () => Promise<T>): Promise<T | undefined> {
+  try {
+    return await build();
+  } catch (err) {
+    reportLeftOut(label, err);
+    return undefined;
+  }
+}

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 }));
+}