@jxsuite/studio 2.4.3 → 4.0.0

package/src/panels/signals-panel.ts

@@ -58,6 +58,7 @@ import { getExtensions, loadExtensions } from "../format/format-host";
 import { optionalStringArg, stringProperty } from "../commands/command-args";
 import type { TemplateResult } from "lit-html";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
+import { isMediaFormat } from "../utils/studio-utils";
 
 interface SignalsPanelState {
   document: JxMutableNode;
@@ -915,7 +916,7 @@ function renderSignalEditorTemplate(
           : nothing
       }
       ${
-        def.format === "image"
+        isMediaFormat(def.format)
           ? renderFieldRow({
               hasValue: false,
               label: "Default",

package/src/panels/toolbar.ts

@@ -41,12 +41,13 @@ import { openQuickSearch } from "./quick-search";
 import { showPromptDialog } from "../ui/layers";
 import { getPlatform, hasPlatform } from "../platform";
 import { getPreviewNavigateHandler } from "../canvas/preview-navigate";
+import { armPreviewOverlay, flushPreviewOverlay } from "../preview/preview-overlay";
 import { documentUrlPattern, dynamicRouteParams } from "../page-params";
 import { getNodeAtPath, nodeLabel, projectState } from "../store";
 import { activeRegistry } from "../commands/active-registry";
 import { notify } from "../services/notify";
 import type { Tab } from "../tabs/tab";
-import type { SiteBuildResult } from "../types";
+import type { SiteBuildResult, SitePreviewResult, StudioPlatform } from "../types";
 import type { CommandRegistry } from "../commands/registry";
 import type { EffectScope } from "@vue/reactivity";
 import type { TemplateResult } from "lit-html";
@@ -253,27 +254,96 @@ export async function runOpenInBrowser() {
     notify.warn(target.reason, { key: OPEN_IN_BROWSER, source: "Preview" });
     return;
   }
-  /* Build first, because the reader is about to see the OUTPUT and the author is looking at the
-     DOCUMENT. Without this they differ by however long it has been since anyone ran a build —
-     which for most projects is "always", since nothing in Studio had ever written the output at
-     all. A preview that quietly shows last week's page is worse than one that says it cannot open.
-
-     The build is also what NAMES the origin. The built site is served on a port of its own, because
-     the editor's own paths mean the project's sources while a built page means its output by the
-     same paths — so a backend that cannot build cannot preview either, and says so instead of
-     sending the reader to an address where half the site is the wrong file. */
   const platform = hasPlatform() ? getPlatform() : null;
-  if (!platform?.buildSite) {
-    notify.warn("This backend cannot build a preview of the site.", {
+  if (!platform?.previewSite && !platform?.buildSite) {
+    notify.warn("This backend cannot preview the site.", {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+    return;
+  }
+
+  /* A LIVE preview is what this action is for, and a build is the fallback for a backend that
+     cannot do one. The two answer different questions: "what does this page look like at its real
+     URL?" wants the tree as it stands, and "does my site build?" is `Build Site`. */
+  if (platform.previewSite) {
+    await runLivePreview(platform.previewSite, target.path);
+    return;
+  }
+  await runBuiltPreview(platform.buildSite!, target.path);
+}
+
+/**
+ * Preview the working tree, and open a tab only if one is not already showing this project.
+ *
+ * The overlay is flushed FIRST, and that ordering is the whole point: the page the author is about
+ * to look at should carry the keystroke they just typed, not the one before the debounce.
+ */
+async function runLivePreview(
+  previewSite: NonNullable<StudioPlatform["previewSite"]>,
+  path: string,
+) {
+  armPreviewOverlay();
+  await flushPreviewOverlay();
+  notify.info("Opening a live preview…", { key: OPEN_IN_BROWSER, source: "Preview" });
+  let result: SitePreviewResult;
+  try {
+    result = await previewSite({ route: path });
+  } catch (error) {
+    notify.error(`The site could not be previewed: ${errorText(error)}`, {
       key: OPEN_IN_BROWSER,
       source: "Preview",
     });
     return;
   }
+  if (!result.url) {
+    notify.warn("This backend serves no preview of the site.", {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+    return;
+  }
+
+  /* `reused` is honoured, and honouring it is the feature. A tab already holding this project's
+     preview has been pointed at the route; opening another would leave the author with two tabs on
+     one project, which is exactly what retargeting the first one exists to prevent. What it costs
+     is that the browser does not come forward — no page can raise a background tab, and handing the
+     URL to the OS again would open a duplicate rather than switch to it — so the notification says
+     where to look. A reader who CLOSED their tab is not stuck here: the stream closes with it, so
+     `reused` comes back false and a fresh tab opens without anyone having to ask. */
+  if (result.reused) {
+    notify.info(`Updated your preview tab — switch to your browser to see ${path}`, {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+    return;
+  }
+
+  if (result.errors.length > 0) {
+    notify.warn(`Previewed with ${result.errors.length} problem(s): ${result.errors[0]}`, {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+  } else {
+    notify.success(
+      `Opened a live preview of ${result.routes} page(s) — rendered from your working tree, not a build.`,
+      { key: OPEN_IN_BROWSER, source: "Preview" },
+    );
+  }
+  openUrlExternally(`${result.url}${path}`);
+}
+
+/**
+ * The compiler-backed path, for a backend that declares no live preview.
+ *
+ * Kept so nothing regresses on a backend that predates `previewSite`: the cloud adapter answers
+ * `buildSite` with `mode: "live"` of its own, and `jx dev` answers it with a real build.
+ */
+async function runBuiltPreview(buildSite: NonNullable<StudioPlatform["buildSite"]>, path: string) {
   notify.info("Building the site…", { key: OPEN_IN_BROWSER, source: "Preview" });
   let result: SiteBuildResult;
   try {
-    result = await platform.buildSite();
+    result = await buildSite();
   } catch (error) {
     notify.error(`The site could not be built: ${errorText(error)}`, {
       key: OPEN_IN_BROWSER,
@@ -288,20 +358,70 @@ export async function runOpenInBrowser() {
     });
     return;
   }
+  /* A live preview is not a build and the report must not say it was: what it renders is the
+     working tree, unsaved edits and all, assembled in the reader's browser rather than compiled. */
+  const live = result.mode === "live";
   if (result.errors.length > 0) {
     /* Named, and the page still opens. A partial build produced pages, and the author can see the
        one they asked for while reading what failed — which is the whole difference between a
        preview and a build log. */
-    notify.warn(`The site built with ${result.errors.length} error(s): ${result.errors[0]}`, {
+    const verb = live ? "previewed" : "built";
+    notify.warn(`The site ${verb} with ${result.errors.length} error(s): ${result.errors[0]}`, {
       key: OPEN_IN_BROWSER,
       source: "Preview",
     });
+  } else if (live) {
+    notify.success(
+      `Opened a live preview of ${result.routes} page(s) — rendered from your working tree, not a build.`,
+      { key: OPEN_IN_BROWSER, source: "Preview" },
+    );
   } else {
     notify.success(`Built ${result.routes} page(s).`, { key: OPEN_IN_BROWSER, source: "Preview" });
   }
-  openUrlExternally(`${result.url}${target.path}`);
+  openUrlExternally(`${result.url}${path}`);
+}
+
+/**
+ * Run `Build Site`, the compiler-backed answer to "does my site build?".
+ *
+ * `View: Open in Browser` stopped meaning this when it started previewing the working tree, and the
+ * question did not stop being worth asking: a build runs the bundler, the image pipeline and every
+ * emitter, and a live preview runs none of them. So it keeps its own verb, its own report, and the
+ * output origin it always opened.
+ */
+export async function runBuildSite() {
+  const platform = hasPlatform() ? getPlatform() : null;
+  if (!platform?.buildSite) {
+    notify.warn("This backend cannot build the site.", { key: BUILD_SITE, source: "Build" });
+    return;
+  }
+  notify.info("Building the site…", { key: BUILD_SITE, source: "Build" });
+  let result: SiteBuildResult;
+  try {
+    result = await platform.buildSite();
+  } catch (error) {
+    notify.error(`The site could not be built: ${errorText(error)}`, {
+      key: BUILD_SITE,
+      source: "Build",
+    });
+    return;
+  }
+  if (result.errors.length > 0) {
+    notify.warn(`Built with ${result.errors.length} error(s): ${result.errors[0]}`, {
+      key: BUILD_SITE,
+      source: "Build",
+    });
+    return;
+  }
+  notify.success(`Built ${result.routes} page(s), ${result.files} file(s).`, {
+    key: BUILD_SITE,
+    source: "Build",
+  });
 }
 
+/** One notification key for the build, kept apart so a build report never replaces a preview's. */
+const BUILD_SITE = "project.buildSite";
+
 /** One notification key for the whole flow, so building → built → failed replaces rather than piles. */
 const OPEN_IN_BROWSER = "view.openInBrowser";
 

package/src/platforms/cloud.ts

@@ -28,6 +28,7 @@ import type {
   GitStatusResult,
   PackageInfo,
   ProjectListEntry,
+  SiteBuildResult,
   ProjectSchemasResponse,
   ReferencesResult,
   RenameResult,
@@ -36,6 +37,7 @@ import type {
   StudioPlatform,
 } from "../types";
 import { problemDetail, problemSlug } from "@jxsuite/protocol";
+import type { UploadResult } from "@jxsuite/protocol";
 
 export interface CloudProject {
   owner: string;
@@ -232,8 +234,15 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
        The session serves the project tree at /raw.
 
        Conditional because `base` is "" until a project is bound, and "/raw/" would be a confident
-       wrong answer — worse than the default, which at least fails visibly. */
-    ...(base ? { documentBaseUrl: `${base}/raw/` } : {}),
+       wrong answer — worse than the default, which at least fails visibly.
+
+       `assetSpace` rides in the SAME spread, and that is the whole of its correctness: studio.jx-
+       suite.com is a multi-tenant SPA origin, so `/hero.jpg` misses Workers Static Assets and the
+       single-page-app fallback answers index.html at HTTP 200 — the <img> gets HTML, renders
+       broken, and logs nothing. Declaring "repo" tells Studio to resolve each reference to the
+       project file it names and address it under /raw. Until a project is bound there is no /raw to
+       address, so the project-less hub declares neither and stays exactly as it was. */
+    ...(base ? { assetSpace: "repo" as const, documentBaseUrl: `${base}/raw/` } : {}),
     /* Open Project routes through Studio's repo picker (write-access repos via listRepos +
        importProject) — sessions are URL-bound, so openProject() below never opens a dialog. */
     openProjectPicker: "repo-list",
@@ -314,7 +323,10 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
         method: "POST",
         body: data,
       });
-      return okJson<unknown>(res, `Upload failed: ${path}`);
+      const body = await okJson<Partial<UploadResult>>(res, `Upload failed: ${path}`);
+      // The session echoes the path today; falling back to the request keeps a backend that says
+      // Nothing working rather than writing `undefined` into a document.
+      return { path: body.path ?? path, ...(body.size === undefined ? {} : { size: body.size }) };
     },
 
     async deleteFile(path: string) {
@@ -754,6 +766,25 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       // The GitHub repo IS the remote; nothing to add.
     },
 
+    /**
+     * Open in Browser, cloud edition — a LIVE preview rather than a build.
+     *
+     * The backend cannot run `jx build`: it never executes project JS, and the compiler needs
+     * `sharp`, a bundler and a filesystem, none of which exist in a Worker. What it can do is serve
+     * the working tree as a real site on an origin of its own, rendering each page with the same
+     * runtime the canvas uses — so the reply names `mode: "live"` and Studio says so, instead of
+     * letting a reader assume they are looking at build output.
+     *
+     * That it is not a build is also the best thing about it: the preview is the tree as it stands,
+     * including edits nobody has saved and edits another collaborator is making right now.
+     */
+    async buildSite() {
+      return okJson<SiteBuildResult>(
+        await api("/build", { method: "POST" }),
+        "The site could not be previewed.",
+      );
+    },
+
     // ─── Project catalogue & navigation (Studio welcome / New Project UI) ──
 
     async listProjects(): Promise<ProjectListEntry[]> {

package/src/platforms/devserver.ts

@@ -28,6 +28,7 @@ import type {
   ExtensionsInfo,
   FsEvent,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
   ProjectSchemasResponse,
   ReferencesResult,
@@ -35,9 +36,11 @@ import type {
   SecretsSetRequest,
   SecretsSetResponse,
   SiteBuildResult,
+  SitePreviewResult,
   StarterInfo,
 } from "../types";
 import { problemDetail, problemMessage } from "@jxsuite/protocol";
+import type { UploadResult } from "@jxsuite/protocol";
 
 /** A directory entry from the server, tolerating extra wire fields. */
 type WireDirEntry = DirEntry & Record<string, unknown>;
@@ -61,11 +64,26 @@ interface SiteEntry {
  *
  * The adapter is stateless apart from `_projectRoot`, which tracks the server-relative project
  * directory (e.g. "examples/site-demo"). All paths passed INTO PAL methods are project-relative;
- * the adapter prefixes them with `_projectRoot` before hitting the server, and strips the prefix
- * from responses.
+ * the adapter prefixes them with `_projectRoot` before hitting the server.
+ *
+ * **Coming back, the space depends on the route, and the routes do not all agree** (the contract is
+ * `specs/server.md` §4.1). `/__studio/files` echoes what it was asked — server-root-relative — so
+ * its replies are stripped. The refactor routes (`file/rename`, `references`) answer in the ACTIVE
+ * PROJECT's space, because that is the space their sweep runs in, so their replies are returned
+ * untouched. Stripping one of those is not a harmless no-op: it would eat the first segment of any
+ * path that begins with the project root's own name.
  */
 export function createDevServerPlatform() {
   let _projectRoot = "";
+  /**
+   * The in-flight `activate()` for the current root, so a query whose answer depends on the
+   * server's project binding can await it.
+   *
+   * `set projectRoot` fires activation fire-and-forget, and `/__studio/references` is the one route
+   * with no `dir` parameter — its sweep root comes solely from the server's activated project. A
+   * query landing inside that window would sweep the server's own root instead (issue 239).
+   */
+  let _activation: Promise<unknown> | null = null;
   /**
    * Lazy /__studio/collab capability probe (null = not asked yet). Its result is the subprotocol
    * negotiation, not a boolean: the probe is the only place the client can learn what envelope the
@@ -125,7 +143,7 @@ export function createDevServerPlatform() {
         // Fire-and-forget: callers that need the binding in place before reading await activate()
         // Themselves. The rejection is reported rather than dropped — an unactivated root leaves
         // Every rootless endpoint (git especially) operating on the server's OWN root.
-        void this.activate(_projectRoot).catch((error: unknown) => {
+        _activation = this.activate(_projectRoot).catch((error: unknown) => {
           console.error("Project activation failed:", error);
         });
       }
@@ -334,8 +352,9 @@ export function createDevServerPlatform() {
       opts: ImportSiteOptions,
       onProgress: (evt: ImportProgressEvent) => void,
       signal?: AbortSignal,
+      onReady?: (evt: ImportReadyEvent) => void,
     ) {
-      return await streamImport("/__studio/import-site", opts, onProgress, signal);
+      return await streamImport("/__studio/import-site", opts, onProgress, signal, onReady);
     },
 
     // ─── File operations ──────────────────────────────────────────────────
@@ -391,7 +410,10 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Upload failed: ${path}`);
       }
-      return await res.json();
+      const body = (await res.json()) as Partial<UploadResult>;
+      // The dev server echoes the path today; falling back to the request keeps a backend that says
+      // Nothing working rather than writing `undefined` into a document.
+      return { path: body.path ?? path, ...(body.size === undefined ? {} : { size: body.size }) };
     },
 
     /** @param {string} path */
@@ -417,21 +439,11 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Failed to rename: ${from} → ${to}`);
       }
-      const report = await readJson<RenameResult>(res);
-      // Map server-root-relative report paths back to project-relative for the studio.
-      if (typeof report.from === "string") {
-        report.from = stripRoot(report.from);
-      }
-      if (typeof report.to === "string") {
-        report.to = stripRoot(report.to);
-      }
-      for (const f of report.references?.files ?? []) {
-        f.path = stripRoot(f.path);
-      }
-      for (const e of report.errors ?? []) {
-        e.path = stripRoot(e.path);
-      }
-      return report;
+      /* No strip on the way back: the route takes its paths in server space and answers in the
+         project's (specs/server.md §4.1). Stripping an already-project-relative path is not merely
+         redundant — it corrupts any path whose first segment happens to match the project root's
+         own name, which a server-root-relative root makes reachable. */
+      return readJson<RenameResult>(res);
     },
 
     /**
@@ -442,6 +454,7 @@ export function createDevServerPlatform() {
      * @param {{ path?: string; tagName?: string }} target
      */
     async findReferences(target: { path?: string; tagName?: string }): Promise<ReferencesResult> {
+      await _activation;
       const params = new URLSearchParams();
       if (target.path) {
         params.set("path", serverPath(target.path));
@@ -453,18 +466,8 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Failed to find references: ${target.path ?? target.tagName ?? ""}`);
       }
-      const result = await readJson<ReferencesResult>(res);
-      // Server-root-relative report paths → project-relative, as renameFile already does.
-      if (typeof result.path === "string") {
-        result.path = stripRoot(result.path);
-      }
-      for (const f of result.files ?? []) {
-        f.path = stripRoot(f.path);
-      }
-      for (const e of result.errors ?? []) {
-        e.path = stripRoot(e.path);
-      }
-      return result;
+      // Project-relative on the way out, exactly as `renameFile` above receives it.
+      return readJson<ReferencesResult>(res);
     },
 
     /**
@@ -623,8 +626,8 @@ export function createDevServerPlatform() {
       return Boolean(data.needsInstall);
     },
 
-    async outdatedPackages() {
-      const res = await fetch("/__studio/packages/outdated");
+    async packageVersions() {
+      const res = await fetch("/__studio/packages/versions");
       if (!res.ok) {
         return [];
       }
@@ -1145,6 +1148,41 @@ export function createDevServerPlatform() {
       return (await res.json()) as SiteBuildResult;
     },
 
+    /**
+     * Preview the working tree live, and point this project's open tab at a route.
+     *
+     * The dev server holds the same live origin the desktop launchers do, so the browser Studio
+     * gets the same preview: composed on demand, unsaved edits included.
+     */
+    async previewSite(opts: { route: string }) {
+      const res = await fetch("/__studio/preview", {
+        body: JSON.stringify(opts),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      if (!res.ok) {
+        const body = await readJson<ErrorBody>(res);
+        throw new Error(problemDetail(body) ?? "The site could not be previewed.");
+      }
+      return (await res.json()) as SitePreviewResult;
+    },
+
+    async setPreviewOverlay(path: string, contents: string) {
+      await fetch("/__studio/preview/overlay", {
+        body: JSON.stringify({ contents, path }),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+    },
+
+    async clearPreviewOverlay(path?: string) {
+      await fetch("/__studio/preview/overlay", {
+        body: JSON.stringify(path === undefined ? {} : { path }),
+        headers: { "Content-Type": "application/json" },
+        method: "DELETE",
+      });
+    },
+
     /**
      * @param {string} name
      * @param {string} url