@jxsuite/studio 2.4.3 → 4.0.0

package/src/studio.ts

@@ -94,7 +94,8 @@ import { mountJumpBar } from "./panels/jump-bar";
 import { cellForPane } from "./panels/pane-grid";
 import { notify } from "./services/notify";
 import { beginActivity } from "./panels/activity-panel";
-import { exportFile, parseSourceForPath, saveFile, serializeDocument } from "./files/file-ops";
+import { exportFile, parseSourceForPath, saveFile } from "./files/file-ops";
+import { serializeDocument } from "./files/serialize-document";
 import {
   formatForPath,
   loadFormats,
@@ -113,6 +114,7 @@ import {
   registerFileTreeDnD,
   reloadCleanTab,
 } from "./files/files";
+import { resetIgnoreCache } from "./files/gitignore";
 import { startFsSync } from "./files/fs-events";
 import { invalidateParamValues } from "./page-params";
 import {
@@ -128,7 +130,13 @@ import { invalidateLibrary } from "./browse/library-pane";
 import { invalidateMediaCache } from "./ui/media-picker";
 import { setMediaChangedHandler } from "./files/media-upload";
 import { applyFileDrop } from "./editor/file-drop-action";
-import { assistantCommands, isAssistantStreaming, seedAssistantMessages } from "./panels/ai-panel";
+import {
+  assistantCommands,
+  isAssistantStreaming,
+  isAssistantWaiting,
+  revealImportHandoff,
+  seedAssistantMessages,
+} from "./panels/ai-panel";
 import { seedPublishConnected } from "./publish/publish-panel";
 
 import { getPlatform, hasPlatform, registerPlatform } from "./platform";
@@ -180,6 +188,8 @@ import * as frontmatterPanelMod from "./panels/frontmatter-panel";
 import * as rightPanelMod from "./panels/right-panel";
 import * as chatPanelMod from "./panels/chat-panel";
 import { setProjectAdopter } from "./services/project-adoption";
+import { setImportHandoff } from "./services/import-seed";
+import { watchConnection } from "./services/connection";
 import { tabBufferUnsaved } from "./services/monaco-buffer";
 import * as leftPanelMod from "./panels/left-panel";
 import * as tabStrip from "./panels/tab-strip";
@@ -204,7 +214,12 @@ import { initQuickSearch } from "./panels/quick-search";
 import { hydrateAccountStatus } from "./account-status";
 import { hydrateProjectList } from "./project-list";
 import { addRecentProject, hydrateRecentProjects, removeRecentProject } from "./recent-projects";
-import { hydrateSettings } from "./services/settings-store";
+import {
+  hydrateSettings,
+  onSettingsChanged,
+  settingsSettled,
+  watchRemoteSettings,
+} from "./services/settings/kernel";
 import { initWelcome } from "./panels/welcome-screen";
 import {
   openAddRepoModal,
@@ -223,6 +238,7 @@ import { registerPreferencesCommands } from "./settings/preferences-dialog";
 import { registerAboutCommands } from "./about/about-modal";
 import { registerCollabCommands } from "./collab/collab-commands";
 import { registerLibraryCommands } from "./browse/library-commands";
+import { registerFileFormatCommands } from "./format/convert-file";
 import { registerPublishCommands } from "./publish/publish-commands";
 import { registerGridViewCommands } from "./grid/grid-panel";
 import { registerRedirectsCommands } from "./grid/redirects-grid";
@@ -794,6 +810,11 @@ frontmatterPanelMod.mount();
 // The assistant's create_project tool adopts freshly scaffolded projects through the same
 // Flow as the recent-projects list.
 setProjectAdopter(openRecentProject);
+setImportHandoff(revealImportHandoff);
+
+/* A launcher whose backend can go away says so. Installs nothing on a platform that cannot lose
+   one — see services/connection.ts for why only the chromium shell can. */
+watchConnection();
 
 leftPanelMod.mount({
   cloneRepository: () => cloneRepository({ openRecentProject }),
@@ -966,6 +987,7 @@ if (_projectParam) {
             }
           }
 
+          resetIgnoreCache();
           setProjectState({
             dirs: new Map(),
             expanded: new Set(),
@@ -995,15 +1017,18 @@ if (_projectParam) {
             "public",
             "styles",
           ]);
-          const dirEntries = await platform.listDirectory(".");
-          requireProjectState().dirs.set(".", dirEntries);
+          /* Through `loadDirectory`, not `platform.listDirectory`: this is the second copy of the
+             conventional-dir walk (the first is `openProject` in files/files.ts), and the loader is
+             what reads the `.gitignore` chain governing each directory. Listing around it left the
+             `?project=` boot as the one door into a project whose tree knew no ignore rules. */
+          await loadDirectory(".");
+          const dirEntries = requireProjectState().dirs.get(".") ?? [];
           const foundDirs = [];
           for (const e of dirEntries) {
             if (e.type === "directory" && conventionalDirs.has(e.name)) {
               foundDirs.push(e.name);
               requireProjectState().expanded.add(e.path || e.name);
-              const sub = await platform.listDirectory(e.path || e.name);
-              requireProjectState().dirs.set(e.path || e.name, sub);
+              await loadDirectory(e.path || e.name);
             }
           }
           requireProjectState().projectDirs = foundDirs;
@@ -1136,6 +1161,32 @@ void hydrateSettings().then(() => {
   render();
 });
 
+/*
+ * A setting changing repaints, wherever the change came from — this window's Preferences, or
+ * hydration landing after boot. Key-gated surfaces (the assistant's setup notice, the New Project
+ * gates, the Accounts list) read the store on the render path rather than caching a copy, so this
+ * one subscription is what keeps every one of them honest.
+ */
+onSettingsChanged(() => {
+  render();
+});
+
+/*
+ * Another window changing a setting is news this one wants. Nothing is lost without it — a patch
+ * cannot clobber a key it does not name — but a second window would otherwise show a provider that
+ * had been reconfigured somewhere else until it was restarted.
+ */
+watchRemoteSettings();
+
+/*
+ * Settings are written on a queue that coalesces a burst into one send, so a change made in the
+ * last moments before the window closes may still be in flight. Draining it here is the difference
+ * between "your provider was saved" and a settings file that never heard about it.
+ */
+globalThis.addEventListener("beforeunload", () => {
+  void settingsSettled();
+});
+
 // ─── Left panel: delegated to panels/left-panel.js ───────────────────────────
 
 function renderLeftPanel() {
@@ -1266,6 +1317,7 @@ async function openRecentProject(root: string) {
     const config = JSON.parse(content) as ProjectConfig;
 
     closeAllTabs();
+    resetIgnoreCache();
 
     setProjectState({
       ...projectState,
@@ -1371,6 +1423,7 @@ const commandRegistry = createCommandRegistry({
     // The probe `live-context.ts` declared optional and nobody ever passed, so `ctx.ai.streaming`
     // Read false forever. `assistant.stop` is gated on it.
     aiStreaming: isAssistantStreaming,
+    aiWaiting: isAssistantWaiting,
     canvasMode: getCanvasMode,
     isCaretActive,
     isModalOpen,
@@ -1385,6 +1438,10 @@ registerStudioCommands(
     // Hands the URL to the launcher's preview-navigate handler — the OS browser — where a bare
     // `window.open` would open a webview with no address bar. The browser build falls back to a
     // New tab either way.
+    // `View: Open in Browser` renders the working tree; `Build Site` runs the compiler. Two
+    // Verbs, because "what does this page look like?" and "does my site build?" are two questions
+    // And only one of them is worth waiting for a bundler and an image pipeline.
+    buildSite: () => toolbarPanel.runBuildSite(),
     openInBrowser: () => toolbarPanel.runOpenInBrowser(),
     openProject,
     // Wrapped rather than passed by reference: `saveFile` takes an optional tab and reports
@@ -1452,6 +1509,7 @@ registerGridCommands(commandRegistry);
 registerSettingsCommands(commandRegistry);
 registerPreferencesCommands(commandRegistry);
 registerLibraryCommands(commandRegistry);
+registerFileFormatCommands(commandRegistry);
 registerContentCommands(commandRegistry);
 /* The four translation verbs: open a sibling translation, create the missing one, show the
    Languages panel, declare a language. `i18n.switchLocale` is deliberately not among them — it sets

package/src/tabs/transact.ts

@@ -1135,6 +1135,46 @@ export function mutateUpdateMediaNestedStyle(
   recordPatch({ op: "set-style", path });
 }
 
+/**
+ * Drop every level of `stylePath` a deletion has just left empty, DEEPEST FIRST.
+ *
+ * Emptying the leaf usually empties its parent with it — `["table", "th"]` losing its last
+ * declaration leaves `table` holding nothing — and an empty object still serialises, so it reaches
+ * the file, the diff, and every equality check the collab layer makes. Every other style writer in
+ * this module is careful about that; these two were not.
+ *
+ * The walk this replaces went top-down and stopped at the first empty level it found, which is the
+ * one order that cannot work: on the way down the shallow levels are still non-empty _because_ the
+ * leaf it is looking for is inside them, so it deleted the leaf and returned with every ancestor
+ * left behind. Writing then deleting `["table", "th"]` on a node with no style at all produced `{
+ * table: {} }` — a style the author never wrote, on a node that should have had none, because
+ * `ensureNestedStyle` creates the intermediates on the way in.
+ *
+ * @param {JxStyle} root - The object `stylePath[0]` is a key of: a node's `style`, or a media
+ *   block.
+ * @param {string[]} stylePath
+ */
+function pruneEmptyStylePath(root: JxStyle, stylePath: string[]) {
+  // Each entry holds the segment at its own index; an absent (or scalar) one ends the descent.
+  const owners: JxStyle[] = [root];
+  for (const seg of stylePath) {
+    const next = getNestedStyle(owners.at(-1), seg);
+    if (!next) {
+      break;
+    }
+    owners.push(next);
+  }
+  for (let i = owners.length - 2; i >= 0; i--) {
+    const owner = owners[i]!;
+    const seg = stylePath[i]!;
+    const block = getNestedStyle(owner, seg);
+    // Re-read rather than reuse `owners[i + 1]`: the level below may have gone this same loop.
+    if (block && Object.keys(block).length === 0) {
+      delete owner[seg];
+    }
+  }
+}
+
 /**
  * Update a style property at a nested style path (e.g., ["table", "th"]). Creates intermediate
  * objects as needed.
@@ -1163,16 +1203,7 @@ export function mutateUpdateNestedStylePath(
   }
   if (value === undefined || value === "") {
     delete obj[prop];
-    // Clean up empty parent objects
-    let cur: JxStyle | undefined = node.style;
-    for (let i = 0; i < stylePath.length && cur; i++) {
-      const child = getNestedStyle(cur, stylePath[i]!);
-      if (child && Object.keys(child).length === 0) {
-        delete cur[stylePath[i]!];
-        break;
-      }
-      cur = child;
-    }
+    pruneEmptyStylePath(node.style, stylePath);
   } else {
     obj[prop] = value;
   }
@@ -1214,15 +1245,7 @@ export function mutateUpdateMediaNestedStylePath(
   }
   if (value === undefined || value === "") {
     delete obj[prop];
-    let cur: JxStyle | undefined = media;
-    for (let i = 0; i < stylePath.length && cur; i++) {
-      const child = getNestedStyle(cur, stylePath[i]!);
-      if (child && Object.keys(child).length === 0) {
-        delete cur[stylePath[i]!];
-        break;
-      }
-      cur = child;
-    }
+    pruneEmptyStylePath(media, stylePath);
     if (Object.keys(media).length === 0) {
       delete node.style[key];
     }

package/src/types.ts

@@ -13,6 +13,7 @@ import type {
 
 import type {
   AppInfo,
+  AssetCapabilities,
   CfConnection,
   CodeServiceResult,
   ComponentMeta,
@@ -31,10 +32,12 @@ import type {
   GitLogEntry,
   GitStatusResult,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
-  OutdatedInfo,
+  ImportSiteSummary,
   PackageInfo,
   PackageOpResult,
+  PackageVersionInfo,
   ProjectListEntry,
   ProjectSchemasResponse,
   RecentProjectEntry,
@@ -42,7 +45,9 @@ import type {
   RenameResult,
   SecretsSetRequest,
   SecretsSetResponse,
+  SettingsPatch,
   StarterInfo,
+  UploadResult,
 } from "@jxsuite/protocol";
 
 export type {
@@ -76,12 +81,15 @@ export type {
   GitFileStatus,
   GitLogEntry,
   GitStatusResult,
+  ImportBreakpointPolicy,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
+  ImportSiteSummary,
   JsonValue,
-  OutdatedInfo,
   PackageInfo,
   PackageOpResult,
+  PackageVersionInfo,
   ProjectListEntry,
   ProjectSchemasResponse,
   PullRequestInfo,
@@ -93,6 +101,7 @@ export type {
   SecretsListResponse,
   SecretsSetRequest,
   SecretsSetResponse,
+  SettingsPatch,
   StarterInfo,
 } from "@jxsuite/protocol";
 
@@ -145,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`.
    *
@@ -156,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;
@@ -200,6 +241,33 @@ export interface StudioPlatform {
    * trailing `/` is added: without it `new URL` drops the last segment.
    */
   documentBaseUrl?: string;
+  /**
+   * What the canvas ORIGIN answers for a SITE URL — and therefore how Studio must address media.
+   *
+   * `"site"` (the default when absent): the canvas origin already serves the published site URL
+   * space, so `/hero.jpg` and `/styles/main.css` resolve on their own and Studio touches neither.
+   * The dev server and the desktop loopback both do — `serveProjectFile` in `@jxsuite/server` IS
+   * that URL space — so neither declares anything here and both stay byte-identical.
+   *
+   * `"repo"`: the host serves PROJECT-RELATIVE paths under {@link documentBaseUrl}, and nothing
+   * answers the site URL space. Studio resolves each authored reference to the project file it
+   * names and rebases that path onto `documentBaseUrl`. Inert without one — a host that says its
+   * site URLs are wrong without saying what is right has told Studio nothing it can act on.
+   *
+   * This is about the ORIGIN, not the backend: a host whose files are perfectly reachable can still
+   * be `"repo"` space, because what decides it is what answers `GET /hero.jpg` on the document the
+   * canvas is running in.
+   */
+  assetSpace?: "site" | "repo";
+  /**
+   * What this backend will accept as an upload, when it says.
+   *
+   * Absent, or any field absent, means "no declared limit", and Studio must not invent one — a
+   * limit it made up is a file the user cannot upload for no reason anyone can name. A DECLARED
+   * limit is different: Studio refuses before spending the round trip and names the number in the
+   * refusal, and narrows the file picker's `accept` to match.
+   */
+  assetCapabilities?: AssetCapabilities;
   activate: (root?: string) => Promise<void>;
   openProject: () => Promise<{
     config: ProjectConfig;
@@ -224,8 +292,26 @@ export interface StudioPlatform {
   listDirectory: (dir: string) => Promise<DirEntry[]>;
   readFile: (path: string) => Promise<string>;
   writeFile: (path: string, content: string) => Promise<void>;
-  uploadFile: (path: string, data: string | File | Blob | ArrayBuffer) => Promise<unknown>;
+  /**
+   * Store bytes at a project path, and report where they really landed.
+   *
+   * The result's `path` is the ANSWER, not an echo: a backend may de-duplicate by content hash,
+   * append a collision suffix, or normalize a name, and the reference Studio writes into the
+   * document has to name what was actually written. This was `Promise<unknown>` and every caller
+   * used the REQUESTED path, so any such backend produced documents pointing at files that are not
+   * there.
+   */
+  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
@@ -239,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>;
@@ -258,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.
@@ -349,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
@@ -389,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
@@ -508,8 +633,39 @@ export interface StudioPlatform {
    * settings live in localStorage only.
    */
   getSettings?: () => Promise<Record<string, string>>;
-  /** Persist the full user-level settings map to the backend store. */
-  saveSettings?: (settings: Record<string, string>) => Promise<void>;
+  /**
+   * Apply a set of changes to the backend store, and answer with the store as it then stands.
+   *
+   * A PATCH rather than the whole map, which is a correctness property and not an optimisation: a
+   * key named by neither `set` nor `remove` must be left exactly as it was found. Writing the whole
+   * map let any window overwrite the shared file with its own view of it, and on the chromium
+   * launcher every window is a separate process with a separate browser profile — so a window that
+   * held no settings could, and did, clear the credentials another window had just stored. It also
+   * preserves keys this build does not know: one written by a newer version, or by hand.
+   */
+  patchSettings?: (patch: SettingsPatch) => Promise<Record<string, string>>;
+  /**
+   * Be told when the backend store changes — by another window, or by hand. Returns the
+   * unsubscribe.
+   *
+   * Optional, and a display concern rather than a correctness one: `patchSettings` already stops a
+   * window from clobbering another's keys, so a platform without this leaves a second window
+   * 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 ───────────────────────────────────────────────────────────