@jxsuite/server 2.2.6 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "2.2.6",
+  "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.1",
-    "@jxsuite/compiler": "^2.0.6",
-    "@jxsuite/create": "^1.3.5",
-    "@jxsuite/import": "^0.39.6",
-    "@jxsuite/protocol": "^1.2.0",
-    "@jxsuite/runtime": "^2.0.4",
-    "@jxsuite/schema": "^1.8.0",
-    "@jxsuite/starters": "^1.6.2",
+    "@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.3",
-    "@jxsuite/connector": "^0.5.3",
-    "@jxsuite/parser": "^1.5.4"
+    "@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 };
 

package/src/studio-api.ts

@@ -8,6 +8,7 @@
  */
 
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { componentMetaFrom } from "@jxsuite/schema/component-meta";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
@@ -93,38 +94,6 @@ interface ComponentDoc {
   [key: string]: unknown;
 }
 
-interface SlotDef {
-  name: string;
-  fallback?: unknown[];
-}
-
-/**
- * Collect slot definitions (name + fallback children) from a parsed component tree. Whitespace-only
- * names count as unnamed (""). Only static children arrays are walked.
- */
-function collectSlotDefs(node: unknown, out: SlotDef[] = []): SlotDef[] {
-  if (!node || typeof node !== "object" || Array.isArray(node)) {
-    return out;
-  }
-  const el = node as Record<string, unknown>;
-  if (el.tagName === "slot") {
-    const attrs = el.attributes as Record<string, unknown> | undefined;
-    const rawName = attrs?.name;
-    const name = typeof rawName === "string" ? rawName.trim() : "";
-    const { children } = el;
-    out.push({
-      name,
-      ...(Array.isArray(children) && children.length > 0 ? { fallback: children } : {}),
-    });
-  }
-  if (Array.isArray(el.children)) {
-    for (const c of el.children) {
-      collectSlotDefs(c, out);
-    }
-  }
-  return out;
-}
-
 // ─── Extension registry (per project root, invalidated on project.json change) ──
 
 const extensionRegistryCache = new Map<string, { mtime: number; registry: ExtensionRegistry }>();
@@ -792,42 +761,14 @@ export async function handleStudioApi(
             const source = await readFile(fp, "utf8");
             content = (await entry.call("parse", source)) as ComponentDoc;
           }
-          if (content.tagName && content.tagName.includes("-")) {
-            const slotDefs = collectSlotDefs(content);
-            components.push({
-              $id: content.$id || null,
-              hasElements: Array.isArray(content.$elements) && content.$elements.length > 0,
-              path: fwd(match),
-              props: Object.entries(content.state || {})
-                .filter(([, d]) => {
-                  if (d == null) {
-                    return false;
-                  }
-                  // Shorthand: "key": "value" or "key": 0 etc.
-                  if (typeof d !== "object") {
-                    return true;
-                  }
-                  // Full form: skip computed/handler/prototype entries
-                  const obj = d as Record<string, unknown>;
-                  return !obj.$prototype && !obj.$handler && !obj.$compute;
-                })
-                .map(([name, d]) => {
-                  if (typeof d !== "object" || d === null) {
-                    // Shorthand: infer type from value
-                    return { default: d, name, type: typeof d };
-                  }
-                  const obj = d as Record<string, unknown>;
-                  return {
-                    default: obj.default,
-                    format: obj.format,
-                    name,
-                    type: obj.type,
-                  };
-                }),
-              ...(slotDefs.length > 0 ? { slots: slotDefs } : {}),
-              source: "jx",
-              tagName: content.tagName,
-            });
+          /* The metadata rules live in @jxsuite/schema/component-meta because THREE backends need
+             the same answer — this one, the desktop session, and now the cloud adapter, which can
+             discover JSON components precisely because deriving them executes nothing. Two copies
+             had already drifted apart in wording; a third would have made "which state entries are
+             props" a question with three answers. */
+          const meta = componentMetaFrom(content, fwd(match));
+          if (meta) {
+            components.push({ ...meta, source: "jx" });
           }
         } catch {} // Skip non-JSON or parse errors
       }