@jxsuite/server 3.0.0 → 4.1.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 {
@@ -113,13 +122,14 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
     }
     const fp = fwd(resolve(opts.root, match));
     try {
-      const { doc, serialize } = await loadDoc(fp, opts.registry);
+      const { doc, rewrite, serialize } = await loadDoc(fp, opts.registry);
       const docNewDir = dirname(fp);
       const docOldDir = isUnder(fp, absTo) ? dirname(absFrom + fp.slice(absTo.length)) : docNewDir;
 
       const { changes } = rewriteDocRefs(doc, {
         docNewDir,
         docOldDir,
+        mounts,
         newAbs: absTo,
         oldAbs: absFrom,
         root,
@@ -129,11 +139,29 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
       if (changes.length === 0 && tagCount === 0) {
         continue;
       }
-      if (!serialize) {
+      /*
+       * Two ways to write a document back, and the narrower one is not a fallback for a broken
+       * format — it is the only honest promise a load-only format can make. A CSV collection has a
+       * parser and deliberately no serializer, so a reference living in one used to be COUNTED and
+       * then reported as a remainder the author had to repair by hand (issue 246). `rewrite`
+       * replaces the authored values in the file's own bytes and changes nothing else, which is all
+       * a rename ever needed.
+       *
+       * `serialize` still wins where it exists: a full round trip can express a change a list of
+       * value edits cannot. A TAG rename is exactly such a change, so a document carrying one and
+       * no serializer is still named in the report rather than half-written.
+       */
+      const written =
+        serialize === null
+          ? tagCount === 0 && rewrite !== null
+            ? await rewrite(changes)
+            : null
+          : await serialize(doc);
+      if (written === null) {
         report.errors.push({ error: `No serializer for "${match}"`, path: fwd(match) });
         continue;
       }
-      await writeFile(fp, await serialize(doc));
+      await writeFile(fp, written);
 
       if (changes.length > 0) {
         report.references.files.push({ changes, count: changes.length, path: fwd(match) });

package/src/refactor/mounts.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ *
+ * That drop is deliberate and is not the near half of a bug. A collection's `source` may point
+ * outside the project (site-architecture.md §9.3), and its media renders — the compiler and the dev
+ * server both publish it at the mount URL — but the editing host's file API is project-scoped by
+ * containment check, so no surface can list, open or ask about the file either. Nothing therefore
+ * reports a confident zero about it, which is the failure the lane math exists to prevent. Reaching
+ * such a file means giving it a mount-relative identity in that file API, not widening this filter;
+ * see §9.3, which records the decision (issue 244).
+ */
+
+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,8 +6,43 @@
  * 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 =
   | { kind: "none" }
@@ -127,6 +162,67 @@ 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 eleven 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);
+}
+
+/**
+ * Restore a trailing slash the path math dropped, when the author wrote one.
+ *
+ * `normalizeSegments` discards empty segments, so `./content/posts/` resolves and re-emits as
+ * `./content/posts`. For a file that is invisible; for a DIRECTORY reference — a content
+ * collection's `source` — it is a gratuitous edit to a line the rename had no business restyling,
+ * and `rewriteRef`'s contract is to preserve the authored style. A bare `/` is left alone: it is
+ * already only a slash.
+ */
+function keepTrailingSlash(out: string, core: string): string {
+  return core.endsWith("/") && core !== "/" && !out.endsWith("/") ? `${out}/` : out;
+}
+
 /** Context describing a single rename, shared by every reference rewrite within one document. */
 export interface RemapCtx {
   /** Absolute POSIX project root. */
@@ -142,6 +238,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 +259,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;
+  out = keepTrailingSlash(out, core) + 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 = keepTrailingSlash(url, core) + suffix;
+    return out === core + suffix ? null : out;
+  }
+  return null;
+}