@unoverse-platform/studio 0.1.54 → 0.1.56

package/bin/studio.mjs

@@ -162,6 +162,13 @@ await scaffoldIfEmpty();
  */
 const projectRoot = findProjectRootFromCwd();
 process.env.UNOVERSE_HOME = projectRoot;
+// Samples this workspace has never seen arrive on launch (new ones ship with Studio
+// releases); anything it ever had — edited or deleted — is never touched. scaffold.mjs
+// topUpSamples explains the record that makes that distinction safe.
+{
+  const { topUpSamples } = await import("../local/scaffold.mjs");
+  try { topUpSamples(projectRoot); } catch { /* a read-only folder must not block launch */ }
+}
 console.log(`\n  Studio reading: ${designHome(projectRoot)}\n`);
 
 /**

package/local/scaffold.mjs

@@ -13,7 +13,7 @@
  *
  * See docs/architecture/LOCAL_STUDIO.md.
  */
-import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, readFileSync } from "node:fs";
 import { designHome } from "./design-home.mjs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -84,6 +84,60 @@ export function createProject(home, name) {
   return root;
 }
 
+/**
+ * The worked example content (sample nodes, a sample agent skill, a sample prompt
+ * block), keyed by the workspace path each lands at. `dir` is relative to this file.
+ *
+ * A NEW ENTRY HERE REACHES EXISTING WORKSPACES on their next Studio launch, because
+ * topUpSamples runs at every launch, not only at scaffold. The record below is what
+ * makes that safe.
+ */
+const SAMPLES = [
+  { id: "nodes/samples", dir: "sample-nodes/samples", to: "nodes/samples" },
+  { id: "prompts/skills/sample-complaint-handling", dir: "sample-prompts/skills/sample-complaint-handling", to: "prompts/skills/sample-complaint-handling" },
+  { id: "prompts/blocks/sample-concise-answers", dir: "sample-prompts/blocks/formatting/sample-concise-answers.md", to: "prompts/blocks/formatting/sample-concise-answers.md" },
+];
+
+/**
+ * Install every sample this workspace has NEVER SEEN, and only those.
+ *
+ * "Absent from disk" is ambiguous — it means either "deleted on purpose" or "shipped
+ * after this workspace was made" — so presence is not the test. The test is the
+ * RECORD (.unoverse/samples.json): a sample id listed there was installed here once,
+ * and whatever the developer did to it since (edit, rename, delete) is theirs and
+ * permanent. A sample id NOT listed is genuinely new to this workspace and arrives.
+ * That is what lets `unoverse studio` top up new samples on every launch without ever
+ * resurrecting deleted work or overwriting changed files.
+ */
+export function topUpSamples(home) {
+  const record = join(home, ".unoverse", "samples.json");
+  let seen = [];
+  try {
+    seen = JSON.parse(readFileSync(record, "utf8")).installed ?? [];
+  } catch {
+    // No record: a workspace from before records existed. Treat every sample already
+    // on disk as seen (it was installed by an old scaffold), so nothing is re-copied.
+    seen = SAMPLES.filter((s) => existsSync(join(home, s.to))).map((s) => s.id);
+  }
+  const here = dirname(fileURLToPath(import.meta.url));
+  let changed = false;
+  for (const s of SAMPLES) {
+    if (seen.includes(s.id)) continue;
+    const src = join(here, s.dir);
+    if (!existsSync(src)) continue;
+    if (!existsSync(join(home, s.to))) {
+      mkdirSync(dirname(join(home, s.to)), { recursive: true });
+      cpSync(src, join(home, s.to), { recursive: true });
+    }
+    seen.push(s.id);
+    changed = true;
+  }
+  if (changed || !existsSync(record)) {
+    mkdirSync(dirname(record), { recursive: true });
+    writeFileSync(record, JSON.stringify({ installed: seen }, null, 2) + "\n");
+  }
+}
+
 /**
  * The FIRST project, plus the folders that live beside the design tree rather than inside it.
  *
@@ -94,47 +148,20 @@ export function createFirstProject(home, name) {
   const root = createProject(home, name);
   for (const d of ["prompts/skills", "prompts/blocks", "nodes"]) mkdirSync(join(home, d), { recursive: true });
 
-  // Two worked example nodes (sample-nodes/samples: a PromiseNode and a CallbackNode,
-  // heavily commented, linking docs.unoverse.ai/nodes), so `nodes/` is never an empty
-  // folder with no hint of what goes in it. Copied only when absent: these are the
-  // developer's files to edit or delete, and a later scaffold run must never put back
-  // what they threw away or overwrite what they changed.
-  const samples = join(dirname(fileURLToPath(import.meta.url)), "sample-nodes/samples");
-  if (existsSync(samples) && !existsSync(join(home, "nodes/samples"))) {
-    cpSync(samples, join(home, "nodes/samples"), { recursive: true });
-  }
-
-  // A worked example agent skill and prompt block, same reason and same rule as the
-  // sample nodes: prompts/ must never be two empty folders, and the samples are the
-  // developer's to edit or delete — copied only when absent, never restored.
-  const samplePrompts = join(dirname(fileURLToPath(import.meta.url)), "sample-prompts");
-  if (existsSync(join(samplePrompts, "skills")) && !existsSync(join(home, "prompts/skills/sample-complaint-handling"))) {
-    cpSync(join(samplePrompts, "skills"), join(home, "prompts/skills"), { recursive: true });
-  }
-  if (existsSync(join(samplePrompts, "blocks")) && !existsSync(join(home, "prompts/blocks/formatting/sample-concise-answers.md"))) {
-    cpSync(join(samplePrompts, "blocks"), join(home, "prompts/blocks"), { recursive: true });
-  }
+  topUpSamples(home);
 
-  // The Claude Code authoring skills, so "open the folder and describe what you want"
-  // works in every Studio project from its first minute. Vendored into the published
-  // app (vendor/skills, written by prepack from the monorepo's .claude/skills, the one
-  // authoring home, mirrored publicly to github.com/unoverse-platform/skills); read
-  // from that home when running as source. `unoverse update` refreshes installed
-  // copies from the public mirror.
+  // SCAFFOLD WRITES NO `.claude/skills` (2026-08-21). It used to copy the Claude Code
+  // authoring skills out of `vendor/skills` and into `<home>/.claude/skills`, which meant
+  // every remote developer who launched Studio got the platform repo's own `.claude`
+  // folder reproduced on their disk, pinned to whatever Studio version they happened to
+  // install and sitting in a workspace they might commit.
   //
-  // ALL of them. One Studio project is where a person designs a brand AND writes the node
-  // behind it, so they need the whole set: naming one skill here shipped the authoring
-  // playbooks and silently withheld the rest.
-  const app = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-  const skillsDir = [join(app, "vendor/skills"), resolve(app, "../../.claude/skills")].find((d) => existsSync(d));
-  if (skillsDir) {
-    const names = readdirSync(skillsDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && existsSync(join(skillsDir, e.name, "SKILL.md")))
-      .map((e) => e.name);
-    if (names.length) mkdirSync(join(home, ".claude/skills"), { recursive: true });
-    for (const name of names) {
-      cpSync(join(skillsDir, name), join(home, ".claude/skills", name), { recursive: true });
-    }
-  }
+  // The skills are PER DEVELOPER, not per project (the same reason prompts/ and nodes/ are
+  // made once here and never by `createProject`). They now install to `~/.claude/skills`
+  // from the public mirror, on `unoverse update` — see packages/cli/lib/skills.mjs.
+  //
+  // `vendor/skills` STAYS, and is not a distribution channel: it is what Studio's builder
+  // MCP reads to teach a connected agent the authoring rules (local/mcp.ts SKILL_DIRS).
+  // Nothing about that copy reaches the developer's filesystem.
   return root;
 }

package/package.json

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

package/screens/AtomsView.tsx

@@ -10,6 +10,7 @@ import { useEffect, useMemo, useState, type MouseEvent as ReactMouseEvent } from
 import { UnoverseComponent, type ResolvedTheme } from "@unoverse/sdk";
 import { client, authedFetch } from "studio-host";
 import { usePersistentState } from "studio-host";
+import { NAV, SCREEN, navItem } from "./chrome";
 
 interface PropDef {
   type?: string;
@@ -127,9 +128,9 @@ export function AtomsView({ theme }: { theme: ResolvedTheme }) {
   const uri = useMemo(() => (selected ? `unoverse://atoms/${slug(selected)}` : ""), [selected]);
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[240px_1fr] overflow-hidden">
+    <div className={SCREEN}>
       {/* NAVIGATOR */}
-      <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#1b2129] p-2">
+      <nav className={NAV}>
         {atoms.length === 0 && (
           <div className="p-2 text-xs text-gray-400">No atoms — restart the Unoverse server so /dev/atoms is available.</div>
         )}
@@ -153,9 +154,7 @@ export function AtomsView({ theme }: { theme: ResolvedTheme }) {
               <button
                 key={a.name}
                 onClick={() => choose(a)}
-                className={`block w-full rounded px-2 py-1 text-left text-sm transition ${
-                  selected === a.name ? "bg-emerald-500/15 text-emerald-300" : "text-gray-300 hover:bg-white/5"
-                }`}
+                className={`block w-full rounded px-2 py-1 text-left text-sm transition ${navItem(selected === a.name)}`}
               >
                 {a.name}
               </button>

package/screens/ComponentsView.tsx

@@ -10,6 +10,7 @@ import { client, authedFetch, hasSourceAccess } from "studio-host";
 import { SourceView } from "./SourceView";
 import { stateActivation, faceOf, faceAxisOf, switchLayers } from "./states";
 import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
+import { NAV, SCREEN, navItem, navSubItem } from "./chrome";
 
 const CHAT_ID = "demo";
 
@@ -382,9 +383,9 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
   for (const [, items] of byCategory) items.sort((a, b) => (a.org ? 0 : 1) - (b.org ? 0 : 1));
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[240px_1fr] overflow-hidden">
+    <div className={SCREEN}>
       {/* NAVIGATOR */}
-      <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#2c2c2e] p-2">
+      <nav className={NAV}>
         {components.length === 0 && (
           <div className="p-2 text-xs text-gray-400">No components — restart the Unoverse server so /dev/components is available.</div>
         )}
@@ -400,9 +401,7 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
               <div key={refOf(c)}>
                 <button
                   onClick={() => choose(c)}
-                  className={`block w-full rounded px-2 py-1 text-left text-sm transition ${
-                    selected === refOf(c) ? "bg-emerald-500/15 text-emerald-300" : "text-gray-300 hover:bg-white/5"
-                  }`}
+                  className={`block w-full rounded px-2 py-1 text-left text-sm transition ${navItem(selected === refOf(c))}`}
                 >
                   {c.name}
                   {/* Ownership mark: tagged = the developer's own (editable); untagged =
@@ -442,9 +441,7 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
                               store.apply({ type: "COMPONENT_DATA", chatId: CHAT_ID, nodeId: refOf(c), data: { [st.on!]: e.step } });
                               setStoreTick((v) => v + 1);
                             }}
-                            className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${
-                              cur === e.step ? "bg-emerald-500/10 text-emerald-300" : "text-gray-400 hover:bg-white/5 hover:text-gray-200"
-                            }`}
+                            className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${navSubItem(cur === e.step)}`}
                           >
                             {e.label}
                           </button>
@@ -469,9 +466,7 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
                             store.apply({ type: "COMPONENT_DATA", chatId: CHAT_ID, nodeId: refOf(c), data });
                             setStoreTick((v) => v + 1);
                           }}
-                          className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${
-                            isActive ? "bg-emerald-500/10 text-emerald-300" : "text-gray-400 hover:bg-white/5 hover:text-gray-200"
-                          }`}
+                          className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${navSubItem(isActive)}`}
                         >
                           {s.name}
                         </button>
@@ -494,9 +489,7 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
                             store.apply({ type: "COMPONENT_DATA", chatId: CHAT_ID, nodeId: refOf(c), data: { [s.on]: s.name } });
                             setStoreTick((v) => v + 1);
                           }}
-                          className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${
-                            on ? "bg-emerald-500/10 text-emerald-300" : "text-gray-400 hover:bg-white/5 hover:text-gray-200"
-                          }`}
+                          className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${navSubItem(on)}`}
                         >
                           {s.name}
                         </button>

package/screens/DesignSystemView.tsx

@@ -7,6 +7,7 @@
  */
 import { useState } from "react";
 import type { ResolvedTheme } from "@unoverse/sdk";
+import { GALLERY, NAV, NAV_SECTION, PANE, SCREEN, navItem } from "./chrome";
 
 const COLOR_GROUP_ORDER = [
   "brand", "primary", "secondary", "success", "action", "text", "surface", "border", "status",
@@ -65,7 +66,12 @@ export function DesignSystemView({
   // loud brand (e.g. an all-red project) doesn't turn the whole page its brand colour. The
   // real token swatches still render their true values; only the chrome is neutralised.
   const accent = "#6366f1";
-  const onAction = "#ffffff";
+  // THE NAVIGATOR IS STUDIO CHROME, NOT THE PREVIEW (2026-08-21). It used to paint itself
+  // from the viewed theme's `surface.base` and size itself by hand, which is the same
+  // mistake the accent above was already fixed for: a project with a white surface gave
+  // Studio a white sub-nav, in the one section where every other section's is dark. It now
+  // takes the shared shell from `./chrome` like every other screen. Reading a project's
+  // tokens is what the CONTENT pane is for, and that pane still does.
   const bodyFont = (theme.text["body.md"]?.fontFamily as string) ?? "system-ui";
 
   // A token is THIS PROJECT'S OVERRIDE when its resolved value differs from the
@@ -276,55 +282,45 @@ export function DesignSystemView({
   const current = SECTIONS.find((s) => s.id === active) ?? SECTIONS[0];
 
   return (
-    <div className="flex h-full" style={{ background: theme.color["surface.sunken"] ?? "#f9fafb", color: ink }}>
-      {/* LEFT NAV — jump between token groups; badge = how many tokens THIS project overrides */}
-      <nav className="w-56 shrink-0 overflow-auto border-r p-5" style={{ borderColor: borderC, background: surface, fontFamily: bodyFont }}>
-        <h1 className="mb-1 text-lg font-bold">Styles</h1>
-        <p className="mb-5 text-[11px] leading-snug" style={{ color: sub }}>
-          {foundation ? (
-            <>Viewing <b style={{ color: ink }}>{org}</b></>
-          ) : (
-            <>The base foundation</>
-          )}
-        </p>
-        <ul className="space-y-1">
-          {SECTIONS.map((s) => {
-            const n = foundation && s.bucket ? overrideCount(s.bucket) : 0;
-            const on = active === s.id;
-            return (
-              <li key={s.id}>
-                <button
-                  onClick={() => setActive(s.id)}
-                  className="flex w-full items-center justify-between rounded px-3 py-2 text-left text-sm font-medium transition-colors"
-                  style={on ? { background: accent, color: onAction } : { color: ink }}
-                >
-                  <span>{s.title}</span>
-                  {n > 0 && (
-                    <span
-                      className="rounded-full px-1.5 py-0.5 text-[10px] font-semibold"
-                      style={{ background: on ? "rgba(255,255,255,0.25)" : accent, color: onAction }}
-                    >
-                      {n}
-                    </span>
-                  )}
-                </button>
-              </li>
-            );
-          })}
-        </ul>
+    <div className={SCREEN}>
+      {/* NAVIGATOR — jump between token groups; badge = how many tokens THIS project overrides */}
+      <nav className={NAV}>
+        <div className={NAV_SECTION}>{foundation ? org : "foundation"}</div>
+        {SECTIONS.map((s) => {
+          const n = foundation && s.bucket ? overrideCount(s.bucket) : 0;
+          const on = active === s.id;
+          return (
+            <button
+              key={s.id}
+              onClick={() => setActive(s.id)}
+              className={`flex w-full items-center justify-between rounded px-2 py-1 text-left text-sm transition ${navItem(on)}`}
+            >
+              <span>{s.title}</span>
+              {n > 0 && (
+                <span className="rounded-full bg-emerald-500/15 px-1.5 py-0.5 text-[10px] font-semibold text-emerald-300">
+                  {n}
+                </span>
+              )}
+            </button>
+          );
+        })}
       </nav>
 
-      {/* CONTENT — the selected group only */}
-      <div className="flex-1 overflow-auto p-10" style={{ fontFamily: bodyFont }}>
-        <h2 className="mb-1 text-2xl font-bold">{current.title}</h2>
-        <p className="mb-8 text-xs" style={{ color: sub }}>
-          {foundation ? (
-            <>Tokens with an <OverrideMark /> are <b style={{ color: ink }}>{org}</b>&rsquo;s own; the rest are inherited from the design-system foundation.</>
-          ) : (
-            <>Live tokens from the design-system foundation (<code>design/marketplace/styles</code>). Toggle the theme to restyle everything.</>
-          )}
-        </p>
-        {current.body}
+      {/* CONTENT — the selected group only. The one pane that IS allowed to look like the
+          project, because looking at the project is its whole job; `bodyFont` renders the
+          typography specimens in the theme's own face. */}
+      <div className={PANE}>
+        <div className={GALLERY} style={{ fontFamily: bodyFont }}>
+          <h1 className="text-xl font-bold leading-tight tracking-tight text-gray-900">{current.title}</h1>
+          <p className="mb-8 mt-1 max-w-3xl text-sm leading-relaxed text-gray-600">
+            {foundation ? (
+              <>Tokens with an <OverrideMark /> are <b className="text-gray-900">{org}</b>&rsquo;s own; the rest are inherited from the design-system foundation.</>
+            ) : (
+              <>Live tokens from the design-system foundation (<code>design/marketplace/styles</code>). Toggle the theme to restyle everything.</>
+            )}
+          </p>
+          {current.body}
+        </div>
       </div>
     </div>
   );

package/screens/PromptBlocksView.tsx

@@ -15,6 +15,7 @@ import { useEffect, useMemo, useState } from "react";
 import { fetchUnoverse } from "studio-host";
 import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
 import { IdentityHeader } from "./IdentityHeader";
+import { DOC, EMPTY, NAV, NAV_SECTION, PANE, SCREEN, navItem } from "./chrome";
 
 interface PromptBlock {
   id: string;
@@ -61,9 +62,9 @@ export function PromptBlocksView() {
   ).sort(([a], [b]) => a.localeCompare(b));
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[220px_1fr] overflow-hidden">
+    <div className={SCREEN}>
       {/* NAVIGATOR */}
-      <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#2c2c2e] p-2">
+      <nav className={NAV}>
         {blocks.length === 0 && (
           <div className="p-2 text-xs text-gray-400">
             {error
@@ -73,14 +74,12 @@ export function PromptBlocksView() {
         )}
         {byCategory.map(([cat, items]) => (
           <div key={cat} className="mb-3">
-            <div className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-gray-400">{cat}</div>
+            <div className={NAV_SECTION}>{cat}</div>
             {items.map((b) => (
               <button
                 key={b.id}
                 onClick={() => setSelected(b.id)}
-                className={`block w-full rounded px-2 py-1.5 text-left transition ${
-                  selected === b.id ? "bg-emerald-500/15 text-emerald-300" : "text-gray-300 hover:bg-white/5"
-                }`}
+                className={`block w-full rounded px-2 py-1.5 text-left transition ${navItem(selected === b.id)}`}
               >
                 <div className="flex items-center gap-1.5 text-sm font-medium">
                   {toggles.isEnabled(b.id) && <span className="h-1.5 w-1.5 rounded-full bg-emerald-400" title="Enabled" />}
@@ -94,11 +93,11 @@ export function PromptBlocksView() {
       </nav>
 
       {/* DETAIL */}
-      <div className="min-h-0 min-w-0 overflow-auto bg-white">
+      <div className={PANE}>
         {!detail ? (
-          <div className="flex h-full items-center justify-center text-sm text-gray-500">Select a prompt block</div>
+          <div className={EMPTY}>Select a prompt block</div>
         ) : (
-          <div className="mx-auto max-w-3xl p-8">
+          <div className={DOC}>
             <IdentityHeader
               name={detail.name}
               category={detail.category}

package/screens/SkillsView.tsx

@@ -13,6 +13,7 @@ import { useEffect, useState } from "react";
 import { fetchUnoverse } from "studio-host";
 import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
 import { IdentityHeader } from "./IdentityHeader";
+import { DOC, EMPTY, NAV, NAV_SECTION, PANE, SCREEN, navItem } from "./chrome";
 
 interface SkillSummary {
   name: string;
@@ -86,9 +87,9 @@ export function SkillsView() {
   ).sort(([a], [b]) => a.localeCompare(b));
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[220px_1fr] overflow-hidden">
+    <div className={SCREEN}>
       {/* NAVIGATOR */}
-      <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#2c2c2e] p-2">
+      <nav className={NAV}>
         {skills.length === 0 && (
           <div className="p-2 text-xs text-gray-400">
             {error
@@ -98,14 +99,12 @@ export function SkillsView() {
         )}
         {byCategory.map(([cat, items]) => (
           <div key={cat} className="mb-3">
-            <div className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-gray-400">{cat}</div>
+            <div className={NAV_SECTION}>{cat}</div>
             {items.map((s) => (
               <button
                 key={s.name}
                 onClick={() => setSelected(s.name)}
-                className={`block w-full rounded px-2 py-1.5 text-left transition ${
-                  selected === s.name ? "bg-emerald-500/15 text-emerald-300" : "text-gray-300 hover:bg-white/5"
-                }`}
+                className={`block w-full rounded px-2 py-1.5 text-left transition ${navItem(selected === s.name)}`}
               >
                 <div className="flex items-center gap-1.5 text-sm font-medium">
                   {s.name}
@@ -118,11 +117,11 @@ export function SkillsView() {
       </nav>
 
       {/* DETAIL */}
-      <div className="min-h-0 min-w-0 overflow-auto bg-white">
+      <div className={PANE}>
         {!selected ? (
-          <div className="flex h-full items-center justify-center text-sm text-gray-500">Select a skill</div>
+          <div className={EMPTY}>Select a skill</div>
         ) : (
-          <div className="mx-auto max-w-3xl p-8">
+          <div className={DOC}>
             {/* AVAILABLE — the master switch. Which workflows actually carry this skill is
                 installed per workflow, in Canvas's Content Library. */}
             <IdentityHeader

package/screens/TemplatesView.tsx

@@ -27,6 +27,7 @@ import { StreamedUnoverseTemplate, useUnoverseConnection, computeAppWidth, resol
 import { NativeAppHost } from "./NativeAppHost";
 import { inArrangement, viewOfSlice } from "./states";
 import { client, authedFetch, hasAuth, UNOVERSE_BASE, liveUniverseUrl } from "studio-host";
+import { NAV, NAV_SECTION, SCREEN, navItem, navSubItem } from "./chrome";
 
 // Per-APP test conversation: each app chats in its own conversation id, so testing
 // one client's app never inherits another's agent history/memory (the "BPP answers
@@ -652,10 +653,10 @@ export function TemplatesView({
   }, [store, selected, components, templates, live, activeState, activeLayout]);
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[190px_1fr] overflow-hidden">
+    <div className={SCREEN}>
       {/* NAVIGATOR */}
-      <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#2c2c2e] p-2">
-        <div className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-gray-400">Apps</div>
+      <nav className={NAV}>
+        <div className={NAV_SECTION}>Apps</div>
         {templates.length === 0 && (
           <div className="p-2 text-xs text-gray-400">No apps yet — add one under design/&lt;project&gt;/templates/.</div>
         )}
@@ -663,9 +664,7 @@ export function TemplatesView({
           <div key={`${t.org ?? ""}/${t.name}`}>
             <button
               onClick={() => setSelected(t.name)}
-              className={`flex w-full items-center gap-2 rounded px-2 py-1 text-left text-sm transition ${
-                selected === t.name ? "bg-emerald-500/15 text-emerald-300" : "text-gray-300 hover:bg-white/5"
-              }`}
+              className={`flex w-full items-center gap-2 rounded px-2 py-1 text-left text-sm transition ${navItem(selected === t.name)}`}
             >
               <span className="min-w-0 flex-1 truncate">{t.name}</span>
               {/* Org badge only in the cross-org ("all") view — scoped, it's redundant */}
@@ -691,9 +690,7 @@ export function TemplatesView({
                       setSeedKey((k) => k + 1); // picking = jump + reseed that scenario
                     }}
                     title={`state: ${s.name}`}
-                    className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${
-                      (liveStateName ?? activeState?.name) === s.name ? "bg-emerald-500/10 text-emerald-300" : "text-gray-400 hover:bg-white/5 hover:text-gray-200"
-                    }`}
+                    className={`block w-full truncate rounded px-2 py-0.5 text-left text-xs capitalize transition ${navSubItem((liveStateName ?? activeState?.name) === s.name)}`}
                   >
                     {s.name}
                   </button>

package/screens/chrome.ts

@@ -0,0 +1,83 @@
+/**
+ * The Studio screen shell, in one place.
+ *
+ * Every section (Apps, Components, Atoms, Styles, Skills, Prompt Blocks, Nodes) is the
+ * same anatomy: a dark navigator on the left, a white working pane on the right. That
+ * was true in spirit and false in the details — the navigators had drifted to four
+ * widths (190/220/240/330), three paddings and two completely different active states,
+ * and Styles had drifted furthest of all, painting its navigator from the THEME IT WAS
+ * PREVIEWING so a project with a white surface got a white sub-nav.
+ *
+ * These constants are the agreement. Import them; do not retype the class strings,
+ * because a retyped string is how the drift happened the first time.
+ *
+ * The reference screen is Skills: it is the one that read as finished, so its
+ * proportions (220px navigator, p-2, a readable measure on white) are the standard
+ * rather than an average of what everything else happened to be doing.
+ *
+ * This is CHROME ONLY. It says how a section frames its content, never what the content
+ * is. The dark ramp it uses (#0f141a shell → #1b2129 navigator → #232a34 panel) is
+ * Studio's own and is never derived from a project's tokens; see DesignSystemView for
+ * the one screen where that distinction actually bites.
+ */
+
+/** The section itself: navigator + working pane, neither scrolling the page. */
+export const SCREEN = "grid min-h-0 flex-1 grid-cols-[220px_1fr] overflow-hidden";
+
+/**
+ * WIDER NAVIGATOR, for a navigator that is a palette rather than a list. Nodes searches
+ * and renders two-line cards, which 220px genuinely cannot hold. An exception with a
+ * reason, spelled out here so the next person does not "fix" it back to SCREEN or, worse,
+ * invent a fifth width.
+ */
+export const SCREEN_WIDE_NAV = "grid min-h-0 flex-1 grid-cols-[330px_1fr] overflow-hidden";
+
+/** The dark navigator column. */
+export const NAV = "flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#1b2129] p-2";
+
+/** A group heading inside the navigator ("PROMPTS", "PRIMARY", a category). */
+export const NAV_SECTION = "px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-gray-400";
+
+/**
+ * SELECTION STATE ONLY, never layout.
+ *
+ * The navigators legitimately differ in row geometry — a Skills row is two lines, a
+ * Templates row is a flex row with a chip, a Components row opens a state tree — and
+ * flattening that into one class string would change row heights across five screens to
+ * buy nothing. What must NOT differ is what "selected" looks like, and that is what these
+ * return. Call sites keep their own layout classes and append one of these.
+ *
+ * Emerald is Studio's selection colour and is deliberately NOT any project's action
+ * colour, so a loud brand cannot restyle the chrome around its own preview.
+ */
+export const navItem = (active: boolean) =>
+  active ? "bg-emerald-500/15 text-emerald-300" : "text-gray-300 hover:bg-white/5";
+
+/** A nested navigator entry (a state under a component, a token group under a section). */
+export const navSubItem = (active: boolean) =>
+  active ? "bg-emerald-500/10 text-emerald-300" : "text-gray-400 hover:bg-white/5 hover:text-gray-200";
+
+/** The common one-line row. Compose with `navItem`; two-line rows add their own padding. */
+export const NAV_ITEM = "block w-full rounded px-2 py-1 text-left text-sm transition";
+
+/** The common nested row. Compose with `navSubItem`. */
+export const NAV_SUBITEM = "block w-full truncate rounded px-2 py-0.5 text-left text-xs transition";
+
+/** The working pane. White, and the only thing that scrolls. */
+export const PANE = "min-h-0 min-w-0 overflow-auto bg-white";
+
+/**
+ * Reading content inside the pane — a skill's instructions, a prompt block, anything
+ * whose job is to be READ. Capped at a readable measure and centred.
+ */
+export const DOC = "mx-auto max-w-3xl p-8";
+
+/**
+ * Browsing content inside the pane — swatch grids, galleries, anything laid out across
+ * the full width. Same padding as DOC so the two feel like one application; no measure
+ * cap, because capping a gallery just wastes the screen.
+ */
+export const GALLERY = "p-8";
+
+/** The empty state, before anything is selected. Same words shape everywhere: "Select a …". */
+export const EMPTY = "flex h-full items-center justify-center text-sm text-gray-500";

package/screens/index.ts

@@ -12,6 +12,10 @@
  * Consumed as SOURCE via a bundler alias, the same convention `@unoverse/sdk`
  * already uses. No build step, no publish cycle, no stale dist.
  */
+// The screen shell (navigator + working pane) every section is built from. Exported so a
+// host's own screens can sit beside these without re-deriving the chrome by eye, which is
+// exactly how the navigators drifted to four widths and two selection colours.
+export * from "./chrome";
 export { ComponentsView } from "./ComponentsView";
 export { AtomsView } from "./AtomsView";
 export { TemplatesView } from "./TemplatesView";

package/src/NodesView.tsx

@@ -11,6 +11,7 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { authedFetch, usePersistentState, useRegistryToggles, ToggleSwitch } from "./host";
 import { ConfigForm, defaultsFromSchema } from "@unoverse/studio";
 import { NodeKeys, type CredentialType } from "./NodeKeys";
+import { NAV, SCREEN_WIDE_NAV } from "../screens/chrome";
 
 interface NodeInput {
   name: string;
@@ -294,9 +295,9 @@ export function NodesView() {
   }
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[330px_1fr] overflow-hidden">
+    <div className={SCREEN_WIDE_NAV}>
       {/* PALETTE — Canvas-style searchable node cards */}
-      <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#1b2129] p-3">
+      <nav className={NAV}>
         <div className="relative mb-3">
           <input
             value={query}

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

@@ -30,8 +30,21 @@ manifest, no folders. Structure is EARNED; start flat.
 ## The state model (v2): data + a state tree
 
 A component is **data plus a state tree**; each state owns the layout(s) that draw it.
-The root's `state:` block IS the design, readable top to bottom. The canonical shape
-(a product-card component: a grid state and a detail page with nested steps):
+The root's `state:` block IS the design, readable top to bottom.
+
+> **THE GATE — answer this before adding ANY state to `view`:**
+> *"Would a hosting template rearrange the page to show this?"*
+> **No → it's a private step**: nest it under `on:` inside an existing public state.
+> **Yes → public.**
+> ⚠ "The user asked for N states" never means N public states. In-place swaps
+> (confirmation, success, empty, error, loading, a form's next step) are almost always
+> PRIVATE. Privacy is the default; promotion to `view` is a deliberate act with a
+> template consequence.
+
+The canonical shape (a product-card component). Note where each state landed and why:
+`products` and `detail` are PUBLIC because a template genuinely rearranges for each (a
+grid rail vs a full page); `detail`'s inner `detail`/`apply` are PRIVATE steps because
+applying swaps content in place — the page does not move:
 
 ```yaml
 state:
@@ -65,9 +78,13 @@ The rules, in the order they bite:
 - **Public states are the top level of the `view` axis** and they are the template's
   WHOLE vocabulary: everything templates can react to, nothing more. Steps nest
   privately (`on: <key>` + `initial` + `states`), invisible outside the component.
-  The placement rule: **if the template must rearrange to show it, make it public;
-  if the template wouldn't move, nest it privately.** Privacy is the default;
-  promotion is deliberate.
+  The placement rule is THE GATE above: **if the template must rearrange to show it,
+  make it public; if the template wouldn't move, nest it privately.** Privacy is the
+  default; promotion is deliberate.
+  **The tell in Studio:** non-initial public states preview FULL-BLEED (no stage
+  padding), precisely because they are template-liftable surfaces. If a state you
+  meant as an in-place swap suddenly renders edge-to-edge, you promoted a private
+  step to `view` — move it into the nest.
 - **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
@@ -280,5 +297,7 @@ component. Its key nouns/verbs must appear in `whenToUse`'s first sentence.
 4. Publish from Studio; its lint must report 0 errors (the rules are v2-aware and cite
    the doc for every rule).
 5. Restart unoverse → Studio: mock (prop defaults + the state switcher reads the tree:
-   public states on top, steps beneath by state name), then live. Debug: stream log →
-   state inspector → definition; never guess.
+   public states on top, steps beneath by state name), then live. Sanity-check the
+   switcher against THE GATE: every entry in its top row is a promise that a template
+   will rearrange for it, and a non-initial public state previews full-bleed. Debug:
+   stream log → state inspector → definition; never guess.