@jxsuite/server 3.0.0 → 4.1.0

package/src/refactor/refs.ts

@@ -14,11 +14,19 @@
  * `rewriteRef`'s resolve-and-compare gate in paths.ts: a reference is only rewritten (or counted as
  * a usage) when it actually resolves to the file in question.
  *
+ * **A reference is not always a value.** Three of the four visit helpers offer a value under a
+ * container-plus-position; {@link visitKeys} offers a map's KEYS, because `project.json`'s `copy`
+ * map names the files it copies there. Everything downstream is unchanged — a key is renamed by the
+ * same visitor returning the same kind of string — but the fourth shape had to exist before the
+ * walk could see the reference at all (issue 242).
+ *
  * 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,8 +45,11 @@ 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 rootRelativeBare — whether a bare value resolves against the project root (`$layout`).
+ * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`,
+ *   `source`, `copy` for a map KEY naming a copied file, 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`,
+ *   `copy`).
  * @returns A replacement string to write back, or `null` to leave the document untouched.
  */
 export type RefVisitor = (
@@ -50,6 +61,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>,
@@ -68,6 +90,41 @@ function visitScalar(
   }
 }
 
+/**
+ * Offer every KEY of a map to the visitor, renaming in place and preserving insertion order.
+ *
+ * The fourth visit helper, and the only one whose reference is not a value. `project.json`'s `copy`
+ * map names its sources in its keys (`{"assets/brochure.pdf": "brochure.pdf"}`), so a walk that
+ * only ever offered values could not see them at all — renaming a copied file reported zero
+ * references and rewrote nothing (issue 242).
+ *
+ * Order is preserved by rebuilding rather than by deleting one key and re-adding it: a plain
+ * `delete` + set moves the renamed entry to the end, which is a diff on a file nobody edited. When
+ * a rename collides with an existing key the later entry wins, exactly as an authored duplicate
+ * would.
+ */
+function visitKeys(
+  container: Record<string, unknown>,
+  refType: string,
+  visit: RefVisitor,
+  rootRelativeBare: boolean,
+): void {
+  const entries = Object.entries(container);
+  const renamed = entries.map(([key, value]): [string, unknown] => {
+    const out = visit(key, refType, rootRelativeBare);
+    return [out === null ? key : out, value];
+  });
+  if (renamed.every(([key], i) => key === entries[i]![0])) {
+    return;
+  }
+  for (const [key] of entries) {
+    delete container[key];
+  }
+  for (const [key, value] of renamed) {
+    container[key] = value;
+  }
+}
+
 /** Offer a string array member (e.g. an `$elements` entry) to the visitor. */
 function visitIndexed(arr: unknown[], index: number, refType: string, visit: RefVisitor): void {
   const value = arr[index];
@@ -189,8 +246,71 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
         walkStyle(value, visit);
         break;
       }
+      case "copy": {
+        /*
+         * `project.json`'s declarative copy map (site-architecture.md §5). Its KEYS are project
+         * files and its VALUES are destinations inside `outDir` — a directory the project does not
+         * contain and a rename can never move. So the key is visited and the value deliberately is
+         * not: offering the value to the shape fallback, which is what happened before, meant
+         * renaming a file at the project root could rewrite an unrelated copy DESTINATION that
+         * merely shared its name.
+         */
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          visitKeys(value as Record<string, unknown>, "copy", visit, true);
+        }
+        break;
+      }
+      case "source": {
+        /*
+         * A content collection's source (site-architecture.md §6), which may name a single file
+         * (`./content/listings.csv`) or a DIRECTORY (`./content/posts/`).
+         *
+         * Named rather than left to the shape fallback because a directory has no extension, and
+         * the extension test is exactly what keeps that fallback from admitting every route and
+         * bare word. Here the key is known and the value's shape is not diagnostic, so the value is
+         * offered unconditionally and precision stays where it always was — the caller's
+         * resolve-and-compare gate, which only matches a value resolving to the file or directory
+         * in question. A remote `https://…` source is filtered by `classifyRef` before that.
+         */
+        visitScalar(obj, key, "source", visit, false);
+        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

@@ -14,18 +14,56 @@ import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 /** Normalise a path to forward slashes (Windows `path` returns backslashes). */
 export const fwd = (p: string) => p.replaceAll("\\", "/");
 
-/** A parsed document plus the serializer that round-trips it back to disk (null when none). */
+/** One authored value to replace in a document's own source text. */
+export interface ValueEdit {
+  from: string;
+  to: string;
+}
+
+/** A parsed document and the two ways it might be written back. */
 export interface LoadedDoc {
   doc: unknown;
+  /** Round-trips the whole document. Null when the format declares no `serialize`. */
   serialize: ((doc: unknown) => Promise<string>) | null;
+  /**
+   * Replaces authored values in the file's own bytes, changing nothing else. Null when the format
+   * declares no `rewrite`.
+   *
+   * The narrower of the two, and the only one a load-only format can offer: a CSV collection is a
+   * data source entries are read FROM, so there is no document to serialize — but one cell's text
+   * can be changed without inventing a quoting style. `applyRename` prefers `serialize` where it
+   * exists, because a full round trip can express a change (a tag rename) that a list of value
+   * edits cannot.
+   */
+  rewrite: ((edits: readonly ValueEdit[]) => Promise<string>) | null;
 }
 
 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. */
@@ -38,8 +76,8 @@ export function documentGlob(registry: FormatRegistry): Bun.Glob {
 }
 
 /**
- * Read + parse a file, returning the doc and a matching serializer (null when the format can parse
- * but not serialize). Throws when no parser claims the extension.
+ * Read + parse a file, returning the doc and whichever write-back paths the format declares. Throws
+ * when no parser claims the extension.
  */
 export async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
   const raw = await readFile(fp, "utf8");
@@ -47,6 +85,7 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
     const trailingNewline = raw.endsWith("\n");
     return {
       doc: JSON.parse(raw) as unknown,
+      rewrite: null,
       serialize: (doc) =>
         Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
     };
@@ -58,8 +97,15 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
   }
   const doc = await parseEntry.call("parse", raw);
   const serializeEntry = registry.byExtension(ext, "serialize");
+  const rewriteEntry = registry.byExtension(ext, "rewrite");
   return {
     doc,
+    rewrite: rewriteEntry
+      ? async (edits) => {
+          const out = await rewriteEntry.call("rewrite", raw, edits);
+          return typeof out === "string" ? out : String(out);
+        }
+      : null,
     serialize: serializeEntry
       ? async (d) => {
           const out = await serializeEntry.call("serialize", d);

package/src/resolve.ts

@@ -1,5 +1,6 @@
 /** Resolve.js — Generic $src module proxy + timing: "server" function proxy */
 
+import { siteBasePath } from "@jxsuite/schema/asset-paths";
 import { dirname, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
 import { existsSync, readFileSync, statSync } from "node:fs";
@@ -99,6 +100,22 @@ async function loadProjectEntry(projectRoot: string) {
   }
 }
 
+/**
+ * The path a project says it is deployed under, or `""` for a site at an origin root.
+ *
+ * Read off `project.json`'s `url` (`@jxsuite/schema/asset-paths`), through the same mtime-keyed
+ * cache the asset mounts use — a second cache on the same file would be a second thing to
+ * invalidate, and this is asked on every request.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string>} A path with a leading slash and no trailing one, or `""`
+ */
+export async function projectSiteBase(projectRoot: string): Promise<string> {
+  const entry = await loadProjectEntry(projectRoot);
+  const config = entry?.context.config as ProjectConfig | undefined;
+  return siteBasePath(config?.url);
+}
+
 /**
  * Extension asset mounts for a project (specs/extensions.md §8.5) — the directories the dev server
  * serves at their site URLs, so content-relative images resolve exactly as they will once built.

package/src/server.ts

@@ -18,7 +18,12 @@ import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
-import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
+import {
+  handleResolve,
+  handleServerFunction,
+  projectAssetMounts,
+  projectSiteBase,
+} from "./resolve.ts";
 import {
   assertAccessible,
   assertCreatableParent,
@@ -301,6 +306,25 @@ export async function createDevServer(options: {
       }
       // Keep the un-collapsed decoded path: the static branch detects a POSIX-absolute "//abs" prefix.
       let { path } = decoded;
+
+      /*
+       * A subpath deployment's base, stripped once at the edge (site-architecture.md §5).
+       *
+       * A project whose `url` carries a path is SERVED from that path, and a build emits every URL
+       * under it — so a preview that only answered the bare path would exercise URLs the deployed
+       * site never uses, which is the class of bug that is only found in production. Stripping
+       * rather than moving the dev root means both spellings work: `localhost:3000/` is unchanged,
+       * and `localhost:3000/m/my-site/assets/x.js` resolves to the same file.
+       *
+       * `url` is mutated too, because everything downstream routes on it — the extension mounts
+       * match `url.pathname` against their own basePath, which is declared bare.
+       */
+      const siteBase = await projectSiteBase(activeProjectRoot ?? absRoot);
+      if (siteBase !== "" && (path === siteBase || path.startsWith(`${siteBase}/`))) {
+        path = path.slice(siteBase.length) || "/";
+        url.pathname = url.pathname.slice(siteBase.length) || "/";
+      }
+
       if (path.endsWith("/")) {
         path += "index.html";
       } else if (path === "") {
@@ -421,6 +445,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) {

package/src/sse.ts

@@ -0,0 +1,126 @@
+/**
+ * The live-reload stream contract, in one place.
+ *
+ * Two surfaces speak it — the dev server's `/__reload` ({@link ./watch.ts}) and the live preview
+ * origin's own channel ({@link ./live-preview.ts}) — and what they share is not "an SSE endpoint"
+ * but a specific reading of the HTML Standard's EventSource contract that took a defect report to
+ * arrive at (specs/server.md §3.1). Re-deriving it per surface is how one of them ends up with a
+ * reconnect that silently never fires.
+ *
+ * The two halves that are easy to omit and expensive to omit:
+ *
+ * - **`retry:`** sets the reconnection time. The default is user-agent defined and is measured in
+ *   seconds; during a server restart that is long enough to watch a save do nothing. 500 ms is
+ *   loopback, so the reconnect costs nothing and lands inside the restart.
+ * - **`Last-Event-ID`** is how the browser says "I was here before", and it is the ONLY way the
+ *   server can tell a reconnection from a first connection. A reconnecting client gets exactly one
+ *   reload and no replay; a first connection gets none at all, because reloading a page that just
+ *   loaded is a reload loop.
+ *
+ * A hub broadcasts to every client it holds. Membership is the socket's whole lifetime — added on
+ * open, dropped on cancel — so a broadcast after a tab closes reaches nobody rather than throwing.
+ */
+
+/**
+ * Reconnection time advertised on the stream, in milliseconds (HTML Standard, `retry:`).
+ *
+ * Both endpoints are on loopback, so a reconnect costs nothing and half a second lands inside a
+ * typical restart.
+ */
+export const RECONNECT_MS = 500;
+
+/** How often a comment frame is sent to keep an idle connection from being reaped. */
+const HEARTBEAT_MS = 15_000;
+
+/** A broadcast hub for one stream. */
+export interface SseHub {
+  /** Send the default (unnamed) `reload` message, stamped with the next `id:`. */
+  broadcast: () => void;
+  /**
+   * Send a _named_ event.
+   *
+   * A consumer wired as `onmessage` sees only the unnamed message, so a named event reaches a
+   * listener that asked for it without triggering everyone else's reload. That is what lets the
+   * studio shell subscribe to `fs` on the same connection the preview reloads on.
+   */
+  broadcastEvent: (event: string, payload: unknown) => void;
+  /** Open the stream. Pass the request so `Last-Event-ID` can be read. */
+  handleSSE: (request?: Request) => Response;
+  /** How many clients are connected right now. */
+  clientCount: () => number;
+}
+
+/** Create a hub. Nothing is shared between hubs — a project's clients are its own. */
+export function createSseHub(): SseHub {
+  const clients = new Set<(msg: string) => void>();
+  const encoder = new TextEncoder();
+
+  /*
+   * Monotonic reload counter, sent as the SSE `id:` of every reload frame.
+   *
+   * Its only job is to arm the browser: a stream that has never sent an `id:` makes the client omit
+   * `Last-Event-ID` on reconnect, and then the server cannot tell a first connection from a
+   * reconnection. **Nothing is buffered against it and nothing is replayed.** A reconnecting client
+   * gets exactly one reload, because the page it is holding was built before the disconnect and a
+   * full reload subsumes every event it missed — one is as correct as a hundred and finishes
+   * sooner. Do not "complete" this into a replay buffer; there is no per-event state to replay.
+   */
+  let lastEventId = 0;
+
+  function broadcast() {
+    lastEventId += 1;
+    const frame = `id: ${lastEventId}\ndata: reload\n\n`;
+    for (const send of clients) {
+      send(frame);
+    }
+  }
+
+  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(request?: Request) {
+    const resuming = (request?.headers.get("Last-Event-ID") ?? "") !== "";
+    let send: ((msg: string) => void) | undefined;
+    const stream = new ReadableStream({
+      cancel() {
+        if (send) {
+          clients.delete(send);
+        }
+      },
+      start(c) {
+        send = (msg: string) => {
+          try {
+            c.enqueue(encoder.encode(msg));
+          } catch {}
+        };
+        clients.add(send);
+        // The retry interval is a stream-level field, so it is set once, before any event.
+        send(`retry: ${RECONNECT_MS}\n\n`);
+        if (resuming) {
+          lastEventId += 1;
+          send(`id: ${lastEventId}\ndata: reload\n\n`);
+        }
+        const hb = setInterval(() => {
+          try {
+            c.enqueue(encoder.encode(": heartbeat\n\n"));
+          } catch {
+            clearInterval(hb);
+          }
+        }, HEARTBEAT_MS);
+      },
+    });
+    return new Response(stream, {
+      headers: {
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "Content-Type": "text/event-stream",
+      },
+    });
+  }
+
+  return { broadcast, broadcastEvent, clientCount: () => clients.size, handleSSE };
+}