@unoverse-platform/studio 0.1.89 → 0.1.91

package/vendor/base/src/lint/design/walk.mjs

@@ -0,0 +1,444 @@
+/**
+ * The per-node structural walk: primitives, style keys, conditions, dimensions, slots.
+ *
+ * This is the hot path of the linter. Every node of every definition passes through it,
+ * and it is where LAW 1 (tokens only, never a raw px or hex) and the closed style
+ * vocabulary are enforced.
+ *
+
+ * These rules close over the run: the design-system location, the token scale, which refs
+ * resolve, which app sizes exist. Rather than thread ten parameters through a recursive
+ * walk, each module exports a MAKER that takes the context once and returns the function.
+ *
+ * The context is created per run by index.mjs, so nothing survives between runs.
+ */
+import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
+import { join, dirname, basename, relative, sep } from "node:path";
+import { PRIMITIVES, CONDITION_KEYS, STYLE_KEYS, RAW_VALUE, CHILD_NODE_KEYS, PARTIAL_DIRS, DIMENSION_KEYS, UNIVERSAL_PROPS, PRIMITIVE_PROPS, PRIMITIVE_BINDS } from "./vocabulary.mjs";
+import { isDefFile, defName, defPath, readDef } from "./defs.mjs";
+
+// THE FOUR WORDS and the two closed blocks (UNOVERSE_TEMPLATE_MODEL.md §9b + §9e).
+const SECTION_WORDS = ["static", "copywriter", "director"];
+const DELIVERY_KEYS = ["state", "pick", "rules", "preview"];
+// §9e: a queried place says WHAT draws it, WHAT it asks, WHAT KIND may answer, HOW MANY.
+const SEARCH_KEYS = ["component", "type", "include", "pick", "items"];
+// The `object_type`s a place may admit. Apps and skills are absent by construction: the
+// page's own searches are SILENT (no app unlocked, no tool minted, no card lane, no
+// director woken), or every place would rain cards onto a page still assembling itself.
+const QUERY_TYPES = ["services", "images", "needs", "actions"];
+
+export function makeWalkNode(ctx) {
+  const { report, checkCondition, checkDimension, checkToken, appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists, stepList, spaceSteps, isAppPath, isTemplatePath, defRoot } = ctx;
+  // One director per LAYOUT FILE, tracked for this run only (each file is walked once).
+  const directorsSeen = new Map();
+
+function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
+  if (Array.isArray(node)) return node.forEach((n) => walkNode(n, file, root, widthCap));
+  if (!node || typeof node !== "object") return;
+
+  // $include — resolves against the DEFINITION ROOT (layouts/ states/ components/…)
+  if (typeof node.$include === "string") {
+    const a = defPath(root, node.$include);
+    const b = join(root, node.$include);
+    if (!a && !existsSync(b))
+      report("error", file, `$include "${node.$include}" does not resolve under ${relative(process.cwd(), root)}/ (docs.unoverse.ai/design/components)`);
+    return; // the included file is linted on its own
+  }
+
+  // THE THREE WORDS (UNOVERSE_TEMPLATE_MODEL.md §9b): a template layout's parts say HOW
+  // they are filled instead of naming a primitive. They compile to ComponentSlots at
+  // serve time, so the linter checks the authored word here and hands the rest of the
+  // node to the ordinary walk as the slot it becomes.
+  const word = SECTION_WORDS.find((w) => node[w] !== undefined);
+  if (word && node.type === undefined) {
+    if (!isTemplatePath(file))
+      report("error", file, `"${word}:" is template grammar — only a template layout's parts say how they are filled. Apps and components author ComponentSlot directly (UNOVERSE_TEMPLATE_MODEL §9b)`);
+    if (node.query !== undefined) {
+      report("error", file, `"query:" is retired vocabulary (§9e rule 10b REVERSED 2026-09-02) — spell the place director: with the same component/items/type/include/pick. One word, one judge`);
+    }
+    if (word === "director") {
+      /**
+       * ONE WORD, TWO MODES (§9e, 2026-09-02): a director place WITH `component` is a
+       * SEARCH place (the page fetches its own content); WITHOUT one it is a DELIVERY
+       * band (the conversation fills it). The key sets are mutually exclusive, so a
+       * place is always unambiguously one or the other — behaviour never forks on a
+       * stray key. The QUESTION is never authored (rule 10d): it is derived from the
+       * writing, the page's pool, the component's contract, or the guest's ask.
+       */
+      const d = node.director;
+      if (!d || typeof d !== "object" || Array.isArray(d)) {
+        report("error", file, `"director:" is a block, not a path (§9b rule 1)`);
+      } else if (d.limit !== undefined) {
+        report("error", file, `director.limit is retired — the one cap word is "pick": how many the director keeps (§9e rule 9, renamed 2026-09-02)`);
+      } else if (d.ask !== undefined || d.query !== undefined) {
+        report("error", file, `a director place never states its question — it is DERIVED (§9e rule 10d): the writer's headings (items), the page's pool (a gallery), the component's own contract, or the guest's ask`);
+      } else if (typeof d.component === "string" && d.component) {
+        // A SEARCH PLACE. The checks here are the ones that fail SILENTLY at runtime: a
+        // place missing include or pick is skipped, and a kind nobody stores draws
+        // nothing — both read as "the design is broken" with no log saying why.
+        //
+        // THE SEARCH WORDS SIT ON THE THING THAT SEARCHES (owner ruling 2026-09-02): on
+        // an items place each ITEM searches, so type/include/pick nest INSIDE items:
+        // beside min/max, and pick reads unambiguously as per-item. Spelled flat, the
+        // same word meant two scopes depending on whether items: was present.
+        const itemed = d.items && typeof d.items === "object" && !Array.isArray(d.items);
+        if (d.items !== undefined && !itemed)
+          report("error", file, `director.items is a block — items: { min, max, type, include, pick } (§9e rule 10c)`);
+        if (itemed && (d.type !== undefined || d.include !== undefined || d.pick !== undefined))
+          report("error", file, `an items place nests its search words INSIDE items: { min, max, type, include, pick } — each ITEM searches, so pick reads per item (§9e rule 10c, 2026-09-02)`);
+        const TOP_KEYS = itemed ? ["component", "items"] : SEARCH_KEYS;
+        for (const k of Object.keys(d))
+          if (!TOP_KEYS.includes(k))
+            report("error", file, `a search place has no "${k}". It reads ${TOP_KEYS.map((x) => `"${x}"`).join(", ")} (§9e; "state"/"rules" belong to a delivery band — a place with a component is governed by the page's brief)`);
+        if (!defPath(root, d.component) && !existsSync(join(root, d.component)))
+          report("error", file, `director.component "${d.component}" does not resolve under ${relative(process.cwd(), root)}/ (§9e)`);
+        const ITEM_KEYS = ["min", "max", "type", "include", "pick"];
+        if (itemed) {
+          for (const k of Object.keys(d.items))
+            if (!ITEM_KEYS.includes(k))
+              report("error", file, `director.items has no "${k}". It reads ${ITEM_KEYS.map((x) => `"${x}"`).join(", ")} (§9e rule 10c)`);
+          const { min, max } = d.items;
+          if (typeof min !== "number" || typeof max !== "number" || min < 1 || max < min)
+            report("error", file, `director.items carries { min, max } — how many items the writer may shape, 1 <= min <= max (§9e rule 10c)`);
+        }
+        // The search words, read where they live: the place itself, or each item.
+        const s = itemed ? d.items : d;
+        const at = itemed ? "director.items" : "director";
+        // REQUIRED, both (2026-09-01, carried over). The engine supplies NO defaults: a
+        // default include or pick would be one template's answer written into the platform.
+        if (s.include === undefined)
+          report("error", file, `${at}.include is REQUIRED on a search place — what KIND may answer; the engine has no default kind (§9e rule 6)`);
+        else if (!Array.isArray(s.include) || s.include.some((t) => typeof t !== "string"))
+          report("error", file, `${at}.include is an array of result types — ${QUERY_TYPES.map((t) => `"${t}"`).join(", ")} (§9e rule 6)`);
+        else
+          for (const t of s.include)
+            if (!QUERY_TYPES.includes(String(t)))
+              report("error", file, `${at}.include has no "${t}". A place may admit ${QUERY_TYPES.map((x) => `"${x}"`).join(", ")}; apps and skills are never included, because the page's own searches are SILENT (§9e rule 6)`);
+        if (s.pick === undefined)
+          report("error", file, `${at}.pick is REQUIRED — how many the director keeps${itemed ? " PER ITEM" : ""}; the engine has no default count (§9e rule 9)`);
+        else if (typeof s.pick !== "number" || s.pick < 1)
+          report("error", file, `${at}.pick is a NUMBER — how many the director keeps${itemed ? " per item" : ""}, a cap the machine enforces (§9e rule 9)`);
+        // `type` is OPTIONAL since the question derives (rule 10d): authored it stands;
+        // absent, a contract subject searches as intent and the guest's ask as discovery.
+        if (s.type !== undefined && s.type !== "discovery" && s.type !== "intent")
+          report("error", file, `${at}.type is "discovery" (what lives around a topic) or "intent" (a named need) — or omitted, and the derivation decides (§9e rule 10d)`);
+      } else {
+        // A DELIVERY BAND.
+        for (const k of Object.keys(d))
+          if (!DELIVERY_KEYS.includes(k))
+            report("error", file, `a delivery band has no "${k}". It reads ${DELIVERY_KEYS.map((x) => `"${x}"`).join(", ")} (§9b; a place that names a component is a search place)`);
+        if (d.pick !== undefined && (typeof d.pick !== "number" || d.pick < 1))
+          report("error", file, `director.pick is a NUMBER — how many the director keeps, a cap the machine enforces (§9e rule 9)`);
+        if (d.rules !== undefined && typeof d.rules !== "string")
+          report("error", file, `director.rules is written like a brief: one string of English (§9b)`);
+        if (d.preview !== undefined && (!Array.isArray(d.preview) || d.preview.some((c) => typeof c !== "string")))
+          report("error", file, `director.preview is an array of component names — Studio's stand-ins until a real run exists (§9b rule 6)`);
+        else if (Array.isArray(d.preview)) {
+          const comps = componentNamesForFile(file);
+          for (const c of d.preview)
+            if (comps && !comps.has(String(c).toLowerCase()))
+              report("error", file, `director.preview names unknown component "${c}". No match in the design system or this org's components (lookup is case-insensitive)`);
+        }
+        // A PLACE NEEDS NO NAME (§9d): the compiler addresses delivery bands by
+        // position; an AUTHORED state: still stands (the flat-email pin), so two bands
+        // pinned to the SAME face remains the one genuine ambiguity.
+        const seen = directorsSeen.get(file) ?? [];
+        const face = typeof d?.state === "string" ? d.state : null;
+        if (face && seen.includes(face))
+          report("error", file, `two directed bands claim the face "${face}". A face has exactly one surface, or the active one is ambiguous (§9b rule 3, the reaction contract)`);
+        directorsSeen.set(file, [...seen, face]);
+      }
+    } else if (typeof node[word] !== "string") {
+      report("error", file, `"${word}:" links a component by PATH (${word}: components/<part>) — that is what makes it a known part (§9b rule 1)`);
+    } else {
+      const path = node[word];
+      if (!defPath(root, path) && !existsSync(join(root, path)))
+        report("error", file, `${word} "${path}" does not resolve under ${relative(process.cwd(), root)}/ (§9b rule 1)`);
+    }
+    // Everything else on the line rides through to the slot it compiles into. The select
+    // is SYNTHESIZED here exactly as the compiler builds it (a linked part claims its own
+    // face, limit 1; the director's claim is its `state:` pin) so the rest of the walk
+    // sees what will actually be served — and an authored one is the ceremony §9b rule 9
+    // exists to abolish.
+    if (node.select !== undefined)
+      report("error", file, `a template part never authors "select" — the three words compile to the wire primitives at serve time (§9b rule 9)`);
+    const { static: _s, copywriter: _c, director: _d, query: _q, select: _sel, ...rest } = node;
+    // An unpinned director claims the OWNING STATE's name (arrivals keep their own state
+    // and the template's states react by name — the free grid↔page dance), so the face
+    // comes from whichever state in the envelope declares this layout.
+    const owningState = () => {
+      const env = defPath(root, basename(root));
+      const states = env ? readDef(env)?.states : undefined;
+      if (!states || typeof states !== "object") return undefined;
+      const here = defName(basename(file));
+      return Object.keys(states).find((s) => {
+        const l = states[s]?.layout;
+        return typeof l === "string" && basename(l).toLowerCase() === here.toLowerCase();
+      });
+    };
+    // A QUERIED place links its component under `component:`, and claims that part's own
+    // face at limit 1 exactly as a linked part does — its `limit:` counts ROWS inside the
+    // part, not instances of it, so it never reaches the slot (§9e).
+    const linkedPath = word === "query" ? node.query?.component : node[word];
+    const face =
+      word === "director" ? (node.director?.state ?? owningState()) : typeof linkedPath === "string" ? linkedPath.split("/").pop() : undefined;
+    const limit = word === "director" ? node.director?.limit : 1;
+    const select = { from: "all", ...(face ? { where: { field: "state", eq: face } } : {}), ...(typeof limit === "number" ? { limit } : {}) };
+    return walkNode({ type: "ComponentSlot", select, ...rest }, file, root, widthCap);
+  }
+
+  const t = node.type;
+  if (typeof t !== "string")
+    report("error", file, `node without "type" (and no $include). Every node names a primitive (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
+  else if (!PRIMITIVES.has(t))
+    report("error", file, `unknown primitive "${t}". The set is closed; compose, don't invent (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
+
+  // WHAT THIS PRIMITIVE IS (UNOVERSE_CONFORMANCE §2a). Before this existed, every node
+  // shared one bag of 36 optional properties, so a wrong field name was accepted by the
+  // schema AND the lint and only showed up as a blank on screen. A wrong name is never a
+  // judgment call, so this is an error rather than a warning.
+  else if (PRIMITIVE_PROPS[t]) {
+    const own = PRIMITIVE_PROPS[t];
+    for (const k of Object.keys(node))
+      if (!UNIVERSAL_PROPS.has(k) && !own.includes(k))
+        report("error", file, `${t} has no "${k}". It reads ${own.length ? own.map((o) => `"${o}"` ).join(", ") : "no properties of its own"} (docs.unoverse.ai/reference/primitives)`);
+
+    // `bind` maps a target onto a data field, and only some targets are read. Binding a
+    // target the view never looks at is the silent failure this whole rule exists for:
+    // the field streams in correctly and the element keeps drawing its preview default.
+    const reads = PRIMITIVE_BINDS[t];
+    if (reads && node.bind && typeof node.bind === "object" && !Array.isArray(node.bind))
+      for (const k of Object.keys(node.bind))
+        if (!reads.includes(k))
+          report("error", file, `${t} never reads "bind.${k}", so the value would arrive and render nothing. It reads ${reads.map((r) => `"bind.${r}"`).join(", ")} (docs.unoverse.ai/reference/primitives)`);
+  }
+
+  if (t === "Switch") {
+    if (typeof node.on !== "string" || !node.cases || typeof node.cases !== "object")
+      report("error", file, `Switch needs "on" (the discriminant field) + "cases" (docs.unoverse.ai/design/state)`);
+    else
+      for (const [caseKey, branch] of Object.entries(node.cases)) {
+        const vw = branch && typeof branch === "object" ? branch.visibleWhen : undefined;
+        const guarded = typeof vw === "string" ? vw : vw && typeof vw === "object" ? vw.field : null;
+        if (guarded === node.on)
+          report("error", file, `Switch on "${node.on}" → case "${caseKey}" re-guards its own discriminant. A layer never guards itself; delete the visibleWhen (docs.unoverse.ai/design/components)`);
+      }
+  }
+  // Each: an `item` + a list — EITHER a literal `items:[]` (hardcoded content,
+  // the microapp default) OR `bind.items` (a workflow-fed array).
+  if (t === "Each") {
+    const hasList = Array.isArray(node.items) || (node.bind && typeof node.bind === "object" && node.bind.items);
+    if (!node.item || !hasList)
+      report("error", file, `Each needs "item" + a list. Literal "items": [...] or "bind": { "items": "<field>" } (docs.unoverse.ai/design/components)`);
+  }
+  if (t === "Ref") {
+    if (typeof node.ref !== "string")
+      report("error", file, `Ref needs "ref": "<atom name>" (docs.unoverse.ai/design/components)`);
+    else if (atomsDirExists && !refResolves(node.ref, file))
+      report("error", file, `Ref "${node.ref}". No matching atom, shared component, or own-org component (bare, or "<org>/<name>" for the file's OWN org only — org-privacy); lookup is case-insensitive by name`);
+    // RESOLVES IS NOT ENOUGH. Ref lookup ignores case; the marketplace fetches
+    // items/<kind>/<key>.json off a case-sensitive host. A Ref that differs only in case
+    // renders forever in design/ and 404s on install (index.mjs, canonicalRef).
+    else if (canonicalRef) {
+      const exact = canonicalRef(node.ref);
+      if (exact && exact !== node.ref)
+        report("warn", file, `Ref "${node.ref}" should be "${exact}". It resolves here because lookup ignores case, and fails on install because the marketplace does not`);
+    }
+    // A KEY THE ATOM DOES NOT DECLARE MATCHES NOTHING, IN SILENCE.
+    //
+    // `props` remaps the atom's own field names onto the host's and `with` supplies
+    // literals for them: both are looked up BY NAME against the atom's `props` block, and
+    // the expander ignores anything it cannot find. So a wrong name is not a broken tree,
+    // it is a perfect-looking element wired to nothing.
+    //
+    // It has cost real screens. `form-toggle` declares `on` and `description`; a form wrote
+    // `props: { value: … }` with `with: { help: … }` and got a switch bound to no field and
+    // a sub-line that never appeared. Every node was structurally valid, every other rule
+    // passed, and the control simply did not move when clicked.
+    if (typeof node.ref === "string" && declaredProps) {
+      const declared = declaredProps(node.ref);
+      // null = not an atom (a shared component declares no prop contract) or unreadable.
+      // Never invent a contract the author would then have to satisfy.
+      if (declared) {
+        for (const [key, source] of [["props", node.props], ["with", node.with]]) {
+          if (!source || typeof source !== "object" || Array.isArray(source)) continue;
+          for (const name of Object.keys(source)) {
+            if (declared.has(name)) continue;
+            const known = [...declared].sort().join(", ");
+            report(
+              "error",
+              file,
+              `Ref "${node.ref}" ${key === "props" ? "remaps" : "passes"} "${name}", which the atom does not declare. ` +
+                `Both \`props\` and \`with\` are matched BY NAME against the atom's own props, and an unknown key is ` +
+                `silently ignored: the element renders and does nothing. ${node.ref} declares: ${known} (docs.unoverse.ai/design/components)`,
+            );
+          }
+        }
+      }
+    }
+  }
+  // Icon glyphs are SERVED (theme.icons ← styles/semantic/icons), and the SDK draws
+  // nothing when the name misses — a blank where a glyph was meant to be, no error.
+  if (t === "Icon" && typeof node.icon === "string" && !node.icon.includes("{{"))
+    checkToken(file, t, "icon", node.icon);
+  if (t === "ComponentSlot") {
+    if (!node.select || typeof node.select !== "object")
+      report("error", file, `ComponentSlot needs "select" ({} for the conversation flow) (docs.unoverse.ai/design/apps)`);
+    else if (node.select.from === "all" && !node.select.type && !node.select.where)
+      report("warn", file, `global ComponentSlot (from:"all") with no "type" and no "where". Selects OLDEST-first; a trap in a multi-turn surface. Filter by "where" (the reaction contract, §5b) or pin "type", unless the shell is deliberately catch-all (docs.unoverse.ai/design/apps)`);
+    // STATE-SELECTED UI (STATE_MODEL §5): a reaction surface reacts to the component's
+    // PUBLIC state — the `view` axis (`defaultState` = legacy alias) — never to a
+    // component's internal state (step/phase/…) which is private to the component.
+    // Selecting on any other field reaches past the boundary the whole model rests on.
+    else if (node.select.where && node.select.where.field && node.select.where.field !== "state" && node.select.where.field !== "view" && node.select.where.field !== "defaultState")
+      report("warn", file, `reaction surface selects on "${node.select.where.field}". A template reacts to a component's PUBLIC state ("state"; legacy "view"/"defaultState"), never its internal state (that is private to the component) (STATE_MODEL §5)`);
+    // ONE STATE AT A TIME: the template is in exactly one state, so a surface must
+    // claim exactly ONE view by `eq` — `ne`/`in`/bare selects make "which state is
+    // the template in?" ambiguous.
+    else if (node.select.where && (node.select.where.field === "state" || node.select.where.field === "view" || node.select.where.field === "defaultState") && typeof node.select.where.eq !== "string")
+      report("error", file, `a reaction surface claims exactly ONE view: select.where needs "eq": "<view>": ne/in/bare make the template's active state ambiguous (docs.unoverse.ai/design/state)`);
+  }
+
+  // STATE-OWNED SIZING (docs.unoverse.ai/design/apps): every PANEL states its width once via
+  // `appWidth`; the app is the sum of the open ones. A plain node = always open (the
+  // core chat column); a reaction-surface ComponentSlot = open while occupied; a
+  // visibleWhen pane = open while its condition matches.
+  if (node.appWidth !== undefined) {
+    if (typeof node.appWidth !== "string" || node.appWidth.trim() === "")
+      report("error", file, `"appWidth" must be a CSS width string ("360px", "min(50vw, 760px)") or a named app size ("chat", "rail", "panel") (docs.unoverse.ai/design/apps)`);
+    // `flex` is contract vocabulary, not a token: the surface takes the REMAINING
+    // host space (the SDK reports a full-width app while it is active).
+    // Any other bare name is a STANDARD SIZE — it must exist in the org's
+    // styles/semantic/app-sizes (or the inherited marketplace set); the server
+    // resolves it at serve time, and an unknown name resolves to NOTHING silently.
+    else if (node.appWidth !== "flex" && /^[a-z][a-z0-9-]*$/i.test(node.appWidth)) {
+      const sizes = appSizesForFile(file);
+      if (sizes && !(node.appWidth in sizes))
+        report("error", file, `"appWidth": "${node.appWidth}" names no app size. Use "flex", a CSS width, or a name from styles/semantic/app-sizes (known: ${Object.keys(sizes).join(", ") || "none"}) (docs.unoverse.ai/design/apps)`);
+    }
+    if (t === "ComponentSlot" && !(node.select && node.select.where))
+      report("error", file, `"appWidth" on a ComponentSlot without select.where. Only a reaction surface can slide out; the flow slot never sizes the app (docs.unoverse.ai/design/apps)`);
+    // ONE declaration per panel: the SDK sizes the frame FROM appWidth (width +
+    // flex: 0 0 auto) — a frame width/flex alongside it is dead duplication that
+    // can silently disagree.
+    if (t === "ComponentSlot" && node.frame && node.frame.style) {
+      for (const dup of ["width", "flex"])
+        if (node.frame.style[dup] !== undefined)
+          report("error", file, `panel frame declares style.${dup} alongside appWidth. The panel states its width ONCE; the SDK sizes the frame from appWidth. Remove the frame ${dup} (docs.unoverse.ai/design/apps)`);
+    }
+  }
+
+  // BRIEFED COMPONENTS (the composer): a `brief` sits on the node that renders what it
+  // describes and compiles into the component's MCP tool schema (server briefSchema →
+  // registry metadata.inputSchema → the minted tool). Shape is a closed contract —
+  // a typo'd key or misplaced constraint silently weakens the compiled schema.
+  if (node.brief !== undefined) {
+    const b = node.brief;
+    if (typeof b !== "string" && (typeof b !== "object" || b === null || Array.isArray(b)))
+      report("error", file, `"brief" must be a string (the description) or { description, maxLength | minItems/maxItems } (docs.unoverse.ai/design/components)`);
+    else if (typeof b === "object") {
+      // description/maxLength/minItems/maxItems COMPILE into the tool inputSchema. `hydrate` is a
+      // NON-schema brief annotation (a hydration hook naming what to hydrate) — a valid brief key
+      // that does NOT compile into the schema; allowed here so it doesn't read as a typo.
+      // `optional` marks a field the model may omit: a brief saying "empty when the source
+      // gives none" must not compile to a required, minLength-1 string, or the model has to
+      // invent a value to satisfy the schema.
+      const BRIEF_KEYS = new Set(["description", "maxLength", "minItems", "maxItems", "hydrate", "optional"]);
+      for (const k of Object.keys(b))
+        if (!BRIEF_KEYS.has(k))
+          report("error", file, `brief.${k} is not part of the brief contract. Only description / maxLength / minItems / maxItems / optional (schema) or hydrate (hydration hook) are allowed (docs.unoverse.ai/design/components)`);
+      if (b.description !== undefined && typeof b.description !== "string")
+        report("error", file, `brief.description must be a string. It IS the schema field's description (docs.unoverse.ai/design/components)`);
+      if (b.optional !== undefined && typeof b.optional !== "boolean")
+        report("error", file, `brief.optional must be a boolean (docs.unoverse.ai/design/components)`);
+      if (b.hydrate !== undefined && typeof b.hydrate !== "string")
+        report("error", file, `brief.hydrate must be a string (names the field/source to hydrate) (docs.unoverse.ai/design/components)`);
+      for (const nk of ["maxLength", "minItems", "maxItems"])
+        if (b[nk] !== undefined && (typeof b[nk] !== "number" || b[nk] < 0 || !Number.isInteger(b[nk])))
+          report("error", file, `brief.${nk} must be a non-negative integer. It compiles to the native JSON Schema keyword (docs.unoverse.ai/design/components)`);
+      if (typeof b.minItems === "number" && typeof b.maxItems === "number" && b.minItems > b.maxItems)
+        report("error", file, `brief.minItems (${b.minItems}) > maxItems (${b.maxItems}). No composition can satisfy this schema (docs.unoverse.ai/design/components)`);
+      const bound = node.bind && (node.bind.value || node.bind.src);
+      const isEach = t === "Each" && node.bind && node.bind.items;
+      if (b.maxLength !== undefined && !bound)
+        report("warn", file, `brief.maxLength on a node with no bind. A length cap only compiles when the brief sits next to the bound field it governs (docs.unoverse.ai/design/components)`);
+      if ((b.minItems !== undefined || b.maxItems !== undefined) && !isEach)
+        report("warn", file, `brief.minItems/maxItems on a non-Each node. Item counts only compile on the Each that binds the array (docs.unoverse.ai/design/components)`);
+    }
+  }
+
+  if (node.visibleWhen !== undefined) checkCondition(node.visibleWhen, file, t || "node");
+
+  // deprecated FOCUS BRIDGE (STATE_MODEL §5b): nothing writes a template `defaultState`
+  // key anymore — a component writes only its own slice; templates react via select.where.
+  // (Legit panel/draft setAppValue writes a DIFFERENT key and is untouched.)
+  //
+  const scanAction = (a) => {
+    if (!a || typeof a !== "object") return;
+    if (a.type === "setAppValue") {
+      // WHAT IS DEPRECATED IS THE FOCUS BRIDGE, not the action (2026-08-23, owner
+      // ruling). Writing `defaultState` to move the template is the bridge: a component
+      // reaching up to change which surface is shown, which the tree reacts to by name
+      // instead. Writing the template's own CHROME (openPanel, draft) is legitimate from
+      // anywhere — a `Ref`-embedded component has no slice of its own, so template state
+      // is the only state in scope, and the shared chat chrome depends on it.
+      if (Array.isArray(a.values) && a.values.some((v) => v && v.key === "defaultState"))
+        report(isAppPath(file) ? "warn" : "error", file, `setAppValue writing "defaultState" is the deprecated focus bridge. Change the view with setValue and let the template react via ComponentSlot.select.where (STATE_MODEL §5b)`);
+    }
+    if (a.then) scanAction(a.then);
+  };
+  if (node.action) scanAction(node.action);
+
+  // style — closed KEY vocabulary + real space-scale VALUES (both cross-platform contracts)
+  if (node.style && typeof node.style === "object") {
+    // a container query the element's own layout can never satisfy — the threshold is
+    // at/above an ancestor's maxWidth cap, so visibility is decided by the HOST surface,
+    // not the design (shows in a wide studio stage, vanishes in a chat column)
+    const mw = node.style.maxWidth;
+    if (typeof mw === "string" && /^\d+$/.test(mw))
+      widthCap = widthCap == null ? Number(mw) : Math.min(widthCap, Number(mw));
+    const hb = node.style.hideBelow;
+    if (typeof hb === "string" && /^\d+$/.test(hb) && widthCap != null && Number(hb) >= widthCap)
+      report("warn", file, `hideBelow "${hb}" ≥ an ancestor maxWidth "${widthCap}". The query can only be satisfied by the surrounding surface, so visibility depends on the host, not the card; lower the threshold below the card's own max width (docs.unoverse.ai/design/styles-and-tokens)`);
+    const checkKeys = (obj, where) => {
+      for (const k of Object.keys(obj)) {
+        if (k === "when") continue; // validated below
+        if (!STYLE_KEYS.has(k))
+          report("error", file, `${where}: unknown style key "${k}". The style vocabulary is closed (the cross-platform contract). Typo, or a web-ism that won't port (docs.unoverse.ai/design/styles-and-tokens)`);
+        else if ((k === "hover" || k === "active") && obj[k] && typeof obj[k] === "object")
+          checkKeys(obj[k], `${where}.${k}`);
+        else if (DIMENSION_KEYS.has(k)) checkDimension(file, where, k, obj[k]);
+        // Every OTHER value the interpreter resolves against the theme: a name that is
+        // not a token is not an error anywhere downstream, it is a dropped declaration.
+        else checkToken(file, where, k, obj[k]);
+      }
+    };
+    checkKeys(node.style, `${t}.style`);
+    // style.when = [{ field, eq|ne|in?, apply:{…} }, …]
+    if (node.style.when !== undefined) {
+      const w = node.style.when;
+      if (!Array.isArray(w))
+        report("error", file, `${t}.style.when must be an array of { field, eq|ne|in, apply } entries (docs.unoverse.ai/design/state)`);
+      else
+        for (const e of w) {
+          if (!e || typeof e !== "object" || typeof e.field !== "string" || !e.apply)
+            report("error", file, `${t}.style.when entry needs "field" + "apply" (docs.unoverse.ai/design/state)`);
+          else {
+            const extra = Object.keys(e).filter((k) => !CONDITION_KEYS.has(k) && k !== "apply");
+            if (extra.length)
+              report("error", file, `${t}.style.when: illegal key(s) ${extra.join(", ")}. Conditions are eq/ne/in/truthy only (docs.unoverse.ai/design/state)`);
+            if (typeof e.apply === "object") checkKeys(e.apply, `${t}.style.when.apply`);
+          }
+        }
+    }
+  }
+
+  for (const key of CHILD_NODE_KEYS) if (node[key] !== undefined) walkNode(node[key], file, root, widthCap);
+  if (t === "Switch" && node.cases && typeof node.cases === "object")
+    for (const branch of Object.values(node.cases)) walkNode(branch, file, root, widthCap);
+}
+
+// ── stateOrder ⇄ states/ folder cross-check ──
+
+  return walkNode;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * The linters. TWO of them, because there are two things to validate and they share
+ * almost nothing.
+ *
+ *   nodes/  node manifests: JSON Schema per part, plus the cross-file rules a schema
+ *           cannot express (events matching output connectors, calls reachable by name,
+ *           credentials declared in the package that needs them)
+ *   design/ definitions: a CLOSED primitive set, a closed style vocabulary, token-only
+ *           values, Switch discriminants, layouts reachable from a case
+ *
+ * They share `context.mjs` and nothing else. One reports on `api/run.yaml`, the other on
+ * whether a colour is a raw hex. Merging them would produce a linter that is worse at both.
+ *
+ * WHY THEY LIVE HERE rather than in scripts/. The same rules are needed by four callers,
+ * and only one of them is a terminal:
+ *
+ *   `unoverse lint` / `lint nodes`  coloured lines (scripts/lib/*.mjs, thin formatters)
+ *   Studio                          findings beside the definition being edited
+ *   POST /publish                   a refusal, so a broken definition never reaches the DB
+ *   CI                              a non-zero exit
+ *
+ * Publishing without them is the gap LOCAL_STUDIO.md:246 names: "a malformed definition is
+ * one restart from a broken server". A published row does not even need the restart.
+ */
+
+export { lintNodes, hasErrors as nodesHaveErrors } from "./nodes/index.mjs";
+export { lintDefinitions, hasErrors as definitionsHaveErrors } from "./design/index.mjs";
+export { problems, report, rel, reset } from "./context.mjs";

package/vendor/base/src/lint/nodes/blocks.mjs

@@ -0,0 +1,63 @@
+/**
+ * THE TEMPLATE VOCABULARY a manifest may use: the helpers the platform registers, and the prompt
+ * blocks it ships. Both answer the same question — "does this name resolve at run time?" — and both
+ * fail the same way if it does not: silently, at run time, in a prompt.
+ *
+ * ITS OWN MODULE TO BREAK A CYCLE. These lived in `package.mjs` after the linter was split out of
+ * scripts/, but the only consumer is `node.mjs`, and `package.mjs` already imports `node.mjs` to
+ * lint each node — so importing them back would be circular. Neither is a package-level rule
+ * anyway: they are facts about the template language, shared by every node in every package.
+ */
+import { readdirSync, existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { rel, state } from "../context.mjs";
+
+/**
+ * Handlebars built-ins plus the helpers the platform registers in
+ * engine/src/template/StringTemplateResolver.ts. Anything else compiles fine and
+ * then throws when the node actually runs, which is the worst place to find out.
+ */
+export const HANDLEBARS_HELPERS = new Set([
+  "if", "unless", "each", "with", "lookup", "log", "else", // built-in
+  "toJSON", "filter", "eq", "contains", // registered
+]);
+
+/**
+ * The prompt-block library: prompts/blocks/**\/*.md, keyed the way the resolver keys them
+ * (engine/src/template/promptBlocks.ts) — the filename camelCased, so markdown-guidelines.md is
+ * referenced as {{prompt.markdownGuidelines}}.
+ *
+ * A manifest must never hold a COPY of a block's words: that is a fork that silently stops tracking
+ * the block. It references, and this checks the reference resolves.
+ *
+ * COMPUTED PER RUN, not once at import. As a CLI this was a module-level IIFE over a `NODES_HOME`
+ * constant; the split left that constant behind and the IIFE ran at import time, so the whole linter
+ * threw `NODES_HOME is not defined` before `lintNodes` was even called. A constant is also wrong on
+ * its own terms now: Studio, /publish and CI each lint their own tree, and a value frozen at import
+ * would describe whichever tree loaded first. `state.nodesHome` is set by `reset()` every run.
+ *
+ * Memoized per home, because one lint walks many packages and the library is the same for all.
+ */
+const CACHE = new Map();
+
+export function promptBlocks() {
+  const home = resolve(state.nodesHome, "../prompts/blocks");
+  const cached = CACHE.get(home);
+  if (cached) return cached;
+
+  const found = new Map();
+  const walk = (d) => {
+    if (!existsSync(d)) return;
+    for (const e of readdirSync(d)) {
+      const p = join(d, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (e.endsWith(".md")) {
+        const id = e.replace(/\.md$/, "");
+        found.set(id.replace(/-([a-z])/g, (_, c) => c.toUpperCase()), rel(p));
+      }
+    }
+  };
+  walk(home);
+  CACHE.set(home, found);
+  return found;
+}

package/vendor/base/src/lint/nodes/index.mjs

@@ -0,0 +1,64 @@
+/**
+ * The declarative node linter, as a LIBRARY. Rules in, findings out.
+ *
+ * It prints nothing and exits nothing, because four callers need the same rules and each
+ * presents them differently:
+ *
+ *   `unoverse lint nodes`  coloured lines in a terminal (scripts/lib/lint-nodes.mjs)
+ *   Studio                 findings beside the definition you are editing
+ *   POST /publish          a refusal, so a broken manifest never reaches the database
+ *   CI                     a non-zero exit
+ *
+ * It lived in scripts/ as a CLI, which meant the universe could not use it. Publishing
+ * without it is the gap LOCAL_STUDIO.md:246 names: "a malformed definition is one restart
+ * from a broken server", and a published row does not even need the restart.
+ *
+ * FOUR TIERS (docs/architecture/DECLARATIVE_NODES.md §6). This is tiers 2 and 3.
+ *   1  editor    $schema pointers + .vscode yaml.schemas, no tool
+ *   2  structural   every part validated against nodes/_schema/*.json
+ *   3  semantic     the cross-file rules a schema cannot express
+ *   4  dry run      `unoverse node test`, executes against testData, not here
+ */
+import { readdirSync, existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { problems, derivedKinds, reset, report } from "../context.mjs";
+import { loadSchemas } from "./schema.mjs";
+import { lintPackage } from "./package.mjs";
+
+/**
+ * Lint every node package under `nodesHome`.
+ *
+ * Returns findings rather than printing them, and NEVER throws for a lint failure: a
+ * missing directory or unreadable schema is itself reported, so a caller gets one shape
+ * of answer whatever went wrong.
+ */
+export function lintNodes(nodesHome) {
+  const home = resolve(nodesHome);
+  reset(home, join(home, "_schema"));
+
+  if (!existsSync(home)) {
+    report("error", home, "no nodes directory here");
+    return { problems: [...problems], derivedKinds: new Map(), nodeCount: 0, pkgCount: 0, nodesHome: home };
+  }
+
+  loadSchemas();
+
+  let nodeCount = 0,
+    pkgCount = 0;
+  for (const entry of readdirSync(home)) {
+    const dir = join(home, entry);
+    if (entry.startsWith("_") || entry.startsWith(".") || !statSync(dir).isDirectory()) continue;
+    if (!existsSync(join(dir, "nodes")) && !existsSync(join(dir, "package.yaml"))) continue; // pure code package
+    pkgCount++;
+    nodeCount += lintPackage(dir);
+  }
+
+  const rank = { error: 0, warn: 1, hint: 2 };
+  const sorted = [...problems].sort((a, b) => rank[a.level] - rank[b.level] || a.file.localeCompare(b.file));
+  return { problems: sorted, derivedKinds: new Map(derivedKinds), nodeCount, pkgCount, nodesHome: home };
+}
+
+/** True when anything would fail a build. Warnings and hints inform, errors stop. */
+export function hasErrors(result) {
+  return result.problems.some((p) => p.level === "error");
+}