@unoverse-platform/studio 0.1.85 → 0.1.87

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

@@ -94,8 +94,15 @@ export class ComponentStore {
   //     ComponentSlot.select.where's "most recent state-write wins" ordering (§5b).
   //     Generic bookkeeping: core stamps WHEN a slice changed, never reads WHAT. ---
   private touches = new Map<string, number>();
-  /** The touch sequence at the guest's last send — the CURRENT DELIVERY's floor. */
+  /** The CURRENT DELIVERY's floor — advanced by the settle (applyDirectorVerdict)
+   *  and the confirmed-empty clear (spendDelivery), NEVER by the guest's send
+   *  (§12e ruling 2: the replacement is the boundary). */
   private deliveryWatermark = 0;
+  /** A judged DIRECTOR_VERDICT's held pointers for the current delivery (null = no
+   *  verdict — the mount holds the whole delivery). Generic bookkeeping: core stores
+   *  WHICH slices the sender's verdict held, never why (the judging happened
+   *  server-side; this only obeys, exactly like COMPONENTS_CLEAR). */
+  private directorHeld: Set<string> | null = null;
   /** Slices whose LATEST write was a guest interaction (`mergeComponentState`) — value is
    *  that write's touch seq. Powers `pinned` layouts: guest writes move them, arrivals don't. */
   private interactionTouches = new Map<string, number>();
@@ -129,12 +136,22 @@ export class ComponentStore {
    * the ONE home for the reset every boundary uses (new turn, guest close, template
    * swap) — never re-hardcode `"inline"` at a call site.
    */
+  /** THE FACE-WRITE KEY: the spelling this slice already speaks — `state` (the
+   *  ruled word, 2026-08-29), else the legacy alias it was seeded with. New
+   *  slices always land on `state`. */
+  private faceKey(slice: Record<string, unknown>): "state" | "view" | "defaultState" {
+    if ("state" in slice) return "state";
+    if ("view" in slice) return "view";
+    if ("defaultState" in slice) return "defaultState";
+    return "state";
+  }
+
   private retractSlice(key: string, slice: Record<string, unknown>): boolean {
-    const current = (slice.view ?? slice.defaultState) as unknown;
+    const current = (slice.state ?? slice.view ?? slice.defaultState) as unknown;
     const base = typeof slice.initialView === "string" ? slice.initialView : "inline";
     if (typeof current !== "string" || current === base) return false;
     const next: Record<string, unknown> = { ...slice };
-    if ("view" in next || !("defaultState" in next)) next.view = base;
+    next[this.faceKey(next)] = base;
     if ("defaultState" in next) next.defaultState = base;
     this.data.set(key, next);
     this.touches.set(key, ++this.touchSeq);
@@ -210,10 +227,10 @@ export class ComponentStore {
     for (const [key, slice] of this.data) {
       if (arrivingChatId && key.startsWith(`${arrivingChatId}:`)) continue;
       if (slice.lifetime === "conversation") continue;
-      const v = (slice.view ?? slice.defaultState) as unknown;
+      const v = (slice.state ?? slice.view ?? slice.defaultState) as unknown;
       if (typeof v !== "string" || !v || v === "inline") continue;
       const next: Record<string, unknown> = { ...slice };
-      if ("view" in next || !("defaultState" in next)) next.view = "inline";
+      next[this.faceKey(next)] = "inline";
       if ("defaultState" in next) next.defaultState = "inline";
       this.data.set(key, next);
       this.touches.set(key, ++this.touchSeq);
@@ -227,11 +244,17 @@ export class ComponentStore {
     let changed = false;
     for (const [key, slice] of this.data) {
       if (key.startsWith(`${arrivingChatId}:`)) continue; // same turn = same delivery
+      // A DIRECTOR-HELD slice is under the director's authority (§12e): its
+      // replacement belongs to the settle, never to the mechanical refresh — a
+      // new batch's first card must not retract the held shelf mid-search (the
+      // between-turns flicker, observed live after the durable shield retired).
+      // Un-directed apps are untouched: no verdict, no hold, rule 5 as ever.
+      if (this.directorHeld?.has(key)) continue;
       if (slice.lifetime === "conversation") continue;
-      const v = (slice.view ?? slice.defaultState) as unknown;
+      const v = (slice.state ?? slice.view ?? slice.defaultState) as unknown;
       if (v !== view) continue;
       const next: Record<string, unknown> = { ...slice };
-      if ("view" in next || !("defaultState" in next)) next.view = "inline";
+      next[this.faceKey(next)] = "inline";
       if ("defaultState" in next) next.defaultState = "inline";
       this.data.set(key, next);
       this.touches.set(key, ++this.touchSeq);
@@ -257,8 +280,8 @@ export class ComponentStore {
     let changed = false;
     for (const [key, slice] of this.data) {
       if (slice.lifetime === "conversation") continue;
-      if (!below.has((slice.view ?? slice.defaultState) as string)) continue;
-      this.data.set(key, { ...slice, ...("defaultState" in slice ? { defaultState: "inline" } : { view: "inline" }) });
+      if (!below.has((slice.state ?? slice.view ?? slice.defaultState) as string)) continue;
+      this.data.set(key, { ...slice, [this.faceKey(slice)]: "inline", ...("defaultState" in slice ? { defaultState: "inline" } : {}) });
       this.touches.set(key, ++this.touchSeq);
       changed = true;
     }
@@ -331,6 +354,24 @@ export class ComponentStore {
     this.bump();
   }
 
+  /**
+   * THE GUEST'S HAND OUTRANKS AN ARRIVAL'S RE-FACE (STATE_MODEL guest-control law,
+   * TEMPLATE_MODEL §6b rule 3: the director — and its deliveries — sit UNDER the
+   * guest's hand). Once the slice's LATEST write is the guest's own (an open Detail
+   * View), an inbound payload keeps its content but loses its face words: a
+   * re-delivered card must refresh WHAT the guest is reading, never yank them out
+   * of it (observed live 2026-08-29: a broad follow-up re-served the open card,
+   * its seeded `view: "grid"` overwrote the guest's `page`, the ladder fell to
+   * grid). The guest releases the face themselves (✕); from then on the server
+   * writes it again as ever.
+   */
+  private shieldGuestFace(key: string, payload: Record<string, unknown>): Record<string, unknown> {
+    if (!("state" in payload) && !("view" in payload) && !("defaultState" in payload)) return payload;
+    if ((this.interactionTouches.get(key) ?? -1) < (this.touches.get(key) ?? 0)) return payload;
+    const { state: _s, view: _v, defaultState: _d, ...content } = payload;
+    return content;
+  }
+
   /** Apply a streamed event (COMPONENT_INIT or COMPONENT_DATA). */
   apply(event: UnoverseEvent): void {
     const key = `${event.chatId}:${event.nodeId}`;
@@ -338,10 +379,10 @@ export class ComponentStore {
       this.types.set(key, event.component.type);
       if (event.component.componentUrl) this.urls.set(key, event.component.componentUrl);
       this.placeInTimeline(event.chatId, key); // structure: place the pointer ONCE
-      this.merge(key, event.component.props ?? {}); // data: seed
+      this.merge(key, this.shieldGuestFace(key, event.component.props ?? {})); // data: seed
       // Rule 5 — an arrival carrying a public state refreshes that state.
       const seeded = event.component.props as Record<string, unknown> | undefined;
-      this.supersede(event.chatId, seeded?.view ?? seeded?.defaultState);
+      this.supersede(event.chatId, seeded?.state ?? seeded?.view ?? seeded?.defaultState);
     } else {
       // NEW ACTIVITY reads newest-at-the-bottom: if this component is no longer the
       // LAST pointer in its turn (something was placed after it), fresh server data
@@ -354,10 +395,10 @@ export class ComponentStore {
         resp.components.push(key);
         this.bump();
       }
-      this.merge(key, event.data);
+      this.merge(key, this.shieldGuestFace(key, event.data));
       // Rule 5 — a server data-write that PLACES a component into a public state
       // (the host's arrival placement rides COMPONENT_DATA) refreshes that state.
-      this.supersede(event.chatId, (event.data as Record<string, unknown> | undefined)?.view ?? (event.data as Record<string, unknown> | undefined)?.defaultState);
+      this.supersede(event.chatId, (event.data as Record<string, unknown> | undefined)?.state ?? (event.data as Record<string, unknown> | undefined)?.view ?? (event.data as Record<string, unknown> | undefined)?.defaultState);
     }
   }
 
@@ -370,9 +411,11 @@ export class ComponentStore {
    *  guest's next message; a stale rail is cleared by the cards that replace it,
    *  never by the message that asked for them. */
   addUserMessage(chatId: string, text: string): void {
-    // The guest's send is the delivery boundary (hold: latest, basic form): every
-    // pointer not server-touched after this moment leaves the current set.
-    this.deliveryWatermark = this.touchSeq;
+    // RULE 7 RESTORED (UNOVERSE_TEMPLATE_MODEL §12e ruling 2): typing changes
+    // NOTHING. The delivery boundary is the REPLACEMENT — the judged batch's
+    // settle (applyDirectorVerdict) or the confirmed-empty clear (spendDelivery)
+    // — never the message that asked for it. The held set stays on screen
+    // through the whole search.
     this.timeline.push({ role: "user", id: `u${this.seq++}`, chatId, text, createdAt: Date.now() });
     this.evict();
     this.bump();
@@ -564,11 +607,10 @@ export class ComponentStore {
   getTimeline(): readonly Turn[] {
     return this.timeline;
   }
-  /** THE CURRENT DELIVERY (hold: latest, basic form — UNOVERSE_TEMPLATE_MODEL §9b):
-   *  the pointers placed since the guest's LAST SEND. A mounted template holds only
-   *  these, so the guest's own send clears the set — nothing stale ever survives a
-   *  turn, and the disappearance happens at the guest's action, never a background
-   *  delivery's. */
+  /** THE CURRENT DELIVERY (hold: latest — UNOVERSE_TEMPLATE_MODEL §9b, boundary per
+   *  §12e): the pointers placed since the last SETTLE or CLEAR. A mounted template
+   *  holds only these; the set survives the guest's next send and is spent exactly
+   *  when its replacement arrives (or emptiness is confirmed) — never sooner. */
   currentDeliveryPointers(): Set<string> {
     // TOUCH-BASED, not turn-based: durable-keyed instances (conversation-chatId
     // renders) file into ONE assistant turn across the whole conversation, so turn
@@ -581,6 +623,47 @@ export class ComponentStore {
         if ((this.touches.get(p) ?? 0) > this.deliveryWatermark) out.add(p);
     return out;
   }
+  /** THE DIRECTOR'S HOLD (UNOVERSE_TEMPLATE_MODEL §7): the verdict's pointers that are
+   *  still in the given delivery. null = no verdict, or nothing it held survives — the
+   *  caller falls back to the whole delivery (fail open, §6c rule 9: the screen never
+   *  pays for a stale or broken verdict). */
+  directorScope(delivery: Set<string>): Set<string> | null {
+    if (!this.directorHeld) return null;
+    const out = new Set<string>();
+    for (const p of this.directorHeld) if (delivery.has(p)) out.add(p);
+    return out.size ? out : null;
+  }
+  /** Apply a judged DIRECTOR_VERDICT: these instances are the delivery's held set, in
+   *  this order. Each item carries the chatId it was DELIVERED under (the turn's, or
+   *  the conversation's for durable renders) so the pointer is exact. ORDER IS RECENCY
+   *  — the strongest is re-stamped LAST so the existing touch-desc sort draws it
+   *  first: the platform's one ordering word, no new machinery. Only slices that
+   *  exist are stamped; unknown ids are ignored (selection only — a verdict can
+   *  never invent an instance). */
+  applyDirectorVerdict(items: Array<{ chatId: string; nodeId: string }>): void {
+    // THE SETTLE IS THE DELIVERY BOUNDARY (§12e ruling 2): spend everything
+    // older, then stamp the held set above the new line — one atomic replace,
+    // so the previous cards survive the whole search and leave exactly when
+    // their replacement arrives.
+    this.deliveryWatermark = this.touchSeq;
+    const held = new Set<string>();
+    for (let i = items.length - 1; i >= 0; i--) {
+      const p = `${items[i].chatId}:${items[i].nodeId}`;
+      if (!this.data.has(p)) continue;
+      held.add(p);
+      this.touches.set(p, ++this.touchSeq);
+    }
+    this.directorHeld = held.size ? held : null;
+    this.bump();
+  }
+  /** The confirmed-empty boundary (COMPONENTS_CLEAR): the run delivered nothing,
+   *  so the current set is spent with nothing replacing it — the mount collapses.
+   *  Same spend as the settle, without a new held set. */
+  spendDelivery(): void {
+    this.deliveryWatermark = this.touchSeq;
+    this.directorHeld = null;
+    this.bump();
+  }
   /** Just the assistant responses, in order. */
   getResponses(): AssistantTurn[] {
     return this.timeline.filter((t): t is AssistantTurn => t.role === "assistant");

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) ----

package/vendor/sdk/lib/transition/MountArrangement.tsx

@@ -0,0 +1,71 @@
+/**
+ * The double-buffered mount (UNOVERSE_TEMPLATE_MODEL §13.3): renders its LAST
+ * COMMITTED arrangement and commits the next one only when the decision allows —
+ * so a data ripple can never move the shelf, and the boundary commit is the one
+ * designed (and, with theme motion, animated) change. Content inside held
+ * instances stays live automatically: the render closure reads slices from the
+ * store at render time; only membership and order are buffered here.
+ *
+ * Fail open (§13.5): a "hold" with no boundary inside the grace window commits
+ * anyway — the screen never pays for machinery failure.
+ *
+ * RENDER-LAYER state, deliberately: the portable core stays frozen and "no UI
+ * state in the store" holds.
+ */
+
+import React, { useEffect, useRef, useState } from "react";
+import type { ReactNode } from "react";
+import { decideCommit, type Arrangement } from "./decide";
+import { commitArrangement } from "./viewTransition";
+
+/** A held-back change commits anyway after this long without a boundary. */
+const GRACE_MS = 4000;
+
+export function MountArrangement({
+  next,
+  directed,
+  motion,
+  render,
+}: {
+  /** The arrangement the store derives RIGHT NOW. */
+  next: Arrangement;
+  /** The placement grants a director — every delivery settles, so membership
+   *  waits for the settle (decide.ts). */
+  directed: boolean;
+  /** Theme-requested motion (§13.4) — absent theme word = instant commits. */
+  motion: boolean;
+  /** Build the tree for an arrangement; slices are read live inside. */
+  render: (arrangement: Arrangement) => ReactNode;
+}) {
+  const [committed, setCommitted] = useState<Arrangement | null>(null);
+  const graceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const decision = decideCommit(committed, next, directed);
+
+  useEffect(() => {
+    if (decision === "none") return;
+    if (decision === "hold") {
+      if (!graceTimer.current) {
+        graceTimer.current = setTimeout(() => {
+          graceTimer.current = null;
+          setCommitted(next);
+        }, GRACE_MS);
+      }
+      return;
+    }
+    if (graceTimer.current) {
+      clearTimeout(graceTimer.current);
+      graceTimer.current = null;
+    }
+    if (decision === "transition") commitArrangement(() => setCommitted(next), motion);
+    else setCommitted(next);
+  });
+
+  useEffect(
+    () => () => {
+      if (graceTimer.current) clearTimeout(graceTimer.current);
+    },
+    [],
+  );
+
+  return <>{render(committed ?? next)}</>;
+}

package/vendor/sdk/lib/transition/decide.ts

@@ -0,0 +1,53 @@
+/**
+ * The commit decision — the Transition Model's pure heart (UNOVERSE_TEMPLATE_MODEL §13).
+ *
+ * The mount double-buffers its arrangement and asks ONE question per render:
+ * may the committed arrangement change now? The answer depends only on the two
+ * arrangements — no store, no DOM, no time — so the contract is a pure function
+ * under conformance tests and can never regress silently.
+ *
+ * - "immediate":   commit with no ceremony (first paint; the guest's own
+ *                  navigation changed the layout; an un-directed mount — no
+ *                  verdict governs it, so its behaviour is exactly pre-contract).
+ * - "transition":  a BOUNDARY happened — the governing verdict changed (settle
+ *                  or clear) — commit as the one designed, animatable change.
+ * - "hold":        membership moved with no boundary (a data ripple). The shelf
+ *                  does not move. The caller owns the fail-open grace (§13.5).
+ * - "none":        nothing changed.
+ */
+
+export interface Arrangement {
+  /** The template's active layout (shape) name. */
+  layoutName: string | null;
+  /** Held pointers, in display order. */
+  held: string[];
+  /** Identity of the governing verdict (sorted held-pointer join), null when no
+   *  verdict governs — the un-directed mount. */
+  verdictSig: string | null;
+}
+
+export type CommitDecision = "immediate" | "transition" | "hold" | "none";
+
+const sameHeld = (a: string[], b: string[]) => a.length === b.length && a.every((p, i) => p === b[i]);
+
+/**
+ * `directed` = the placement grants a director, so every delivery WILL settle.
+ * A directed mount's membership therefore moves only at the settle — including
+ * the very first batch, whose cards arrive as separate messages before any
+ * verdict exists (committing each arrival painted the shelf in six pops, the
+ * first-appearance flicker observed live). Un-directed mounts keep committing
+ * immediately: no settle is ever coming for them.
+ */
+export function decideCommit(committed: Arrangement | null, next: Arrangement, directed: boolean): CommitDecision {
+  if (!committed) return "immediate";
+  // The guest's own navigation (name-sync layout change) is never held back.
+  if (next.layoutName !== committed.layoutName) return "immediate";
+  if (sameHeld(next.held, committed.held)) return "none";
+  // Membership moved. A changed governing verdict IS the boundary (settle/clear).
+  if (next.verdictSig !== committed.verdictSig) return "transition";
+  // Directed: the settle is coming — hold until it lands (grace fails open).
+  if (directed) return "hold";
+  // No verdict governs an un-directed mount: commit as it always did.
+  if (next.verdictSig === null) return "immediate";
+  return "hold";
+}

package/vendor/sdk/lib/transition/guestHold.ts

@@ -0,0 +1,34 @@
+/**
+ * THE GUEST'S HAND OUTRANKS THE DIRECTOR (UNOVERSE_TEMPLATE_MODEL §6b rule 3,
+ * state priority): a pointer whose LATEST write is the guest's own interaction,
+ * holding a non-base face the mount claims (an open Detail View), stays in the
+ * mount's scope regardless of deliveries and settles. Observed live without
+ * this: a new batch settled and yanked the guest out of an open detail page.
+ *
+ * The hold releases exactly as the model says: the guest's ✕ writes the face
+ * back to the base — no longer a non-base guest hold — and the current
+ * arrangement takes over. A re-delivered instance is an ARRIVAL (its merge
+ * out-touches the guest write) and may be re-faced, per §4 level 2.
+ *
+ * Pure over reads so the priority law is conformance-testable.
+ */
+
+export interface GuestHoldReads {
+  touchOf(p: string): number;
+  interactionTouchOf(p: string): number;
+  viewOf(p: string): string | undefined;
+}
+
+export function guestHeldPointers(
+  pointers: readonly string[],
+  reads: GuestHoldReads,
+  claimedLayouts: readonly string[],
+  baseLayout: string | null,
+): string[] {
+  return pointers.filter((p) => {
+    const it = reads.interactionTouchOf(p);
+    if (!it || it < reads.touchOf(p)) return false; // latest write is not the guest's
+    const v = reads.viewOf(p);
+    return !!v && v !== baseLayout && claimedLayouts.includes(v);
+  });
+}

package/vendor/sdk/lib/transition/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The Transition Model (UNOVERSE_TEMPLATE_MODEL §13) — the render layer's
+ * designed way of moving interfaces in and out of a mounted template:
+ * `decide.ts` (the pure commit decision), `MountArrangement.tsx` (the
+ * double-buffer), `viewTransition.ts` (the theme-gated animated commit).
+ */
+export { decideCommit, type Arrangement, type CommitDecision } from "./decide";
+export { MountArrangement } from "./MountArrangement";
+export { commitArrangement } from "./viewTransition";

package/vendor/sdk/lib/transition/viewTransition.ts

@@ -0,0 +1,29 @@
+/**
+ * The commit IS the animation (UNOVERSE_TEMPLATE_MODEL §13.4): when the theme
+ * asks for motion, the boundary commit is wrapped in the browser's View
+ * Transitions API — the browser diffs old and new and animates; the THEME's CSS
+ * owns every duration and ease. The SDK contributes only this generic behaviour
+ * and NO styles. Engines without the API, and themes that author no motion, get
+ * the instant commit — today's behaviour, gracefully.
+ */
+
+import { flushSync } from "react-dom";
+
+type WithViewTransition = { startViewTransition?: (cb: () => void) => unknown };
+
+export function commitArrangement(commit: () => void, motion: boolean): void {
+  const doc = typeof document !== "undefined" ? (document as unknown as WithViewTransition) : undefined;
+  if (!motion || typeof doc?.startViewTransition !== "function") {
+    commit();
+    return;
+  }
+  // From a microtask, outside React's lifecycle, so flushSync is legal: the
+  // API snapshots, the commit flushes the new DOM, the browser animates.
+  queueMicrotask(() => {
+    try {
+      doc.startViewTransition!(() => flushSync(commit));
+    } catch {
+      commit(); // fail open — the change lands even if the ceremony breaks
+    }
+  });
+}

package/vendor/skills/unoverse-create/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: unoverse-create
-description: "Create or edit Unoverse platform artifacts: UI components (including briefed/AI-filled components), apps, atoms and styles (design/), brand and org packs (themes, tokens, rebranding, cloning a universe for a new client), agent skills and prompt blocks (prompts/), custom workflow nodes (nodes/), and workflows built live on the Canvas via the builder MCP. Use whenever the user wants to create, add, build, or modify a component, app, card, page, theme, brand, org pack, agent skill, prompt block, custom node, or workflow in an Unoverse project, even if they don't say 'Unoverse' (they'll describe UI like 'a card with a button and an image' or 'a page the AI fills in')."
+description: "Create or edit Unoverse platform artifacts: UI components (including briefed/AI-filled components), apps, templates (arrangements with open parts a delivery fills — shelf grids, emails, comparison pages), atoms and styles (design/), brand and org packs (themes, tokens, rebranding, cloning a universe for a new client), agent skills and prompt blocks (prompts/), custom workflow nodes (nodes/), and workflows built live on the Canvas via the builder MCP. Use whenever the user wants to create, add, build, or modify a component, app, card, page, theme, brand, org pack, agent skill, prompt block, custom node, or workflow in an Unoverse project, even if they don't say 'Unoverse' (they'll describe UI like 'a card with a button and an image' or 'a page the AI fills in')."
 ---
 
 # Creating Unoverse Artifacts
@@ -30,8 +30,10 @@ that is the workspace folder itself; in the platform monorepo it is `apps/unover
    ([components](https://github.com/unoverse-platform/marketplace/tree/main/definitions/components), [atoms](https://github.com/unoverse-platform/marketplace/tree/main/definitions/atoms), [styles](https://github.com/unoverse-platform/marketplace/tree/main/definitions/styles)).
    Study the closest exemplar there, then compose those atoms and reference those
    components; never hand-roll a shape the base already ships. Everything is plain
-   YAML files — no connection, no running platform needed. (In the platform monorepo
+   YAML files: no connection, no running platform needed. (In the platform monorepo
    the same material is on disk at `design/marketplace/`.)
+   [The design system](https://docs.unoverse.ai/design/design-system.md) is the guide to
+   what ships and how to use it.
 
 ## Step 1: Identify the artifact, read its playbook
 
@@ -42,6 +44,7 @@ anything**:
 |---|---|
 | A UI component or shared atom, incl. a page/card the AI fills with content (briefed) | `references/component.md` (§Briefs for AI-filled) |
 | An app (chat surface, wizard shell) | `references/app.md` |
+| A template: an arrangement with open parts a delivery fills (a shelf grid, an email, a comparison page) | `references/template.md` |
 | A style / theme / token change on ONE component | `references/component.md` §Tokens |
 | A brand: an org pack, a rebrand, a new client universe, cloning an org | `references/brand.md` |
 | An agent skill (behavior guide the AI follows) | `references/agent-skill.md` |
@@ -59,15 +62,18 @@ If it's ambiguous (e.g. "add a card that shows weather"), it's usually a **compo
 **New to design artifacts?** The guided learning journey at
 [docs.unoverse.ai/design](https://docs.unoverse.ai/design/overview.md)
 ([quick-start](https://docs.unoverse.ai/design/quick-start.md) →
+[essentials](https://docs.unoverse.ai/design/essentials.md) →
+[interface-data](https://docs.unoverse.ai/design/interface-data.md) →
 [components](https://docs.unoverse.ai/design/components.md) →
 [state](https://docs.unoverse.ai/design/state.md) →
+[templates](https://docs.unoverse.ai/design/templates.md) →
 [apps](https://docs.unoverse.ai/design/apps.md) →
 [styles-and-tokens](https://docs.unoverse.ai/design/styles-and-tokens.md) →
 [studio](https://docs.unoverse.ai/design/studio.md) →
 [validate-and-ship](https://docs.unoverse.ai/design/validate-and-ship.md) →
-[troubleshooting](https://docs.unoverse.ai/design/troubleshooting.md)) teaches
-components, apps, the state model (incl. locked voice/native state), tokens,
-Studio, and validation in order;
+[troubleshooting](https://docs.unoverse.ai/design/troubleshooting.md)) teaches the
+shared grammar every artifact uses, the four kinds, the state model (incl. locked
+voice/native state), tokens, **studio**, and validation in order;
 [design/CLAUDE.md](https://docs.unoverse.ai/design/CLAUDE.md) is the condensed agent
 rulebook. The playbooks here assume that material. Append `.md` to any docs URL to
 fetch it as raw markdown.

package/vendor/skills/unoverse-create/references/app.md

@@ -16,15 +16,16 @@ already in the workspace. (Monorepo: `design/sab/apps/sab-chat`.)
 A component is a state tree whose public states are its whole interface; an app
 declares its OWN state tree in the manifest and reacts to components by name:
 
-> A component enters a public view → the app asks "do I have a state with that
+> A component enters a public state → the app asks "do I have a state with that
 > name?" Match: the app enters that state and its layout draws. No match: the
 > component renders inline in the flow. Always.
 
 Derived off the store, never stored, no wiring. The component never knows apps
 exist, and post-spawn the app NEVER writes a component's state. Name-match is the
-default convention (`reactsTo:` on an app state is the rare escape hatch for
-vocabulary mismatches). **Rule of thumb: component causes it = a reaction state;
-app knows it = a base substate or app state.**
+ONLY mechanism: an app state reacts because its name matches, so give the app the
+name the component writes. (`reactsTo:` is DESIGN-ONLY: nothing in the runtime
+reads it, so never author it.) **Rule of thumb: component causes it = a reaction
+state; app knows it = a base substate or app state.**
 
 ## The manifest states tree: one declaration, everything follows
 
@@ -33,13 +34,21 @@ The canonical shape (a chat layout: a base arrangement plus a reaction ladder):
 ```yaml
 states:
   main:                 # the base arrangement, FIRST
+    layout: layouts/main
     states:
-      welcome: {}       # contained substate; first substate = the landing default
-  focus: {}             # then the reaction ladder, in priority order
-  products: {}
-  detail: {}
+      welcome:          # contained substate; first substate = the landing default
+        layout: layouts/main-welcome
+  focus:                # then the reaction ladder, in priority order
+    layout: layouts/focus
+  products:
+    layout: layouts/products
+  detail:
+    layout: layouts/detail
 ```
 
+Every state DECLARES its drawing as a path relative to the app folder (2026-08-29
+ruling): no same-name default, no assumed folder, `{}` is not a complete state.
+
 - **Top-level order IS the priority ladder**, base first. The app can be in ONE
   state at a time: it walks the list top-down and enters the first of its states that
   ANY hosted component currently matches. The ladder is DERIVED from the tree; never
@@ -59,19 +68,22 @@ states:
 - **A higher state CANCELS the claims below it**: while active, hosted components in
   lower-ranked states retract to inline (durable `lifetime: "conversation"` slices opt
   out), so releasing it lands on the BASE arrangement, never a stale lower one.
-- Ties (two components in the same view): most recent write wins (`limit: 1`).
+- Ties (two components in the same state): most recent write wins (`limit: 1`).
 - **No word is special.** `focus` outranks `products` by list position only; the engine
   matches names and walks the list. Even priority is data.
 - The app's own condition-guarded moods (a welcome hero on an empty conversation)
   are private substates of the base, never ladder entries: the app does not
   rearrange between them.
 
-## The anatomy: manifest-only (NO `<name>.yaml` envelope)
+## The anatomy: ONE FOLDER GRAMMAR (2026-08-29 — apps match components/templates)
 
 ```
 design/<project>/apps/<name>/
-  manifest.yaml    # THE ENVELOPE: the whole app contract, incl. the states tree
-  layouts/         # the ARRANGEMENTS: one per state that owns one (same-name default)
+  <name>.yaml      # THE ENVELOPE: type: app + the states tree (what the app IS);
+                   #   each state declares its layout path and carries its preview
+  manifest.yaml    # THE MCP FACE: description/whenToUse/inputSchema/binding/
+                   #   makeMCP/assetDomains — how the outside finds and calls it
+  layouts/         # the ARRANGEMENTS: one per state, each DECLARED by path in the tree
     main.yaml      #   the base: the core alone
     products.yaml  #   state "products" → core + cards rail
     detail.yaml    #   state "detail"  → core + full record page
@@ -84,7 +96,7 @@ design/<project>/apps/<name>/
 Each layout = a complete arrangement: `$include: components/core` + that state's
 surface. Shared chrome lives ONCE in `components/`; every layout includes it. The tree
 claims the instance, the layout's surface renders it: a reaction state's layout holds a
-ComponentSlot selecting the matching view.
+ComponentSlot selecting the matching state.
 
 ## manifest.yaml (the app contract)
 
@@ -121,27 +133,29 @@ ComponentSlot. Lint-enforced:
 ## Surfaces: apps REACT, they never own
 
 One instance → one placeholder: the flow is the placeholder for `inline`; a reaction
-state's layout (via its inner surface) is the placeholder for a matched view. The SDK
+state's layout (via its inner surface) is the placeholder for a matched state. The SDK
 keeps a claimed instance out of the flow; never hide a flow copy yourself.
 
 - **Flow slot**: `{ type: ComponentSlot, select: {} }`, always present.
-- **Reaction surface**: select by the public `view`, never by type/id:
+- **Reaction surface**: select by the public `state`, never by type/id:
   ```yaml
   type: ComponentSlot
   appWidth: panel
   select:
     from: all
-    where: { field: view, eq: detail }
+    where:
+      field: state
+      eq: page
     limit: 1
   frame:  # chrome; an inner bare ComponentSlot marks the placement
   ```
-  ❌ `select: { type: [...] }`, ❌ `where.field` ≠ `view`, ❌ app chrome
-  writing a component's slice, all lint-flagged. (`defaultState` as the select field
-  is the v1 legacy spelling.)
+  ❌ `select: { type: [...] }`, ❌ `where.field` ≠ `state`, ❌ app chrome
+  writing a component's slice, all lint-flagged. (`view` and `defaultState` are the
+  legacy spellings of the select field.)
 - **Input tools are app chrome** (unchanged rule): a composer, an edit form, a
   picker is owned by the app, never a streamed component state; chrome never
   "arrives". A card's Edit stages its data into the app's one input tool.
-- **App state** (`setTemplateValue`) is ONLY for the app's own chrome (a
+- **App state** (`setAppValue`) is ONLY for the app's own chrome (a
   disclosure, the composer `draft`). "Is something focused" is DERIVED, never stored.
 - **Chrome reacts via `surfacedView`** (SDK-projected active view name, `""` = all
   inline): `visibleWhen { field: surfacedView, in: ["", "products"] }`.
@@ -180,5 +194,5 @@ whole, see brand.md). Addresses: apps
 4. **See it**: in Studio, the state switcher reads the tree (base first, ladder order),
    base substates beneath, freely combinable; acting inside the preview transitions
    like the runtime. Then run it live: the bound workflow streams components, a card
-   entering a public view walks the ladder and rearranges the app end-to-end,
+   entering a public state walks the ladder and rearranges the app end-to-end,
    and its ✕ hands the lower state back.