@jxsuite/server 2.2.7 → 4.0.0

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/packages.ts

@@ -16,11 +16,19 @@ export interface PackageInfo {
   dev?: boolean;
 }
 
-export interface OutdatedInfo {
+/**
+ * A dependency's pinned range beside the newest version published for it on the registry.
+ *
+ * Every registry-range dependency gets a row, behind or not. Deciding whether a row is an upgrade
+ * needs a semver comparison against the range's base, and the caller — which has to make that
+ * comparison anyway to tell an upgrade from a project deliberately pinned ahead — is where it
+ * belongs. A backend that filtered here could only describe an up-to-date package as an absence.
+ */
+export interface PackageVersionInfo {
   name: string;
   /** The version range pinned in package.json (e.g. "^0.19.0"). */
   current: string;
-  /** The newest published version. */
+  /** The newest version published for this package on the registry. */
   latest: string;
   dev?: boolean;
 }
@@ -165,31 +173,41 @@ export async function fetchLatestVersion(
 }
 
 /**
- * List dependencies whose newest published version differs from the pinned base. Registry lookups
- * run concurrently; non-registry specs (workspace:, file:, …) and lookup failures are skipped.
+ * The newest published version of every dependency, asked of the registry package by package.
+ *
+ * Lookups run concurrently; non-registry specs (workspace:, file:, …) and lookup failures are
+ * skipped, because there is no honest answer for either and a guess is worse than a blank.
+ *
+ * This used to be `outdatedPackages`, which dropped any package whose latest matched its pinned
+ * base. Two assumptions were folded into that filter and both have since gone: that the only caller
+ * wanted a to-do list, and that `latest !== base` is the same question as "is there an upgrade" (it
+ * is not — a project pinned ahead of the registry, on a prerelease or a range bumped before the
+ * publish landed, differs from latest in the other direction). Reporting the registry's answer for
+ * every package leaves both judgements to the caller and lets the Packages table show a Latest
+ * column for rows that are already current.
  */
-export async function outdatedPackages(
+export async function packageVersions(
   root: string,
   fetchImpl: FetchLike = fetch,
-): Promise<OutdatedInfo[]> {
+): Promise<PackageVersionInfo[]> {
   const pkgs = await listPackages(root);
   const checks = await Promise.all(
-    pkgs.map(async (p): Promise<OutdatedInfo | null> => {
+    pkgs.map(async (p): Promise<PackageVersionInfo | null> => {
       if (!isRegistryRange(p.version)) {
         return null;
       }
       const latest = await fetchLatestVersion(p.name, fetchImpl);
-      if (!latest || latest === stripRange(p.version)) {
+      if (!latest) {
         return null;
       }
-      const entry: OutdatedInfo = { current: p.version, latest, name: p.name };
+      const entry: PackageVersionInfo = { current: p.version, latest, name: p.name };
       if (p.dev) {
         entry.dev = true;
       }
       return entry;
     }),
   );
-  return checks.filter((entry): entry is OutdatedInfo => entry !== null);
+  return checks.filter((entry): entry is PackageVersionInfo => entry !== null);
 }
 
 /**

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 {
@@ -120,6 +129,7 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
       const { changes } = rewriteDocRefs(doc, {
         docNewDir,
         docOldDir,
+        mounts,
         newAbs: absTo,
         oldAbs: absFrom,
         root,

package/src/refactor/mounts.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+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,7 +6,42 @@
  * 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 =
@@ -127,6 +162,54 @@ 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 nine 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);
+}
+
 /** Context describing a single rename, shared by every reference rewrite within one document. */
 export interface RemapCtx {
   /** Absolute POSIX project root. */
@@ -142,6 +225,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 +246,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;
   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 = url + suffix;
+    return out === core + suffix ? null : out;
+  }
+  return null;
+}