@jxsuite/server 2.2.7 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "2.2.7",
+  "version": "3.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -38,21 +38,21 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.8.2",
-    "@jxsuite/compiler": "^2.0.7",
-    "@jxsuite/create": "^1.3.6",
-    "@jxsuite/import": "^0.39.7",
-    "@jxsuite/protocol": "^1.2.1",
-    "@jxsuite/runtime": "^2.0.5",
-    "@jxsuite/schema": "^1.8.1",
-    "@jxsuite/starters": "^1.6.3",
+    "@jxsuite/collab": "^0.8.3",
+    "@jxsuite/compiler": "^2.0.8",
+    "@jxsuite/create": "^1.3.7",
+    "@jxsuite/import": "^0.39.8",
+    "@jxsuite/protocol": "^2.0.0",
+    "@jxsuite/runtime": "^2.1.0",
+    "@jxsuite/schema": "^1.9.0",
+    "@jxsuite/starters": "^1.6.4",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.5.4",
-    "@jxsuite/connector": "^0.5.4",
-    "@jxsuite/parser": "^1.5.5"
+    "@jxsuite/auth": "^0.5.5",
+    "@jxsuite/connector": "^0.5.5",
+    "@jxsuite/parser": "^1.5.6"
   }
 }

package/src/net-guard.ts

@@ -307,14 +307,83 @@ export async function serveContained(absPath: string, root: string): Promise<Res
   return null;
 }
 
+/**
+ * Extensions a BUILD publishes as static assets, so a page may reference one by site URL.
+ *
+ * Deliberately excludes `.json`, `.md` and every other document extension: `serveProjectFile`
+ * serves two URL spaces at once — the SITE's, and the project tree's, which is how the Studio
+ * canvas fetches a component `$ref` — and only the site's is what {@link BUILD_LANES} defines. A
+ * `/components/x-card.json` answered from the project root is Studio's own protocol working
+ * correctly; a `/hero.jpg` answered from the project root is a preview telling a lie.
+ */
+const SITE_ASSET_EXTENSIONS = new Set([
+  ".apng",
+  ".avif",
+  ".bmp",
+  ".css",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".mp3",
+  ".mp4",
+  ".oga",
+  ".ogg",
+  ".ogv",
+  ".otf",
+  ".pdf",
+  ".png",
+  ".svg",
+  ".ttf",
+  ".txt",
+  ".wav",
+  ".webm",
+  ".webmanifest",
+  ".webp",
+  ".woff",
+  ".woff2",
+  ".xml",
+]);
+
+/** Paths already warned about, so a page that loads one image fifty times says it once. */
+const rootLaneWarned = new Set<string>();
+
+/**
+ * Say once, per path, that a file resolves here and will not resolve on the built site.
+ *
+ * @param {string} decodedPath - The site URL that matched the compatibility lane
+ */
+function warnRootLane(decodedPath: string): void {
+  const dot = decodedPath.lastIndexOf(".");
+  const ext = dot === -1 ? "" : decodedPath.slice(dot).toLowerCase();
+  if (!SITE_ASSET_EXTENSIONS.has(ext) || rootLaneWarned.has(decodedPath)) {
+    return;
+  }
+  rootLaneWarned.add(decodedPath);
+  console.warn(
+    `${decodedPath} resolves from the project root, which a BUILD does not do: it publishes ` +
+      `public/ at the site root and nothing else (site-architecture.md §9.3). This file loads in ` +
+      `the preview and 404s on the deployed site — move it into public/ to fix it. This ` +
+      `compatibility lane is going away.`,
+  );
+}
+
 /**
  * Try to serve a project file at its natural URL: an extension asset mount, then
- * absolute-under-root, then root-relative, then public/. Each candidate goes through containedPath
- * (realpath). `decodedPath` is the once-decoded URL pathname (leading slash, forward slashes).
+ * absolute-under-root, then `public/`, then the project root. Each candidate goes through
+ * containedPath (realpath). `decodedPath` is the once-decoded URL pathname (leading slash, forward
+ * slashes).
  *
  * Mounts come first and are contained against their own directory rather than the project root:
  * they exist precisely to publish directories that may sit outside it (extensions.md §8.5).
  *
+ * **`public/` precedes the project root, which is the order a BUILD resolves in.** It did not: the
+ * root came first, so a file at `<root>/hero.jpg` loaded at `/hero.jpg` here and 404'd in
+ * production — a preview that lies in the one direction that matters, and one the spec never
+ * described (`site-architecture.md` §9.3 has always matched the compiler). The root lane survives
+ * as a COMPATIBILITY lane that warns, and is going away; it also still answers the project tree's
+ * own URL space, which is how the Studio canvas fetches a component `$ref`.
+ *
  * The project's BUILT OUTPUT is deliberately NOT here, nor anywhere else in an editing server's
  * chain: these paths mean the project's SOURCES, and a built page addresses the same paths meaning
  * its own output. The built site is served on its own origin instead — see
@@ -342,7 +411,8 @@ export async function serveProjectFile(
     ? decodedPath.slice(1)
     : decodedPath.replace(/^\/([A-Za-z]:)/, "$1");
 
-  // 1. Absolute path that falls under the project root.
+  /* 1. Absolute path that falls under the project root. Not a site URL at all — it is how Studio
+        addresses a file it already holds an absolute path for, so it stays ahead of both lanes. */
   if (normalizeForCompare(fsPath).startsWith(normalizeForCompare(root))) {
     const res = await serveContained(fsPath, root);
     if (res) {
@@ -350,21 +420,27 @@ export async function serveProjectFile(
     }
   }
 
-  // 2. Root-relative.
-  const relRes = await serveContained(resolve(root, `.${decodedPath}`), root);
-  if (relRes) {
-    return relRes;
-  }
-
-  // 3. public/ subdirectory.
+  // 2. public/ — the site's own URL space, and the only one a build publishes.
   const pubRes = await serveContained(resolve(root, "public", `.${decodedPath}`), root);
   if (pubRes) {
     return pubRes;
   }
 
+  // 3. The project root — the project tree's URL space, and a compatibility lane for site URLs.
+  const relRes = await serveContained(resolve(root, `.${decodedPath}`), root);
+  if (relRes) {
+    warnRootLane(decodedPath);
+    return relRes;
+  }
+
   return null;
 }
 
+/** Forget which paths have been warned about — for tests, which assert the warning fires. */
+export function resetRootLaneWarnings(): void {
+  rootLaneWarned.clear();
+}
+
 /** Result of decoding a URL pathname: the safe decoded/normalized path, or a rejection Response. */
 export type DecodedPath = { path: string; normPath: string } | { reject: Response };