@unoverse-platform/studio 0.1.68 → 0.1.69

package/local/{sample-template/chat/states/conversation.yaml → sample-component/text-chat/layouts/chat-active.yaml}

@@ -1,5 +1,4 @@
 type: Box
-visibleWhen: hasMessages
 autoScroll: true
 style:
   flex: 1

package/local/{sample-template/chat/states/welcome.yaml → sample-component/text-chat/layouts/chat-welcome.yaml}

@@ -1,5 +1,4 @@
 type: Box
-visibleWhen: isEmpty
 style:
   direction: column
   flex: 1

package/local/sample-component/text-chat/layouts/chat.yaml

@@ -0,0 +1,77 @@
+# THE SHELL of the one public state: the FULL chat CX — the header, the mood region
+# (welcome hero / live timeline), the suggestion chips over its foot, and the composer.
+# The steps switch on chatState (the declared axis): Studio writes it when you step
+# Welcome/Active. Live, nothing writes it, so the Switch falls to its default case,
+# where the projected conversation facts pick the mood.
+type: Box
+style:
+  direction: column
+  # `flex: 1` fills a flex column (the template's core); `height: full` fills a block
+  # parent with a real height (the standalone preview).
+  flex: 1
+  height: full
+  minHeight: "0"
+children:
+  - $include: components/header
+  - type: Box
+    style:
+      direction: column
+      flex: 1
+      minHeight: "0"
+      position: relative
+      when:
+        - field: hasMessages
+          eq: true
+          apply:
+            background: surface.base
+            radiusTopLeft: 2xl
+            overflow: hidden
+        - field: chatState
+          eq: active
+          apply:
+            background: surface.base
+            radiusTopLeft: 2xl
+            overflow: hidden
+            # chatState is only ever set by Studio's stepper, so this height is
+            # preview-only: live, the template's flex sizes the region.
+            minHeight: "120"
+    children:
+      - type: Switch
+        on: chatState
+        cases:
+          welcome: { $include: layouts/chat-welcome }
+          active: { $include: layouts/chat-active }
+          default:
+            type: Box
+            style:
+              direction: column
+              flex: 1
+              minHeight: "0"
+            children:
+              - type: Box
+                visibleWhen: isEmpty
+                style:
+                  direction: column
+                  flex: 1
+                  minHeight: "0"
+                children:
+                  - $include: layouts/chat-welcome
+              - type: Box
+                visibleWhen: hasMessages
+                style:
+                  direction: column
+                  flex: 1
+                  minHeight: "0"
+                children:
+                  - $include: layouts/chat-active
+      - type: Box
+        style:
+          position: absolute
+          bottom: "0"
+          left: "0"
+          right: "0"
+          direction: column
+        children:
+          - $include: components/suggestions
+  - type: Ref
+    ref: composer-bar

package/local/sample-component/text-chat/manifest.yaml

@@ -0,0 +1,10 @@
+title: Text Chat
+description: The conversation surface, a welcome hero on an empty chat and the live message timeline once it begins.
+whenToUse: Start talking to the assistant and see the conversation itself, the welcome screen to begin from, then the running exchange of messages once the chat is underway. Not for typing a message and not a page or card of its own, it is the chat surface inside your own apps.
+category: Communication
+version: 1.0.0
+
+# The app-level LOAD MODE: absent, a component app would load in `focus`. Arrival
+# inside a template is the tree's first declared state (chat); this key keeps the app
+# load honest to it.
+defaultState: chat

package/local/sample-component/text-chat/text-chat.yaml

@@ -0,0 +1,59 @@
+# THE CHAT SURFACE — a worked example component, shipped with Studio so the chat CX
+# lives in ONE place your apps can share. It is yours: rename it, restyle it (it uses
+# only foundation tokens, so your project's theme restyles it whole), or delete it.
+# Guide: https://docs.unoverse.ai/design/components.md
+unoverse: "1.0"
+kind: component
+name: text-chat
+category: Communication
+nodeSize:
+  width: 480
+  height: 400
+props:
+  # `input: false` on all three — no workflow fills them, so none of them join the
+  # node's config contract. They exist so the preview has something to draw.
+  #
+  # chatState is THE PREVIEW AXIS: Studio writes it when you step Welcome/Active. The
+  # default is EMPTY on purpose — live, nothing writes it, the Switch falls to its
+  # default case and the conversation facts pick the mood. A non-empty default would
+  # pin the mood forever.
+  chatState:
+    type: string
+    input: false
+    default: ""
+    enum: ["", welcome, active]
+  # Preview defaults for the live fallback's guards (the conversation facts the
+  # platform projects for real).
+  isEmpty:
+    type: boolean
+    input: false
+    default: true
+  hasMessages:
+    type: boolean
+    input: false
+    default: false
+# THE STATE TREE (State Model v2): ONE public state — the single-state permanent
+# component: it lives in a template's core and templates never rearrange around it.
+# The chat's two moods NEST beneath it as PRIVATE substates (the rearrange rule: the
+# template wouldn't move, so they nest), which is also what makes them steppable in
+# Studio. The mood is DERIVED from the conversation, so the shell's default case keeps
+# its own conditions. The template has the state; this component just reacts.
+state:
+  view:
+    states:
+      chat:
+        on: chatState
+        states:
+          welcome:
+            layout: chat-welcome
+          active:
+            layout: chat-active
+root:
+  type: Switch
+  on: view
+  cases:
+    chat: { $include: layouts/chat }
+    # Ref placement: embedded in a template's core the component has no spawned
+    # instance slice, so `view` is absent from scope — the chat is still the one
+    # thing to draw.
+    default: { $include: layouts/chat }

package/local/sample-template/chat/components/chat-region.yaml

@@ -0,0 +1,10 @@
+# THE CHAT REGION — one shared component (text-chat) owns the whole chat CX: the
+# welcome hero on an empty chat, the live timeline once messages exist, the suggestion
+# chips and the composer. The switching rides the projected conversation facts inside
+# the component; nothing is wired here. Shared by core and core-focus.
+#
+# A BARE ref resolves your own project's component: a ref inside a project's tree
+# matches that project first. Qualify it (`<project>/text-chat`) only if you ship two
+# projects that both carry the name.
+type: Ref
+ref: text-chat

package/local/sample-template/chat/components/core-focus.yaml

@@ -1,7 +1,6 @@
 # THE CHAT COLUMN WITH A FOCUSED COMPONENT OVER IT — core, plus the focus surface
-# laid over the conversation region. A core VARIANT, not a copy: header, states and
-# composer are the same shared files core.yaml includes; the only difference is the
-# overlay slot.
+# laid over it. A core VARIANT, not a copy: chat-region is the same shared file
+# core.yaml includes; the only difference is the overlay slot.
 type: Box
 appWidth: chat
 style:
@@ -15,32 +14,5 @@ children:
       minHeight: "0"
       position: relative
     children:
-      - $include: components/header
-      - type: Box
-        style:
-          direction: column
-          flex: 1
-          minHeight: "0"
-          position: relative
-          when:
-            - field: hasMessages
-              eq: true
-              apply:
-                background: surface.base
-                radiusTopLeft: 2xl
-                overflow: hidden
-        children:
-          - $include: states/welcome
-          - $include: states/conversation
-      - type: Box
-        style:
-          position: absolute
-          bottom: "0"
-          left: "0"
-          right: "0"
-          direction: column
-        children:
-          - $include: components/suggestions
+      - $include: components/chat-region
       - $include: components/focus-overlay
-  - type: Ref
-    ref: composer-bar

package/local/sample-template/chat/components/core.yaml

@@ -11,31 +11,4 @@ children:
       minHeight: "0"
       position: relative
     children:
-      - $include: components/header
-      - type: Box
-        style:
-          direction: column
-          flex: 1
-          minHeight: "0"
-          position: relative
-          when:
-            - field: hasMessages
-              eq: true
-              apply:
-                background: surface.base
-                radiusTopLeft: 2xl
-                overflow: hidden
-        children:
-          - $include: states/welcome
-          - $include: states/conversation
-      - type: Box
-        style:
-          position: absolute
-          bottom: "0"
-          left: "0"
-          right: "0"
-          direction: column
-        children:
-          - $include: components/suggestions
-  - type: Ref
-    ref: composer-bar
+      - $include: components/chat-region

package/local/sample-template/chat/manifest.yaml

@@ -16,22 +16,17 @@ inputSchema:
       description: The user's request
 
 # THE TEMPLATE TREE (State Model v2): one declaration, everything follows.
-# Top-level order IS the priority ladder (base first, then reaction states). NESTING
-# is containment: welcome exists only inside standard — the compiler strips it from
-# every other arrangement — and it is the landing default. No stateOrder, no
-# hand-written guards.
-# NOTE: the conversation timeline is NOT declared as a substate — it is standard's own
-# shell content (states/conversation), included by the shared chrome (components/core)
-# and legitimately drawn under the focus overlay too. Declaring it would contain it to
-# standard and empty the chat column in every reaction state.
+# Top-level order IS the priority ladder (base first, then reaction states). No
+# stateOrder, no hand-written guards.
+# NOTE: the chat itself is not a state here. Its two moods (welcome hero / live
+# timeline) live inside the text-chat component, which both cores draw via
+# components/chat-region. The component defaults to welcome on an empty conversation
+# and hands over to the timeline the moment messages exist.
 states:
-  standard:
-    states:
-      welcome: {}
+  standard: {}
   focused: {}
 
 preview:
-  conversation: [ markdown-renderer ]
   focused: [ card ]
 
 autoTrigger: false

package/local/scaffold.mjs

@@ -86,13 +86,18 @@ export function createProject(home, name) {
     cpSync(sampleStyles, join(root, "styles"), { recursive: true });
   }
 
-  // A worked example TEMPLATE (a generic chat: welcome hero, suggestions, focus
-  // overlay — the bpp-chat-layout shape, neutralized to foundation tokens), so
-  // templates/ is never an empty folder and the first app is a rename away. Same
+  // A worked example TEMPLATE (a generic chat: focus overlay + the chat region),
+  // so templates/ is never an empty folder and the first app is a rename away. Same
   // rule as the styles: copied only into an empty folder, then the developer's.
   const sampleTemplate = join(dirname(fileURLToPath(import.meta.url)), "sample-template/chat");
   if (existsSync(sampleTemplate) && readdirSync(join(root, "templates")).length === 0) {
     cpSync(sampleTemplate, join(root, "templates/chat"), { recursive: true });
+    // Its other half: the chat CX itself (welcome hero, timeline, suggestions,
+    // composer) is a COMPONENT the template draws via `Ref`, so the surface lives once
+    // and every app of this project shares it. Copied with the template, never without
+    // it — a template whose chat-region resolves nothing renders an empty column.
+    const sampleComponent = join(dirname(fileURLToPath(import.meta.url)), "sample-component/text-chat");
+    if (existsSync(sampleComponent)) cpSync(sampleComponent, join(root, "components/text-chat"), { recursive: true });
   }
   return root;
 }

package/package.json

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

package/screens/ComponentsView.tsx

@@ -715,9 +715,16 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
               </>
             )}
             <div className={isFocused ? "min-h-0 flex-1 overflow-auto" : "min-w-0 flex-1 overflow-auto p-10"}>
+              {/* THE STAGE OFFERS ITS HEIGHT; the component decides whether to take it.
+                  A single-row GRID, not a flex column: the SDK's shadow host is
+                  `display: contents`, so `.uno-isolate-root` is the item here, and a grid
+                  item stretches on BOTH axes by default — a flex item only stretches
+                  across. That gives the isolate root a real height to resolve against,
+                  so a full surface (chat, voice) fills and a card still sizes to its
+                  content. */}
               <div
                 key={`${masterState}:${previewNonce}`}
-                className={`mx-auto max-w-full ${isFocused ? "h-full" : "transition-[width] duration-200"}`}
+                className={`mx-auto max-w-full ${isFocused ? "h-full" : "grid h-full grid-rows-1 transition-[width] duration-200"}`}
                 style={{ width: sourceOpen ? "100%" : (stageWidth ?? "100%"), ...(isFocused ? { animation: "wb-focusFadeIn 0.2s ease-out" } : {}) }}
               >
                 {selected && <UnoverseComponent client={client} store={store} chatId={CHAT_ID} nodeId={selected} theme={theme} onAction={(a) => setLastAction(typeof a === "string" ? a : a?.type ?? null)} />}

package/vendor/sdk/appEngine.tsx

@@ -151,7 +151,7 @@ export function AppEngine(cfg: AppConfig) {
     // the ordinary case (one org, one `chat` size), and the incoming app then reported
     // nothing: its frame sat at the host default (100%) while its core panel held its
     // declared width, leaving a dead band beside it (observed live 2026-08-13,
-    // bpp-voice-layout). Clearing the guard here makes the first report after an app
+    // bpp-voice). Clearing the guard here makes the first report after an app
     // switch unconditional; the guard still suppresses repeats within one app.
     lastWidthRef.current = undefined;
     const report = () => {

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

@@ -133,7 +133,7 @@ place. Work through them in order.
 
 1. **Copy the folder.** `design/<source>/` → `design/<neworg>/`, keeping `styles/`, `components/`,
    `templates/`.
-2. **Rename the templates.** Folder AND the id inside the manifest. `bpp-chat-layout`
+2. **Rename the templates.** Folder AND the id inside the manifest. `bpp-chat`
    becomes `lyceum-chat-layout` in both places. Template ids are org-qualified and they
    are referenced by string.
 3. **Component names stay as copied.** Names are unique per org, not across orgs, so a

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

@@ -88,7 +88,9 @@ The rules, in the order they bite:
 - **Each state owns its layout(s).** `layout:` is OPTIONAL: a state with no declaration
   draws the layout of its own name, and `{}` is a complete state. Write `layout:` only
   when the filename differs. A layout is never addressable on its own; only its owning
-  state selects it. Name states for what they MEAN (`detail`), never for their drawing.
+  state selects it. Name states for what they MEAN (`detail`), never for their drawing. **Substate drawings are axis-prefixed**: a step's file carries its axis key
+  (`step-register`, `callState-idle`) and is declared via `layout:`; unprefixed
+  files are arrangements (exemplars: `course-application`, `voice-chat`).
 - **Shell vs steps.** A state's own layout is its SHELL, always on while the state is
   active. Its nested substates are the STEPS, the only choices inside it, addressed by
   state names (layout filenames are plumbing).
@@ -120,6 +122,24 @@ The rules, in the order they bite:
      static → hardcode);
    - workflow-fed data → **`props` with `input: true`** (the `default` is the preview mock).
      Usually empty.
+   - **Projected-field preview rule:** any LOCKED/projected field a
+     component branches on (`callState`, `isEmpty`, `hasMessages`) must ALSO be declared as
+     a prop with a preview default: Studio's bare component preview supplies ONLY prop
+     defaults, so an undeclared projected read renders NOTHING there; live, the projected
+     value wins and the default never applies. A Ref-embedded component's root Switch
+     likewise needs a `default:` case (`view` is absent without a spawned slice).
+   - **Who owns a mood: the DRIVER decides.** Ask what WRITES the discriminant:
+     (1) the component's own buttons (`setValue`) → component substates on a private axis,
+     names from the design (`course-application`); (2) a service projecting a NAMED value
+     (`callState`) → component substates named for those values + a preview prop
+     (`voice-chat`); (3) DERIVED from conversation facts (`isEmpty`/`hasMessages`) → the
+     TEMPLATE tier owns it: a condition-guarded mood, or guarded drawings inside an
+     embedded component reacting to the same facts — the template has the state,
+     components just react. NEVER model a derived mood as component named substates, and
+     never borrow another field's values (`lifecycle`) as state names (bpp `text-chat`). Declare the axis as a prop with enum + default
+     (preview only; live the projection wins), give the root Switch a `default:` case for
+     Ref placement, and prefix the step drawings with the axis (`callState-idle`,
+     `lifecycle-active`). Exemplars: `voice-chat`, bpp `text-chat`.
    - **Prop names = the data contract. Never invent them.** Source data hydrates props
      BY NAME (as-is, no mapping); a name the source doesn't carry silently renders the
      preview default (tell: title streams, image stays mock). Content-attached cards use

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

@@ -9,7 +9,7 @@ Everything in the component playbook (closed vocabulary, tokens, scale steps) ap
 here too. **Study an exemplar before writing**: templates are always a project's own
 (none ship in the base set), so your references are the canonical manifest tree inlined
 below, [design/templates](https://docs.unoverse.ai/design/templates.md), and any template
-already in the workspace. (Monorepo: `design/sab/templates/sab-chat-layout`.)
+already in the workspace. (Monorepo: `design/sab/templates/sab-chat`.)
 
 ## THE model: the component drives; the template reacts by name