@jxsuite/studio 4.1.0 → 5.0.0

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,
@@ -27,6 +32,8 @@ import {
   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 {
@@ -39,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.
  *
@@ -52,6 +76,8 @@ 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 is managed and the platform can run the hosted OAuth flow
@@ -137,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 };

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

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * Ai-model-picker.ts — the provider's model catalogue as one `sp-picker`, for every surface that
+ * Ai-model-picker.ts — the provider's model catalogue as one control, 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
@@ -14,14 +14,18 @@
  * 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.
  *
+ * This module is the FLOW; `surfaces/ai-model-picker.json` is what it draws. `render()` hands back
+ * the surface's own host element rather than a template, because both hosts are still lit templates
+ * that interpolate the picker into a row of their own — see `surfaces/ai-model-picker.ts` for why
+ * that element is the mount point and why re-rendering the row cannot disturb it.
+ *
  * A closure factory (precedent: `createComposer`, `createAiCredentialsForm`) so two hosts never
  * share a loading flag or a failed-fetch record.
  *
+ * @docs studio/ai
  * @license MIT
  */
 
-import { html, nothing } from "lit-html";
-import { live } from "lit-html/directives/live.js";
 import {
   aiConnection,
   cachedModels,
@@ -30,14 +34,17 @@ import {
   preferredModel,
 } from "../services/ai-models";
 import { setModel } from "../services/ai-settings";
+import { createModelPickerSurface } from "../surfaces/ai-model-picker";
 
-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. */
+import type {
+  ModelPickerRow,
+  ModelPickerSurface,
+  ModelPickerView,
+  ModelPickerWidth,
+} from "../surfaces/ai-model-picker";
+
+/** The row value of the disabled placeholder shown during the first listing. */
 export const LOADING_MODELS = "__loading__";
 
 /** What a listed model's row says when the backend reported it cannot call tools. */
@@ -70,14 +77,26 @@ export interface ModelPickerOptions {
    * 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";
+  /**
+   * Which of the surface's two shapes to draw. `"compact"` (the composer's) by default; the Import
+   * form's field column asks for `"fill"`.
+   *
+   * This replaced a `className`. A document styles through `part` rather than through a class
+   * (`ui.md` §3.1), so the two rules the hosts used to supply are one attribute the document
+   * branches on — and a host can no longer reach in and restyle a control it does not own.
+   */
+  width?: ModelPickerWidth;
+  /** Control size; `"sm"` (the composer's) by default. */
+  size?: "sm" | "md";
 }
 
 export interface ModelPicker {
-  render: () => TemplateResult;
+  /**
+   * The picker's host element.
+   *
+   * A host interpolates it into its own lit template, which inserts a Node it is handed as-is.
+   */
+  render: () => HTMLElement;
   /** Whether a fetch is in flight — for a host that wants to disable a submit button. */
   isLoading: () => boolean;
   /** The last fetch's failure, or `""`. */
@@ -110,6 +129,9 @@ export function createModelPicker(opts: ModelPickerOptions): ModelPicker {
    */
   let attempted: AiCredentials | null = null;
 
+  /** Made on the first render, and kept for the life of the controller. */
+  let surface: ModelPickerSurface | null = null;
+
   function sameConnection(a: AiCredentials | null, b: AiCredentials): boolean {
     return a !== null && a.apiKey === b.apiKey && a.baseUrl === b.baseUrl;
   }
@@ -133,22 +155,23 @@ export function createModelPicker(opts: ModelPickerOptions): ModelPicker {
       });
   }
 
-  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;
-    }
+  /** List again, from the beginning: a refusal is forgotten so the same credentials are re-asked. */
+  function retry() {
+    attempted = null;
+    ensureModels(true);
+    opts.requestRender();
+  }
+
+  function choose(value: string) {
+    /* The placeholder is disabled, so a reader cannot land on it; a host driving the control
+       directly still can, and a state is not a model. */
     if (value && value !== LOADING_MODELS) {
       onChange(value);
     }
   }
 
-  function render(): TemplateResult {
-    ensureModels();
+  /** The rows to offer — what the catalogue holds, plus the one state that is worth a row. */
+  function rows(): ModelPickerRow[] {
     const current = getModel();
     const listed = cachedModels(aiConnection()) ?? [];
     /* A catalogue that does not contain the current model still has to show it selected — an
@@ -156,28 +179,33 @@ export function createModelPicker(opts: ModelPickerOptions): ModelPicker {
     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>
-    `;
+    const offered: ModelPickerRow[] = items.map((m) => ({ label: itemLabel(m), value: m.id }));
+    if (loading) {
+      offered.push({ disabled: true, label: "Loading models…", value: LOADING_MODELS });
+    }
+    return offered;
+  }
+
+  /** What the picker says right now — the whole of what the surface is told. */
+  function view(): ModelPickerView {
+    return {
+      failure,
+      hint: failure ? `Couldn't load models: ${failure}` : "Model",
+      options: rows(),
+      size: opts.size ?? "sm",
+      value: getModel(),
+      width: opts.width ?? "compact",
+    };
+  }
+
+  function render(): HTMLElement {
+    ensureModels();
+    if (surface) {
+      surface.update(view());
+    } else {
+      surface = createModelPickerSurface(view(), { choose, retry });
+    }
+    return surface.host;
   }
 
   return {