@jxsuite/studio 3.0.0 → 4.1.0

package/src/platforms/devserver.ts

@@ -28,6 +28,7 @@ import type {
   ExtensionsInfo,
   FsEvent,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
   ProjectSchemasResponse,
   ReferencesResult,
@@ -35,6 +36,7 @@ import type {
   SecretsSetRequest,
   SecretsSetResponse,
   SiteBuildResult,
+  SitePreviewResult,
   StarterInfo,
 } from "../types";
 import { problemDetail, problemMessage } from "@jxsuite/protocol";
@@ -62,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
@@ -126,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);
         });
       }
@@ -335,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 ──────────────────────────────────────────────────
@@ -421,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);
     },
 
     /**
@@ -446,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));
@@ -457,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);
     },
 
     /**
@@ -627,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 [];
       }
@@ -1149,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

package/src/preview/preview-overlay.ts

@@ -0,0 +1,226 @@
+/**
+ * Publishing what the author is looking at, so a live preview shows the canvas and not the disk.
+ *
+ * A live preview composes a page from the project's working TREE, and the tree is what has been
+ * saved. The document the author is actually editing lives in a tab's reactive memory and nowhere
+ * else, so without this the one thing that makes a live preview worth having — seeing an edit
+ * before it is written — would be exactly the thing it could not show.
+ *
+ * What travels is BYTES, and specifically {@link serializeDocument}'s: the same function `saveFile`
+ * writes through, grid controllers, format round-trips, frontmatter and all. That is what makes
+ * "what the reader sees" and "what saving would produce" one answer rather than two that drift. A
+ * document object would bypass the format layer, and a `.md` page's bytes are not
+ * `JSON.stringify(doc)`.
+ *
+ * **Why an effect and not `transactDoc`.** `transact.ts` has exactly one observer slot and the
+ * collab layer owns it. More importantly a transaction hook would MISS three of the most common
+ * ways a document changes: a Monaco source commit, a content-entry field edit, and every grid edit
+ * route around `transactDoc` entirely. "I edited it in Source and the preview did not change" is
+ * the bug this shape avoids.
+ *
+ * **Why one effect over the whole tab set rather than one per tab.** Reading the map tracks
+ * additions, so a tab opened later needs no registration and a tab closed needs no teardown. And
+ * the publish is a DIFF against what was last published, which means save, close, discard and undo
+ * back to clean all resolve through the same line instead of four hooks that can each be
+ * forgotten.
+ *
+ * **Armed, not always on.** Serializing dirty documents on every edit is not free, and before the
+ * author has ever opened a preview there is nothing to publish to. Nothing happens until a preview
+ * origin exists.
+ *
+ * @docs studio/interface
+ */
+
+import { effect, effectScope } from "../reactivity";
+import { getPlatform, hasPlatform } from "../platform";
+import { serializeDocument } from "../files/serialize-document";
+import { workspace } from "../workspace/workspace";
+import type { Tab } from "../tabs/tab";
+
+/**
+ * Trailing debounce on a publish.
+ *
+ * No leading edge: a leading publish would send the first keystroke of a burst and the last, which
+ * is two reloads for one thought. The max wait is what keeps a continuous drag from starving the
+ * trailing timer forever.
+ */
+const PUBLISH_DEBOUNCE_MS = 200;
+const PUBLISH_MAX_WAIT_MS = 500;
+
+/** Bytes one document may publish before it is left showing its saved state instead. */
+const MAX_ENTRY_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Path to the bytes last published for it, so identical bytes cost nothing.
+ *
+ * The TEXT rather than a digest of it. An edit that lands back on the same bytes — a character
+ * typed and deleted — must not cost the reader a reload, and comparing what was sent is exact where
+ * a hash would be a collision away from being wrong for no saving anyone can measure. Memory is
+ * bounded by the same per-entry cap the publish is.
+ */
+const published = new Map<string, string>();
+
+let armed = false;
+let scope: ReturnType<typeof effectScope> | null = null;
+let timer: ReturnType<typeof setTimeout> | null = null;
+let burstStartedAt: number | null = null;
+/** The publish in flight, so a flush awaits it rather than racing it. */
+let inFlight: Promise<void> | null = null;
+
+/** The documents whose unsaved bytes a preview needs, in the order they were opened. */
+function dirtyTabs(): Tab[] {
+  const tabs: Tab[] = [];
+  for (const tab of workspace.tabs.values()) {
+    /* Dirty only. A clean tab's bytes are on disk by definition, and publishing them would create
+       a second source of truth for identical content. */
+    if (tab.doc.dirty && tab.documentPath) {
+      tabs.push(tab);
+    }
+  }
+  return tabs;
+}
+
+/**
+ * Publish what changed and retract what no longer applies.
+ *
+ * A diff rather than a stream of events: whatever reason a document has for no longer being unsaved
+ * — saved, closed, discarded, undone back to its file — it is simply absent from this pass, and the
+ * retraction follows without anywhere else having to remember to ask for it.
+ */
+async function publish(): Promise<void> {
+  /* Not `armed` too: `flushPreviewOverlay` refuses when disarmed and `disarmPreviewOverlay` clears
+     the pending timer, so there is no path into here without it. A host with no platform at all is
+     real though — `getPlatform()` throws rather than answering null. */
+  if (!hasPlatform()) {
+    return;
+  }
+  const platform = getPlatform();
+  if (!platform.setPreviewOverlay || !platform.clearPreviewOverlay) {
+    return;
+  }
+  const live = new Set<string>();
+  for (const tab of dirtyTabs()) {
+    const path = tab.documentPath!.replace(/^\.\//, "");
+    let text: string;
+    try {
+      text = await serializeDocument(tab);
+    } catch {
+      /* A half-typed document that will not serialize is not a reason to stop previewing the layout
+         beside it. Skipped, and the next edit that does serialize publishes it. */
+      continue;
+    }
+    if (text.length > MAX_ENTRY_BYTES) {
+      continue;
+    }
+    live.add(path);
+    if (published.get(path) === text) {
+      continue;
+    }
+    published.set(path, text);
+    await platform.setPreviewOverlay(path, text);
+  }
+  for (const path of published.keys()) {
+    if (!live.has(path)) {
+      published.delete(path);
+      await platform.clearPreviewOverlay(path);
+    }
+  }
+}
+
+/** Run a publish, coalescing with any already scheduled. */
+function schedule(): void {
+  if (!armed) {
+    return;
+  }
+  const now = Date.now();
+  burstStartedAt ??= now;
+  if (timer) {
+    clearTimeout(timer);
+  }
+  const waited = now - burstStartedAt;
+  const delay = Math.max(0, Math.min(PUBLISH_DEBOUNCE_MS, PUBLISH_MAX_WAIT_MS - waited));
+  timer = setTimeout(() => {
+    timer = null;
+    burstStartedAt = null;
+    inFlight = publish().finally(() => {
+      inFlight = null;
+    });
+  }, delay);
+}
+
+/**
+ * Note an edit the reactive effect cannot see.
+ *
+ * `transactDoc` replaces the document's ROOT REFERENCE on every transaction, and a Monaco source
+ * commit assigns a fresh one, so a shallow read catches both. A content-entry field edit writes a
+ * key in place on an already-dirty tab, which changes nothing the effect reads. This is the seam
+ * for exactly that: an explicit call from the few places that mutate without swapping.
+ */
+export function notePreviewOverlayEdit(): void {
+  schedule();
+}
+
+/**
+ * Start publishing, because a preview origin now exists to publish to.
+ *
+ * Idempotent: `View: Open in Browser` calls it on every invocation and only the first does work.
+ */
+export function armPreviewOverlay(): void {
+  if (armed) {
+    return;
+  }
+  armed = true;
+  scope = effectScope();
+  scope.run(() => {
+    effect(() => {
+      for (const tab of workspace.tabs.values()) {
+        /* Two reads, both shallow. `document` is a fresh reference on every transaction — see
+           `transactDoc`, which assigns one specifically so effects re-run — so this costs a
+           property read rather than a walk of the document. */
+        void tab.doc.dirty;
+        void tab.doc.document;
+      }
+      schedule();
+    });
+  });
+}
+
+/**
+ * Stop publishing and forget what was published, without retracting it.
+ *
+ * Called when the window changes project. The published map is keyed by project-relative path, so
+ * carrying it across a switch would let one project's `pages/index.json` be read as the answer for
+ * another's — and the backend lets go of the old root's overlay on its own re-root anyway.
+ */
+export function disarmPreviewOverlay(): void {
+  armed = false;
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  burstStartedAt = null;
+  scope?.stop();
+  scope = null;
+  published.clear();
+}
+
+/**
+ * Publish now and wait for it.
+ *
+ * Two callers, and both are moments where the debounce is exactly wrong: on the way to opening a
+ * browser tab, so the page the author is about to look at already carries their last keystroke; and
+ * after a save, so the retraction rides with the write instead of arriving a debounce later and
+ * costing a second reload.
+ */
+export async function flushPreviewOverlay(): Promise<void> {
+  if (!armed) {
+    return;
+  }
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+    burstStartedAt = null;
+  }
+  await inFlight;
+  await publish();
+}

package/src/publish/publish-panel.ts

@@ -26,6 +26,7 @@ import { activeRegistry } from "../commands/active-registry";
 import { currentDeploy, noteDeployment } from "./deploy-checklist";
 import { getPlatform } from "../platform";
 import { getCfToken, setCfToken } from "../services/cf-settings";
+import { resetModelCache } from "../services/ai-models";
 import { projectState } from "../store";
 import type { CfConnection } from "../types";
 import { openModal } from "../ui/layers";
@@ -76,7 +77,13 @@ async function loadConnection(): Promise<void> {
   render();
   try {
     _connection = (await getPlatform().cfConnection?.()) ?? null;
-    if (_connection?.connected) {
+    /*
+     * A lapsed brokered connection is `connected: true`, and asking Cloudflare anything through one
+     * is a guaranteed 401. Every such call landed in the catch below, which nulled the connection —
+     * so the panel showed the FIRST-TIME "Connect Cloudflare" invitation next to a raw
+     * "Cloudflare API: …" string, and never the one sentence that was true: it expired.
+     */
+    if (_connection?.connected && !_connection.needsReconnect) {
       _accounts = await listAccounts();
       _form.accountId = _connection.accountId ?? _accounts[0]?.id ?? "";
       const deploy = currentDeploy();
@@ -122,15 +129,37 @@ function openAccounts(): void {
   void activeRegistry()?.run("app.preferences", { section: "accounts" });
 }
 
+/**
+ * Run the hosted OAuth flow and act on how it ended.
+ *
+ * The four endings are not interchangeable, and collapsing them is what left a user staring at an
+ * unchanged panel: a deadline that passed and a popup the browser turned into a full-page redirect
+ * both resolved null, and both were reported as "not completed" — one of them while the document
+ * was already navigating away.
+ */
 async function hostedConnect(): Promise<void> {
   _busy = true;
+  _error = "";
   render();
   try {
-    await getPlatform().cfConnect?.();
+    const outcome = (await getPlatform().cfConnect?.()) ?? null;
+    if (outcome?.status === "timeout") {
+      _error =
+        "The Cloudflare window didn't finish. Sign in there, then reconnect — nothing was changed.";
+    } else if (outcome?.status === "connected" && !outcome.connection.accountId) {
+      /* Lazily: this module is the publish modal, and the picker drags the dialog layer with it. */
+      const { openCfAccountPicker } = await import("../ui/cf-account-picker");
+      await openCfAccountPicker();
+    }
+    /* `canceled` and `redirect` say nothing. The user closed the popup, or the page is on its way
+       to Cloudflare — an apology painted over either one is noise. */
   } catch (error) {
     _error = error instanceof Error ? error.message : String(error);
   }
   _busy = false;
+  // The assistant's gate reads the same grant through /models, so a reconnect it does not hear
+  // About leaves it insisting the connection is dead.
+  resetModelCache();
   await loadConnection();
 }
 
@@ -194,6 +223,32 @@ function fieldRow(label: string, input: unknown) {
   `;
 }
 
+/**
+ * The connection exists and has lapsed.
+ *
+ * Its own template rather than a line inside {@link credentialTpl}, because the honest words are the
+ * opposite of that one's: nothing needs to be set up, nothing was lost, and the only action is to
+ * sign in again. The panel used to say "Connect your Cloudflare account to publish this site" to a
+ * user who had already done exactly that.
+ */
+function lapsedTpl() {
+  return html`
+    <p>
+      Your Cloudflare connection has expired, so publishing cannot reach your account. Reconnect to
+      restore it — this site's Pages project and its settings are untouched.
+    </p>
+    <sp-button
+      variant="accent"
+      ?disabled=${_busy}
+      @click=${() => {
+        void hostedConnect();
+      }}
+    >
+      ${_busy ? "Reconnecting…" : "Reconnect Cloudflare"}
+    </sp-button>
+  `;
+}
+
 function credentialTpl() {
   const platform = getPlatform();
   if (platform.cfConnect) {
@@ -393,6 +448,11 @@ function bodyTpl() {
   if (_connection === "loading") {
     return html`<p>Checking Cloudflare connection…</p>`;
   }
+  // Before the credential template, and that order is the fix: a lapsed row is `connected: true`,
+  // So neither branch below could ever have claimed it.
+  if (_connection?.connected && _connection.needsReconnect) {
+    return lapsedTpl();
+  }
   if (!_connection?.connected) {
     return credentialTpl();
   }