@jxsuite/studio 4.0.0 → 5.0.0

package/src/types.ts

@@ -14,7 +14,9 @@ import type {
 import type {
   AppInfo,
   AssetCapabilities,
+  CfAccountSummary,
   CfConnection,
+  CfConnectOutcome,
   CodeServiceResult,
   ComponentMeta,
   DataConnectionsResponse,
@@ -26,6 +28,7 @@ import type {
   DataRowsResult,
   DataRowUpdate,
   DirEntry,
+  ExtensionCatalogEntry,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
@@ -54,7 +57,9 @@ export type {
   AiModelInfo,
   AiModelsResponse,
   AppInfo,
+  CfAccountSummary,
   CfConnection,
+  CfConnectOutcome,
   CodeServiceResult,
   ComponentMeta,
   ComponentSlotMeta,
@@ -73,8 +78,10 @@ export type {
   DataRowUpdate,
   DirEntry,
   ErrorBody,
+  ExtensionCatalogEntry,
   ExtensionContributionInfo,
   ExtensionProjectBlock,
+  ExtensionSectionInfo,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
@@ -382,6 +389,25 @@ export interface StudioPlatform {
    * platforms without it lose descriptor-contributed settings sections.
    */
   listExtensions?: () => Promise<ExtensionsInfo[]>;
+  /**
+   * The extensions this backend can OFFER, enabled or not — the AVAILABLE half of the pair whose
+   * enabled half is {@link StudioPlatform.listExtensions} above.
+   *
+   * A capability rather than a constant because not every host can run every extension: a Worker
+   * ships a fixed set of extension packages (specs/extensions.md §5.5), and one it does not bundle
+   * is dropped from the registry before composition rather than passed to it. A studio that
+   * advertised a shipped list would offer rows the host would refuse.
+   *
+   * Each entry additionally carries two facts only a backend holds: whether THIS host resolves the
+   * package without a project install (`bundled`), and whether the project has it installed
+   * (`installed`) — the latter because `listPackages` does not mean one thing across backends.
+   * `enabled` is deliberately absent: it is `projectConfig.extensions.includes(name)`, which Studio
+   * already owns and rewrites through the `updateSiteConfig` chokepoint.
+   *
+   * Optional: platforms without it offer no catalogue, and adding an extension stays a typed
+   * package name.
+   */
+  listExtensionCatalog?: () => Promise<ExtensionCatalogEntry[]>;
   /**
    * Fetch the project's generated entry schemas (project.schema.json / document.schema.json),
    * PRE-BUNDLED into self-contained documents for editor registration. Optional: without it the
@@ -612,14 +638,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.
-   */
-  cfConnect?: () => Promise<CfConnection | null>;
+   *
+   * 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`.
+   */
+  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

package/src/ui/ai-credentials-form.ts

@@ -11,16 +11,18 @@
  * it and revoke it (plan §9.3). Nothing about this form changed for the move, which is the argument
  * for it having been a reusable form rather than a section of a dialog.
  *
- * Built from Spectrum controls with its layout in `styles/shell.css`: a roaming credential the user
- * configures once does not get its own bespoke inputs, and it certainly does not get 200-character
- * inline `style=` strings that stop responding the moment the theme changes.
+ * This module is the FLOW; `surfaces/ai-credentials-form.json` is what it draws. It keeps the three
+ * drafts, decides which credentials a listing is sent with, what Save persists and re-reads, and
+ * whether Cancel is on offer; the surface renders those and reports what the reader did. `render()`
+ * hands back the surface's own host element rather than a template, because every gate is still a
+ * lit template that interpolates the form beside the keyless offer — see
+ * `surfaces/ai-credentials-form.ts` for why that element is the mount point and why re-rendering
+ * the gate cannot disturb it.
  *
+ * @docs studio/ai
  * @license MIT
  */
 
-import { html, nothing } from "lit-html";
-import { live } from "lit-html/directives/live.js";
-import type { TemplateResult } from "lit-html";
 import { fetchAvailableModels } from "../services/ai-models";
 import {
   getBaseUrl,
@@ -29,6 +31,16 @@ import {
   saveAiProvider,
   storedModel,
 } from "../services/ai-settings";
+import { createAiCredentialsSurface } from "../surfaces/ai-credentials-form";
+import type {
+  AiCredentialsSurface,
+  AiCredentialsView,
+  CredentialsModelRow,
+} from "../surfaces/ai-credentials-form";
+
+/** The blurb a host that says nothing gets. */
+const DEFAULT_INTRO =
+  "Any OpenAI-compatible key works. Stored locally in this browser; sent only to the Studio proxy (never to a third party except your chosen endpoint).";
 
 export interface AiCredentialsFormOptions {
   /** Host re-render scheduler — called whenever the form's internal state changes. */
@@ -37,12 +49,22 @@ export interface AiCredentialsFormOptions {
   onSaved?: () => void;
   /** Called when Cancel dismisses the form (Cancel is only offered when a key already exists). */
   onCancel?: () => void;
-  /** Optional context line (TemplateResult | string) replacing the default blurb. */
-  intro?: unknown;
+  /**
+   * Optional context line replacing the default blurb.
+   *
+   * A string, not a template: the line is drawn by a document, and a document renders text rather
+   * than somebody else's markup. Nothing that passed one ever passed more than a sentence.
+   */
+  intro?: string;
 }
 
 export interface AiCredentialsForm {
-  render: () => TemplateResult;
+  /**
+   * The form's host element.
+   *
+   * A gate interpolates it into its own lit template, which inserts a Node it is handed as-is.
+   */
+  render: () => HTMLElement;
   /** Preload drafts from the stored ai-settings and auto-fetch the model list. */
   startEdit: () => void;
 }
@@ -63,6 +85,9 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
   let modelsLoading = false;
   let modelsError = "";
 
+  /** Made on the first render, and kept for the life of the controller. */
+  let surface: AiCredentialsSurface | null = null;
+
   /**
    * Load the drafts from what is stored.
    *
@@ -104,7 +129,7 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
     loadDrafts();
     modelsError = "";
     /* The fetched list stays: it was listed under exactly these credentials, and dropping it
-       collapsed the model combobox back to a free-text field on every save. The module cache is
+       collapsed the model combobox back to a bare text field on every save. The module cache is
        dropped by ai-models' own settings subscription, so this form does not have to remember to. */
     opts.onSaved?.();
     opts.requestRender();
@@ -148,96 +173,75 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
     }
   }
 
-  /** The key + model + endpoint form column. */
-  function render(): TemplateResult {
-    const haveKey = hasOpenAiKey();
-    return html`
-      <div class="ai-creds-form">
-        <div class="ai-creds-title">AI provider key</div>
-        <div class="ai-creds-note">
-          ${
-            opts.intro === undefined
-              ? html`
-                  Any OpenAI-compatible key works. Stored locally in this browser; sent only to the
-                  Studio proxy (never to a third party except your chosen endpoint).
-                `
-              : opts.intro
-          }
-        </div>
-        <sp-textfield
-          class="ai-creds-field"
-          type="password"
-          size="s"
-          placeholder="sk-… or any compatible key"
-          .value=${live(keyDraft)}
-          @input=${(e: Event) => {
-            keyDraft = (e.target as HTMLInputElement).value;
-          }}
-        ></sp-textfield>
-        <div class="ai-creds-label">Model</div>
-        ${
-          availableModels.length > 0
-            ? html`
-                <sp-combobox
-                  class="ai-creds-field"
-                  size="s"
-                  allows-custom-value
-                  .value=${live(modelDraft)}
-                  @change=${(e: Event) => {
-                    modelDraft = (e.target as HTMLInputElement).value;
-                  }}
-                  @input=${(e: Event) => {
-                    modelDraft = (e.target as HTMLInputElement).value;
-                  }}
-                >
-                  ${availableModels.map(
-                    (m) => html`<sp-menu-item value=${m.id}>${m.name}</sp-menu-item>`,
-                  )}
-                </sp-combobox>
-              `
-            : html`
-                <sp-textfield
-                  class="ai-creds-field"
-                  size="s"
-                  placeholder="Model ID (e.g. gpt-4o, claude-sonnet-4-20250514, etc.)"
-                  .value=${live(modelDraft)}
-                  @input=${(e: Event) => {
-                    modelDraft = (e.target as HTMLInputElement).value;
-                  }}
-                ></sp-textfield>
-              `
-        }
-        <div class="ai-creds-models">
-          <sp-button size="s" variant="secondary" ?disabled=${modelsLoading} @click=${fetchModels}>
-            ${
-              modelsLoading
-                ? "Fetching…"
-                : availableModels.length > 0
-                  ? "Refresh models"
-                  : "Fetch models"
-            }
-          </sp-button>
-          ${modelsError ? html`<span class="ai-creds-error">${modelsError}</span>` : nothing}
-        </div>
-        <sp-textfield
-          class="ai-creds-field"
-          size="s"
-          placeholder="Endpoint (optional, e.g. http://localhost:11434/v1)"
-          .value=${live(baseUrlDraft)}
-          @input=${(e: Event) => {
-            baseUrlDraft = (e.target as HTMLInputElement).value;
-          }}
-        ></sp-textfield>
-        <div class="ai-creds-actions">
-          ${
-            haveKey
-              ? html`<sp-button size="s" variant="secondary" @click=${cancel}>Cancel</sp-button>`
-              : nothing
-          }
-          <sp-button size="s" variant="primary" @click=${save}>Save</sp-button>
-        </div>
-      </div>
-    `;
+  /**
+   * The catalogue as rows — the list the combobox will draw, never a corpus it matches against. A
+   * model with no name of its own is called by its id.
+   */
+  function rows(): CredentialsModelRow[] {
+    return availableModels.map((model) => ({ label: model.name, value: model.id }));
+  }
+
+  /** What the form says right now — the whole of what the surface is told. */
+  function view(): AiCredentialsView {
+    return {
+      baseUrlDraft,
+      fetchLabel: modelsLoading
+        ? "Fetching…"
+        : availableModels.length > 0
+          ? "Refresh models"
+          : "Fetch models",
+      haveKey: hasOpenAiKey(),
+      intro: opts.intro ?? DEFAULT_INTRO,
+      keyDraft,
+      modelDraft,
+      models: rows(),
+      modelsError,
+      modelsLoading,
+    };
+  }
+
+  /**
+   * What the reader typed, announced on the scope before anything else reads it.
+   *
+   * A document's binding writes only when the value it reads CHANGES (§9.3), so a draft the flow
+   * decided without the raw text passing through would leave the field holding something the flow
+   * does not have. Nothing rewrites a draft today; the echo is what makes a rewrite possible.
+   */
+  function setKey(value: string) {
+    keyDraft = value;
+    surface?.update(view());
+  }
+
+  /**
+   * Typed, picked from the catalogue, or committed — the combobox says all three through one value,
+   * and the draft is the one place it lands.
+   */
+  function setModel(value: string) {
+    modelDraft = value;
+    surface?.update(view());
+  }
+
+  function setBaseUrl(value: string) {
+    baseUrlDraft = value;
+    surface?.update(view());
+  }
+
+  function render(): HTMLElement {
+    if (surface) {
+      surface.update(view());
+    } else {
+      surface = createAiCredentialsSurface(view(), {
+        cancel,
+        fetchModels: () => {
+          void fetchModels();
+        },
+        save,
+        setBaseUrl,
+        setKey,
+        setModel,
+      });
+    }
+    return surface.host;
   }
 
   return { render, startEdit };

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

@@ -9,6 +9,13 @@
  * gate on credentials (the assistant sidebar and the New Project modal's Import/Agent tabs) embed
  * this alongside the form so both real paths are always on offer.
  *
+ * This module is the FLOW; `surfaces/ai-managed-connect.json` is what it draws. It decides whether
+ * the offer applies, what a finished OAuth round trip meant, and the words a fresh grant and a
+ * lapsed one get; the surface renders those words and reports the click. `render()` hands back the
+ * surface's own host element rather than a template, because every gate is still a lit template
+ * that interpolates the offer beside the key form — see `surfaces/ai-managed-connect.ts` for why
+ * that element is the mount point and why re-rendering the gate cannot disturb it.
+ *
  * State is per-instance (closure-scoped) like the credentials form; the capability probe behind
  * `ensureProbe` is shared module-wide by services/ai-models.ts.
  *
@@ -16,8 +23,6 @@
  * @license MIT
  */
 
-import { html, nothing } from "lit-html";
-import type { TemplateResult } from "lit-html";
 import { getPlatform, hasPlatform } from "../platform";
 import {
   ensureProxyProbe,
@@ -25,7 +30,11 @@ import {
   isManagedProxy,
   isProxyConfigured,
   proxyStateCode,
+  resetModelCache,
 } from "../services/ai-models";
+import { createManagedConnectSurface } from "../surfaces/ai-managed-connect";
+import type { ManagedConnectSurface, ManagedConnectView } from "../surfaces/ai-managed-connect";
+import type { CfConnectOutcome } from "../types";
 
 export interface ManagedConnectOptions {
   /** Host re-render scheduler — called on connect start/finish and when the probe settles. */
@@ -37,10 +46,27 @@ export interface ManagedConnect {
   canOffer: () => boolean;
   /** Fire the shared capability probe, repainting the host when it settles. */
   ensureProbe: () => void;
-  /** The CTA block, or `nothing` when the platform cannot broker AI. */
-  render: () => TemplateResult | typeof nothing;
+  /**
+   * The CTA block's host element, or `null` when the platform cannot broker AI.
+   *
+   * A gate interpolates it into its own lit template, which inserts a Node it is handed as-is;
+   * `null` clears that position exactly as `nothing` did.
+   */
+  render: () => HTMLElement | null;
 }
 
+/**
+ * A lede that says which path is recommended, and one that explains why the button is back.
+ *
+ * A lapsed grant and a fresh one get different words. The backend distinguishes them because
+ * "connect" is an invitation and "reconnect" is an explanation — and on a managed platform the
+ * lapsed case is the common one: a Cloudflare access token lives an hour.
+ */
+const LEDE_FRESH =
+  "Recommended — run the assistant on Workers AI in your own Cloudflare account. No API key to create, copy or rotate.";
+const LEDE_LAPSED =
+  "Your Cloudflare connection has expired. Reconnect to keep using the assistant.";
+
 /**
  * Create a managed-connect controller bound to a host's render scheduler.
  *
@@ -50,22 +76,77 @@ export interface ManagedConnect {
 export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnect {
   let busy = false;
   let connectError = "";
+  /** Made on the first render that offers, and kept for the life of the controller. */
+  let surface: ManagedConnectSurface | null = null;
 
   /*
-   * 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 +155,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);
     }
@@ -88,40 +163,32 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
     opts.requestRender();
   }
 
-  function render(): TemplateResult | typeof nothing {
+  /** What the offer says right now — the whole of what the surface is told. */
+  function view(): ManagedConnectView {
+    const lapsed = proxyStateCode() === "cf_reconnect_required";
+    const idleLabel = lapsed ? "Reconnect Cloudflare" : "Connect Cloudflare";
+    return {
+      buttonLabel: busy ? (lapsed ? "Reconnecting…" : "Connecting…") : idleLabel,
+      busy,
+      error: connectError,
+      intro: lapsed ? LEDE_LAPSED : LEDE_FRESH,
+    };
+  }
+
+  function render(): HTMLElement | null {
     if (!canOffer()) {
-      return nothing;
+      return null;
     }
-    /*
-     * A lapsed grant and a fresh one get different words. The backend distinguishes them because
-     * "connect" is an invitation and "reconnect" is an explanation — and on a managed platform the
-     * lapsed case is the common one: a Cloudflare access token lives an hour.
-     */
-    const lapsed = proxyStateCode() === "cf_reconnect_required";
-    const busyLabel = lapsed ? "Reconnecting…" : "Connecting…";
-    return html`
-      <div class="ai-managed-connect" data-jx-recommended="cloudflare">
-        <div class="ai-managed-connect-lede">
-          ${
-            lapsed
-              ? "Your Cloudflare connection has expired. Reconnect to keep using the assistant."
-              : "Recommended — run the assistant on Workers AI in your own Cloudflare account. No API key to create, copy or rotate."
-          }
-        </div>
-        <sp-button
-          size="s"
-          variant="accent"
-          ?disabled=${busy}
-          @click=${() => {
-            void connect();
-          }}
-        >
-          ${busy ? busyLabel : lapsed ? "Reconnect Cloudflare" : "Connect Cloudflare"}
-        </sp-button>
-        ${connectError ? html`<div class="ai-managed-connect-error">${connectError}</div>` : nothing}
-        <div class="ai-managed-connect-divider">— or bring your own key —</div>
-      </div>
-    `;
+    if (surface) {
+      surface.update(view());
+    } else {
+      surface = createManagedConnectSurface(view(), {
+        connect: () => {
+          void connect();
+        },
+      });
+    }
+    return surface.host;
   }
 
   return { canOffer, ensureProbe, render };