@jxsuite/server 0.29.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,8 @@
   "exports": {
     ".": "./src/server.ts",
     "./claude-session": "./src/claude-session.ts",
+    "./packages": "./src/packages.ts",
+    "./refactor": "./src/refactor/index.ts",
     "./resolve": "./src/resolve.ts",
     "./types": "./src/types.ts"
   },
@@ -27,13 +29,13 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.175",
-    "@anthropic-ai/sdk": "^0.104.1",
-    "@jxsuite/compiler": "^0.29.0",
-    "@jxsuite/create": "^0.29.0",
-    "@jxsuite/parser": "^0.29.0",
-    "@jxsuite/runtime": "^0.29.0",
-    "@jxsuite/schema": "^0.29.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.190",
+    "@anthropic-ai/sdk": "^0.105.0",
+    "@jxsuite/compiler": "^0.31.0",
+    "@jxsuite/create": "^0.31.0",
+    "@jxsuite/parser": "^0.31.0",
+    "@jxsuite/runtime": "^0.31.0",
+    "@jxsuite/schema": "^0.31.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "chokidar": "^5.0.0",
     "zod": "^4.4.3"

package/src/packages.ts

@@ -0,0 +1,209 @@
+/**
+ * Bun-driven package operations, parameterized by a project root. Shared by the desktop app
+ * (`createPackageOps`) and the dev server's `/__studio/packages*` endpoints so both backends behave
+ * identically. Every function is pure with respect to its `root` argument and spawns `bun` in that
+ * directory.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export interface PackageInfo {
+  name: string;
+  version: string;
+  /** True when the dependency lives in `devDependencies` rather than `dependencies`. */
+  dev?: boolean;
+}
+
+export interface OutdatedInfo {
+  name: string;
+  /** The version range pinned in package.json (e.g. "^0.19.0"). */
+  current: string;
+  /** The newest published version. */
+  latest: string;
+  dev?: boolean;
+}
+
+/** Result of a package mutation that runs `bun install` (install / set-versions). */
+export interface PackageOpResult {
+  ok: boolean;
+  /** Combined stdout/stderr from the bun invocation, surfaced to the user on failure. */
+  log?: string;
+}
+
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+/** Minimal fetch signature (injectable for tests; the global `fetch` satisfies it). */
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+/** Strip a semver range prefix to its base version: "^0.19.0" → "0.19.0". */
+export function stripRange(range: string): string {
+  const base = range.replace(/^[\^~>=<v\s]+/, "").trim();
+  return base.split(/\s+/)[0] ?? "";
+}
+
+/**
+ * Whether a version spec points at the npm registry (a plain semver range). Skips workspace:,
+ * file:, link:, npm:, git, and URL specs, plus wildcards like "*" or "latest".
+ */
+export function isRegistryRange(spec: string): boolean {
+  if (spec.includes(":")) {
+    return false;
+  }
+  return /^\d/.test(stripRange(spec));
+}
+
+async function readPackageJson(root: string): Promise<PackageJson | null> {
+  const pkgPath = resolve(root, "package.json");
+  if (!existsSync(pkgPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(await readFile(pkgPath, "utf8")) as PackageJson;
+  } catch {
+    return null;
+  }
+}
+
+/** List the project's dependencies and devDependencies (devDeps tagged with `dev: true`). */
+export async function listPackages(root: string): Promise<PackageInfo[]> {
+  const pkg = await readPackageJson(root);
+  if (!pkg) {
+    return [];
+  }
+  const out: PackageInfo[] = [];
+  for (const [name, version] of Object.entries(pkg.dependencies ?? {})) {
+    out.push({ name, version });
+  }
+  for (const [name, version] of Object.entries(pkg.devDependencies ?? {})) {
+    out.push({ dev: true, name, version });
+  }
+  return out;
+}
+
+/** Whether the project has a package.json but no installed node_modules. */
+export function dependenciesNeedInstall(root: string): boolean {
+  if (!existsSync(resolve(root, "package.json"))) {
+    return false;
+  }
+  return !existsSync(resolve(root, "node_modules"));
+}
+
+async function runBun(args: string[], cwd: string): Promise<PackageOpResult> {
+  const proc = Bun.spawn(["bun", ...args], { cwd, stderr: "pipe", stdout: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  const log = `${stdout}${stderr}`.trim();
+  return { ok: exitCode === 0, ...(log ? { log } : {}) };
+}
+
+/** Run `bun install` in the project root. */
+export async function installDependencies(root: string): Promise<PackageOpResult> {
+  return runBun(["install"], root);
+}
+
+/** Run `bun add` (with `-d` for a dev dependency). */
+export async function addPackage(
+  root: string,
+  name: string,
+  dev = false,
+): Promise<PackageOpResult> {
+  return runBun(dev ? ["add", "-d", name] : ["add", name], root);
+}
+
+/** Run `bun remove`. */
+export async function removePackage(root: string, name: string): Promise<PackageOpResult> {
+  return runBun(["remove", name], root);
+}
+
+/** Fetch the newest published version for a package from the npm registry, or null on any failure. */
+export async function fetchLatestVersion(
+  name: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<string | null> {
+  try {
+    const res = await fetchImpl(`https://registry.npmjs.org/${name}/latest`, {
+      headers: { accept: "application/vnd.npm.install-v1+json" },
+    });
+    if (!res.ok) {
+      return null;
+    }
+    const data = (await res.json()) as { version?: string };
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List dependencies whose newest published version differs from the pinned base. Registry lookups
+ * run concurrently; non-registry specs (workspace:, file:, …) and lookup failures are skipped.
+ */
+export async function outdatedPackages(
+  root: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<OutdatedInfo[]> {
+  const pkgs = await listPackages(root);
+  const checks = await Promise.all(
+    pkgs.map(async (p): Promise<OutdatedInfo | null> => {
+      if (!isRegistryRange(p.version)) {
+        return null;
+      }
+      const latest = await fetchLatestVersion(p.name, fetchImpl);
+      if (!latest || latest === stripRange(p.version)) {
+        return null;
+      }
+      const entry: OutdatedInfo = { current: p.version, latest, name: p.name };
+      if (p.dev) {
+        entry.dev = true;
+      }
+      return entry;
+    }),
+  );
+  return checks.filter((entry): entry is OutdatedInfo => entry !== null);
+}
+
+/**
+ * Rewrite the version range of each named package in whichever section it already occupies
+ * (preserving dependencies/devDependencies placement; new names default to the caller's `dev`
+ * flag), then run a single `bun install`.
+ */
+export async function setPackageVersions(
+  root: string,
+  updates: { name: string; version: string; dev?: boolean }[],
+): Promise<PackageOpResult> {
+  if (updates.length === 0) {
+    return { ok: true };
+  }
+  const pkgPath = resolve(root, "package.json");
+  if (!existsSync(pkgPath)) {
+    return { log: "No package.json in project root", ok: false };
+  }
+  let pkg: PackageJson;
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, "utf8")) as PackageJson;
+  } catch (error) {
+    return { log: `Unparseable package.json: ${String(error)}`, ok: false };
+  }
+  for (const update of updates) {
+    if (pkg.devDependencies && update.name in pkg.devDependencies) {
+      pkg.devDependencies[update.name] = update.version;
+    } else if (pkg.dependencies && update.name in pkg.dependencies) {
+      pkg.dependencies[update.name] = update.version;
+    } else {
+      const bucket = update.dev ? "devDependencies" : "dependencies";
+      pkg[bucket] = { ...(pkg[bucket] as Record<string, string> | undefined) };
+      (pkg[bucket] as Record<string, string>)[update.name] = update.version;
+    }
+  }
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+  return installDependencies(root);
+}

package/src/refactor/apply.ts

@@ -0,0 +1,215 @@
+/**
+ * Apply.ts — IO orchestrator for rename-refactoring, shared by the dev-server endpoint
+ * (studio-api.ts) and the desktop project session.
+ *
+ * The caller performs the filesystem move first, then calls `applyRename`, which globs the
+ * project's document + content files, runs the pure engines from refs.ts against each, writes back
+ * only the files that changed, and returns a `RenameReport`. When the renamed file is a component,
+ * the tag is auto-derived from the new filename and renamed everywhere it is used (Pillar C).
+ */
+
+import { basename, dirname, extname, relative, resolve } from "node:path";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { errorMessage } from "@jxsuite/schema/parse";
+import { isUnder } from "./paths.ts";
+import { rewriteDocRefs, rewriteTagName } from "./refs.ts";
+import type { RefChange } from "./refs.ts";
+import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+
+/** Normalise a path to forward slashes. */
+const fwd = (p: string) => p.replaceAll("\\", "/");
+
+export interface FileChange {
+  path: string;
+  count: number;
+  changes: RefChange[];
+}
+
+export interface RenameReport {
+  ok: boolean;
+  from: string;
+  to: string;
+  isDir: boolean;
+  references: {
+    filesChanged: number;
+    refsUpdated: number;
+    files: FileChange[];
+  };
+  errors: { path: string; error: string }[];
+  tag?: { from: string; to: string; filesChanged: number; refsUpdated: number };
+  tagSkipped?: string;
+}
+
+export interface ApplyRenameOptions {
+  /** Absolute project root to scan. */
+  root: string;
+  /** Absolute path of the renamed file/dir, before the move. */
+  absFrom: string;
+  /** Absolute path of the renamed file/dir, after the move (already on disk). */
+  absTo: string;
+  /** Format registry for the project (parse/serialize of non-JSON documents). */
+  registry: FormatRegistry;
+}
+
+/** A parsed document plus the serializer that round-trips it back to disk. */
+interface LoadedDoc {
+  doc: unknown;
+  serialize: ((doc: unknown) => Promise<string>) | null;
+}
+
+const isJsonPath = (p: string) => p.endsWith(".json");
+
+/** Skip vendored / build / agent directories (mirrors the component-discovery filter). */
+function skip(match: string): boolean {
+  const f = fwd(match);
+  return match.includes("node_modules") || f.includes("dist/") || f.includes(".claude/");
+}
+
+/** Derive a custom-element tag from a component filename (strips `.class.json` or the extension). */
+export function deriveTag(absPath: string): string {
+  const base = basename(absPath);
+  if (base.endsWith(".class.json")) {
+    return base.slice(0, -".class.json".length);
+  }
+  const ext = extname(base);
+  return ext ? base.slice(0, -ext.length) : base;
+}
+
+/** Read + parse a file, returning the doc and a matching serializer (null when none is available). */
+async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
+  const raw = await readFile(fp, "utf8");
+  if (isJsonPath(fp)) {
+    const trailingNewline = raw.endsWith("\n");
+    return {
+      doc: JSON.parse(raw) as unknown,
+      serialize: (doc) =>
+        Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
+    };
+  }
+  const ext = extname(fp);
+  const parseEntry = registry.byExtension(ext, "parse");
+  if (!parseEntry) {
+    throw new Error(`No parser for "${ext}"`);
+  }
+  const doc = await parseEntry.call("parse", raw);
+  const serializeEntry = registry.byExtension(ext, "serialize");
+  return {
+    doc,
+    serialize: serializeEntry
+      ? async (d) => {
+          const out = await serializeEntry.call("serialize", d);
+          return typeof out === "string" ? out : String(out);
+        }
+      : null,
+  };
+}
+
+/** Build the recursive glob covering JSON plus every registered document/content extension. */
+function documentGlob(registry: FormatRegistry) {
+  const exts = new Set(["json"]);
+  for (const ext of registry.documentExtensions()) {
+    exts.add(ext.replace(/^\./, ""));
+  }
+  return new Bun.Glob(`**/*.{${[...exts].join(",")}}`);
+}
+
+/**
+ * Rewrite references (and, for components, the tag) across the project after a rename. The caller
+ * must have already moved the file on disk.
+ */
+export async function applyRename(opts: ApplyRenameOptions): Promise<RenameReport> {
+  const root = fwd(opts.root);
+  const absFrom = fwd(opts.absFrom);
+  const absTo = fwd(opts.absTo);
+
+  let isDir = false;
+  try {
+    const stats = await stat(absTo);
+    isDir = stats.isDirectory();
+  } catch {
+    isDir = false;
+  }
+
+  const report: RenameReport = {
+    errors: [],
+    from: fwd(relative(opts.root, opts.absFrom)),
+    isDir,
+    ok: true,
+    references: { files: [], filesChanged: 0, refsUpdated: 0 },
+    to: fwd(relative(opts.root, opts.absTo)),
+  };
+
+  // For a component file rename, derive the new tag from the new filename (Pillar C).
+  let tagRename: { from: string; to: string } | null = null;
+  if (!isDir) {
+    try {
+      const { doc } = await loadDoc(absTo, opts.registry);
+      const oldTag = (doc as { tagName?: unknown }).tagName;
+      const newTag = deriveTag(absTo);
+      if (typeof oldTag === "string" && oldTag.includes("-") && newTag !== oldTag) {
+        if (newTag.includes("-")) {
+          tagRename = { from: oldTag, to: newTag };
+        } else {
+          report.tagSkipped = `Tag "${oldTag}" left unchanged: "${newTag}" is not a valid custom-element name`;
+        }
+      }
+    } catch {
+      // Not a parseable component — skip tag derivation.
+    }
+  }
+
+  let tagFilesChanged = 0;
+  let tagRefsUpdated = 0;
+
+  for await (const match of documentGlob(opts.registry).scan({ cwd: opts.root, dot: false })) {
+    if (skip(match)) {
+      continue;
+    }
+    const fp = fwd(resolve(opts.root, match));
+    try {
+      const { doc, serialize } = await loadDoc(fp, opts.registry);
+      const docNewDir = dirname(fp);
+      const docOldDir = isUnder(fp, absTo) ? dirname(absFrom + fp.slice(absTo.length)) : docNewDir;
+
+      const { changes } = rewriteDocRefs(doc, {
+        docNewDir,
+        docOldDir,
+        newAbs: absTo,
+        oldAbs: absFrom,
+        root,
+      });
+      const tagCount = tagRename ? rewriteTagName(doc, tagRename.from, tagRename.to).count : 0;
+
+      if (changes.length === 0 && tagCount === 0) {
+        continue;
+      }
+      if (!serialize) {
+        report.errors.push({ error: `No serializer for "${match}"`, path: fwd(match) });
+        continue;
+      }
+      await writeFile(fp, await serialize(doc));
+
+      if (changes.length > 0) {
+        report.references.files.push({ changes, count: changes.length, path: fwd(match) });
+        report.references.filesChanged += 1;
+        report.references.refsUpdated += changes.length;
+      }
+      if (tagCount > 0) {
+        tagFilesChanged += 1;
+        tagRefsUpdated += tagCount;
+      }
+    } catch (error) {
+      report.errors.push({ error: errorMessage(error), path: fwd(match) });
+    }
+  }
+
+  if (tagRename) {
+    report.tag = {
+      filesChanged: tagFilesChanged,
+      from: tagRename.from,
+      refsUpdated: tagRefsUpdated,
+      to: tagRename.to,
+    };
+  }
+  return report;
+}

package/src/refactor/fs-events.ts

@@ -0,0 +1,71 @@
+/**
+ * Fs-events.ts — pure translation + coalescing of chokidar events into the wire payloads the studio
+ * sidebar consumes. No filesystem access (node:path.relative is a pure string op), so it is shared
+ * by the dev-server watcher (watch.ts) and the desktop project session, and unit-tests directly.
+ */
+
+import { relative } from "node:path";
+
+/** A filesystem change as broadcast to the studio shell (root-relative, forward-slashed path). */
+export interface FsEventPayload {
+  type: "add" | "change" | "unlink" | "addDir" | "unlinkDir";
+  path: string;
+  isDir: boolean;
+}
+
+const VALID = new Set(["add", "change", "unlink", "addDir", "unlinkDir"]);
+
+/**
+ * Map one chokidar event to a payload, or null for events we ignore (`ready`/`raw`/`error`) or
+ * paths that escape the root.
+ */
+export function toFsEvent(
+  eventType: string,
+  root: string,
+  changedPath: string,
+): FsEventPayload | null {
+  if (!VALID.has(eventType)) {
+    return null;
+  }
+  const path = relative(root, changedPath).replaceAll("\\", "/");
+  if (!path || path.startsWith("..")) {
+    return null;
+  }
+  return {
+    isDir: eventType === "addDir" || eventType === "unlinkDir",
+    path,
+    type: eventType as FsEventPayload["type"],
+  };
+}
+
+/**
+ * Fold one event into a buffer, collapsing redundant churn per path (last-write-wins, except
+ * add+unlink cancels, add+change stays add, and unlink+add becomes a re-add). Returns a new array.
+ */
+export function coalesceFsEvents(buffer: FsEventPayload[], next: FsEventPayload): FsEventPayload[] {
+  const prev = buffer.find((e) => e.path === next.path);
+  if (!prev) {
+    return [...buffer, next];
+  }
+  const index = buffer.indexOf(prev);
+  const out = [...buffer];
+  // A file (or dir) created then removed within the window is a no-op.
+  if (
+    (prev.type === "add" && next.type === "unlink") ||
+    (prev.type === "addDir" && next.type === "unlinkDir")
+  ) {
+    out.splice(index, 1);
+    return out;
+  }
+  // A content change after a create is still just a create.
+  if ((prev.type === "add" || prev.type === "addDir") && next.type === "change") {
+    return out;
+  }
+  // Removed then recreated → treat as a fresh add.
+  if (prev.type === "unlink" && next.type === "add") {
+    out[index] = next;
+    return out;
+  }
+  out[index] = next;
+  return out;
+}

package/src/refactor/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Public entrypoint for the rename-refactor engine (`@jxsuite/server/refactor`), shared by the
+ * dev-server endpoint and the desktop project session.
+ */
+
+export { applyRename, deriveTag } from "./apply.ts";
+export type { ApplyRenameOptions, FileChange, RenameReport } from "./apply.ts";
+export { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
+export type { FsEventPayload } from "./fs-events.ts";
+export { createFsWatcher } from "./watcher.ts";
+export type { FsWatcherHandle } from "./watcher.ts";

package/src/refactor/paths.ts

@@ -0,0 +1,187 @@
+/**
+ * Paths.ts — pure, OS-independent path math for the rename-refactor engine.
+ *
+ * Everything here operates on forward-slash POSIX strings and never touches the filesystem, so it
+ * unit-tests deterministically. Callers (apply.ts) normalise real paths with `fwd()` before handing
+ * them in. The relative-path style mirrors `computeRelativePath` in the studio
+ * (packages/studio/src/files/components.ts): "./" for same-dir/descendant targets, "../"-chains
+ * otherwise.
+ */
+
+/** Classification of a reference string value. */
+export type RefClass =
+  | { kind: "none" }
+  | { kind: "state" }
+  | { kind: "external" }
+  | { kind: "path"; core: string; suffix: string; rooted: boolean };
+
+/** Split a trailing `?query` or `#fragment` off a path-like value. */
+export function splitQueryHash(value: string): { core: string; suffix: string } {
+  for (let i = 0; i < value.length; i += 1) {
+    const ch = value[i];
+    if (ch === "?" || ch === "#") {
+      return { core: value.slice(0, i), suffix: value.slice(i) };
+    }
+  }
+  return { core: value, suffix: "" };
+}
+
+/**
+ * Classify a reference value. State-scope refs (`#/state/…`, `$map/…`, `parent#…`, `window#…`,
+ * `document#…`) and external URLs (`http:`, `data:`, protocol-relative `//…`) are never file paths.
+ * Everything else is treated as a `path`; the resolve-and-compare gate in `rewriteRef` provides the
+ * actual precision, so bare npm specifiers (which never resolve to the renamed file) are simply
+ * never matched.
+ */
+export function classifyRef(value: unknown): RefClass {
+  if (typeof value !== "string" || value.length === 0) {
+    return { kind: "none" };
+  }
+  if (
+    value === "$map" ||
+    value.startsWith("#") ||
+    value.startsWith("$map/") ||
+    value.startsWith("parent#") ||
+    value.startsWith("window#") ||
+    value.startsWith("document#")
+  ) {
+    return { kind: "state" };
+  }
+  // Absolute URL with a scheme (http:, data:, mailto:) or protocol-relative (//host).
+  if (value.startsWith("//") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value)) {
+    return { kind: "external" };
+  }
+  const { core, suffix } = splitQueryHash(value);
+  if (core.length === 0) {
+    return { kind: "none" };
+  }
+  return { core, kind: "path", rooted: core.startsWith("/"), suffix };
+}
+
+/** Collapse `.`/`..` segments in a POSIX path. Absolute paths cannot escape above root. */
+export function normalizeSegments(path: string): string {
+  const isAbs = path.startsWith("/");
+  const out: string[] = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      if (out.length > 0 && out.at(-1) !== "..") {
+        out.pop();
+      } else if (!isAbs) {
+        out.push("..");
+      }
+      continue;
+    }
+    out.push(part);
+  }
+  return (isAbs ? "/" : "") + out.join("/");
+}
+
+/**
+ * Join `rel` onto an absolute POSIX `base` and normalise (a leading "/" on rel still joins to
+ * base).
+ */
+export function joinPosix(base: string, rel: string): string {
+  return normalizeSegments(`${base}/${rel}`);
+}
+
+/**
+ * Relative path from directory `fromDir` to `to` (both absolute POSIX). Returns a bare path for
+ * descendants ("a/b.json") and "../"-chains otherwise — without a leading "./" (callers add it to
+ * preserve author style).
+ */
+export function relativeChain(fromDir: string, to: string): string {
+  const fromParts = fromDir.split("/").filter(Boolean);
+  const toParts = to.split("/").filter(Boolean);
+  let common = 0;
+  while (
+    common < fromParts.length &&
+    common < toParts.length &&
+    fromParts[common] === toParts[common]
+  ) {
+    common += 1;
+  }
+  const ups = fromParts.length - common;
+  const remaining = toParts.slice(common);
+  return (ups > 0 ? "../".repeat(ups) : "") + remaining.join("/");
+}
+
+/** True when `p` is `dir` itself or nested under it. */
+export function isUnder(p: string, dir: string): boolean {
+  return p === dir || p.startsWith(`${dir}/`);
+}
+
+/**
+ * Remap a resolved absolute target across a rename. If the target is the renamed file (or under the
+ * renamed directory), re-root it onto the new location; otherwise it is unaffected.
+ */
+export function remapTarget(targetOld: string, oldAbs: string, newAbs: string): string {
+  if (targetOld === oldAbs) {
+    return newAbs;
+  }
+  if (isUnder(targetOld, oldAbs)) {
+    return newAbs + targetOld.slice(oldAbs.length);
+  }
+  return targetOld;
+}
+
+/** Context describing a single rename, shared by every reference rewrite within one document. */
+export interface RemapCtx {
+  /** Absolute POSIX project root. */
+  root: string;
+  /** Absolute POSIX path of the renamed file/dir, before the move. */
+  oldAbs: string;
+  /** Absolute POSIX path of the renamed file/dir, after the move. */
+  newAbs: string;
+  /** Directory the referencing document lived in before the move. */
+  docOldDir: string;
+  /**
+   * Directory the referencing document lives in after the move (differs from docOldDir only when
+   * the document itself is inside the moved subtree).
+   */
+  docNewDir: string;
+}
+
+/**
+ * Recompute a single path reference for a rename, preserving its original style. Returns the new
+ * string, or null when nothing changes.
+ *
+ * `rootRelativeBare` makes a bare value (no "./" or "../") resolve against the project root rather
+ * than the document directory — used for `$layout`, which the compiler resolves against projectRoot
+ * (layout-resolver.ts), and for site-relative conventions.
+ */
+export function rewriteRef(
+  cls: { core: string; suffix: string; rooted: boolean },
+  ctx: RemapCtx,
+  rootRelativeBare = false,
+): string | null {
+  const { core, rooted, suffix } = cls;
+  const startsRel = core.startsWith("./") || core.startsWith("../");
+  const useRoot = rooted || (rootRelativeBare && !startsRel);
+  const baseOld = useRoot ? ctx.root : ctx.docOldDir;
+  const baseNew = useRoot ? ctx.root : ctx.docNewDir;
+
+  const targetOld = joinPosix(useRoot ? ctx.root : baseOld, core);
+  const targetNew = remapTarget(targetOld, ctx.oldAbs, ctx.newAbs);
+  if (targetNew === targetOld && baseOld === baseNew) {
+    return null;
+  }
+
+  let out: string;
+  if (rooted) {
+    out = `/${relativeChain(ctx.root, targetNew)}`;
+  } else {
+    const rel = relativeChain(baseNew, targetNew);
+    if (rel.startsWith("..")) {
+      out = rel;
+    } else if (core.startsWith("./")) {
+      out = `./${rel}`;
+    } else {
+      out = rel;
+    }
+  }
+  out += suffix;
+  return out === core + suffix ? null : out;
+}

package/src/refactor/refs.ts

@@ -0,0 +1,236 @@
+/**
+ * Refs.ts — pure document reference engine for rename-refactoring.
+ *
+ * Two passes, both operating on a parsed (JSON) document tree with no filesystem access: -
+ * `rewriteDocRefs` — recompute every file-path reference across a rename (Pillar B). -
+ * `rewriteTagName` — rename a custom-element tag wherever it is used (Pillar C).
+ *
+ * The walk is structure-aware (it dispatches by JSON key), not a blind string search, and mutates
+ * the passed document in place — callers parse a fresh object per file, so this is safe. Precision
+ * comes from `rewriteRef`'s resolve-and-compare gate in paths.ts: a reference is only rewritten
+ * when it actually resolves to the renamed file.
+ */
+
+import { classifyRef, rewriteRef } from "./paths.ts";
+import type { RemapCtx } from "./paths.ts";
+
+/** A single reference rewrite, for the rename report. */
+export interface RefChange {
+  refType: string;
+  from: string;
+  to: string;
+}
+
+export interface RewriteResult {
+  doc: unknown;
+  changes: RefChange[];
+}
+
+/** Matches `url(...)` targets inside a CSS string value, capturing the optional quote. */
+const URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+
+/** Recompute a scalar string reference under `key`, recording any change. */
+function rewriteScalar(
+  container: Record<string, unknown>,
+  key: string,
+  refType: string,
+  ctx: RemapCtx,
+  changes: RefChange[],
+  rootRelativeBare: boolean,
+): void {
+  const value = container[key];
+  const cls = classifyRef(value);
+  if (cls.kind !== "path") {
+    return;
+  }
+  const out = rewriteRef(cls, ctx, rootRelativeBare);
+  if (out !== null) {
+    changes.push({ from: value as string, refType, to: out });
+    container[key] = out;
+  }
+}
+
+/** Recompute a string array member (e.g. an `$elements` entry), recording any change. */
+function rewriteIndexed(
+  arr: unknown[],
+  index: number,
+  refType: string,
+  ctx: RemapCtx,
+  changes: RefChange[],
+): void {
+  const value = arr[index];
+  const cls = classifyRef(value);
+  if (cls.kind !== "path") {
+    return;
+  }
+  const out = rewriteRef(cls, ctx, false);
+  if (out !== null) {
+    changes.push({ from: value as string, refType, to: out });
+    arr[index] = out;
+  }
+}
+
+/** Rewrite every `url(...)` target inside a CSS string. */
+function rewriteUrls(value: string, ctx: RemapCtx, changes: RefChange[]): string {
+  return value.replaceAll(URL_RE, (match, quote: string, inner: string) => {
+    const cls = classifyRef(inner.trim());
+    if (cls.kind !== "path") {
+      return match;
+    }
+    const out = rewriteRef(cls, ctx, false);
+    if (out === null) {
+      return match;
+    }
+    changes.push({ from: inner.trim(), refType: "url", to: out });
+    return `url(${quote}${out}${quote})`;
+  });
+}
+
+/** Walk a `style` value tree, rewriting `url(...)` in every string it contains. */
+function walkStyle(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
+  if (Array.isArray(node)) {
+    const arr = node as unknown[];
+    for (let i = 0; i < arr.length; i += 1) {
+      const item = arr[i];
+      if (typeof item === "string") {
+        const out = rewriteUrls(item, ctx, changes);
+        if (out !== item) {
+          arr[i] = out;
+        }
+      } else {
+        walkStyle(item, ctx, changes);
+      }
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    if (typeof value === "string") {
+      const out = rewriteUrls(value, ctx, changes);
+      if (out !== value) {
+        obj[key] = out;
+      }
+    } else {
+      walkStyle(value, ctx, changes);
+    }
+  }
+}
+
+/** Recursive document walk dispatching each reference-bearing key. */
+function walk(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
+  if (Array.isArray(node)) {
+    for (const item of node as unknown[]) {
+      walk(item, ctx, changes);
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    switch (key) {
+      case "$ref": {
+        // File-path $ref only; state-scope refs (#/…, $map/…) are filtered by classifyRef.
+        rewriteScalar(obj, key, "$ref", ctx, changes, false);
+        break;
+      }
+      case "$layout": {
+        rewriteScalar(obj, key, "$layout", ctx, changes, true);
+        break;
+      }
+      case "$src":
+      case "$implementation": {
+        rewriteScalar(obj, key, key, ctx, changes, false);
+        break;
+      }
+      case "src":
+      case "href": {
+        rewriteScalar(obj, key, "attr", ctx, changes, false);
+        break;
+      }
+      case "imports": {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          const imp = value as Record<string, unknown>;
+          for (const name of Object.keys(imp)) {
+            rewriteScalar(imp, name, "imports", ctx, changes, false);
+          }
+        }
+        break;
+      }
+      case "$elements": {
+        if (Array.isArray(value)) {
+          const els = value as unknown[];
+          for (let i = 0; i < els.length; i += 1) {
+            if (typeof els[i] === "string") {
+              rewriteIndexed(els, i, "$elements", ctx, changes);
+            } else {
+              walk(els[i], ctx, changes);
+            }
+          }
+        } else {
+          walk(value, ctx, changes);
+        }
+        break;
+      }
+      case "style": {
+        walkStyle(value, ctx, changes);
+        break;
+      }
+      default: {
+        walk(value, ctx, changes);
+      }
+    }
+  }
+}
+
+/** Rewrite every file-path reference in `doc` for a rename described by `ctx`. Mutates `doc`. */
+export function rewriteDocRefs(doc: unknown, ctx: RemapCtx): RewriteResult {
+  const changes: RefChange[] = [];
+  walk(doc, ctx, changes);
+  return { changes, doc };
+}
+
+/** Recursive walk setting `tagName: newTag` wherever it currently equals `oldTag`. */
+function walkTags(node: unknown, oldTag: string, newTag: string, counter: { n: number }): void {
+  if (Array.isArray(node)) {
+    for (const item of node as unknown[]) {
+      walkTags(item, oldTag, newTag, counter);
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (obj.tagName === oldTag) {
+    obj.tagName = newTag;
+    counter.n += 1;
+  }
+  for (const key of Object.keys(obj)) {
+    walkTags(obj[key], oldTag, newTag, counter);
+  }
+}
+
+/**
+ * Rename a custom-element tag throughout `doc` — instance nodes (`<old-tag>`), mapped-list
+ * `map.tagName`, and the component definition file's own root `tagName`. File references (`$ref`,
+ * `$elements`, `cases`) are intentionally left to `rewriteDocRefs`, so the two passes compose.
+ * Mutates `doc`.
+ */
+export function rewriteTagName(
+  doc: unknown,
+  oldTag: string,
+  newTag: string,
+): { doc: unknown; count: number } {
+  const counter = { n: 0 };
+  if (oldTag !== newTag) {
+    walkTags(doc, oldTag, newTag, counter);
+  }
+  return { count: counter.n, doc };
+}

package/src/refactor/watcher.ts

@@ -0,0 +1,70 @@
+/**
+ * Watcher.ts — a small chokidar wrapper that emits coalesced, batched FS-event payloads to a sink.
+ *
+ * Used by the desktop project session (which has no SSE stream) to push filesystem changes to its
+ * webview over RPC. The dev server keeps its own watcher in watch.ts (intertwined with
+ * build/reload); both share the pure `toFsEvent`/`coalesceFsEvents` helpers.
+ */
+
+import { watch as chokidarWatch } from "chokidar";
+import { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
+import type { FsEventPayload } from "./fs-events.ts";
+
+const IGNORE_SEGMENTS = ["node_modules", ".git", "dist", ".jx", ".direnv", ".devenv"];
+
+function isIgnored(path: string): boolean {
+  const f = path.replaceAll("\\", "/");
+  return IGNORE_SEGMENTS.some((s) => f.includes(`/${s}/`) || f.endsWith(`/${s}`));
+}
+
+export interface FsWatcherHandle {
+  close: () => Promise<void>;
+}
+
+/**
+ * Watch `root`, coalescing rapid changes and delivering batches to `sink`. Returns a handle whose
+ * `close()` stops the watcher and clears any pending batch.
+ */
+export function createFsWatcher(
+  root: string,
+  sink: (events: FsEventPayload[]) => void,
+  opts: { debounce?: number } = {},
+): FsWatcherHandle {
+  const debounceMs = opts.debounce ?? 40;
+  let buffer: FsEventPayload[] = [];
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const watcher = chokidarWatch(root, {
+    ignoreInitial: true,
+    ignorePermissionErrors: true,
+    ignored: (path) => isIgnored(path),
+  });
+
+  watcher.on("all", (eventType, changedPath) => {
+    const event = toFsEvent(eventType, root, changedPath);
+    if (!event) {
+      return;
+    }
+    buffer = coalesceFsEvents(buffer, event);
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      if (buffer.length > 0) {
+        sink(buffer);
+        buffer = [];
+      }
+    }, debounceMs);
+  });
+
+  return {
+    close: async () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      buffer = [];
+      await watcher.close();
+    },
+  };
+}

package/src/server.ts

@@ -274,9 +274,12 @@ export async function createDevServer(options: {
       // Static files
 
       // If the URL path is an absolute filesystem path under the active project, serve directly.
-      // Browsers produce "//abs/path" when an absolute path is used as a URL path — normalise.
-      const fsPath = path.startsWith("//") ? path.slice(1) : path;
-      if (activeProjectRoot && fsPath.startsWith(activeProjectRoot)) {
+      // A POSIX absolute path arrives as "//abs/path"; a Windows one as "/C:/dir/file" (leading
+      // Slash + forward slashes), so drop the slash before the drive letter. Compare with
+      // Separators normalised, since activeProjectRoot is OS-native (backslashes on Windows).
+      const fsPath = path.startsWith("//") ? path.slice(1) : path.replace(/^\/([A-Za-z]:)/, "$1");
+      const normSep = (p: string) => p.replaceAll("\\", "/");
+      if (activeProjectRoot && normSep(fsPath).startsWith(normSep(activeProjectRoot))) {
         const file = Bun.file(fsPath);
         if (await file.exists()) {
           return new Response(file);

package/src/studio-api.ts

@@ -7,11 +7,18 @@
  * All paths are relative to the project root. Directory traversal above root is rejected.
  */
 
-import { basename, dirname, extname, isAbsolute, relative, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { buildProjectFormatRegistry } from "@jxsuite/compiler/format-host";
+import { applyRename } from "./refactor/apply.ts";
+import {
+  dependenciesNeedInstall,
+  installDependencies,
+  outdatedPackages,
+  setPackageVersions,
+} from "./packages.ts";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 import * as claude from "./claude-session.ts";
 import type { ClassJsonDef } from "./types.ts";
@@ -20,6 +27,14 @@ import type { ProjectConfig } from "@jxsuite/schema/types";
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
 const fwd = (p: string) => p.replaceAll("\\", "/");
 
+/**
+ * Expand a leading `~` to the user's home directory using path.join so separators are normalised (a
+ * plain string replace left the input's forward slashes intact, yielding mixed separators on
+ * Windows) and falling back to USERPROFILE where HOME is unset.
+ */
+const expandTilde = (p: string) =>
+  p.startsWith("~") ? join(process.env.HOME || process.env.USERPROFILE || "", p.slice(1)) : p;
+
 interface PackageJson {
   name?: string;
   workspaces?: unknown;
@@ -189,8 +204,8 @@ export function parseGitStatus(out: string) {
     } else if (line.startsWith("# branch.ab ")) {
       const m = line.match(/\+(\d+) -(\d+)/);
       if (m) {
-        ahead = Number.parseInt(m[1]!, 10);
-        behind = Number.parseInt(m[2]!, 10);
+        ahead = Math.trunc(Number(m[1]!));
+        behind = Math.trunc(Number(m[2]!));
       }
     } else if (line.startsWith("1 ") || line.startsWith("2 ")) {
       const parts = line.split(" ");
@@ -317,17 +332,13 @@ export async function handleStudioApi(
     }
     try {
       // Walk up from file's directory looking for project.json
-      let dir = dirname(
-        filePath.startsWith("~") ? filePath.replace("~", process.env.HOME || "") : filePath,
-      );
+      const absFile = expandTilde(filePath);
+      let dir = dirname(absFile);
       while (dir) {
         const candidate = resolve(dir, "project.json");
         if (existsSync(candidate)) {
           const config = JSON.parse(readFileSync(candidate, "utf8")) as ProjectConfig;
           const relPath = fwd(dir);
-          const absFile = filePath.startsWith("~")
-            ? filePath.replace("~", process.env.HOME || "")
-            : filePath;
           const fileRelPath = fwd(relative(dir, absFile));
           return Response.json({
             fileRelPath,
@@ -672,6 +683,7 @@ export async function handleStudioApi(
       const packages: {
         name: string;
         version: string;
+        dev: boolean;
         hasCem: boolean;
         customElementsPath: string | null;
       }[] = [];
@@ -690,6 +702,7 @@ export async function handleStudioApi(
           const depPkg = JSON.parse(await readFile(actualPath, "utf8")) as PackageJson;
           packages.push({
             customElementsPath: depPkg.customElements || null,
+            dev: pkg.dependencies?.[name] === undefined,
             hasCem: Boolean(depPkg.customElements),
             name,
             version,
@@ -798,13 +811,61 @@ export async function handleStudioApi(
     }
   }
 
+  // Install all dependencies (bun install)
+  if (path === "/__studio/packages/install" && req.method === "POST") {
+    try {
+      const body = (await req.json().catch(() => ({}))) as { dir?: string };
+      const dir = body.dir || activeProjectRoot || root;
+      const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
+      return Response.json(await installDependencies(scanRoot));
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
+  // Whether dependencies need installing (node_modules missing)
+  if (path === "/__studio/packages/needs-install" && req.method === "GET") {
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+    const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
+    return Response.json({ needsInstall: dependenciesNeedInstall(scanRoot) });
+  }
+
+  // Dependencies with a newer version available
+  if (path === "/__studio/packages/outdated" && req.method === "GET") {
+    try {
+      const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+      const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
+      return Response.json(await outdatedPackages(scanRoot));
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
+  // Set version ranges for one or more packages, then reinstall
+  if (path === "/__studio/packages/set-versions" && req.method === "POST") {
+    try {
+      const body = (await req.json()) as {
+        dir?: string;
+        updates?: { name: string; version: string; dev?: boolean }[];
+      };
+      if (!Array.isArray(body.updates)) {
+        return Response.json({ error: "Missing updates" }, { status: 400 });
+      }
+      const dir = body.dir || activeProjectRoot || root;
+      const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
+      return Response.json(await setPackageVersions(scanRoot, body.updates));
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
   // Read file
   if (path === "/__studio/file" && req.method === "GET") {
     const fp = url.searchParams.get("path");
     if (!fp) {
       return new Response("Missing path", { status: 400 });
     }
-    const abs = fp.startsWith("~") ? fp.replace("~", process.env.HOME || "") : fp;
+    const abs = expandTilde(fp);
     try {
       assertAccessible(abs, root, activeProjectRoot);
     } catch (error) {
@@ -913,13 +974,23 @@ export async function handleStudioApi(
     try {
       await mkdir(dirname(absTo), { recursive: true });
       await rename(absFrom, absTo);
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+    // Refactor pass: rewrite path references project-wide and, for a component, auto-rename its tag.
+    // The move already succeeded, so a refactor failure is reported but never fails the rename.
+    const scanRoot = activeProjectRoot ?? root;
+    try {
+      const registry = await getFormatRegistry(scanRoot);
+      const report = await applyRename({ absFrom, absTo, registry, root: scanRoot });
+      return Response.json(report);
+    } catch (error) {
       return Response.json({
+        error: errorMessage(error),
         from: fwd(relative(root, absFrom)),
         ok: true,
         to: fwd(relative(root, absTo)),
       });
-    } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
     }
   }
 

package/src/watch.ts

@@ -3,7 +3,9 @@
 import { watch as chokidarWatch } from "chokidar";
 import { relative } from "node:path";
 import { rebuild } from "./build.ts";
+import { coalesceFsEvents, toFsEvent } from "./refactor/fs-events.ts";
 import type { BuildEntry } from "./types.ts";
+import type { FsEventPayload } from "./refactor/fs-events.ts";
 
 const DEFAULT_IGNORE = [
   "**/node_modules/**",
@@ -86,6 +88,17 @@ export function createWatcher(
     }
   }
 
+  /**
+   * Send a _named_ SSE event. The preview iframe only listens to the default (unnamed) `onmessage`,
+   * so named events (e.g. "fs") reach the studio shell without triggering a preview reload.
+   */
+  function broadcastEvent(event: string, payload: unknown) {
+    const frame = `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
+    for (const send of clients) {
+      send(frame);
+    }
+  }
+
   function handleSSE() {
     /** @type {((msg: string) => void) | undefined} */
     let send: ((msg: string) => void) | undefined;
@@ -121,6 +134,9 @@ export function createWatcher(
   }
 
   let timer: ReturnType<typeof setTimeout> | null = null;
+  let fsTimer: ReturnType<typeof setTimeout> | null = null;
+  let fsBuffer: FsEventPayload[] = [];
+  const fsDebounceMs = 40;
   const watcher = chokidarWatch(root, {
     awaitWriteFinish: {
       pollInterval: 10,
@@ -131,11 +147,26 @@ export function createWatcher(
     ignored: (watchedPath) => shouldIgnore(watchedPath, ignore),
   });
 
-  watcher.on("all", (_, changedPath) => {
+  watcher.on("all", (eventType, changedPath) => {
     const filename = relative(root, changedPath);
     if (!filename || filename.startsWith("..")) {
       return;
     }
+
+    // Structured FS events for the studio sidebar (coalesced + batched), emitted as a named "fs"
+    // SSE event so the preview iframe ignores them while the studio shell subscribes to them.
+    const fsEvent = toFsEvent(eventType, root, changedPath);
+    if (fsEvent) {
+      fsBuffer = coalesceFsEvents(fsBuffer, fsEvent);
+      clearTimeout(fsTimer ?? undefined);
+      fsTimer = setTimeout(() => {
+        if (fsBuffer.length > 0) {
+          broadcastEvent("fs", { events: fsBuffer });
+          fsBuffer = [];
+        }
+      }, fsDebounceMs);
+    }
+
     clearTimeout(timer ?? undefined);
     timer = setTimeout(async () => {
       if (builds.length > 0) {
@@ -155,5 +186,5 @@ export function createWatcher(
     }, debounceMs);
   });
 
-  return { broadcast, handleSSE, watcher };
+  return { broadcast, broadcastEvent, handleSSE, watcher };
 }