@jxsuite/studio 3.0.0 → 4.1.0

package/src/types.ts

@@ -14,7 +14,9 @@ import type {
 import type {
   AppInfo,
   AssetCapabilities,
+  CfAccountSummary,
   CfConnection,
+  CfConnectOutcome,
   CodeServiceResult,
   ComponentMeta,
   DataConnectionsResponse,
@@ -32,10 +34,12 @@ import type {
   GitLogEntry,
   GitStatusResult,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
-  OutdatedInfo,
+  ImportSiteSummary,
   PackageInfo,
   PackageOpResult,
+  PackageVersionInfo,
   ProjectListEntry,
   ProjectSchemasResponse,
   RecentProjectEntry,
@@ -52,7 +56,9 @@ export type {
   AiModelInfo,
   AiModelsResponse,
   AppInfo,
+  CfAccountSummary,
   CfConnection,
+  CfConnectOutcome,
   CodeServiceResult,
   ComponentMeta,
   ComponentSlotMeta,
@@ -79,12 +85,15 @@ export type {
   GitFileStatus,
   GitLogEntry,
   GitStatusResult,
+  ImportBreakpointPolicy,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
+  ImportSiteSummary,
   JsonValue,
-  OutdatedInfo,
   PackageInfo,
   PackageOpResult,
+  PackageVersionInfo,
   ProjectListEntry,
   ProjectSchemasResponse,
   PullRequestInfo,
@@ -149,6 +158,20 @@ export interface SiteBuildResult {
   routes: number;
   files: number;
   errors: string[];
+  /**
+   * How the backend produced what {@link url} serves.
+   *
+   * `"built"` is compiler output — what the published site will literally be. `"live"` is the
+   * working tree rendered as a site: the same pages at the same routes, assembled by the runtime in
+   * the reader's browser rather than prerendered, because the backend cannot run a build at all.
+   *
+   * The distinction is reported rather than hidden because the two differ in ways a reader would
+   * otherwise be misled by — a live preview has no prerendered HTML, no optimized images, no
+   * islands and no server-timing results — and because a live preview has something a build does
+   * not: it shows the tree as it stands, unsaved edits included. Absent means `"built"`, so a
+   * backend that predates this keeps its meaning.
+   */
+  mode?: "built" | "live";
   /**
    * Origin the built site is browsable at, e.g. `http://127.0.0.1:41234`.
    *
@@ -160,6 +183,24 @@ export interface SiteBuildResult {
   url?: string;
 }
 
+/**
+ * What a live site preview reports back.
+ *
+ * Everything {@link SiteBuildResult} carries, plus the one answer only a live preview can give:
+ * whether the reader already had a tab on this project.
+ */
+export interface SitePreviewResult extends SiteBuildResult {
+  /**
+   * A tab already holding this project's preview took the route, so open nothing.
+   *
+   * The caller MUST honour it. One tab per project is the contract, and a caller that opens a
+   * second one anyway gives the author two tabs on the same project — which is precisely what
+   * retargeting the first one exists to prevent. `false` means the backend has no live client, or
+   * had one that did not answer, and the caller should open a tab itself.
+   */
+  reused?: boolean;
+}
+
 export interface StudioPlatform {
   id: string;
   projectRoot: string;
@@ -266,6 +307,15 @@ export interface StudioPlatform {
    */
   uploadFile: (path: string, data: string | File | Blob | ArrayBuffer) => Promise<UploadResult>;
   deleteFile: (path: string) => Promise<void>;
+  /**
+   * Move a file and rewrite the project's references to it.
+   *
+   * `from` and `to` are project-relative, and so is every path in the report — including
+   * `references.files[].path` and the `errors[].path` naming a document the refactor could not
+   * write. An adapter over a backend with a different path space translates the REQUEST or the
+   * REPLY, never both: which one needs translating is a property of that backend's route, and doing
+   * both silently assumes it echoes its own input space (specs/desktop.md §3.1).
+   */
   renameFile: (from: string, to: string) => Promise<RenameResult>;
   /**
    * Where a file or a component tag is used across the project — the read side of the same walker
@@ -279,6 +329,9 @@ export interface StudioPlatform {
    *
    * At least one of `path` / `tagName` must be given. A `path` naming a component document
    * contributes its own root tag, so one call answers "as a file AND as an element" together.
+   *
+   * `path` is project-relative going in, and every path coming back is too. A backend that cannot
+   * place the target inside the active project MUST fail rather than answer zero.
    */
   findReferences?: (target: { path?: string; tagName?: string }) => Promise<ReferencesResult>;
   createDirectory: (path: string) => Promise<void>;
@@ -298,8 +351,12 @@ export interface StudioPlatform {
   installDependencies?: () => Promise<PackageOpResult>;
   /** Whether the project has uninstalled dependencies (node_modules missing). */
   dependenciesNeedInstall?: () => Promise<boolean>;
-  /** List dependencies that have a newer version available. */
-  outdatedPackages?: () => Promise<OutdatedInfo[]>;
+  /**
+   * The newest version published on the registry for each dependency, whether or not it is behind.
+   * Optional: a platform that cannot reach a registry omits it, and Studio shows no Latest column
+   * values rather than inventing them.
+   */
+  packageVersions?: () => Promise<PackageVersionInfo[]>;
   /**
    * Rewrite the version range of each named package (preserving its dependencies/devDependencies
    * placement) and run `bun install`. Used by the @jxsuite bump and per-dependency updates.
@@ -389,6 +446,31 @@ export interface StudioPlatform {
    * build happened to leave — which for most projects is nothing at all.
    */
   buildSite?: () => Promise<SiteBuildResult>;
+  /**
+   * Preview the site LIVE at `route`, with no build on the path.
+   *
+   * The sibling of {@link buildSite} and what `View: Open in Browser` reaches first. Nothing is
+   * compiled: the backend composes the working tree on demand and the runtime assembles each page
+   * in the reader's browser, so what opens carries edits nobody has saved. `buildSite` keeps its
+   * own meaning and its own command, because "what does this page look like at its real URL?" and
+   * "does my site build?" are different questions and only one of them wants to wait.
+   *
+   * Optional, and the fallback is `buildSite`: a backend that predates this keeps working, and a
+   * backend that can do neither says so rather than opening an origin where half the site is the
+   * wrong file.
+   */
+  previewSite?: (opts: { route: string }) => Promise<SitePreviewResult>;
+  /**
+   * Publish the bytes a save WOULD write for one document, so a live preview shows the canvas
+   * rather than the disk.
+   *
+   * Bytes rather than a document, and the same bytes `writeFile` would receive: that is what makes
+   * "what the reader sees" and "what saving would produce" one answer instead of two that drift. A
+   * backend holds them in memory and writes them nowhere.
+   */
+  setPreviewOverlay?: (path: string, contents: string) => Promise<void>;
+  /** Drop one document's unsaved bytes, or every one of this project's when no path is given. */
+  clearPreviewOverlay?: (path?: string) => Promise<void>;
   gitAddRemote: (name: string, url: string) => Promise<void>;
   /**
    * How the New Project modal collects a destination, and which `CreateProjectDestination` variant
@@ -429,12 +511,19 @@ export interface StudioPlatform {
    * AI-guided import of an existing site into a new project. Runs in the backend (headless Chrome +
    * fs), streaming progress until the project is written. Absent on platforms without a backend
    * import pipeline — the New Project modal hides its Import tab then.
+   *
+   * `onReady` fires the moment the destination holds an openable `project.json` — seconds in, where
+   * the resolved promise is minutes away on a real crawl. It is what lets the caller OPEN the
+   * project and let its file tree fill up while the run continues, instead of showing a welcome
+   * screen throughout. Optional on both sides: a backend that never sends the line simply never
+   * calls it, and the caller opens the project when the run ends, as it always did.
    */
   importSite?: (
     opts: ImportSiteOptions,
     onProgress: (evt: ImportProgressEvent) => void,
     signal?: AbortSignal,
-  ) => Promise<{ root: string; config: ProjectConfig }>;
+    onReady?: (evt: ImportReadyEvent) => void,
+  ) => Promise<{ root: string; config: ProjectConfig; result?: ImportSiteSummary }>;
   /**
    * Open a native directory picker and return the chosen absolute path (null when cancelled). Backs
    * the New Project modal's **Browse…** button on `createDestination: "path"` platforms. Desktop
@@ -527,14 +616,34 @@ export interface StudioPlatform {
     head?: string;
     base?: string;
   }) => Promise<{ url: string; number: number }>;
-  /** Current Cloudflare connection state, when the platform can broker one. */
+  /**
+   * Current Cloudflare connection state, when the platform can broker one. See {@link CfConnection}
+   * for what null, `{connected: false}` and `needsReconnect` each mean — they are three different
+   * states and the UI says a different sentence for each.
+   */
   cfConnection?: () => Promise<CfConnection | null>;
   /**
    * Interactively connect a Cloudflare account (hosted OAuth on the cloud platform). Local
    * platforms omit it — the publish UI collects an API token instead and verifies via
    * cfConnection.
+   *
+   * Resolves a {@link CfConnectOutcome} rather than a connection, because "connected" is only one of
+   * four endings: a blocked popup navigates the whole page (`redirect`), a closed popup is a
+   * cancellation, and a passed deadline is a timeout. Rejects only when the flow actually failed —
+   * a relayed OAuth error, or a success the platform could not confirm. Resolves null only where
+   * there is no DOM to open a popup in.
+   */
+  cfConnect?: () => Promise<CfConnectOutcome | null>;
+  /**
+   * Every Cloudflare account the connected grant can reach. Backs the account picker a
+   * multi-account user needs before publishing: the broker stores one account id per connection,
+   * and until one is chosen every Cloudflare-backed call answers `cf_account_required`.
    */
-  cfConnect?: () => Promise<CfConnection | null>;
+  cfAccounts?: () => Promise<CfAccountSummary[]>;
+  /** Store the chosen account on the brokered connection (the picker's commit). */
+  cfSelectAccount?: (account: { id: string; name?: string }) => Promise<void>;
+  /** Forget the brokered connection and revoke its tokens upstream. */
+  cfDisconnect?: () => Promise<void>;
   /**
    * Allowlisted Cloudflare API passthrough (accounts, Pages projects and deployments). The backend
    * injects credentials — an OAuth token on the cloud platform, the user's pasted API token locally
@@ -568,6 +677,19 @@ export interface StudioPlatform {
    * showing a stale value until its next boot rather than losing anything.
    */
   subscribeSettings?: (handler: (settings: Record<string, string>) => void) => () => void;
+  /**
+   * Watch the backend connection, on platforms whose transport can lose one.
+   *
+   * Only a socket-based launcher implements this: the dev server talks over `fetch` and has nothing
+   * to lose, and the electrobun launcher's RPC times a request out rather than dropping it. The
+   * chromium launcher holds one long-lived WebSocket, and when it died every call after it hung
+   * with no error anywhere — so the transport reports the state, and the studio says it out loud.
+   *
+   * The handler is called on each transition, never repeatedly for one state.
+   */
+  subscribeConnection?: (
+    handler: (state: { online: boolean; reason?: string }) => void,
+  ) => () => void;
 }
 
 // ─── Studio Types ───────────────────────────────────────────────────────────

package/src/ui/ai-managed-connect.ts

@@ -25,7 +25,9 @@ import {
   isManagedProxy,
   isProxyConfigured,
   proxyStateCode,
+  resetModelCache,
 } from "../services/ai-models";
+import type { CfConnectOutcome } from "../types";
 
 export interface ManagedConnectOptions {
   /** Host re-render scheduler — called on connect start/finish and when the probe settles. */
@@ -52,20 +54,73 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
   let connectError = "";
 
   /*
-   * Offer the keyless path when the proxy says managed-but-unconfigured and the platform can run
-   * the hosted OAuth flow (the PAL seam — desktop shells can implement cfConnect later). Guarded on
-   * hasPlatform() because gates can render from modules that load before registration.
+   * Offer the keyless path when the proxy is managed and the platform can run the hosted OAuth flow
+   * (the PAL seam — desktop shells can implement cfConnect later). Guarded on hasPlatform() because
+   * gates can render from modules that load before registration.
+   *
+   * `configured` alone does NOT withdraw the offer any more. A backend can answer `configured: true`
+   * over a grant it cannot actually use, and hiding the CTA there left the user with a broken
+   * assistant and no button at all — the one state in which reconnecting is the whole fix. So the
+   * lapsed code overrides `configured`, while `cf_upstream_error` (also `configured: true`, and
+   * carrying no reconnect code) still hides it: an unreachable Cloudflare is not fixed by an OAuth
+   * round trip.
    */
   function canOffer(): boolean {
-    return (
-      isManagedProxy() && !isProxyConfigured() && hasPlatform() && Boolean(getPlatform().cfConnect)
-    );
+    if (!isManagedProxy() || !hasPlatform() || !getPlatform().cfConnect) {
+      return false;
+    }
+    return !isProxyConfigured() || proxyStateCode() === "cf_reconnect_required";
   }
 
   function ensureProbe() {
     ensureProxyProbe(opts.requestRender);
   }
 
+  /**
+   * Act on how the flow ended.
+   *
+   * Every branch here exists because the old code had ONE: any truthy result was success, so a
+   * connect that landed on the same lapsed row re-probed, got the same `cf_reconnect_required`
+   * back, and re-rendered a byte-identical CTA. The user clicked Reconnect and observably nothing
+   * happened — which is the half of the outage that made the other half impossible to diagnose.
+   *
+   * @param {CfConnectOutcome | null} outcome - Null where the platform had no DOM to open a popup
+   *   in.
+   */
+  async function settle(outcome: CfConnectOutcome | null): Promise<void> {
+    /* A blocked popup turns into a full-page redirect, and null is a host with nowhere to open one:
+       in both the document is on its way out, so an apology would be the last thing painted before
+       it goes. Cancellation is silent for the opposite reason — the user already knows. */
+    if (!outcome || outcome.status === "redirect" || outcome.status === "canceled") {
+      return;
+    }
+    if (outcome.status === "timeout") {
+      connectError =
+        "The Cloudflare window didn't finish. Sign in there, then reconnect — nothing was changed.";
+      return;
+    }
+    if (!outcome.connection.accountId) {
+      /* Lazily, because the picker pulls the dialog layer in and this module is imported by every
+         credentials gate — including ones that render before layers are bound. */
+      const { openCfAccountPicker } = await import("./cf-account-picker");
+      if (!(await openCfAccountPicker())) {
+        connectError =
+          "Cloudflare is connected, but no account is chosen yet — pick one to finish setting up the assistant.";
+        return;
+      }
+    }
+    // Re-probe: /models flips to configured once the connection lands, opening the gate.
+    resetModelCache();
+    await fetchAvailableModels({ force: true });
+    /* And then CHECK, because a connect the backend does not honour must not look like one that
+       worked. This is the only place that can tell the difference. */
+    if (!isProxyConfigured() || proxyStateCode() === "cf_reconnect_required") {
+      connectError =
+        "Cloudflare connected, but the assistant backend still reports the connection as unusable. " +
+        "Try reconnecting, or use your own API key below.";
+    }
+  }
+
   async function connect() {
     if (busy) {
       return;
@@ -74,13 +129,7 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
     connectError = "";
     opts.requestRender();
     try {
-      const connection = await getPlatform().cfConnect?.();
-      if (connection) {
-        // Re-probe: /models flips to configured once the connection lands, opening the gate.
-        await fetchAvailableModels({ force: true });
-      } else {
-        connectError = "Cloudflare connection was not completed.";
-      }
+      await settle((await getPlatform().cfConnect?.()) ?? null);
     } catch (error) {
       connectError = error instanceof Error ? error.message : String(error);
     }

package/src/ui/ai-model-picker.ts

@@ -0,0 +1,189 @@
+/// <reference lib="dom" />
+/**
+ * Ai-model-picker.ts — the provider's model catalogue as one `sp-picker`, for every surface that
+ * chooses a model.
+ *
+ * It was private to `panels/ai-chat/composer.ts`, which was correct while the chat composer was the
+ * only place a model could be chosen. The New Project **Import** source now chooses one too — and
+ * that run spends more tokens than any single chat turn — so the choice needed a second host. A
+ * copy would have been two implementations of the invariant below, which is exactly the kind that
+ * only breaks in the copy nobody looked at.
+ *
+ * **The list is never held privately.** It is read from `cachedModels(credentials)` on every
+ * render, so a list can only ever be shown for the credentials it was listed under: change the key
+ * and the catalogue becomes UNAVAILABLE rather than stale. Holding it in a closure is what once let
+ * the picker offer one provider's models while another was configured.
+ *
+ * A closure factory (precedent: `createComposer`, `createAiCredentialsForm`) so two hosts never
+ * share a loading flag or a failed-fetch record.
+ *
+ * @license MIT
+ */
+
+import { html, nothing } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import {
+  aiConnection,
+  cachedModels,
+  fetchAvailableModels,
+  modelToolSupport,
+  preferredModel,
+} from "../services/ai-models";
+import { setModel } from "../services/ai-settings";
+
+import type { TemplateResult } from "lit-html";
+import type { AiCredentials } from "../services/ai-models";
+
+/** The `sp-menu-item` value that means "try listing again" rather than "select this model". */
+export const RETRY_MODELS = "__retry_models__";
+
+/** The `sp-menu-item` value of the disabled placeholder shown during the first fetch. */
+export const LOADING_MODELS = "__loading__";
+
+/** What a listed model's row says when the backend reported it cannot call tools. */
+export const NO_TOOLS_SUFFIX = " — no tools";
+
+/**
+ * A model's row label: its name, plus a note when it is known to be chat-only.
+ *
+ * Labelled, never filtered or disabled. Choosing a chat-only model to ask questions of is a
+ * legitimate thing to do, and a picker that hides half a managed catalogue would be reporting a
+ * capability gap as an outage. Only `toolSupport === false` is labelled — `undefined` is a BYOK
+ * provider saying nothing, and a suffix there would be an invention.
+ */
+function itemLabel(model: { id: string; name: string }): string {
+  return modelToolSupport(model.id) === false ? `${model.name}${NO_TOOLS_SUFFIX}` : model.name;
+}
+
+export interface ModelPickerOptions {
+  /** Host re-render scheduler — called whenever a fetch settles. */
+  requestRender: () => void;
+  /**
+   * The model to show as selected. Defaults to the stored/proxy-preferred one, which is what the
+   * chat composer wants; the Import form passes its own draft, which is not a stored setting until
+   * the run starts.
+   */
+  getModel?: () => string;
+  /**
+   * Where a choice goes. Defaults to `setModel` (the roaming application preference). The Import
+   * form passes its own setter, because choosing a model for one import must not silently retarget
+   * the assistant.
+   */
+  onChange?: (id: string) => void;
+  /** Extra class on the `sp-picker`, so a host can size it without touching this module. */
+  className?: string;
+  /** Picker size; `"s"` (the composer's) by default. */
+  size?: "s" | "m";
+}
+
+export interface ModelPicker {
+  render: () => TemplateResult;
+  /** Whether a fetch is in flight — for a host that wants to disable a submit button. */
+  isLoading: () => boolean;
+  /** The last fetch's failure, or `""`. */
+  error: () => string;
+  /**
+   * Whether the selected model is known NOT to support tools — for a host that wants to say so.
+   *
+   * `false` while the backend has no opinion, so a host reads it as "warn" rather than as "block".
+   */
+  selectedLacksTools: () => boolean;
+}
+
+/**
+ * Create a model picker bound to a host's render scheduler.
+ *
+ * @param {ModelPickerOptions} opts
+ * @returns {ModelPicker}
+ */
+export function createModelPicker(opts: ModelPickerOptions): ModelPicker {
+  const getModel = opts.getModel ?? preferredModel;
+  const onChange = opts.onChange ?? setModel;
+
+  let loading = false;
+  let failure = "";
+
+  /**
+   * The credentials the last fetch was made FOR, so a failure is not retried on every render.
+   *
+   * The list itself is deliberately not held here — see the module docblock.
+   */
+  let attempted: AiCredentials | null = null;
+
+  function sameConnection(a: AiCredentials | null, b: AiCredentials): boolean {
+    return a !== null && a.apiKey === b.apiKey && a.baseUrl === b.baseUrl;
+  }
+
+  function ensureModels(force = false) {
+    const credentials = aiConnection();
+    const settled = cachedModels(credentials) !== null || sameConnection(attempted, credentials);
+    if (loading || (settled && !force)) {
+      return;
+    }
+    loading = true;
+    failure = "";
+    attempted = credentials;
+    fetchAvailableModels({ credentials, force })
+      .catch((error: unknown) => {
+        failure = (error as Error).message || "Failed to fetch models";
+      })
+      .finally(() => {
+        loading = false;
+        opts.requestRender();
+      });
+  }
+
+  function onPickerChange(e: Event) {
+    const { value } = e.target as HTMLInputElement;
+    if (value === RETRY_MODELS) {
+      attempted = null;
+      ensureModels(true);
+      // Re-render so the picker snaps back to the current model instead of showing "Retry".
+      opts.requestRender();
+      return;
+    }
+    if (value && value !== LOADING_MODELS) {
+      onChange(value);
+    }
+  }
+
+  function render(): TemplateResult {
+    ensureModels();
+    const current = getModel();
+    const listed = cachedModels(aiConnection()) ?? [];
+    /* A catalogue that does not contain the current model still has to show it selected — an
+       unlisted id is the normal case for a self-hosted or newly released model. */
+    const items = listed.some((m) => m.id === current)
+      ? listed
+      : [{ id: current, name: current }, ...listed];
+    return html`
+      <sp-picker
+        size=${opts.size ?? "s"}
+        quiet
+        class=${opts.className ?? "ai-model-picker"}
+        title=${failure ? `Couldn't load models: ${failure}` : "Model"}
+        .value=${live(current)}
+        @change=${onPickerChange}
+      >
+        ${items.map((m) => html`<sp-menu-item value=${m.id}>${itemLabel(m)}</sp-menu-item>`)}
+        ${
+          loading
+            ? html`<sp-menu-item disabled value=${LOADING_MODELS}>Loading models…</sp-menu-item>`
+            : nothing
+        }
+        ${
+          failure
+            ? html`<sp-menu-item value=${RETRY_MODELS}>Retry loading models</sp-menu-item>`
+            : nothing
+        }
+      </sp-picker>
+    `;
+  }
+
+  return {
+    error: () => failure,
+    isLoading: () => loading,
+    render,
+    selectedLacksTools: () => modelToolSupport(getModel()) === false,
+  };
+}