@jxsuite/studio 3.0.0 → 4.0.0

package/src/types.ts

@@ -32,10 +32,12 @@ import type {
   GitLogEntry,
   GitStatusResult,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
-  OutdatedInfo,
+  ImportSiteSummary,
   PackageInfo,
   PackageOpResult,
+  PackageVersionInfo,
   ProjectListEntry,
   ProjectSchemasResponse,
   RecentProjectEntry,
@@ -79,12 +81,15 @@ export type {
   GitFileStatus,
   GitLogEntry,
   GitStatusResult,
+  ImportBreakpointPolicy,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
+  ImportSiteSummary,
   JsonValue,
-  OutdatedInfo,
   PackageInfo,
   PackageOpResult,
+  PackageVersionInfo,
   ProjectListEntry,
   ProjectSchemasResponse,
   PullRequestInfo,
@@ -149,6 +154,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 +179,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 +303,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 +325,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 +347,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 +442,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 +507,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
@@ -568,6 +653,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-model-picker.ts

@@ -0,0 +1,162 @@
+/// <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,
+  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__";
+
+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;
+}
+
+/**
+ * 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}>${m.name}</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 };
+}

package/src/ui/choice-field.ts

@@ -0,0 +1,72 @@
+/**
+ * `choiceField` — one labelled choice, rendered the way every Spectrum picker in Studio is.
+ *
+ * It exists so the New File dialog's format picker and the Convert dialog's target picker are the
+ * SAME control rather than two that drift: same divider idiom for a sentinel row, same `live()`
+ * guard, same "one kind is not a choice" collapse to static text.
+ *
+ * **It imports lit only.** Both callers live in modules the other imports — `ui/layers.ts` is
+ * imported by `format/convert-file.ts`, which also wants this fragment — so a shared control that
+ * reached into either would be a cycle, and `import/no-cycle` is an error here.
+ *
+ * `.value=${live(...)}` is not stylistic. `sp-picker` writes its own `value` when the reader picks
+ * a row, so lit's dirty check sees the value it last committed and skips the re-commit that would
+ * put the control back where the model says it is. `scripts/check-lit-conventions.ts` fails on the
+ * unguarded form.
+ */
+
+import { html, nothing } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import type { TemplateResult } from "lit-html";
+
+/** One row of a {@link choiceField}. */
+export interface ChoiceOption {
+  value: string;
+  label: string;
+  /** Draw an `sp-menu-divider` immediately before this row — how a sentinel row is set apart. */
+  dividerBefore?: boolean;
+}
+
+/** What a {@link choiceField} renders and reports. */
+export interface ChoiceSpec {
+  label: string;
+  options: readonly ChoiceOption[];
+  value: string;
+  onChange: (next: string) => void;
+}
+
+/**
+ * A labelled picker, or static text when there is nothing to choose.
+ *
+ * The collapse is the rule `panels/pane-context.ts` already states about editor kinds: **one kind
+ * is not a choice**. A picker whose menu holds a single row is a control that cannot do anything,
+ * and drawing it invites the reader to open it and find out.
+ *
+ * @param spec - The label, the rows, the current value and the change sink.
+ * @returns The fragment, for a caller's own template.
+ */
+export function choiceField(spec: ChoiceSpec): TemplateResult {
+  const current = spec.options.find((option) => option.value === spec.value);
+  if (spec.options.length < 2) {
+    return html`<div class="choice-row">
+      <sp-field-label size="s">${spec.label}</sp-field-label>
+      <span class="choice-static">${current?.label ?? spec.value}</span>
+    </div>`;
+  }
+  return html`<div class="choice-row">
+    <sp-field-label size="s">${spec.label}</sp-field-label>
+    <sp-picker
+      size="s"
+      label=${spec.label}
+      .value=${live(spec.value)}
+      @change=${(e: Event) => spec.onChange((e.target as HTMLInputElement).value)}
+    >
+      ${spec.options.map(
+        (option) =>
+          html`${
+              option.dividerBefore === true ? html`<sp-menu-divider></sp-menu-divider>` : nothing
+            }<sp-menu-item value=${option.value}>${option.label}</sp-menu-item>`,
+      )}
+    </sp-picker>
+  </div>`;
+}

package/src/ui/layers.ts

@@ -15,10 +15,12 @@
 import { html, render as litRender, nothing } from "lit-html";
 import { ref } from "lit-html/directives/ref.js";
 import { repeat } from "lit-html/directives/repeat.js";
+import { choiceField } from "./choice-field";
 import { overlayRegion, REGION_ATTR } from "./regions";
 import { dismiss, toasts } from "../services/notify";
 import { activeRegistry } from "../commands/active-registry";
 import { effect, effectScope } from "../reactivity";
+import type { ChoiceOption } from "./choice-field";
 import type { Notification, Severity } from "../services/notify";
 import type { EffectScope } from "@vue/reactivity";
 import type { TemplateResult } from "lit-html";
@@ -338,6 +340,31 @@ export function showSaveDiscardDialog(
   );
 }
 
+/**
+ * A picker rendered above the field, whose selection the dialog OWNS.
+ *
+ * Owned, not merely displayed: the choice reaches `validate` as its second argument, and picking a
+ * row re-runs it. That is the whole reason this lives here rather than being smuggled in through
+ * `message` — `check` and `rerender` are private to {@link showPromptDialog}, so a caller-built
+ * control could change the selection but could never make the field's refusal catch up with it. The
+ * New File dialog's format picker is exactly that case: switching from Markdown to JSON changes
+ * whether the typed name is already taken, with no keystroke to notice.
+ */
+export interface PromptChoice {
+  /** Label above the picker. */
+  label: string;
+  /**
+   * The rows, re-read on EVERY render rather than captured once. A snapshot taken when the options
+   * object is built freezes a list the project can still be loading — the same defect
+   * `content/entry-commands.ts`'s `derivedEnumProperty` exists to prevent one layer up.
+   */
+  options: () => readonly ChoiceOption[];
+  /** Which row starts selected. */
+  initial: string;
+  /** Told what was picked, for a caller keeping its own derived state. */
+  onChange?: (next: string) => void;
+}
+
 /** Options accepted by {@link showPromptDialog}. */
 export interface PromptDialogOptions {
   /** Label on the confirming button. */
@@ -346,17 +373,21 @@ export interface PromptDialogOptions {
   cancelLabel?: string;
   /** Explanatory copy rendered above the text field. */
   message?: string | TemplateResult;
-  /** Placeholder shown while the field is empty. */
-  placeholder?: string;
+  /** Placeholder shown while the field is empty. Read on every render, so it may follow the choice. */
+  placeholder?: string | (() => string);
   /** How much of the pre-filled value to select once the field takes focus. */
   select?: "all" | "stem" | "none";
   /**
    * Validate the raw field value. Return an empty string when valid, or a message to show as
    * negative help text (which also blocks confirmation). Defaults to "must not be blank".
+   *
+   * `chosen` is the {@link PromptChoice} selection, or `""` when the dialog offers no choice.
    */
-  validate?: (value: string) => string;
+  validate?: (value: string, chosen: string) => string;
   /** Pre-filled value. */
   value?: string;
+  /** A picker above the field whose selection this dialog owns. */
+  choice?: PromptChoice;
 }
 
 /**
@@ -375,6 +406,7 @@ export function showPromptDialog(
 ): Promise<string | null> {
   const {
     cancelLabel = "Cancel",
+    choice,
     confirmLabel = "OK",
     message,
     placeholder = "",
@@ -384,12 +416,22 @@ export function showPromptDialog(
   } = opts;
 
   const check = (candidate: string) =>
-    validate ? validate(candidate) : candidate.trim() ? "" : "Enter a value.";
+    validate ? validate(candidate, chosen) : candidate.trim() ? "" : "Enter a value.";
 
   let value = initialValue;
+  let chosen = choice?.initial ?? "";
   let error = "";
   let wrapperEl: HTMLElement | null = null;
   let focusRequested = false;
+  /*
+   * Whether the reader has typed yet.
+   *
+   * A dialog opens with a valid prefill and NO error, and picking a format must not be the thing
+   * that first paints one under a field nobody has touched — "untitled" is not yet a mistake. So a
+   * pick refreshes an error that is already showing and never mints the first one; the confirm
+   * still refuses, because `confirm()` runs `check` unconditionally.
+   */
+  let touched = false;
 
   return showDialog<string | null>((done) => {
     function rerender() {
@@ -411,6 +453,7 @@ export function showPromptDialog(
     }
 
     function onInput(e: Event) {
+      touched = true;
       value = (e.target as HTMLInputElement).value || "";
       const next = check(value);
       if (next !== error) {
@@ -419,6 +462,23 @@ export function showPromptDialog(
       }
     }
 
+    /**
+     * Take a pick, and re-render UNCONDITIONALLY.
+     *
+     * `onInput` re-renders only when the error string changed, which is right for a keystroke: the
+     * template it would rebuild is identical. A pick is not that. It can change the placeholder,
+     * the picker's own selected row, and — for the New File dialog — whether the composed filename
+     * is already taken, all with the error text unchanged. Comparing error strings here would leave
+     * a dialog showing "about.md already exists" after the reader switched the format to JSON.
+     */
+    function onPick(next: string) {
+      chosen = next;
+      choice?.onChange?.(next);
+      const candidate = check(value);
+      error = touched || error ? candidate : "";
+      rerender();
+    }
+
     function onKeydown(e: KeyboardEvent) {
       if (e.key === "Enter") {
         confirm();
@@ -472,9 +532,27 @@ export function showPromptDialog(
             // Spectrum resets <p> margins to 0, so without this the copy sits flush on the field.
             message ? html`<p style="margin:0 0 8px">${message}</p>` : nothing
           }
+          ${
+            /*
+             * Above the field, and in ONE template position in every mode.
+             *
+             * The `sp-textfield` below must never move or be rebuilt by a conditional branch: lit
+             * would commit a new element, `onFieldRef` would fire again, the `focusRequested` latch
+             * would refuse to re-focus it, and the caret would be stranded mid-name. Only the
+             * placeholder, the validation rules and the help text vary between modes.
+             */
+            choice
+              ? choiceField({
+                  label: choice.label,
+                  onChange: onPick,
+                  options: choice.options(),
+                  value: chosen,
+                })
+              : nothing
+          }
           <sp-textfield
             style="width:100%"
-            placeholder=${placeholder}
+            placeholder=${typeof placeholder === "function" ? placeholder() : placeholder}
             value=${value}
             ?invalid=${Boolean(error)}
             @input=${onInput}