@unoverse-platform/studio 0.1.68 → 0.1.70

package/bin/studio.mjs

@@ -141,7 +141,7 @@ async function scaffoldIfEmpty() {
   // identical (local/scaffold.mjs). rx/<name>/ stays nested: every subfolder of rx/ IS a
   // project (base collect.ts listProjects) and its folder name is the `org` that
   // publishes, so a flat rx/ could hold exactly one project and would read `components`
-  // and `templates` as orgs.
+  // and `apps` as orgs.
   createFirstProject(home, name);
   console.log(`\n  Created design/${name}/, prompts/ and nodes/ in ${cwd}\n`);
 }

package/local/catalog.ts

@@ -18,7 +18,7 @@ import { existsSync } from "fs";
 type Loaders = {
   listDefinitions: (kind: string, org?: string) => unknown[];
   listStates: (kind: string, name: string) => unknown[];
-  listTemplatesForWorkbench: (org?: string) => unknown[];
+  listAppsForWorkbench: (org?: string) => unknown[];
   loadDefinition: (ref: string, kind: string) => unknown;
   listOrgs: () => string[];
   inputPropKeys: (props: unknown) => string[];
@@ -98,7 +98,7 @@ export async function loadCatalog(
   return {
     listDefinitions: defs.listDefinitions as Loaders["listDefinitions"],
     listStates: defs.listStates as Loaders["listStates"],
-    listTemplatesForWorkbench: defs.listTemplatesForWorkbench as Loaders["listTemplatesForWorkbench"],
+    listAppsForWorkbench: defs.listAppsForWorkbench as Loaders["listAppsForWorkbench"],
     loadDefinition: defs.loadDefinition as Loaders["loadDefinition"],
     listOrgs: defs.listOrgs as Loaders["listOrgs"],
     inputPropKeys: inputs.inputPropKeys as Loaders["inputPropKeys"],

package/local/mcp.ts

@@ -155,8 +155,9 @@ export function buildTools(deps: McpDeps, appRoot: string): Record<string, Tool>
       run: async ({ uri }) => {
         needsBinding();
         const c = await deps.catalog();
-        const ref = String(uri).replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "");
-        const kind = /\/(apps|templates)\//.test(String(uri)) ? "template" : /\/atoms\//.test(String(uri)) ? "atom" : "component";
+        // `.../definition` is a suffix on the app's URI, not part of its ref.
+        const ref = String(uri).replace(/^unoverse:\/\/(components|atoms|apps)\//, "").replace(/\/definition$/, "");
+        const kind = /\/apps\//.test(String(uri)) ? "template" : /\/atoms\//.test(String(uri)) ? "atom" : "component";
         return { definition: c.loadDefinition(ref, kind), files: deps.sourceFiles(String(uri)) };
       },
     },

package/local/plugin.ts

@@ -8,7 +8,7 @@
  *
  * Routes mirror the server's shapes exactly, because the screens parse those shapes:
  *   GET /dev/orgs        GET /dev/themes?org=      GET /dev/components?org=
- *   GET /dev/templates?org=   GET /dev/atoms
+ *   GET /dev/apps?org=   GET /dev/atoms
  *   GET /local/theme?ref=     GET /local/definition?uri=
  *   GET /skills  /skills/:name   GET /prompt-blocks
  *   GET|POST /registry/state  (no database locally, see below)
@@ -29,10 +29,10 @@ import { atomNames, vocabulary } from "./authoring.js";
 import { buildTools, handleMcp, mintPairingCode } from "./mcp.js";
 
 /**
- * A definition URI's home on disk: a component's folder, or a template's.
+ * A definition URI's home on disk: a component's folder, or an app's.
  *
  * Resolution is the loaders', not this file's: `componentFolder` already knows a
- * component lives in either tier and that names are unique across them. Templates are
+ * component lives in either tier and that names are unique across them. Apps are
  * manifest-only under their own project, which `projectDir` locates.
  */
 function definitionHome(
@@ -40,13 +40,15 @@ function definitionHome(
   c: { componentFolder: (ref: string) => string | null; projectDir: (n: string) => string; listOrgs: () => string[] },
   projectRoot: string,
 ): string | null {
-  const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "");
-  if (/\/(apps|templates)\//.test(uri)) {
+  // An app definition is addressed as `unoverse://apps/<org>/<name>/definition`, so the
+  // suffix has to come off before the rest is read as `<org>/<name>`.
+  const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps)\//, "").replace(/\/definition$/, "");
+  if (/\/apps\//.test(uri)) {
     const i = ref.indexOf("/");
     const [org, name] = i === -1 ? [null, ref] : [ref.slice(0, i), ref.slice(i + 1)];
     const orgs = org ? [org] : c.listOrgs();
     for (const o of orgs) {
-      const dir = resolve(c.projectDir(o), "templates", name.toLowerCase());
+      const dir = resolve(c.projectDir(o), "apps", name.toLowerCase());
       if (existsSync(dir)) return dir;
     }
     return null;
@@ -346,8 +348,8 @@ export function localStudioHost(): Plugin {
                 }),
               });
 
-            case path === "/dev/templates":
-              return json(res, { templates: c.listTemplatesForWorkbench(org) });
+            case path === "/dev/apps":
+              return json(res, { apps: c.listAppsForWorkbench(org) });
 
             case path === "/dev/atoms":
               return json(res, { atoms: c.listDefinitions("atom") });
@@ -360,14 +362,14 @@ export function localStudioHost(): Plugin {
             case path === "/local/definition": {
               const uri = url.searchParams.get("uri") ?? "";
               // Apps are addressed both ways (unoverse://apps/<org>/<id> and
-              // unoverse://templates/<org>/<id>); both load the template kind.
-              const kind = /\/(apps|templates)\//.test(uri) ? "template" : /\/atoms\//.test(uri) ? "atom" : "component";
+              // unoverse://apps/<org>/<id>/definition); both load the app kind.
+              const kind = /\/apps\//.test(uri) ? "template" : /\/atoms\//.test(uri) ? "atom" : "component";
               // A trailing `@form` is a request for a VARIANT of the definition, not part of
               // its name. This door did not know that convention and looked up the whole
               // string, so every component read as `<name>@refs` answered "definition not
               // found". Strip any variant: this route serves the one form it has, which is
               // also the only form the server serves.
-              const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "").replace(/@[a-z]+$/, "");
+              const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps)\//, "").replace(/\/definition$/, "").replace(/@[a-z]+$/, "");
               const d = c.loadDefinition(ref, kind);
               return d ? json(res, d) : json(res, { error: `definition not found: ${uri}` }, 404);
             }

package/local/sample-app/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-app/chat/components/core-focus.yaml

@@ -0,0 +1,18 @@
+# THE CHAT COLUMN WITH A FOCUSED COMPONENT OVER IT — core, plus the focus surface
+# 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:
+  direction: column
+  minHeight: "0"
+children:
+  - type: Box
+    style:
+      direction: column
+      flex: 1
+      minHeight: "0"
+      position: relative
+    children:
+      - $include: components/chat-region
+      - $include: components/focus-overlay

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

@@ -0,0 +1,14 @@
+type: Box
+appWidth: chat
+style:
+  direction: column
+  minHeight: "0"
+children:
+  - type: Box
+    style:
+      direction: column
+      flex: 1
+      minHeight: "0"
+      position: relative
+    children:
+      - $include: components/chat-region

package/local/{sample-template → sample-app}/chat/manifest.yaml

@@ -1,13 +1,13 @@
-# A GENERIC CHAT — a worked example template, shipped with Studio so templates/ is
+# A GENERIC CHAT — a worked example app, shipped with Studio so apps/ is
 # never an empty folder. 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/templates.md
+# Guide: https://docs.unoverse.ai/design/apps.md
 name: chat
 description: A conversational assistant surface with a welcome hero, suggestions, and a focus overlay.
 whenToUse: Talk to the assistant — ask a question, get help, or start any task in conversation. The conversational home and fallback surface.
 category: Assistant
 version: 1.0.0
-defaultState: template
+defaultState: app
 inputSchema:
   type: object
   properties:
@@ -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/{sample-template/chat → sample-component/text-chat}/components/suggestions.yaml

@@ -32,7 +32,7 @@ children:
         children:
           - type: Button
             action:
-              type: setTemplateValue
+              type: setAppValue
               values:
                 - key: openPanel
                   value: null
@@ -70,7 +70,7 @@ children:
           action:
             type: sendMessage
             then:
-              type: setTemplateValue
+              type: setAppValue
               values:
                 - key: openPanel
                   value: null
@@ -110,7 +110,7 @@ children:
     children:
       - type: Button
         action:
-          type: setTemplateValue
+          type: setAppValue
           values:
             - key: openPanel
               value: faq

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/scaffold.mjs

@@ -1,8 +1,8 @@
 /**
  * Creating a project, from either end.
  *
- * A project (an "org") is `design/<name>/` holding components, styles and
- * templates. It is the unit a developer authors in and the unit that publishes: every row
+ * A project (an "org") is `design/<name>/` holding components, styles and apps.
+ * It is the unit a developer authors in and the unit that publishes: every row
  * that lands in a universe carries its name in the `org` column.
  *
  * ONE IMPLEMENTATION, TWO CALLERS. `bin/studio.mjs` creates the FIRST project at launch,
@@ -73,7 +73,7 @@ export function createProject(home, name) {
   const root = join(designHome(home), name);
   if (existsSync(root)) throw new Error(`${name} already exists in this workspace`);
 
-  for (const d of ["components/welcome", "templates", "styles"]) mkdirSync(join(root, d), { recursive: true });
+  for (const d of ["components/welcome", "apps", "styles"]) mkdirSync(join(root, d), { recursive: true });
   writeFileSync(join(root, "components/welcome/welcome.yaml"), WELCOME);
 
   // Worked example styles (sample-styles: brand ingredients + the override rules), so
@@ -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 APP (a generic chat: focus overlay + the chat region),
+  // so apps/ 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 });
+  const sampleApp = join(dirname(fileURLToPath(import.meta.url)), "sample-app/chat");
+  if (existsSync(sampleApp) && readdirSync(join(root, "apps")).length === 0) {
+    cpSync(sampleApp, join(root, "apps/chat"), { recursive: true });
+    // Its other half: the chat CX itself (welcome hero, timeline, suggestions,
+    // composer) is a COMPONENT the app draws via `Ref`, so the surface lives once
+    // and every app of this project shares it. Copied with the app, never without
+    // it: an app 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.70",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {
@@ -29,6 +29,7 @@
     "@unoverse-platform/base": "^0.3.37",
     "@unoverse-platform/marketplace": "*",
     "@vitejs/plugin-react": "^4.3.4",
+    "lucide-react": "^0.546.0",
     "markdown-to-jsx": "^7.7.17",
     "oidc-client-ts": "^3.4.1",
     "react": "^18.2.0",

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/screens/NativeAppHost.tsx

@@ -18,7 +18,7 @@ const APP_UI_URI = "ui://unoverse/app.html";
 export function NativeAppHost({
   server,
   token,
-  templateId,
+  appId,
   userId,
   conversationId,
   onStatus,
@@ -26,7 +26,7 @@ export function NativeAppHost({
   /** Universe origin, e.g. http://localhost:4105 — the /mcp and /stream host. */
   server: string;
   token?: string;
-  templateId?: string;
+  appId?: string;
   userId: string;
   conversationId: string;
   /** The iframe app owns the ONLY live connection — it posts `unoverse:status`
@@ -53,7 +53,7 @@ export function NativeAppHost({
     return () => window.removeEventListener("message", onSize);
   }, [onStatus]);
   // A different app starts back at the host default until it reports.
-  useEffect(() => setAppWidth(null), [templateId]);
+  useEffect(() => setAppWidth(null), [appId]);
 
   // Pull the app shell from the universe — one resources/read, then the client closes.
   useEffect(() => {
@@ -110,13 +110,13 @@ then come back — Studio picks the session up by itself.`
     frame.current?.contentWindow?.postMessage(
       {
         type: "unoverse:config",
-        config: { serverUrl: server, apiUrl: server, templateId, userId, conversationId, token },
+        config: { serverUrl: server, apiUrl: server, appId, userId, conversationId, token },
       },
       "*",
     );
   };
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  useEffect(postConfig, [token, templateId, userId, conversationId, server, html]);
+  useEffect(postConfig, [token, appId, userId, conversationId, server, html]);
 
   if (error)
     return (