@jxsuite/server 3.0.0 → 4.0.0

package/src/preview-client.ts

@@ -0,0 +1,177 @@
+/**
+ * The script a live-preview page runs: reload when the tree changes, follow a retarget, and say so
+ * when the origin is gone.
+ *
+ * It ships as a string rather than a file because it is served, not imported — the page that runs
+ * it is on a different origin from anything in this package, and generating it is how the URLs it
+ * needs stay a fact of the server that serves it.
+ *
+ * Three behaviours are here rather than in the page because only this side can know them:
+ *
+ * **A reload, not an in-place re-render.** The runtime cannot be re-run over a live document:
+ * `Jx()` does not scope its effects, a custom element cannot be re-registered in a realm (so an
+ * edited component would keep its old class forever), the document cache has no invalidation,
+ * `$head` would be injected twice, and the shell renders the head server-side anyway. A document
+ * load is the only thing that is actually correct, and it is cheap here because composing is
+ * local.
+ *
+ * **Scroll is restored by hand.** The browser's own restoration runs against the document as it
+ * exists at that moment, and a client-rendered page has an empty body then — so it restores to a
+ * zero-height document and lands at the top. The shell turns it off; this puts it back after the
+ * render, and keeps re-applying briefly because content resolved after mount changes the height.
+ *
+ * **A dead origin is distinguished from a restarting one.** EventSource retries forever and cannot
+ * tell the two apart, so after enough consecutive failures this asks: one fetch that a live origin
+ * always answers. A network error means the project closed, and then the stream is stopped rather
+ * than left retrying every half-second for as long as the tab is open. The last render stays on
+ * screen, because it is still what the reader was reading.
+ */
+
+/** Where the client's own surfaces live, so the page and the server cannot disagree about them. */
+export const LIVE_NAMESPACE = "/__jx_live__";
+
+/** Consecutive reconnect failures before the client asks whether the origin is gone at all. */
+const PROBE_AFTER_FAILURES = 20;
+
+/** How long the restore keeps re-applying, for content that resolves after the render. */
+const SCROLL_SETTLE_MS = 1500;
+
+/**
+ * The reload client, as source.
+ *
+ * Written as one string with no build step: it is ~80 lines of DOM code that must run in a page
+ * this package does not otherwise touch, and a bundler in the path would be a second thing to keep
+ * working for no gain.
+ */
+export const PREVIEW_CLIENT_JS = `
+const NS = ${JSON.stringify(LIVE_NAMESPACE)};
+const KEY = "jx-preview-scroll";
+let failures = 0;
+let stopped = false;
+let source = null;
+
+/* The banner lives in a shadow root: the page around it is the project's own site, carrying the
+   project's own CSS, which is free to style every div on the page. */
+function banner(text, tone) {
+  let host = document.getElementById("jx-preview-status");
+  if (!host) {
+    host = document.createElement("div");
+    host.id = "jx-preview-status";
+    document.documentElement.append(host);
+    host.attachShadow({ mode: "open" });
+  }
+  host.shadowRoot.innerHTML = text
+    ? '<div style="position:fixed;left:0;right:0;bottom:0;z-index:2147483647;' +
+      "font:13px/1.4 system-ui,sans-serif;padding:8px 12px;color:#fff;background:" +
+      (tone === "dead" ? "#8a1c1c" : "#444") + ';">' + text + "</div>"
+    : "";
+}
+
+function saveScroll() {
+  try {
+    sessionStorage.setItem(
+      KEY,
+      JSON.stringify({ path: location.pathname, x: scrollX, y: scrollY }),
+    );
+  } catch {}
+}
+
+/* Restored after the render resolves, then re-applied for a moment: a page whose height depends on
+   data fetched after mount is shorter at restore time than it will be a tick later. */
+function restoreScroll() {
+  let saved = null;
+  try {
+    saved = JSON.parse(sessionStorage.getItem(KEY) || "null");
+  } catch {}
+  if (!saved || saved.path !== location.pathname || (saved.x === 0 && saved.y === 0)) {
+    return;
+  }
+  const until = Date.now() + ${SCROLL_SETTLE_MS};
+  const apply = () => {
+    scrollTo(saved.x, saved.y);
+    if (Date.now() < until) {
+      requestAnimationFrame(apply);
+    }
+  };
+  apply();
+}
+
+function reload() {
+  saveScroll();
+  location.reload();
+}
+
+function connect() {
+  if (stopped) {
+    return;
+  }
+  source = new EventSource(NS + "/reload?route=" + encodeURIComponent(location.pathname));
+  source.onopen = () => {
+    failures = 0;
+    banner("");
+  };
+  source.onmessage = reload;
+  source.addEventListener("navigate", (event) => {
+    const message = JSON.parse(event.data);
+    /* Acknowledge BEFORE navigating: the navigation tears this stream down, so an ack sent after
+       it would never leave the tab, and the editor would open a second one. */
+    fetch(NS + "/ack", {
+      body: JSON.stringify({ gen: message.gen }),
+      headers: { "Content-Type": "application/json" },
+      keepalive: true,
+      method: "POST",
+    }).catch(() => {});
+    /* Best effort, and never advertised: a background tab cannot raise itself in Chrome, and
+       under Wayland the compositor arbitrates. It costs one line and occasionally works. */
+    try {
+      window.focus();
+    } catch {}
+    if (message.route === location.pathname) {
+      reload();
+    } else {
+      saveScroll();
+      location.assign(message.route);
+    }
+  });
+  source.onerror = () => {
+    failures += 1;
+    if (failures === 1) {
+      /* A restart reconnects inside half a second, so saying anything now is noise. */
+      setTimeout(() => {
+        if (failures > 0 && !stopped) {
+          banner("Preview disconnected — reconnecting…", "warn");
+        }
+      }, 2000);
+    }
+    if (failures >= ${PROBE_AFTER_FAILURES}) {
+      probe();
+    }
+  };
+}
+
+/* EventSource cannot tell "restarting" from "gone", so ask something a live origin always answers. */
+function probe() {
+  fetch(NS + "/ping", { cache: "no-store" }).catch(() => {
+    stopped = true;
+    if (source) {
+      source.close();
+    }
+    banner(
+      "This preview is no longer live — Jx Studio closed this project. " +
+        "The page below is the last render.",
+      "dead",
+    );
+  });
+}
+
+addEventListener("pagehide", saveScroll);
+/* A tab restored from the back/forward cache has a suspended stream and a stale document, and no
+   reload will arrive to fix either. */
+addEventListener("pageshow", (event) => {
+  if (event.persisted) {
+    location.reload();
+  }
+});
+restoreScroll();
+connect();
+`;

package/src/project-server.ts

@@ -345,6 +345,22 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
           return;
         }
 
+        /*
+         * The keepalive, answered AHEAD of the session lookup.
+         *
+         * A ping's whole job is to prove the socket is alive, and that is a fact about the socket,
+         * not about which project a window is bound to. Behind the lookup it would be refused —
+         * and close the socket — in exactly the states where staying connected matters most: a
+         * window mid-re-root, or one whose session was torn down and rebuilt. The shell sends one
+         * every 30s because this server's idle timeout is 120s and a studio can be quiet for far
+         * longer than that (a site import runs for minutes over a separate HTTP stream and touches
+         * this socket not at all).
+         */
+        if (msg.method === "__ping") {
+          ws.send(JSON.stringify({ id: msg.id, result: null }));
+          return;
+        }
+
         // Re-resolve the session FRESH each message (fail-closed for Phase 7 multi-window).
         const session = resolveSession(ws.data.winId);
         if (!session) {

package/src/refactor/apply.ts

@@ -14,7 +14,9 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { isUnder } from "./paths.ts";
 import { rewriteDocRefs, rewriteTagName } from "./refs.ts";
 import { documentGlob, fwd, loadDoc, skipScanPath } from "./scan.ts";
+import { refactorMounts } from "./mounts.ts";
 import type { RefChange } from "./refs.ts";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 
 export interface FileChange {
@@ -47,6 +49,12 @@ export interface ApplyRenameOptions {
   absTo: string;
   /** Format registry for the project (parse/serialize of non-JSON documents). */
   registry: FormatRegistry;
+  /**
+   * Project-relative asset mounts, for rewriting rooted references through the mount lane. Omitted,
+   * the engine loads them from `root` — see `mounts.ts` for why that is the default and not the
+   * exception.
+   */
+  mounts?: readonly AssetMount[];
 }
 
 /** Derive a custom-element tag from a component filename (strips `.class.json` or the extension). */
@@ -67,6 +75,7 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
   const root = fwd(opts.root);
   const absFrom = fwd(opts.absFrom);
   const absTo = fwd(opts.absTo);
+  const mounts = opts.mounts ?? (await refactorMounts(opts.root));
 
   let isDir = false;
   try {
@@ -120,6 +129,7 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
       const { changes } = rewriteDocRefs(doc, {
         docNewDir,
         docOldDir,
+        mounts,
         newAbs: absTo,
         oldAbs: absFrom,
         root,

package/src/refactor/mounts.ts

@@ -0,0 +1,49 @@
+/**
+ * Mounts.ts — the asset mounts the refactor engine resolves rooted references through.
+ *
+ * A rooted reference (`/images/hero.jpg`) is a site URL, and an extension may claim a slice of that
+ * URL space and serve it out of a directory of its own (specs/extensions.md §8.5). So "which file
+ * does this URL name?" cannot be answered from the project root alone, and neither the read pass
+ * nor the write pass can be correct without the mount list.
+ *
+ * **The engine loads them rather than taking them.** The format registry is passed in by every
+ * caller because every caller already has one; nobody has a mount list, and there are four hosts
+ * (two dev-server routes, the desktop project session, the cloud gateway). An option four hosts
+ * each have to remember is an option three of them eventually do not — and a lane that silently
+ * fails to resolve is precisely the defect this module exists to close (issue 239). `mounts` stays
+ * available on both option types for a host that already has the list, and for tests.
+ *
+ * **Project-relative, filtered.** `loadAssetMounts` hands back whatever directory an extension
+ * declared, which is normally absolute; `asset-paths.ts` documents its mount parameter as
+ * project-relative. Rebasing here is that conversion, and a mount resolving OUTSIDE the project is
+ * dropped: its files are not addressable by a project-relative path, so no rename can reach them
+ * and no reference to them can be counted. `projectPathsForSiteUrl` declines the same case by
+ * name.
+ */
+
+import { relative } from "node:path";
+import { projectAssetMounts } from "../resolve.ts";
+import { fwd } from "./scan.ts";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
+
+/**
+ * Project-relative asset mounts for a project root, or an empty list when there is no project here.
+ *
+ * Not memoised on its own account: `projectAssetMounts` is already cached against `project.json`'s
+ * mtime, and a second cache here would be a second thing to invalidate.
+ *
+ * @param {string} root - Absolute project root
+ * @returns {Promise<AssetMount[]>} Mounts whose `dir` is relative to `root`
+ */
+export async function refactorMounts(root: string): Promise<AssetMount[]> {
+  const declared = await projectAssetMounts(root);
+  const out: AssetMount[] = [];
+  for (const mount of declared) {
+    const dir = fwd(relative(root, mount.dir));
+    if (dir === "" || dir.startsWith("../") || /^[A-Za-z]:/.test(dir)) {
+      continue;
+    }
+    out.push({ dir, urlPrefix: mount.urlPrefix });
+  }
+  return out;
+}

package/src/refactor/paths.ts

@@ -6,7 +6,42 @@
  * them in. The relative-path style mirrors `computeRelativePath` in the studio
  * (packages/studio/src/files/components.ts): "./" for same-dir/descendant targets, "../"-chains
  * otherwise.
+ *
+ * **A rooted reference is a site URL, not a project path.** `/images/hero.jpg` names whichever file
+ * the host serves at that URL, and there are three places it can live: an extension's asset mount,
+ * the project root, and `public/`. This module does not re-derive that mapping — it calls
+ * `@jxsuite/schema/asset-paths`, the same lane math the canvas, the dev server and the build all
+ * use. Resolving a rooted ref against the project root alone was how a rename of any file under
+ * `public/` rewrote nothing while promising otherwise (issue 239).
+ *
+ * @docs studio/projects/pages-layouts-components
+ */
+
+import { BUILD_LANES, projectPathsForSiteUrl, siteUrlForPath } from "@jxsuite/schema/asset-paths";
+import type { AssetLane, AssetMount } from "@jxsuite/schema/asset-paths";
+
+/**
+ * The lanes a rewritten site URL is re-emitted through, most-publishable first.
+ *
+ * {@link BUILD_LANES} first, so a file that a deployed build publishes keeps the URL that build
+ * serves — `public/images/hero.jpg` re-emits as `/images/hero.jpg`, not the `/public/...` form the
+ * dev server would also answer. The `root` lane is the fallback for a file only the dev server can
+ * reach: that reference was already build-broken before the rename (the server says so at request
+ * time), and preserving it is strictly better than leaving it pointing at a file that has moved.
+ *
+ * The consequence is that this is total for any non-empty in-project path — a rename can always
+ * express its destination — so there is no "unrewritable reference" case to report.
+ */
+const AUTHORED_LANES: readonly AssetLane[] = [...BUILD_LANES, "root"];
+
+/**
+ * The lanes a rooted reference is READ through: every place the dev server would look.
+ *
+ * Deliberately wider than {@link AUTHORED_LANES} and unordered in effect, because the reader checks
+ * all of them. Where two lanes both name an existing file, `/hero.jpg` genuinely is ambiguous, and
+ * counting both is the safe side of a question asked to warn someone before a delete.
  */
+const READ_LANES: readonly AssetLane[] = ["mounts", "root", "public"];
 
 /** Classification of a reference string value. */
 export type RefClass =
@@ -127,6 +162,54 @@ export function remapTarget(targetOld: string, oldAbs: string, newAbs: string):
   return targetOld;
 }
 
+/**
+ * Every project-relative path a rooted (site-URL) reference could name, most-preferred first.
+ *
+ * @param {string} core - The reference with any `?query`/`#fragment` already split off
+ * @param {readonly AssetMount[]} mounts - Project-relative asset mounts
+ * @returns {string[]} Candidate project-relative paths
+ */
+export function projectPathsForRootedRef(core: string, mounts: readonly AssetMount[]): string[] {
+  return projectPathsForSiteUrl(core, mounts, READ_LANES);
+}
+
+/** A final path segment must carry an extension, and the extension must contain a letter. */
+const FILE_SEGMENT_RE = /^[^.][^/]*\.[A-Za-z0-9]{0,7}[A-Za-z][A-Za-z0-9]{0,7}$/;
+
+/**
+ * True when a string is shaped like a file a document could reference.
+ *
+ * The walker in refs.ts knows nine keys that carry references by name. The commonest media
+ * reference in a real project is under none of them — a schema-typed component prop (`$props.bg`),
+ * a content entry's frontmatter (`cover:`), `project.json`'s `defaults.layout` — so the walker
+ * falls back to SHAPE for every other key, and this is the shape test.
+ *
+ * It is deliberately not schema-aware. `walkDocRefs` is pure and schema-blind by design, and the
+ * write side shares it; a schema oracle would have to be threaded through `applyRename` too, would
+ * need a project-wide `tagName → media prop` index from a second pass, and would still miss a prop
+ * whose component definition failed to parse.
+ *
+ * Precision does not come from here. It comes from the resolve-and-compare gate the callers already
+ * apply: a candidate only counts when it resolves to the exact file queried. This just has to be
+ * cheap and to refuse prose. The extension requirement is what does that — it rejects routes
+ * (`/pricing`), bare words, MIME types (`image/png`) and identifiers, and the letter-in-extension
+ * rule additionally rejects version strings (`1.2.3`), which are otherwise file-shaped.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function looksLikeFileRef(value: string): boolean {
+  if (value.length === 0 || /\s/.test(value) || value.includes("${")) {
+    return false;
+  }
+  const cls = classifyRef(value);
+  if (cls.kind !== "path") {
+    return false;
+  }
+  const last = cls.core.slice(cls.core.lastIndexOf("/") + 1);
+  return FILE_SEGMENT_RE.test(last);
+}
+
 /** Context describing a single rename, shared by every reference rewrite within one document. */
 export interface RemapCtx {
   /** Absolute POSIX project root. */
@@ -142,6 +225,11 @@ export interface RemapCtx {
    * the document itself is inside the moved subtree).
    */
   docNewDir: string;
+  /**
+   * Project-relative asset mounts, for resolving rooted references through the mount lane. Absent
+   * is the same as none, which leaves the `root` and `public/` lanes.
+   */
+  mounts?: readonly AssetMount[];
 }
 
 /**
@@ -158,30 +246,63 @@ export function rewriteRef(
   rootRelativeBare = false,
 ): string | null {
   const { core, rooted, suffix } = cls;
+  if (rooted) {
+    return rewriteSiteUrl(core, suffix, ctx);
+  }
   const startsRel = core.startsWith("./") || core.startsWith("../");
-  const useRoot = rooted || (rootRelativeBare && !startsRel);
+  const useRoot = 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 targetOld = joinPosix(baseOld, core);
   const targetNew = remapTarget(targetOld, ctx.oldAbs, ctx.newAbs);
   if (targetNew === targetOld && baseOld === baseNew) {
     return null;
   }
 
+  const rel = relativeChain(baseNew, targetNew);
   let out: string;
-  if (rooted) {
-    out = `/${relativeChain(ctx.root, targetNew)}`;
+  if (rel.startsWith("..")) {
+    out = rel;
+  } else if (core.startsWith("./")) {
+    out = `./${rel}`;
   } else {
-    const rel = relativeChain(baseNew, targetNew);
-    if (rel.startsWith("..")) {
-      out = rel;
-    } else if (core.startsWith("./")) {
-      out = `./${rel}`;
-    } else {
-      out = rel;
-    }
+    out = rel;
   }
   out += suffix;
   return out === core + suffix ? null : out;
 }
+
+/**
+ * Rewrite a rooted reference — a site URL — across a rename, through the lanes that give it
+ * meaning.
+ *
+ * Each lane is tried on its own so the MATCHED one is known: a lane is only a candidate when the
+ * file it names is the one that moved. The answer is then re-derived from the destination through
+ * {@link AUTHORED_LANES}, which is what turns a `public/` move into the right URL rather than a
+ * root-relative path that would 404 on the deployed site.
+ *
+ * Returns null when no lane names the moved file, which is the overwhelmingly common case — most
+ * references in a document have nothing to do with any given rename.
+ */
+function rewriteSiteUrl(core: string, suffix: string, ctx: RemapCtx): string | null {
+  const mounts = ctx.mounts ?? [];
+  for (const lane of READ_LANES) {
+    const [candidate] = projectPathsForSiteUrl(core, mounts, [lane]);
+    if (candidate === undefined) {
+      continue;
+    }
+    const targetOld = joinPosix(ctx.root, candidate);
+    const targetNew = remapTarget(targetOld, ctx.oldAbs, ctx.newAbs);
+    if (targetNew === targetOld) {
+      continue;
+    }
+    const url = siteUrlForPath(relativeChain(ctx.root, targetNew), mounts, AUTHORED_LANES);
+    if (url === null) {
+      continue;
+    }
+    const out = url + suffix;
+    return out === core + suffix ? null : out;
+  }
+  return null;
+}

package/src/refactor/refs.ts

@@ -16,9 +16,11 @@
  *
  * The visitor seam is what stops the read side from being a second, drifting copy of the key list.
  * A new reference-bearing key added below is a key the usage count sees on the same commit.
+ *
+ * @docs studio/projects/pages-layouts-components
  */
 
-import { classifyRef, rewriteRef } from "./paths.ts";
+import { classifyRef, looksLikeFileRef, rewriteRef } from "./paths.ts";
 import type { RemapCtx } from "./paths.ts";
 
 /** A single reference rewrite, for the rename report. */
@@ -37,7 +39,8 @@ export interface RewriteResult {
  * One visit of a reference-bearing string.
  *
  * @param value — the raw authored reference, exactly as written.
- * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`).
+ * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`,
+ *   or `path` for a value matched by shape rather than by key name).
  * @param rootRelativeBare — whether a bare value resolves against the project root (`$layout`).
  * @returns A replacement string to write back, or `null` to leave the document untouched.
  */
@@ -50,6 +53,17 @@ export type RefVisitor = (
 /** Matches `url(...)` targets inside a CSS string value, capturing the optional quote. */
 const URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
 
+/**
+ * Keys whose string values are PROSE, and are therefore never offered to the shape fallback.
+ *
+ * A page that writes "see layouts/base.json" in its body text names a file without referencing it,
+ * and rewriting that sentence during a rename would be vandalism. Almost every such string is
+ * already excluded by the whitespace test in `looksLikeFileRef`; these two keys are where a
+ * single-token one is plausible, and a whole-repo survey of file-shaped string values found
+ * non-reference hits under no other key.
+ */
+const PROSE_KEYS = new Set(["textContent", "innerHTML"]);
+
 /** Offer a scalar string reference under `key` to the visitor, writing back any replacement. */
 function visitScalar(
   container: Record<string, unknown>,
@@ -189,8 +203,42 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
         walkStyle(value, visit);
         break;
       }
+      /*
+       * Everything else, by SHAPE.
+       *
+       * The cases above are the keys that carry a reference BY NAME, and for years that list was
+       * taken to be the whole of it. It is not: the commonest media reference in a real project is
+       * a schema-typed component prop (`$props.bg`, `attributes["props.image"]`), and beside it sit
+       * a content entry's frontmatter (`cover:`), a prop schema's `default`, `project.json`'s
+       * `defaults.layout`, `poster`, `srcset` and `$head` meta `content`. Measured across the
+       * committed starters, 73 of 101 files under `public/` were used and reported zero.
+       *
+       * Naming those keys one at a time would be the same mistake with a longer list — the next
+       * extension to define a media-typed prop would reopen it. So an unrecognised string is
+       * offered whenever it is SHAPED like a file, and precision stays where it already was: the
+       * caller's resolve-and-compare gate, which only counts a value that resolves to the exact
+       * file in question.
+       */
       default: {
-        walkDocRefs(value, visit);
+        if (typeof value === "string") {
+          if (!PROSE_KEYS.has(key) && looksLikeFileRef(value)) {
+            visitScalar(obj, key, "path", visit, false);
+          }
+        } else if (Array.isArray(value)) {
+          const arr = value as unknown[];
+          for (let i = 0; i < arr.length; i += 1) {
+            const item = arr[i];
+            if (typeof item === "string") {
+              if (!PROSE_KEYS.has(key) && looksLikeFileRef(item)) {
+                visitIndexed(arr, i, "path", visit);
+              }
+            } else {
+              walkDocRefs(item, visit);
+            }
+          }
+        } else {
+          walkDocRefs(value, visit);
+        }
       }
     }
   }

package/src/refactor/scan.ts

@@ -22,10 +22,30 @@ export interface LoadedDoc {
 
 const isJsonPath = (p: string) => p.endsWith(".json");
 
-/** Skip vendored / build / agent directories (mirrors the component-discovery filter). */
+/**
+ * Skip vendored / build / agent directories (mirrors the component-discovery filter), and generated
+ * schema artifacts.
+ *
+ * Every committed `*.schema.json` in a project is a build output — `bun run schema:generate-all`
+ * composes the `project.schema.json` / `document.schema.json` pair into each project root — and the
+ * generators embed live `examples` blocks. `project.core.schema.json`'s `$head` example carries
+ * `/favicon.svg`, and the per-project entry schema enumerates the project's own layouts, so a sweep
+ * that reads them makes every project report its own schema as a referrer of its favicon and its
+ * base layout. Those are not references anyone authored, and nobody should be told a rename will
+ * break one.
+ *
+ * The stale-schema problem a skipped file leaves behind already has an owner: `bun run
+ * schema:verify` catches it and `schema:sync` regenerates it. A rewrite here would be a second
+ * writer on a generated file.
+ */
 export function skipScanPath(match: string): boolean {
   const f = fwd(match);
-  return match.includes("node_modules") || f.includes("dist/") || f.includes(".claude/");
+  return (
+    match.includes("node_modules") ||
+    f.includes("dist/") ||
+    f.includes(".claude/") ||
+    f.endsWith(".schema.json")
+  );
 }
 
 /** Build the recursive glob covering JSON plus every registered document/content extension. */

package/src/server.ts

@@ -421,6 +421,7 @@ export async function createDevServer(options: {
 
         const res = await handleStudioApi(req, url, absRoot, activeProjectRoot, {
           allowedRoots,
+          onFileMoved: (absPath) => collabRegistry.handleExternalChange(absPath),
           onProjectCreated: (created) => createdRoots.push(created),
         });
         if (res) {