@unoverse-platform/studio 0.1.3 → 0.1.5

package/local/plugin.ts

@@ -16,12 +16,53 @@
  * See docs/architecture/LOCAL_STUDIO.md.
  */
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import { resolve } from "path";
 import { readdirSync, existsSync, readFileSync, statSync } from "fs";
 import type { Plugin, ViteDevServer } from "vite";
 import { findProjectRoot, loadCatalog } from "./catalog.js";
 import { loadLocalNodes, type LocalNodes } from "./nodes.js";
 import { credentialsFromEnv, keyPresence, readEnv } from "./keys.js";
+import { readSource, saveSource, sourceFiles, writableRoots } from "./source.js";
+import { atomNames, vocabulary } from "./authoring.js";
+import { buildTools, handleMcp, mintPairingCode } from "./mcp.js";
+
+/**
+ * A definition URI's home on disk: a component's folder, or a template's.
+ *
+ * Resolution is the loaders', not this file's: `componentFolder` already knows a
+ * component lives in either tier and that names are unique across them. Templates are
+ * manifest-only under their own project, which `projectDir` locates.
+ */
+function definitionHome(
+  uri: string,
+  c: { componentFolder: (ref: string) => string | null; projectDir: (n: string) => string; listOrgs: () => string[] },
+  projectRoot: string,
+): string | null {
+  const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "");
+  if (/\/(apps|templates)\//.test(uri)) {
+    const i = ref.indexOf("/");
+    const [org, name] = i === -1 ? [null, ref] : [ref.slice(0, i), ref.slice(i + 1)];
+    const orgs = org ? [org] : c.listOrgs();
+    for (const o of orgs) {
+      const dir = resolve(c.projectDir(o), "templates", name.toLowerCase());
+      if (existsSync(dir)) return dir;
+    }
+    return null;
+  }
+  if (/\/atoms\//.test(uri)) {
+    const flat = resolve(projectRoot, "rx/atoms", `${ref.toLowerCase()}.json`);
+    return existsSync(flat) ? flat : null;
+  }
+  const folder = c.componentFolder(ref);
+  if (folder) return folder;
+  // A flat, folderless component: `rx/components/<name>.json` in either tier.
+  for (const dir of [resolve(projectRoot, "rx/marketplace/components"), resolve(projectRoot, "rx/components")]) {
+    const flat = resolve(dir, `${ref.toLowerCase()}.json`);
+    if (existsSync(flat)) return flat;
+  }
+  return null;
+}
 
 /** JSON response helper matching the server's content type. */
 function json(res: import("http").ServerResponse, body: unknown, status = 200): void {
@@ -102,9 +143,27 @@ function readMarkdownLibrary(dir: string): MarkdownEntry[] {
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/**
+ * Files this server has just written, so the watcher can tell Studio's own save apart from
+ * the developer's other editor. The window only has to outlast the filesystem event, which
+ * arrives in milliseconds; a stale entry costs one skipped reload and nothing else.
+ */
+const recentSelfWrites = new Map<string, number>();
+const SELF_WRITE_WINDOW_MS = 2000;
+
 export function localStudioHost(): Plugin {
   let projectRoot: string;
   let baseSrc: string;
+  /** The node the developer last picked in the preview, for an agent to read. */
+  let selection: Record<string, unknown> | null = null;
+  /** The agent tool surface, built on first use so the catalog is loaded by then. */
+  let mcpTools: ReturnType<typeof buildTools> | null = null;
+  /** This package's own root, for the vendored authoring skill. */
+  // Derived from this module's own URL, never RESOLVED: `createRequire().resolve("./plugin.js")`
+  // throws here, because Vite loads the TypeScript source and no sibling .js exists. Throwing
+  // at plugin construction kills the config load, which stops the dev server restarting at
+  // all, and the symptom is every new route 404ing with no error in the browser.
+  const appRoot = resolve(fileURLToPath(import.meta.url), "../..");
 
   return {
     name: "local-studio-host",
@@ -138,6 +197,22 @@ export function localStudioHost(): Plugin {
 
       server.config.logger.info(`\n  Studio reading: ${resolve(projectRoot, "rx")}\n`);
 
+      /**
+       * WATCH THE PROJECT EXPLICITLY. Vite watches its own root, which is this package,
+       * and the developer's project is somewhere else entirely: another folder in this
+       * monorepo, or the parent of node_modules once Studio is installed. So the
+       * `handleHotUpdate` hook below never saw a definition change and the "edit in your
+       * IDE, Studio updates" it promised did not happen (verified 2026-08-01: the watcher
+       * held 19 directories, all under packages/studio, and a touch of a real rx/ file
+       * raised no event).
+       *
+       * Adding the paths puts them in the same watcher, so the existing hook fires.
+       */
+      for (const dir of ["rx", "prompts"]) {
+        const full = resolve(projectRoot, dir);
+        if (existsSync(full)) server.watcher.add(full);
+      }
+
       server.middlewares.use(async (req, res, next) => {
         const url = new URL(req.url ?? "/", "http://local");
         const path = url.pathname;
@@ -146,7 +221,7 @@ export function localStudioHost(): Plugin {
         // 200. That has now cost three separate bugs (the /api allowlist, the dev proxy for
         // /.well-known and /publish), each of which looked like a missing route rather than
         // a filtered one.
-        if (!/^\/(dev|local|skills|prompt-blocks|registry|nodes|keys|execute|publish)\b/.test(path)) return next();
+        if (!/^\/(dev|local|mcp|skills|prompt-blocks|registry|nodes|keys|execute|publish)\b/.test(path)) return next();
 
         /** Read a JSON request body. */
         const body = async (): Promise<Record<string, unknown>> => {
@@ -298,6 +373,166 @@ export function localStudioHost(): Plugin {
               return d ? json(res, d) : json(res, { error: `definition not found: ${uri}` }, 404);
             }
 
+            /**
+             * SOURCE VIEW (read-only at this step).
+             *
+             * The screens render a definition; this serves the FILES behind it, so a
+             * developer can read what they are looking at without leaving Studio. The
+             * writable flag on every file comes from source.ts, the single place that
+             * decides it, so the pane never invents its own idea of what may be edited.
+             *
+             *   GET /local/source?uri=unoverse://components/<name>   the file list
+             *   GET /local/source?path=<abs>                          a skill or block
+             *   GET /local/source/file?path=<abs>                     one file's text
+             */
+            case path === "/local/source": {
+              const roots = writableRoots(projectRoot, c);
+              const direct = url.searchParams.get("path");
+              if (direct) return json(res, { files: sourceFiles(direct, roots, projectRoot) });
+
+              const uri = url.searchParams.get("uri") ?? "";
+              const home = definitionHome(uri, c, projectRoot);
+              if (!home) return json(res, { error: `no source for ${uri}` }, 404);
+              return json(res, { home, files: sourceFiles(home, roots, projectRoot) });
+            }
+
+            case path === "/local/source/file" && req.method !== "POST": {
+              const p = url.searchParams.get("path") ?? "";
+              const found = readSource(p, writableRoots(projectRoot, c), projectRoot);
+              return found ? json(res, found) : json(res, { error: "not readable" }, 404);
+            }
+
+            /**
+             * THE WRITE CHOKEPOINT. Every write local Studio performs goes through here:
+             * the developer typing in the source pane, and the connected agent calling
+             * saveDefinition. One gate, one rule set, no second implementation.
+             *
+             * It refuses installed assets outright and rolls back a save that fails lint
+             * (source.ts saveSource). The linter is the SAME library publish and the CLI
+             * use, loaded the same way, so the three cannot disagree about a rule.
+             */
+            case path === "/local/source/file" && req.method === "POST": {
+              const b = await body();
+              const p = String(b.path ?? "");
+              if (!p || typeof b.text !== "string") return json(res, { error: "path and text are required" }, 400);
+
+              type LintModule = { lintDefinitions(rxHome: string): { problems: { level?: string; file?: string }[] } };
+              const lintMod = (await ssr(`${baseSrc}/lint/rx/index.mjs`)) as unknown as LintModule;
+
+              // Marked BEFORE the write, so the filesystem event can never beat the mark.
+              recentSelfWrites.set(resolve(p), Date.now());
+              const result = await saveSource(
+                p,
+                b.text as string,
+                writableRoots(projectRoot, c),
+                projectRoot,
+                (rxHome) => lintMod.lintDefinitions(rxHome),
+              );
+              return json(res, result, result.saved ? 200 : result.error === "lint errors" ? 422 : 403);
+            }
+
+            /**
+             * DIAGNOSTICS FOR UNSAVED TEXT, from the one linter.
+             *
+             * The editor posts what the developer has typed and the shared library judges
+             * it through an overlay, so a squiggle in the pane is the same rule publish
+             * and CI apply. Findings for other files come back separately: a developer
+             * fixing this file should not be shouted at about that one.
+             */
+            case path === "/local/lint/draft": {
+              const b = await body();
+              const p = String(b.path ?? "");
+              if (!p || typeof b.text !== "string") return json(res, { error: "path and text are required" }, 400);
+
+              type LintModule = {
+                lintDefinitions(
+                  rxHome: string,
+                  options?: { overlay?: Record<string, string> },
+                ): { problems: { level?: string; file?: string; line?: number; msg?: string }[] };
+              };
+              const lintMod = (await ssr(`${baseSrc}/lint/rx/index.mjs`)) as unknown as LintModule;
+              const abs = resolve(p);
+              const { problems } = lintMod.lintDefinitions(resolve(projectRoot, "rx"), { overlay: { [abs]: b.text as string } });
+              return json(res, {
+                findings: problems.filter((f) => f.file && resolve(f.file) === abs),
+                elsewhere: problems.filter((f) => !f.file || resolve(f.file) !== abs).length,
+              });
+            }
+
+            /**
+             * THE CLOSED VOCABULARY, for completion. Data, not rules: the same sets the
+             * linter enforces, plus this project's own token, atom and component names.
+             */
+            case path === "/local/vocabulary": {
+              const vocabMod = (await ssr(`${baseSrc}/lint/rx/vocabulary.mjs`)) as unknown as Parameters<typeof vocabulary>[0];
+              const theme = c.resolveTheme(url.searchParams.get("theme") ?? "light");
+              return json(
+                res,
+                vocabulary(vocabMod, theme, atomNames(projectRoot), c.listDefinitions("component") as { name?: string }[]),
+              );
+            }
+
+            /**
+             * WHAT THE DEVELOPER IS POINTING AT.
+             *
+             * The editor posts the node it selected; an agent reads it back. "Make this
+             * bigger" is only answerable if something outside the developer's head knows
+             * what "this" is, and the picker is how they say it: a click on the rendered
+             * element resolves to a file, a line and the node's own definition.
+             *
+             * IN MEMORY, AND LAST WINS. It describes what is on screen right now, so it
+             * belongs to the running server and not to disk.
+             */
+            case path === "/local/selection" && req.method === "POST": {
+              selection = { ...(await body()), at: new Date().toISOString() };
+              return json(res, { ok: true });
+            }
+            case path === "/local/selection":
+              return json(res, selection ?? { empty: true });
+
+            /**
+             * CONNECT AN AGENT. Mints the code the developer pastes into Claude, the same
+             * flow Canvas uses. Ten minutes, single use, burned on redeem.
+             */
+            case path === "/local/pair" && req.method === "POST":
+              return json(res, mintPairingCode());
+
+            /** The MCP endpoint itself. Same origin, same port, no separate install. */
+            case path === "/mcp" && req.method === "POST": {
+              mcpTools ??= buildTools(
+                {
+                  projectRoot,
+                  catalog: async () => (await catalog) as never,
+                  sourceFiles: (uri) => {
+                    const home = definitionHome(uri, c, projectRoot);
+                    return home ? sourceFiles(home, writableRoots(projectRoot, c), projectRoot) : [];
+                  },
+                  readSource: (p) => readSource(p, writableRoots(projectRoot, c), projectRoot),
+                  saveSource: async (p, text) => {
+                    type LintModule = { lintDefinitions(rxHome: string): { problems: { level?: string; file?: string }[] } };
+                    const lintMod = (await ssr(`${baseSrc}/lint/rx/index.mjs`)) as unknown as LintModule;
+                    recentSelfWrites.set(resolve(p), Date.now());
+                    return saveSource(p, text, writableRoots(projectRoot, c), projectRoot, (rxHome) =>
+                      lintMod.lintDefinitions(rxHome),
+                    );
+                  },
+                  lintProject: async () => {
+                    type LintModule = { lintDefinitions(rxHome: string): { problems: unknown[] } };
+                    const lintMod = (await ssr(`${baseSrc}/lint/rx/index.mjs`)) as unknown as LintModule;
+                    return lintMod.lintDefinitions(resolve(projectRoot, "rx"));
+                  },
+                  selection: () => selection,
+                  vocabulary: async () => {
+                    const vocabMod = (await ssr(`${baseSrc}/lint/rx/vocabulary.mjs`)) as unknown as Parameters<typeof vocabulary>[0];
+                    return vocabulary(vocabMod, c.resolveTheme("light"), atomNames(projectRoot), c.listDefinitions("component") as { name?: string }[]);
+                  },
+                },
+                appRoot,
+              );
+              await handleMcp(req, res, await body(), mcpTools);
+              return;
+            }
+
             case path === "/skills":
               return json(res, { skills: readMarkdownLibrary(resolve(projectRoot, "prompts/skills")) });
 
@@ -379,15 +614,22 @@ export function localStudioHost(): Plugin {
 
     /**
      * Definitions are fetched at runtime, so Vite never sees them in the module graph.
-     * Watch the developer's rx/ and prompts/ and force a reload on any change: edit in
-     * your IDE, Studio updates. This is the same watcher the old coupled studio had.
+     * Watch the developer's rx/ and prompts/ and reload on any change: edit in your IDE,
+     * Studio updates.
+     *
+     * A SAVE FROM STUDIO'S OWN EDITOR IS NOT AN EXTERNAL EDIT. Reloading the page on it
+     * would throw away the cursor, the scroll position, the open file and any unsaved work
+     * in another tab, every time the developer pressed Cmd+S. The editor already refreshes
+     * the preview itself, so a write this server just performed is skipped here. Anything
+     * else, which means the developer's other editor, still reloads.
      */
     handleHotUpdate({ server, file }) {
       const watched = [resolve(projectRoot, "rx"), resolve(projectRoot, "prompts")];
-      if (watched.some((w) => file.startsWith(w))) {
-        server.ws.send({ type: "full-reload" });
-        return [];
-      }
+      if (!watched.some((w) => file.startsWith(w))) return;
+      const self = recentSelfWrites.get(resolve(file));
+      if (self !== undefined && Date.now() - self < SELF_WRITE_WINDOW_MS) return [];
+      server.ws.send({ type: "full-reload" });
+      return [];
     },
 
     configResolved() {

package/local/scaffold.mjs

@@ -13,8 +13,9 @@
  *
  * See docs/architecture/LOCAL_STUDIO.md.
  */
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, writeFileSync, cpSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /**
  * A name that is safe as a folder AND legal as an item's `org`.
@@ -81,5 +82,16 @@ export function createProject(home, name) {
 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 });
+
+  // The Claude Code authoring skill, 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); read from the repo when running as source.
+  const app = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const skill = [join(app, "vendor/skills/unoverse-create"), resolve(app, "../../.claude/skills/unoverse-create")]
+    .find((d) => existsSync(d));
+  if (skill) {
+    mkdirSync(join(home, ".claude/skills"), { recursive: true });
+    cpSync(skill, join(home, ".claude/skills/unoverse-create"), { recursive: true });
+  }
   return root;
 }

package/local/source.ts

@@ -0,0 +1,230 @@
+/**
+ * SOURCE ACCESS: which files local Studio may show, and which it may write.
+ *
+ * Studio previews definitions. The source view shows the file behind one, and the write
+ * route (step 3) saves it back. Both ask this module first, so there is ONE answer to
+ * "may this be written" and it cannot drift between the human typing in the pane and a
+ * connected agent calling saveDefinition.
+ *
+ * THE WRITABLE SET IS NAMED, NOT INFERRED. A path check alone is wrong in this monorepo:
+ * the design-system source lives on disk INSIDE the project root (definitions.ts
+ * `marketplaceDir` prefers `rx/marketplace/<kind>` when it exists), so "under projectRoot"
+ * would happily let a developer edit the design system. Installed assets are read-only
+ * everywhere: an edit to one is invisible to every other machine and lost on the next
+ * install, and §Design-system resolution is what keeps the token contract stable.
+ *
+ * So the writable set is exactly the developer's own work:
+ *   rx/<project>/**   every project listOrgs() reports, via projectDir()
+ *   prompts/**        skills and prompt blocks
+ *   nodes/**          their own node packages
+ * Everything else is readable and not writable, the marketplace and anything resolved out
+ * of node_modules included.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md §Authoring in Studio.
+ */
+import { resolve, sep, relative } from "path";
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
+
+/** The reason a path is not writable. Shown to the developer and returned to the agent. */
+export type ReadOnlyReason = "installed" | "outside-project" | "not-a-file";
+
+export interface Writability {
+  writable: boolean;
+  reason?: ReadOnlyReason;
+}
+
+/** True when `child` is `parent` or sits beneath it. Path-separator aware, so a sibling
+ *  folder sharing a name prefix (`rx/shop` vs `rx/shop-admin`) is not a match. */
+function within(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !resolve(child).includes(`${sep}..${sep}`));
+}
+
+/**
+ * The folders a developer may write, absolute and existing.
+ *
+ * Built from the SAME loaders that resolve definitions, so a project Studio can show is a
+ * project Studio can write, with no second notion of what a project is.
+ */
+export function writableRoots(
+  projectRoot: string,
+  loaders: { listOrgs: () => string[]; projectDir: (name: string) => string },
+): string[] {
+  const roots = [
+    ...loaders.listOrgs().map((org) => loaders.projectDir(org)),
+    resolve(projectRoot, "prompts"),
+    resolve(projectRoot, "nodes"),
+  ];
+  return roots.map((r) => resolve(r)).filter((r) => existsSync(r));
+}
+
+/**
+ * May this exact path be written?
+ *
+ * `roots` comes from writableRoots(). A path inside one of them is the developer's own
+ * work. Everything else is read-only, and the reason distinguishes the design system a
+ * developer builds ON (normal, shown without a save button) from a path that has no
+ * business being addressed at all.
+ */
+export function writability(path: string, roots: string[], projectRoot: string): Writability {
+  const abs = resolve(path);
+  if (roots.some((r) => within(r, abs))) return { writable: true };
+  // Inside the project but not in a writable root: the marketplace on disk, rx/_schema,
+  // or the legacy orgs/ container. Reading is the point; writing is what is refused.
+  if (within(resolve(projectRoot), abs)) return { writable: false, reason: "installed" };
+  // node_modules, or anywhere else entirely. The design system resolves here for a
+  // consumer, which is the same answer for a different reason.
+  return { writable: false, reason: abs.includes(`${sep}node_modules${sep}`) ? "installed" : "outside-project" };
+}
+
+export interface SourceFile {
+  /** Absolute, because the route is addressed by path and the UI shows where it reads. */
+  path: string;
+  /** Relative to the definition's folder, for display: `manifest.json`, `layouts/idle.json`. */
+  rel: string;
+  writable: boolean;
+  reason?: ReadOnlyReason;
+}
+
+/**
+ * Definition source, plus the lifecycle handlers a component folder may hold.
+ *
+ * YAML AND JSON BOTH. The rx YAML migration is under way, so the design system is `.yaml`
+ * today while other trees are still `.json` (verified 2026-08-01: every marketplace
+ * component folder held only `<name>.yaml`, and a JSON-only filter listed nothing at all).
+ */
+const SOURCE_EXT = /\.(ya?ml|json|jsonc|md|mjs|js)$/;
+
+/**
+ * Every source file behind one definition.
+ *
+ * A component is a FOLDER (`<name>.json` or `manifest.json`, plus `layouts/`, `states/`,
+ * `components/`), and a simple one is a single flat file. Both shapes are returned as a
+ * list so the pane never has to know which it is looking at.
+ */
+export function sourceFiles(folderOrFile: string, roots: string[], projectRoot: string): SourceFile[] {
+  const abs = resolve(folderOrFile);
+  if (!existsSync(abs)) return [];
+  const out: SourceFile[] = [];
+  const base = statSync(abs).isDirectory() ? abs : resolve(abs, "..");
+
+  const add = (p: string) => {
+    const w = writability(p, roots, projectRoot);
+    out.push({ path: p, rel: relative(base, p) || p.split(sep).pop()!, writable: w.writable, reason: w.reason });
+  };
+
+  if (statSync(abs).isFile()) {
+    add(abs);
+    return out;
+  }
+
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const p = resolve(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (SOURCE_EXT.test(e.name)) add(p);
+    }
+  };
+  walk(abs);
+
+  // The envelope first: it is what a developer opens the view to read. Nested files
+  // (layouts/, states/, components/) last, and the manifest between them.
+  return out.sort((a, b) => {
+    const rank = (f: SourceFile) => (f.rel.includes(sep) ? 2 : /^manifest\.(ya?ml|json)$/.test(f.rel) ? 1 : 0);
+    return rank(a) - rank(b) || a.rel.localeCompare(b.rel);
+  });
+}
+
+export interface SaveResult {
+  saved: boolean;
+  /** Why a refusal, in the caller's terms. Shown in the pane, returned to an agent. */
+  error?: string;
+  /** Lint findings for THIS file. Errors here mean the write was rolled back. */
+  findings?: unknown[];
+  /** Findings elsewhere in the project. Reported, never blocking. */
+  otherFindings?: unknown[];
+}
+
+/**
+ * Save one file, gated on the linter.
+ *
+ * THE GATE IS SCOPED TO THIS FILE. `lintDefinitions` reads the whole rx tree, so a gate
+ * built naively on its verdict refuses a clean save whenever some unrelated file is
+ * broken, and can never say which finding the edit caused. Findings for the saved file
+ * block; the rest are reported and do not.
+ *
+ * WRITE, LINT, ROLL BACK. The linter reads from disk and takes no in-memory overlay, so
+ * the file has to be on disk to be judged. A refusal therefore restores the previous
+ * bytes, which is why the developer sees an atomic accept-or-reject even though the
+ * sequence underneath is not. A new file that fails is removed rather than restored.
+ */
+export async function saveSource(
+  path: string,
+  text: string,
+  roots: string[],
+  projectRoot: string,
+  lint: (rxHome: string) => Promise<{ problems: LintFinding[] }> | { problems: LintFinding[] },
+): Promise<SaveResult> {
+  const abs = resolve(path);
+  const w = writability(abs, roots, projectRoot);
+  if (!w.writable) {
+    const why =
+      w.reason === "installed"
+        ? "installed assets are read-only: edit your own project, not the design system"
+        : "outside your project";
+    return { saved: false, error: why };
+  }
+  if (!existsSync(resolve(abs, "..")))
+    return { saved: false, error: `no folder for ${abs}` };
+
+  const existed = existsSync(abs);
+  const previous = existed ? readFileSync(abs, "utf8") : null;
+  if (previous === text) return { saved: true, findings: [], otherFindings: [] };
+
+  writeFileSync(abs, text, "utf8");
+
+  const rxHome = resolve(projectRoot, "rx");
+  let problems: LintFinding[] = [];
+  try {
+    problems = (await lint(rxHome)).problems ?? [];
+  } catch (e) {
+    // A linter that throws must not silently accept the write.
+    if (previous === null) rmSync(abs, { force: true });
+    else writeFileSync(abs, previous, "utf8");
+    return { saved: false, error: `lint failed to run: ${(e as Error).message}` };
+  }
+
+  // The linter reports paths relative to the working directory, and `resolve` reads the
+  // same directory, so the two agree by construction rather than by string matching.
+  const mine = problems.filter((p) => p.file && resolve(p.file) === abs);
+  const errors = mine.filter((p) => p.level === "error");
+  if (errors.length) {
+    if (previous === null) rmSync(abs, { force: true });
+    else writeFileSync(abs, previous, "utf8");
+    return { saved: false, error: "lint errors", findings: mine, otherFindings: [] };
+  }
+
+  return {
+    saved: true,
+    findings: mine,
+    otherFindings: problems.filter((p) => !p.file || resolve(p.file) !== abs),
+  };
+}
+
+export interface LintFinding {
+  level?: string;
+  file?: string;
+  msg?: string;
+  [k: string]: unknown;
+}
+
+/** One file's text, refused unless it is a file Studio would list. */
+export function readSource(path: string, roots: string[], projectRoot: string): { text: string; writable: boolean; reason?: ReadOnlyReason } | null {
+  const abs = resolve(path);
+  if (!existsSync(abs) || !statSync(abs).isFile()) return null;
+  const w = writability(abs, roots, projectRoot);
+  // A path outside the project entirely is not shown. The design system is, because
+  // reading what you build on is the normal case.
+  if (w.reason === "outside-project" && !abs.includes(`${sep}node_modules${sep}`)) return null;
+  return { text: readFileSync(abs, "utf8"), writable: w.writable, reason: w.reason };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {
@@ -11,6 +11,19 @@
     "prepack": "node scripts/vendor-sdk.mjs"
   },
   "dependencies": {
+    "@codemirror/autocomplete": "^6.18.6",
+    "@codemirror/commands": "^6.8.1",
+    "@codemirror/lang-javascript": "^6.2.4",
+    "@codemirror/lang-json": "^6.0.1",
+    "@codemirror/lang-markdown": "^6.3.0",
+    "@codemirror/lang-yaml": "^6.1.2",
+    "@codemirror/language": "^6.11.0",
+    "@codemirror/lint": "^6.8.0",
+    "@codemirror/search": "^6.5.0",
+    "@codemirror/state": "^6.5.2",
+    "@codemirror/theme-one-dark": "^6.1.2",
+    "@codemirror/view": "^6.37.1",
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "@tailwindcss/vite": "^4.0.0",
     "@unoverse-platform/base": "^0.3.0",
     "@unoverse-platform/marketplace": "*",
@@ -21,7 +34,7 @@
     "react-oidc-context": "^3.1.0",
     "tailwindcss": "^4.0.0",
     "vite": "^6.0.0",
-    "@modelcontextprotocol/sdk": "^1.25.1"
+    "yaml": "^2.4.0"
   },
   "license": "MIT",
   "bin": {