@jxsuite/studio 4.1.0 → 5.1.0

package/src/tabs/tab.ts

@@ -2,11 +2,13 @@
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
+import type { JxPath } from "../state";
 import type { FormulaEditDef, FunctionEditDef, InlineEditDef, JsonValue } from "../types";
 import { editorKindForMode } from "../commands/context";
 import type { EditorKind } from "../commands/context";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { JxDocOp, JxFmOp } from "./patch-ops";
+import type { JsonLayout } from "../files/json-layout";
 
 /**
  * The project's configuration file, project-relative.
@@ -39,6 +41,29 @@ export interface TabUi {
   editZoom: number;
   activeMedia: string | null;
   activeSelector: string | null;
+  /**
+   * The popover the canvas is drawing OPEN, by document path, or null for none.
+   *
+   * Per tab rather than per pane, beside `activeMedia` and `previewColorScheme`, because it is a
+   * fact about a DOCUMENT's elements: two panes showing the same tab show the same open panel,
+   * which is correct — it is the same element.
+   *
+   * Exactly one, never a set. Several de-popovered panels in flow at once would shove the page
+   * around and make the canvas unreadable; native `popover="auto"` already enforces a single stack,
+   * so a set would model something the platform does not have; and "exactly one" makes the
+   * open-on-selection rule total, with no ordering decision to make.
+   *
+   * A VIEW state — it writes nothing to the document, so it takes no undo entry, does not dirty the
+   * tab and is not replicated over collaboration. It is also deliberately not restored with a
+   * session (§14.8): reopening a project with a modal spread across the page is a worse first frame
+   * than reopening it closed.
+   */
+  openPopover: JxPath | null;
+  /**
+   * The `<dialog>` the canvas draws open in place, per tab and exactly one; view state like
+   * `openPopover`.
+   */
+  openDialog: JxPath | null;
   editingFunction: FunctionEditDef | null;
   /** Logic-tab formula target ($expression editing); editingFunction wins if both are set. */
   editingFormula: FormulaEditDef | null;
@@ -161,6 +186,18 @@ export interface Tab {
     sourceFormat: string | null;
     handlersSource: string | null;
     dirty: boolean;
+    /**
+     * The layout the document's JSON file was written in (`files/json-layout.ts`), or null for a
+     * document with no JSON source — a format-class file, a new document, a stub.
+     *
+     * On the document record because it is a fact about the FILE the document came from, and it
+     * lives exactly as long as that fact does: every edit leaves it alone (the pointers it is keyed
+     * by survive a changed value, a new sibling, a removed one), a reload from disk or a
+     * source-view commit replaces it with the layout of the text just read, and opening a different
+     * file makes a new tab. The history ring never snapshots it — undo restores a document, not a
+     * file.
+     */
+    layout: JsonLayout | null;
   };
   session: {
     /**
@@ -216,6 +253,8 @@ function createDefaultUi(canvasMode: string, preview = false) {
   return {
     activeMedia: null,
     activeSelector: null,
+    openPopover: null,
+    openDialog: null,
     canvasMode,
     editZoom: 1,
     editingFormula: null,
@@ -239,7 +278,15 @@ function createDefaultUi(canvasMode: string, preview = false) {
   };
 }
 
-const ALL_MODES = ["edit", "design", "preview", "source", "stylebook"];
+/*
+ * `git-diff` is here because a comparison is a MODE of a document, and until now nothing said so.
+ * The Source Control panel reached it through the injected `setCanvasMode`, which performs no
+ * capability check — so the mode worked while `editorKindsOf` could never report `diff`, the Editor
+ * picker could never offer it, and `canvas.setMode { mode: "git-diff" }` threw for every document in
+ * the project. Declaring it makes the palette, the assistant and the screenshot runner able to open
+ * a comparison by name, and puts Diff on the Editor axis where §18.4 already says it belongs.
+ */
+const ALL_MODES = ["edit", "design", "preview", "source", "stylebook", "git-diff"];
 
 /**
  * Create a new tab with reactive doc/session/history trees, owned by an effectScope.
@@ -254,6 +301,7 @@ const ALL_MODES = ["edit", "design", "preview", "source", "stylebook"];
  *   capabilities?: { modes?: string[] };
  *   openedFrom?: TabOrigin | null;
  *   preview?: boolean;
+ *   layout?: JsonLayout | null;
  * }} opts
  * @returns {Tab}
  */
@@ -267,6 +315,7 @@ export function createTab({
   capabilities,
   openedFrom = null,
   preview: previewTab = false,
+  layout = null,
 }: {
   id: string;
   documentPath?: string | null;
@@ -277,6 +326,7 @@ export function createTab({
   capabilities?: { modes?: string[] };
   openedFrom?: TabOrigin | null;
   preview?: boolean;
+  layout?: JsonLayout | null;
 }) {
   const scope = effectScope();
 
@@ -299,6 +349,7 @@ export function createTab({
       dirty: false,
       document,
       handlersSource: null,
+      layout,
       mode: inferDocumentMode(documentPath, sourceFormat),
       sourceFormat,
     }),

package/src/types.ts

@@ -28,6 +28,7 @@ import type {
   DataRowsResult,
   DataRowUpdate,
   DirEntry,
+  ExtensionCatalogEntry,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
@@ -77,8 +78,10 @@ export type {
   DataRowUpdate,
   DirEntry,
   ErrorBody,
+  ExtensionCatalogEntry,
   ExtensionContributionInfo,
   ExtensionProjectBlock,
+  ExtensionSectionInfo,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
@@ -386,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

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 };