@jxsuite/server 2.2.7 → 4.0.0

package/README.md

@@ -26,19 +26,19 @@ await createDevServer({
 
 ## Endpoints
 
-### Live reload — `GET /__reload`
+### Live reload: `GET /__reload`
 
 SSE endpoint. `chokidar` watches the project root and pushes change events to connected browsers, triggering automatic page reload.
 
-### `$prototype`/`$src` proxy — `POST /__jx_resolve__`
+### `$prototype`/`$src` proxy: `POST /__jx_resolve__`
 
 Resolves external `$prototype` data sources server-side. Supports `.js` modules and `.class.json` schemas. Avoids browser CORS issues and enables Node.js-only dependencies (`fs`, `glob`, etc.).
 
-### Server functions — `POST /__jx_server__`
+### Server functions: `POST /__jx_server__`
 
 Executes `timing: "server"` function entries during development. The runtime sends `{ $src, $export, arguments }` and receives the return value as JSON.
 
-### Studio filesystem API — `/__studio/*`
+### Studio filesystem API: `/__studio/*`
 
 REST API for the Studio visual builder:
 
@@ -53,7 +53,7 @@ REST API for the Studio visual builder:
 
 All file operations are constrained to the project root (path traversal is rejected).
 
-### Code services — `/__studio/code/*`
+### Code services: `/__studio/code/*`
 
 OXC-powered tools for the Studio function body editor:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "2.2.7",
+  "version": "4.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
     "./packages": "./src/packages.ts",
     "./project-server": "./src/project-server.ts",
     "./oauth-loopback": "./src/oauth-loopback.ts",
+    "./live-preview": "./src/live-preview.ts",
     "./site-preview": "./src/site-preview.ts",
     "./refactor": "./src/refactor/index.ts",
     "./resolve": "./src/resolve.ts",
@@ -35,24 +36,25 @@
     "lint:errors": "bun run scripts/check-error-shapes.ts",
     "test": "bun run lint:errors && bun test --isolate",
     "test:coverage": "bun run lint:errors && bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && 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.4",
+    "@jxsuite/compiler": "^3.0.0",
+    "@jxsuite/create": "^1.3.8",
+    "@jxsuite/import": "^0.40.0",
+    "@jxsuite/protocol": "^2.1.0",
+    "@jxsuite/runtime": "^3.0.0",
+    "@jxsuite/schema": "^2.0.0",
+    "@jxsuite/site": "^1.0.0",
+    "@jxsuite/starters": "^1.6.5",
     "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.6",
+    "@jxsuite/connector": "^0.5.6",
+    "@jxsuite/parser": "^1.6.0"
   }
 }

package/src/import-api.ts

@@ -8,10 +8,16 @@
  *
  * Stream protocol (one JSON object per line):
  *   {"type":"progress","phase":"...","message":"...","current":n,"total":n}
+ *   {"type":"ready","root":"..."}              — the destination exists and is openable
  *   {"type":"heartbeat"}                       — keep-alives during silent phases
- *   {"type":"done","root":"...","config":{…}}  — terminal success
+ *   {"type":"done","root":"...","config":{…},"result":{…}}  — terminal success
  *   {"type":"error","error":"..."}             — terminal failure
  *
+ * `ready` arrives seconds in, before the browser launches; `done` arrives minutes later. They are
+ * two lines rather than one because they answer different questions — "where is it" and "what did it
+ * find" — and a caller that waits for the second to learn the first spends the whole crawl with
+ * nothing to show.
+ *
  * LLM key flow (matches ai-api.ts): X-Api-Key / Authorization: Bearer header, falling back to the
  * OPENAI_API_KEY env var; base URL from X-Api-Base-URL / OPENAI_BASE_URL. When AI component naming
  * is requested but no key resolves, the import proceeds without the AI pass and emits a warning
@@ -23,6 +29,8 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { problem } from "./problem.ts";
+import type { BreakpointPolicy, BreakpointRounding } from "@jxsuite/import/breakpoint-plan";
+import type { ImportBreakpointPolicy } from "@jxsuite/protocol";
 
 export interface ImportApiOptions {
   /**
@@ -44,6 +52,10 @@ interface ImportRequestBody {
   maxNodesPerPage?: number;
   aiComponents?: boolean;
   aiModel?: string;
+  verify?: boolean;
+  verifyThreshold?: number;
+  verifyMinFidelity?: number;
+  breakpoints?: ImportBreakpointPolicy;
 }
 
 /** Seconds between keep-alive lines while a phase is silent (browser launch is the longest gap). */
@@ -52,10 +64,60 @@ const HEARTBEAT_INTERVAL_MS = 15_000;
 const MAX_DEPTH = 5;
 const MAX_PAGES = 100;
 
+/** Pixelmatch colour-tolerance bounds for the optional verify pass. */
+const MIN_THRESHOLD = 0.01;
+const MAX_THRESHOLD = 1;
+
+/**
+ * The fidelity bar's bounds, as a percentage.
+ *
+ * `0` is a legal answer and means "report only", which is what this transport did before the bar
+ * existed — so the floor here is 0 rather than the CLI's default of 25.
+ */
+const MIN_FIDELITY_FLOOR = 0;
+const MIN_FIDELITY_CEILING = 100;
+
 function clamp(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, Math.trunc(value)));
 }
 
+/**
+ * The breakpoint policy this request asks for, or `undefined` for "whatever the pipeline defaults
+ * to".
+ *
+ * Shape only. The bounds — how many breakpoints a project may keep, which widths are plausible —
+ * belong to `@jxsuite/import`'s planner, which clamps them and is tested doing so; restating them
+ * here would be a second set of numbers to keep in step with the first. What this does is refuse to
+ * hand the pipeline JSON it would have to interpret: a `widths` that is not an array of numbers, a
+ * `mode` that is not one of the three.
+ */
+function readBreakpointPolicy(
+  policy: ImportBreakpointPolicy | undefined,
+): BreakpointPolicy | undefined {
+  if (!policy) {
+    return undefined;
+  }
+  const rounding: BreakpointRounding =
+    policy.rounding === "down" || policy.rounding === "up" ? policy.rounding : "nearest";
+
+  if (policy.mode === "all") {
+    return { mode: "all" };
+  }
+  if (policy.mode === "explicit") {
+    const widths = (Array.isArray(policy.widths) ? policy.widths : [])
+      .map((width) => Math.trunc(Number(width)))
+      .filter((width) => Number.isFinite(width));
+    /* An override with no usable width in it is an empty override, not an instruction to keep
+       nothing. Falling through to the default beats both a 400 and an empty $media. */
+    return widths.length > 0 ? { mode: "explicit", rounding, widths } : undefined;
+  }
+  if (policy.mode === "limit") {
+    const count = Math.trunc(Number(policy.count));
+    return { count: Number.isFinite(count) && count > 0 ? count : 3, mode: "limit", rounding };
+  }
+  return undefined;
+}
+
 function getAiConfig(req: Request): { apiKey: string | null; baseUrl: string | undefined } {
   const authHeader = req.headers.get("Authorization") || "";
   const apiKeyHeader = req.headers.get("X-Api-Key") || "";
@@ -102,8 +164,33 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
   }
 
   const depth = clamp(body.depth ?? 1, 0, MAX_DEPTH);
+  /*
+   * `verify` builds the emitted project and screenshot-diffs every page, so it roughly doubles the
+   * run — opt-in, and never a default. It is worth the option because it produces the one number
+   * the caller can act on: every other finding is a count of things that were skipped, and "the
+   * pricing page renders at 61%" is a question worth putting to a person.
+   */
+  const verify: false | { threshold: number; minFidelity: number } = body.verify
+    ? {
+        /*
+         * Two different numbers, and conflating them is what let a run scoring 8% report success.
+         * `threshold` is pixelmatch's per-pixel COLOUR tolerance and only moves the score;
+         * `minFidelity` is the bar the run's `passed` is measured against.
+         */
+        threshold: Math.min(
+          MAX_THRESHOLD,
+          Math.max(MIN_THRESHOLD, Number(body.verifyThreshold ?? 0.15) || 0.15),
+        ),
+        minFidelity: clamp(
+          Number(body.verifyMinFidelity ?? 0) || 0,
+          MIN_FIDELITY_FLOOR,
+          MIN_FIDELITY_CEILING,
+        ),
+      }
+    : false;
   const maxPages = clamp(body.maxPages ?? 20, 1, MAX_PAGES);
   const maxNodesPerPage = clamp(body.maxNodesPerPage ?? 5000, 100, 50_000);
+  const breakpoints = readBreakpointPolicy(body.breakpoints);
   const { apiKey, baseUrl } = getAiConfig(req);
   const toRoot = opts.toRoot ?? ((p: string) => p);
 
@@ -151,16 +238,44 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
             maxPages,
             maxNodesPerPage,
             ai,
+            verify,
             signal: req.signal,
+            ...(breakpoints === undefined ? {} : { breakpoints }),
             ...(opts.chromePath === undefined ? {} : { chromePath: opts.chromePath }),
           },
-          (e) => writeLine({ type: "progress", ...e }),
+          (e) => {
+            /* The seed event carries the root, and it is the ONE thing a caller cannot wait for the
+               terminal line to learn: it arrives seconds in, and `done` arrives minutes later. It
+               is re-emitted as its own line rather than left inside a progress message, because a
+               root parsed out of prose is a root that breaks when the prose is reworded. */
+            if (e.phase === "seed" && e.root) {
+              writeLine({ type: "ready", root: toRoot(e.root) });
+            }
+            const { root: _root, ...progress } = e;
+            writeLine({ type: "progress", ...progress });
+          },
         );
 
         const config = JSON.parse(
           await readFile(resolve(result.outDir, "project.json"), "utf8"),
         ) as Record<string, unknown>;
-        writeLine({ type: "done", root: toRoot(result.outDir), config });
+        /*
+         * The result travels with the `done` line. It used to be discarded here: the pipeline had
+         * computed the page list, the file count, the warnings and (with verify) a per-page
+         * fidelity score, and the caller learned only that an import had happened. A caller that
+         * cannot see what a run found cannot report it, and cannot ask about it either.
+         */
+        writeLine({
+          type: "done",
+          root: toRoot(result.outDir),
+          config,
+          result: {
+            pages: result.pages,
+            fileCount: result.fileCount,
+            warnings: result.warnings,
+            ...(result.verify ? { verify: result.verify } : {}),
+          },
+        });
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         writeLine({ type: "error", error: message });