unoverse 0.1.186 → 0.1.187

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unoverse",
-  "version": "0.1.186",
+  "version": "0.1.187",
   "description": "The Unoverse front door — create a Studio project, a universe, or a client app, and launch Studio.",
   "license": "SEE LICENSE IN README.md",
   "type": "module",

package/vendor/base/lint/design/file.mjs

@@ -45,6 +45,46 @@ function checkProps(props, file, report, path) {
   }
 }
 
+/**
+ * THE DISCOVERY META CONTRACT (docs.unoverse.ai/nodes/node-discoverability).
+ * Four fields, one job each, and the SAME rules for a component, a template and an app:
+ * all three are ranked against what a PERSON said, so an app gets these errors rather
+ * than the warnings it used to get.
+ *
+ * The embedded text is "<title>. <whenToUse> <description>" (runtime/bootstrap.ts), so a
+ * missing title means the def name, or the folder slug, is the first token the ranker
+ * sees. That is a warning rather than an error: the fallback is fine when the name
+ * already reads as the thing.
+ */
+const SELECTOR_SHAPED = /\b(pick when|pick whenever|pick for|use (this|when)|when the (user|customer|learner|caller) (asks|wants|says|needs|expresses)|select (this|when))\b/i;
+const MECHANISM_WORDS = /(two-column|\blayout\b|componentslot|\bstreamed\b|\bskeleton\b|\bfull-height\b|\bshell\b)/i;
+
+function checkDiscoveryMeta(report, file, json, kind, docs) {
+  const desc = typeof json.description === "string" ? json.description.trim() : "";
+  if (desc.length < 20)
+    report("error", file, `discovery manifest.description missing/too short. One line (\u226520 chars) saying what the ${kind} IS (${docs})`);
+  else if (desc.length > 120)
+    report("error", file, `discovery manifest.description is ${desc.length} chars: it's the listing subtitle (\u2264120); move detail into whenToUse (${docs})`);
+  if (/\buse when\b/i.test(desc))
+    report("error", file, `discovery manifest.description smuggles "use when\u2026". Description says what it IS; routing text belongs in whenToUse (${docs})`);
+
+  const wtu = typeof json.whenToUse === "string" ? json.whenToUse.trim() : "";
+  if (wtu.length < 20)
+    report("error", file, `discovery manifest.whenToUse missing/too short. The utterance-shaped selection text findIntent ranks on (${docs})`);
+  else {
+    if (SELECTOR_SHAPED.test(wtu))
+      report("error", file, `discovery manifest.whenToUse is selector-shaped. Write the words the USER would say, not instructions about the user (${docs})`);
+    const mech = wtu.match(MECHANISM_WORDS);
+    if (mech)
+      report("error", file, `discovery manifest.whenToUse leads with mechanism ("${mech[0]}"), so it ranks near layout vocabulary instead of the job. Outcome first (${docs})`);
+  }
+
+  if (!(typeof json.title === "string" && json.title.trim()))
+    report("warn", file, `discovery manifest has no "title". The embedding is "<title>. <whenToUse> <description>", so the name or the folder slug leads it instead (${docs})`);
+  if (!(typeof json.category === "string" && json.category.trim()))
+    report("warn", file, `discovery manifest has no "category". Name the domain of the job, never the implementation (${docs})`);
+}
+
 export function makeLintFile(ctx) {
   const { report, walkNode, isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePart, defRoot, componentNamesForFile, DS, orgDirs, RX, readText } = ctx;
 
@@ -201,8 +241,8 @@ function lintFile(file) {
     const root = dirname(file);
     if (isAppPath(file)) {
       // TEMPLATE manifest = the envelope. Requires binding + a resolvable root.
-      for (const req of ["name", "whenToUse"])
-        if (!json[req]) report("warn", file, `template manifest missing "${req}": ${req === "whenToUse" ? "the AI selects the app by it" : "the display name"} (docs.unoverse.ai/design/apps)`);
+      if (!json.name) report("warn", file, `app manifest missing "name": the display name (docs.unoverse.ai/design/apps)`);
+      checkDiscoveryMeta(report, file, json, "app", "docs.unoverse.ai/design/apps");
       if (!(json.binding && json.binding.workflow))
         report("warn", file, `template manifest has no binding.workflow. The app owns its workflow binding (docs.unoverse.ai/design/apps)`);
       // Two valid roots (definitions.ts:229): the STANDARD manifest-only form (root =
@@ -331,16 +371,9 @@ function lintFile(file) {
     } else {
       // COMPONENT manifest = OPTIONAL spatial discovery. No binding. Mirrors the
       // discovery-meta assertions in server/src/runtime/microapp-structure.test.ts.
-      const desc = typeof json.description === "string" ? json.description.trim() : "";
-      if (desc.length < 20)
-        report("error", file, `discovery manifest.description missing/too short. One line (≥20 chars) saying what the component IS (docs.unoverse.ai/design/components)`);
-      else if (desc.length > 120)
-        report("error", file, `discovery manifest.description is ${desc.length} chars: it's the listing subtitle (≤120); move detail into whenToUse (docs.unoverse.ai/design/components)`);
-      const wtu = typeof json.whenToUse === "string" ? json.whenToUse.trim() : "";
-      if (wtu.length < 20)
-        report("error", file, `discovery manifest.whenToUse missing/too short. The utterance-shaped selection text findIntent ranks on (docs.unoverse.ai/design/components)`);
-      else if (/\b(pick when|use (this|when)|when the user|the user (asks|wants|needs)|select (this|when))\b/i.test(wtu))
-        report("error", file, `discovery manifest.whenToUse is selector-shaped. Write the words the USER would say, not instructions about the user (docs.unoverse.ai/design/components)`);
+      const isTpl = /[\\/]templates[\\/]/.test(file);
+      checkDiscoveryMeta(report, file, json, isTpl ? "template" : "component",
+        isTpl ? "docs.unoverse.ai/design/templates" : "docs.unoverse.ai/design/components");
       if (json.binding)
         report("warn", file, `a component discovery manifest has no workflow. Drop "binding" (a component is streamed or node-hydrated) (docs.unoverse.ai/design/components)`);
       // `lifetime` — OPTIONAL render lifetime (docs.unoverse.ai/design/state §Two lifetimes). Closed set:

package/vendor/base/lint/design/index.mjs

@@ -683,6 +683,67 @@ for (const orgDir of orgDirs) {
         );
   }
 
+/**
+ * ── the LATCH, on a state (docs/MCP_COMPLETE_GUIDE.md §The Component Latch) ──
+ *
+ * Declaring it makes whatever wears that face ADDRESSABLE: the pill goes up and the guest's
+ * next sentences travel to that instance instead of opening a new answer. Every finding here
+ * is something that produces a pill which looks fine and behaves wrongly, which is why they
+ * are errors rather than warnings.
+ *
+ * Read from the ENVELOPE first and the manifest second, the same order the loader reads the
+ * states tree in — a rule that judged only one home would pass whatever was authored in the
+ * other.
+ */
+const LATCH_KEYS = new Set(["title", "icon"]);
+for (const orgDir of orgDirs) {
+  const adir = join(orgDir, "apps");
+  if (!(existsSync(adir) && statSync(adir).isDirectory())) continue;
+  for (const e of readdirSync(adir)) {
+    const folder = join(adir, e);
+    let src, states;
+    try {
+      if (!statSync(folder).isDirectory()) continue;
+      // The envelope (`<name>.yaml`) is the app tree's home; the manifest is the legacy one.
+      const envelope = defPath(folder, e);
+      const manifest = defPath(folder, "manifest");
+      for (const p of [envelope, manifest]) {
+        if (!p || !existsSync(p)) continue;
+        const s = readDef(p).states;
+        if (s && typeof s === "object" && !Array.isArray(s)) {
+          src = p;
+          states = s;
+          break;
+        }
+      }
+    } catch {
+      continue; // a malformed envelope is reported elsewhere
+    }
+    if (!states) continue;
+    for (const [sname, sentry] of Object.entries(states)) {
+      const latch = sentry && typeof sentry === "object" && !Array.isArray(sentry) ? sentry.latch : undefined;
+      if (latch === undefined) continue;
+      if (typeof latch !== "object" || latch === null || Array.isArray(latch)) {
+        report("error", src, `state "${sname}": "latch" must be a block ({ title, icon }), not ${Array.isArray(latch) ? "a list" : typeof latch}. Presence is what makes a state addressable, so a malformed one is an intent nothing can honour (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`);
+        continue;
+      }
+      // The pill is the ONLY sign the guest has that their words are landing on this page
+      // rather than the conversation. Unlabelled, it says nothing — and the compiler drops
+      // a titleless block, so the state would silently stop being addressable.
+      if (typeof latch.title !== "string" || !latch.title.trim())
+        report("error", src, `state "${sname}": "latch" needs a "title" — it is what the pill reads, and the pill is the only thing telling the guest what they are addressing. Name the thing, not the verb ("Your Perfect Day", not "Edit the day")`);
+      const extra = Object.keys(latch).filter((k) => !LATCH_KEYS.has(k));
+      if (extra.length)
+        report("error", src, `state "${sname}": "latch" has no key(s) ${extra.join(", ")}. The block is exactly ${[...LATCH_KEYS].join(", ")} — an invented key is silently ignored, so whatever it was meant to do never happens. The pill's colours belong to the design system's composer-bar, never to a state`);
+      // A STATE NOTHING CAN ENTER CANNOT BE ADDRESSED. The base state is the app at rest —
+      // the conversation itself — and `stateOrder` excludes it, so `resolveLatch` can never
+      // rank a base-state instance and the pill would never appear.
+      if (sname === Object.keys(states)[0])
+        report("error", src, `state "${sname}": it is the BASE state — the app at rest, which the priority ladder excludes by construction (stateOrder is every state BUT the base). A latch here can never resolve, so no pill would ever draw. Declare it on a state something ARRIVES into`);
+    }
+  }
+}
+
 // ── lifecycle declarations (the ONE sanctioned code carve-out) ──
 // A component may run server-side code at a platform fire point, and the safety of that
 // rests on the manifest and the thing that runs agreeing. Both halves are checked here so
@@ -691,7 +752,6 @@ for (const orgDir of orgDirs) {
 const KNOWN_LIFECYCLES = new Set(["onStart", "onEnterView"]);
 const PHASES_WITH_LAYOUTS = new Set(["onEnterView"]); // phases that fire per VIEW
 const PLATFORM_HANDLERS = new Set(["getDetail"]); // named handlers needing no file
-const LATCH_KEYS = new Set(["title", "background", "color"]);
 
 // Every credential DEFINITION this universe can offer a form for. They ship with node
 // packages (nodes/<pkg>/credentials/<name>.yaml); a component NAMES one, it never defines
@@ -782,61 +842,23 @@ for (const orgDir of [DS, ...orgDirs]) {
         report("error", join(folder, f), `${f} is a lifecycle handler no manifest opted into. Add "${f.slice(0, -3)}" to the manifest's lifecycle array, or delete the file — un-opted code never runs`);
 
     /**
-     * LATCH (docs/MCP_COMPLETE_GUIDE.md §The Component Latch). Declaring it makes the
-     * component addressable: the pill goes up and the guest's next sentences travel to THIS
-     * instance. Every finding here is something that produces a pill which looks fine and
-     * behaves wrongly, which is why they are errors rather than warnings.
+     * LATCH, RETIRED FROM THE MANIFEST (2026-08-31, MCP guide §The Component Latch).
+     *
+     * It moved to the STATE, in the app's own tree, beside that state's `layout:` and
+     * `preview:`. A component said one thing about itself for the whole of its life, but a
+     * page is addressable when it IS the page and not when it is a summary in the flow, and
+     * only the state knows which of those is on screen.
+     *
+     * An ERROR rather than a silent ignore: nothing reads this key any more, so a manifest
+     * still carrying it declares an intent that never happens, and the author has no way to
+     * tell that from a latch that simply does not work.
      */
-    let latch;
-    try {
-      latch = readDef(mf).latch;
-    } catch {
-      latch = undefined; // malformed manifest is reported elsewhere
-    }
-    if (latch !== undefined) {
-      if (typeof latch !== "object" || latch === null || Array.isArray(latch)) {
-        report("error", mf, `"latch" must be a block ({ title, icon, background, color }), not ${Array.isArray(latch) ? "a list" : typeof latch}. Presence is what makes a component latchable, so a malformed one is an intent nothing can honour (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`);
-      } else {
-        // The pill is the ONLY sign the guest has that their words are landing on this
-        // component rather than the conversation. Unlabelled, it says nothing.
-        if (typeof latch.title !== "string" || !latch.title.trim())
-          report("error", mf, `"latch" needs a "title" — it is what the pill reads, and the pill is the only thing telling the guest what they are addressing. Name the thing, not the verb ("Booking", not "Edit booking")`);
-
-        const extra = Object.keys(latch).filter((k) => !LATCH_KEYS.has(k));
-        if (extra.length)
-          report("error", mf, `"latch" has no key(s) ${extra.join(", ")}. The block is exactly ${[...LATCH_KEYS].join(", ")} — an invented key is silently ignored, so whatever it was meant to do never happens`);
-
-        // Same law as every other surface: tokens, never hex. ABSTAINS where the token set
-        // cannot be read, exactly as checkToken does — judging against half a set rejects
-        // correct work.
-        const T = tokensForFile(mf);
-        if (T) {
-          for (const k of ["background", "color"])
-            if (typeof latch[k] === "string" && latch[k].trim() && !T.color.has(latch[k]))
-              report("error", mf, `latch.${k}: "${latch[k]}" is not a colour token. Unknown names reach CSS verbatim and are dropped, so the pill renders unstyled with no error anywhere. Known: ${[...T.color].sort().join(", ") || "none"} (docs.unoverse.ai/design/styles-and-tokens)`);
-        }
-
-        /**
-         * TWO CONTRADICTORY DECLARATIONS. A latch says "the conversation is now ABOUT this
-         * instance", which is a conversation-scoped relationship; `lifetime: turn` (the
-         * default) says the instance is done being the subject at the end of this turn.
-         * One manifest cannot mean both.
-         *
-         * NOT because typing wipes it — it does not. The new-turn reset (`beginExchange`)
-         * is GONE (store.ts, the seven rules, rule 7: "typing changes NOTHING by itself"),
-         * so a turn-lifetime page survives the guest's next message and a latch on it
-         * appears to work. It comes apart LATER and conditionally: `supersede` retracts a
-         * non-durable slice when another component arrives into the SAME state, and
-         * `cancelBelow` / `closeSurfaces` release it on a higher arrival or a guest close.
-         * Each skips `lifetime: "conversation"` and nothing else. The pill is derived from
-         * the slice, which survives the retract, so it stays up pointing at a page that has
-         * left the surface. Intermittent, silent, and indistinguishable from the latch
-         * "just not working" — which is why it is caught here rather than lived with.
-         */
-        if (readDef(mf).lifetime !== "conversation")
-          report("error", mf, `"latch" needs "lifetime: conversation". A latch makes the conversation ABOUT this instance, which outlives a turn; the default turn lifetime says the opposite. Concretely: another component arriving into this component's state retracts it to inline (store.ts supersede) while the pill — derived from the surviving slice — stays up, so the guest goes on addressing a page that has left the surface (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`);
-      }
-    }
+    if (readDef(mf).latch !== undefined)
+      report(
+        "error",
+        mf,
+        `"latch" is no longer a manifest key — it moved to the STATE (2026-08-31). Declare it on the app state this component is addressable IN, beside that state's layout: \`states: { <state>: { layout: ..., latch: { title: "..." } } }\`. Nothing reads a manifest latch, so this one produces no pill (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`,
+      );
   }
 }