@jxsuite/studio 3.0.0 → 4.1.0

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

@@ -6,9 +6,9 @@
  * `/api/v1/ai/chat`. The session is pre-bound to one (repo, branch) — the shell picks the project
  * before Studio boots — while project-less mode (null) powers the /studio welcome screen.
  *
- * Cloud omissions (Studio degrades per @jxsuite/protocol's route table): pickDirectory/importSite,
- * package install/outdated/set-versions (package ops are manifest-only edits), multi-window,
- * gitClone, resolveClass, component discovery, code services.
+ * Cloud omissions (Studio degrades per @jxsuite/protocol's route table): pickDirectory, package
+ * install/outdated/set-versions (package ops are manifest-only edits), multi-window, gitClone,
+ * resolveClass, component discovery, code services.
  */
 
 import { negotiateCollab } from "@jxsuite/collab/negotiate";
@@ -16,8 +16,12 @@ import type { CollabNegotiation } from "@jxsuite/collab/negotiate";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
+import { streamImport } from "../services/import-client";
 import type {
   AccountStatus,
+  CfAccountSummary,
+  CfConnection,
+  CfConnectOutcome,
   ComponentMeta,
   CreateProjectDestination,
   DirEntry,
@@ -26,8 +30,12 @@ import type {
   GitBranchesResult,
   GitLogEntry,
   GitStatusResult,
+  ImportProgressEvent,
+  ImportReadyEvent,
+  ImportSiteOptions,
   PackageInfo,
   ProjectListEntry,
+  SiteBuildResult,
   ProjectSchemasResponse,
   ReferencesResult,
   RenameResult,
@@ -123,12 +131,16 @@ export function projectRootKey(project: CloudProject): string {
   return `${project.owner}/${project.repo}@${project.branch}`;
 }
 
-/** Current hosted Cloudflare connection; null when none is brokered yet. */
-async function fetchCfConnection(): Promise<{
-  connected: boolean;
-  accountId?: string | undefined;
-  accountName?: string | undefined;
-} | null> {
+/**
+ * Current hosted Cloudflare connection; null when none is brokered yet.
+ *
+ * A LAPSED row is not a healthy one. This reader used to answer `{connected: true}` for any body
+ * whose `connected` flag was set and drop `needsReconnect` on the floor, so a row whose grant had
+ * expired came back indistinguishable from one that works — which is how `cfConnect`'s poll came to
+ * close the popup the moment it opened, over a row from a previous session, while the user was
+ * still on Cloudflare's login page. Every diagnostic the broker sends now passes straight through.
+ */
+async function fetchCfConnection(): Promise<CfConnection | null> {
   const res = await fetch("/api/v1/cf/connection", { credentials: "include" });
   if (!res.ok) {
     return null;
@@ -137,7 +149,15 @@ async function fetchCfConnection(): Promise<{
     connected: boolean;
     accountId?: string | null;
     accountName?: string | null;
+    needsReconnect?: boolean;
+    needsAccount?: boolean;
+    code?: CfConnection["code"];
+    reason?: string;
+    hasRefreshToken?: boolean;
+    expiresAt?: number;
   };
+  /* Cloud never emits {connected: false} to the PAL — no brokered row at all is `null`, and a row
+     that cannot be used arrives as connected + needsReconnect. See CfConnection. */
   if (!body.connected) {
     return null;
   }
@@ -145,10 +165,131 @@ async function fetchCfConnection(): Promise<{
     connected: true,
     ...(body.accountId ? { accountId: body.accountId } : {}),
     ...(body.accountName ? { accountName: body.accountName } : {}),
+    ...(body.needsReconnect ? { needsReconnect: true } : {}),
+    ...(body.needsAccount ? { needsAccount: true } : {}),
+    ...(body.code ? { code: body.code } : {}),
+    ...(body.reason ? { reason: body.reason } : {}),
+    ...(body.hasRefreshToken === undefined ? {} : { hasRefreshToken: body.hasRefreshToken }),
+    ...(body.expiresAt === undefined ? {} : { expiresAt: body.expiresAt }),
   };
 }
 
-type CfConnectionInfo = Awaited<ReturnType<typeof fetchCfConnection>>;
+interface CfConnectFlow {
+  popup: Window | null;
+  promise: Promise<CfConnectOutcome | null>;
+}
+
+/**
+ * The connect flow currently running, or null.
+ *
+ * Module-level rather than per-platform because the popup's TARGET NAME ("cf-connect") is global to
+ * the browsing context: a second `window.open` on that name re-uses the first flow's popup, and the
+ * first flow's cleanup then closes it out from under the second — the user watches their half-typed
+ * Cloudflare login vanish. Joining the in-flight promise is the only answer that leaves both
+ * callers correct.
+ */
+let cfConnectFlow: CfConnectFlow | null = null;
+
+/**
+ * Drive one hosted OAuth connect to a {@link CfConnectOutcome}. See `cfConnect` for the semantics;
+ * this lives at module scope so the single-flight handle can too.
+ */
+async function runCfConnect(handle: CfConnectFlow): Promise<CfConnectOutcome | null> {
+  /* The baseline is read BEFORE the popup opens, and it is what keeps the poll honest: a row that
+     was already healthy proves nothing about THIS flow, so the poll must not settle on one. Reading
+     it after the popup opened would race the callback and could capture the new row as "old". */
+  const baseline = await fetchCfConnection().catch(() => null);
+  const healthyBaseline = Boolean(baseline?.connected && !baseline.needsReconnect);
+  const popup = window.open("/api/v1/cf/connect", "cf-connect", "width=980,height=780");
+  if (!popup) {
+    /* Popup blocked: the whole page is now navigating to the broker. Not a failure — the caller
+       must render nothing at all rather than an error it will never get to show. */
+    location.assign("/api/v1/cf/connect");
+    return { status: "redirect" };
+  }
+  handle.popup = popup;
+  const deadline = Date.now() + 180_000;
+  return new Promise<CfConnectOutcome>((resolve, reject) => {
+    let timer = 0;
+    const cleanup = () => {
+      window.removeEventListener("message", onMessage);
+      window.clearTimeout(timer);
+      if (!popup.closed) {
+        popup.close();
+      }
+    };
+    const settle = (outcome: CfConnectOutcome) => {
+      cleanup();
+      resolve(outcome);
+    };
+    const fail = (reason: string) => {
+      cleanup();
+      reject(new Error(reason));
+    };
+    /** A usable row: brokered, and its grant has not lapsed. */
+    const usable = (connection: CfConnection | null): connection is CfConnection =>
+      Boolean(connection?.connected && !connection.needsReconnect);
+    const onMessage = (event: MessageEvent) => {
+      if (event.origin !== location.origin) {
+        return;
+      }
+      const data = event.data as { source?: string; status?: string; reason?: string | null };
+      if (!data || data.source !== "jx-cf") {
+        return;
+      }
+      if (data.status === "error") {
+        fail(data.reason ?? "Cloudflare authorization failed");
+        return;
+      }
+      /* Any other status — "connected", "pick-account", or one a shell of another vintage sends —
+         is a CLAIM that the callback ran, and the broker row is what adjudicates it. */
+      void fetchCfConnection().then(
+        (connection) => {
+          settle(usable(connection) ? { connection, status: "connected" } : { status: "timeout" });
+        },
+        /* This promise had no rejection handler, so one network blip left the listener installed,
+           the timer armed and the popup open forever. */
+        () => {
+          fail("Cloudflare connected, but the connection could not be confirmed");
+        },
+      );
+    };
+    window.addEventListener("message", onMessage);
+    const poll = async () => {
+      if (Date.now() > deadline) {
+        settle({ status: "timeout" });
+        return;
+      }
+      let connection: CfConnection | null = null;
+      let answered = true;
+      try {
+        connection = await fetchCfConnection();
+      } catch {
+        answered = false; // A blip is not an answer: re-arm and ask again.
+      }
+      /* The poll is a FALLBACK for shells whose postMessage never arrives, so it may only settle on
+         proof that THIS flow stored a fresh token: a usable row that was NOT already usable at the
+         baseline. For a reconnect, `needsReconnect` flipping false is that proof; for a connection
+         that was healthy all along nothing the poll can see is, so it must never settle — the relay
+         or the popup-closed path answers that case instead. */
+      if (answered && usable(connection) && !healthyBaseline) {
+        settle({ connection, status: "connected" });
+        return;
+      }
+      if (popup.closed) {
+        const final = await fetchCfConnection().catch(() => null);
+        settle(usable(final) ? { connection: final, status: "connected" } : { status: "canceled" });
+        return;
+      }
+      timer = window.setTimeout(() => {
+        void poll();
+      }, 1500);
+    };
+    timer = window.setTimeout(() => {
+      void poll();
+    }, 1500);
+  });
+}
 
 /** Parse an "owner/repo@branch" root key; null when malformed. */
 export function parseRootKey(root: string): CloudProject | null {
@@ -765,6 +906,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[]> {
@@ -876,6 +1036,33 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       };
     },
 
+    /**
+     * AI-guided site import, streamed from the PLATFORM's import route rather than a session one.
+     *
+     * Deliberately not routed through `api()`: importing is how a cloud project comes into
+     * existence, so the one mode it has to work in is the project-less hub, where `api()` rejects
+     * before a request is ever made and `base` is "".
+     *
+     * The path is same-origin and relative, so `streamImport`'s plain `fetch` carries the session
+     * cookie under the default `same-origin` credentials mode — the same authority every
+     * `/api/v1/*` call here sends `credentials: "include"` for, with no cloud-shaped option added
+     * to the shared client. A bring-your-own-key run rides on the headers that client already sets,
+     * so the backend sees `X-Api-Key` / `X-Api-Base-URL` exactly as the OSS server does.
+     *
+     * `onReady` is forwarded and this backend never calls it, which is a difference worth naming:
+     * adopting the project mid-run would navigate this page to the editor and abort the request
+     * still writing the import, so the stream carries no `ready` line and the caller adopts on
+     * `done`. That is the same path a backend older than `ready` has always taken.
+     */
+    async importSite(
+      opts: ImportSiteOptions,
+      onProgress: (evt: ImportProgressEvent) => void,
+      signal?: AbortSignal,
+      onReady?: (evt: ImportReadyEvent) => void,
+    ) {
+      return await streamImport("/api/v1/import/site", opts, onProgress, signal, onReady);
+    },
+
     // ─── Identity & Cloudflare publish surface ──────────────────────────────
 
     async getUser() {
@@ -981,71 +1168,75 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
      * OAuth errors (denial, invalid_scope misregistration) REJECT with the real reason instead of
      * timing out. A 1.5s poll remains as fallback for older shells / blocked message delivery, and
      * popup-blocked browsers fall back to a full-page redirect.
+     *
+     * Promise semantics, which are narrower than they look:
+     *
+     * - **Resolves `null`** only under the SSR guard, where there is no window to open.
+     * - **Resolves an outcome** for all four real endings — `connected`, `redirect` (popup blocked,
+     *   page navigating away), `canceled` (popup closed with nothing stored), `timeout` (180s).
+     * - **Rejects** only on a relayed OAuth error, or on a relayed success this platform could not
+     *   confirm against the broker.
+     *
+     * Concurrent calls JOIN the flow already running rather than starting a second one: both would
+     * open the same "cf-connect" target, and the first one's cleanup would then close the popup the
+     * second is waiting on.
      */
-    async cfConnect() {
+    cfConnect() {
       if (typeof window === "undefined" || typeof location === "undefined") {
-        return null;
+        return Promise.resolve(null);
       }
-      const popup = window.open("/api/v1/cf/connect", "cf-connect", "width=980,height=780");
-      if (!popup) {
-        location.assign("/api/v1/cf/connect");
-        return null;
+      const running = cfConnectFlow;
+      if (running) {
+        try {
+          running.popup?.focus();
+        } catch {
+          // A cross-origin popup may refuse focus; joining the flow is what mattered.
+        }
+        return running.promise;
       }
-      const deadline = Date.now() + 180_000;
-      return new Promise<CfConnectionInfo>((resolve, reject) => {
-        let timer = 0;
-        const cleanup = () => {
-          window.removeEventListener("message", onMessage);
-          window.clearTimeout(timer);
-          if (!popup.closed) {
-            popup.close();
-          }
-        };
-        const settle = (connection: CfConnectionInfo) => {
-          cleanup();
-          resolve(connection);
-        };
-        const fail = (reason: string) => {
-          cleanup();
-          reject(new Error(reason));
-        };
-        const onMessage = (event: MessageEvent) => {
-          if (event.origin !== location.origin) {
-            return;
-          }
-          const data = event.data as { source?: string; status?: string; reason?: string | null };
-          if (!data || data.source !== "jx-cf") {
-            return;
-          }
-          if (data.status === "error") {
-            fail(data.reason ?? "Cloudflare authorization failed");
-            return;
-          }
-          void fetchCfConnection().then(settle);
-        };
-        window.addEventListener("message", onMessage);
-        const poll = async () => {
-          if (Date.now() > deadline) {
-            settle(null);
-            return;
-          }
-          const connection = await fetchCfConnection();
-          if (connection) {
-            settle(connection);
-            return;
-          }
-          if (popup.closed) {
-            settle(await fetchCfConnection());
-            return;
-          }
-          timer = window.setTimeout(() => {
-            void poll();
-          }, 1500);
-        };
-        timer = window.setTimeout(() => {
-          void poll();
-        }, 1500);
+      const handle: CfConnectFlow = { popup: null, promise: Promise.resolve(null) };
+      cfConnectFlow = handle;
+      handle.promise = runCfConnect(handle).finally(() => {
+        if (cfConnectFlow === handle) {
+          cfConnectFlow = null;
+        }
+      });
+      return handle.promise;
+    },
+
+    /**
+     * Every Cloudflare account this connection can reach (the account picker's rows).
+     *
+     * A non-OK body is the broker's own unusable-connection payload — `{error, code}` naming a
+     * lapsed grant or a connection that never existed — so its sentence is the one worth showing.
+     */
+    async cfAccounts() {
+      const res = await fetch("/api/v1/cf/accounts", { credentials: "include" });
+      return okJson<CfAccountSummary[]>(res, "Failed to list Cloudflare accounts");
+    },
+
+    /** Store the chosen account on the brokered connection. */
+    async cfSelectAccount(account: { id: string; name?: string }) {
+      const res = await fetch("/api/v1/cf/select-account", {
+        body: JSON.stringify({ accountId: account.id, accountName: account.name }),
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
       });
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, "Failed to select a Cloudflare account"));
+      }
+    },
+
+    /** Forget the brokered connection (the broker revokes its tokens upstream). */
+    async cfDisconnect() {
+      const res = await fetch("/api/v1/cf/connection", {
+        credentials: "include",
+        method: "DELETE",
+      });
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, "Failed to disconnect Cloudflare"));
+      }
     },
 
     /** Allowlisted Cloudflare API passthrough (platform injects the OAuth token). */