@jxsuite/studio 5.5.0 → 5.7.0

package/src/files/fs-events.ts

@@ -6,21 +6,49 @@
  * without a DOM). `startFsSync` is the only impure part: it feature-detects the platform's
  * `subscribeFileEvents`, debounces bursts, drops the echoes of the user's own local mutations, and
  * triggers a single re-render through the existing left-panel render path (no imperative DOM).
+ *
+ * It also answers the transport's `onResync`, which is the platform admitting that its event stream
+ * has a gap (a reconnect, or the stream's first open after listings were made) or never carried the
+ * change (a commit). Events are deltas; a gap in deltas cannot be patched by more deltas, so a
+ * resync re-reads what this window has cached.
  */
 
 import { getPlatform } from "../platform";
 import { reloadIgnoreCache, touchesGitignore } from "./gitignore";
 import { invalidateUsages } from "../services/references";
+import { forgetAllVersions, forgetVersions, notedListing } from "./asset-versions";
+import { isCollabPath } from "../collab/collab-state";
 import { projectState } from "../store";
-import type { DirEntry, FsEvent } from "../types";
+import { workspace } from "../workspace/workspace";
+import type { DirEntry, FsEvent, FsResyncReason, StudioPlatform } from "../types";
 
 const RECENT_MS = 1500;
+/**
+ * How wide each resync reason's pass is: a coalesced burst runs the widest one it saw. A reconnect
+ * re-derives everything; an open forgets the content versions and re-lists; a commit re-lists.
+ */
+const RESYNC_RANK: Record<FsResyncReason, number> = { commit: 0, open: 1, reconnect: 2 };
+/**
+ * How long a resync request waits for company. A flapping network reconnects several times in a
+ * second, and a commit notice can arrive on the heels of a reconnect; each resync re-lists every
+ * loaded directory, so a burst is coalesced into one pass.
+ */
+const RESYNC_DEBOUNCE_MS = 250;
+/** Listings in flight at once during a resync — a deep expanded tree is many round trips. */
+const RELIST_CONCURRENCY = 8;
 const recentLocal = new Map<string, number>();
 
 const norm = (p: string) => p.replaceAll("\\", "/");
 
-/** Mark paths the user just mutated locally so the watcher's echo of them is ignored briefly. */
+/**
+ * Mark paths the user just mutated locally so the watcher's echo of them is ignored briefly.
+ *
+ * Their content versions are forgotten too, each path as a file AND as a directory (a rename or a
+ * delete may name either): the bytes are about to change, and a version that outlived them would
+ * let an immutable cache serve the old ones.
+ */
 export function markLocalMutation(...paths: string[]): void {
+  forgetVersions(paths, paths);
   const expiry = Date.now() + RECENT_MS;
   for (const p of paths) {
     if (p) {
@@ -114,6 +142,146 @@ export function applyFsEvents(
   return changedDirs;
 }
 
+/**
+ * Forget the content versions every event in a batch could have invalidated: the file an `add`,
+ * `change` or `unlink` names, and everything under a removed directory.
+ */
+export function forgetEventVersions(events: readonly FsEvent[]): void {
+  const paths: string[] = [];
+  const dirs: string[] = [];
+  for (const event of events) {
+    if (event.type === "unlinkDir") {
+      dirs.push(event.path);
+    } else if (event.type !== "addDir") {
+      paths.push(event.path);
+    }
+  }
+  if (paths.length > 0 || dirs.length > 0) {
+    forgetVersions(paths, dirs);
+  }
+}
+
+/** Whether a cached listing still holds exactly the entries a snapshot of it took. */
+function sameEntries(current: DirEntry[] | undefined, snapshot: DirEntry[]): boolean {
+  return (
+    current !== undefined &&
+    current.length === snapshot.length &&
+    current.every((entry, index) => entry === snapshot[index])
+  );
+}
+
+/** Reads of one directory a resync makes before it lets newer changes have the last word. */
+const RELIST_ATTEMPTS = 2;
+
+/**
+ * Re-list every directory `dirs` has cached and replace its entries in place.
+ *
+ * Only directories already in the cache are read: the tree's lazy loading is the authority on what
+ * is worth fetching, and a resync that grew the cache would turn one reconnect into a crawl of the
+ * project. A directory whose listing FAILS is dropped rather than kept — after a gap in the event
+ * stream, "this directory vanished" is the likeliest reason, and a stale listing of a directory
+ * that no longer exists is the very thing a resync exists to remove. Expanding it again re-reads
+ * it.
+ *
+ * Live events keep landing while the listings are in flight, and Studio's own create / rename /
+ * delete re-load their parent, so a listing can come back OLDER than the cache it would replace:
+ * nothing orders an HTTP response against a message on the event socket. Each directory is
+ * therefore snapshotted before its read and the listing applied only if the cache still matches the
+ * snapshot. A directory that moved is read again — that read starts after the change, so it
+ * includes it — and if it moves again under the second read the cache keeps what the newer changes
+ * made of it. Identity alone could not tell: `applyFsEvents` edits a listing in place. For the same
+ * reason a directory that left the cache mid-read (an `unlinkDir`) stays gone: the event is newer
+ * than the read.
+ */
+export async function relistLoadedDirs(
+  dirs: Map<string, DirEntry[]>,
+  listDirectory: StudioPlatform["listDirectory"],
+): Promise<void> {
+  const keys = [...dirs.keys()];
+  let next = 0;
+  const relist = async (dir: string) => {
+    for (let attempt = 0; attempt < RELIST_ATTEMPTS; attempt += 1) {
+      const before = dirs.get(dir);
+      if (!before) {
+        return;
+      }
+      const snapshot = [...before];
+      let entries: DirEntry[] | null;
+      try {
+        entries = await listDirectory(dir);
+      } catch {
+        entries = null;
+      }
+      if (!dirs.has(dir)) {
+        return;
+      }
+      if (!sameEntries(dirs.get(dir), snapshot)) {
+        continue;
+      }
+      if (entries) {
+        dirs.set(dir, entries);
+      } else {
+        dirs.delete(dir);
+      }
+      return;
+    }
+  };
+  const worker = async () => {
+    while (next < keys.length) {
+      const dir = keys[next]!;
+      next += 1;
+      await relist(dir);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(RELIST_CONCURRENCY, keys.length) }, worker));
+}
+
+/**
+ * Modes only a tab whose `document` is a placeholder offers: the media viewer, a CSV grid, the
+ * Library. Spelled out as strings, not imported, because each constant's module drags its whole
+ * editor in behind it.
+ */
+const STUB_DOCUMENT_MODES = new Set(["media", "grid", "manage"]);
+
+/**
+ * Whether a tab's `document` is a placeholder rather than its parsed file. Such a tab reads its
+ * file through its own channel, if at all, so a re-read through `readFile` has nothing to refresh —
+ * and is worse than waste: the cloud session's `/file` route refuses a binary file (415), and the
+ * failed reload would raise "could not reload" for a file that never changed. A git comparison stub
+ * is recognised by offering `git-diff` and NOTHING else, since every document tab offers it too.
+ */
+function holdsPlaceholder(modes: string[]): boolean {
+  return (
+    modes.some((mode) => STUB_DOCUMENT_MODES.has(mode)) ||
+    (modes.length > 0 && modes.every((mode) => mode === "git-diff"))
+  );
+}
+
+/**
+ * The open tabs a reconnect may refresh from disk: clean ones holding a parsed document, and none
+ * that are co-edited.
+ *
+ * A dirty tab holds the author's unsaved work, which a reload would discard. A co-edited one never
+ * reloads from disk at all — its shared document is ahead of whatever the provider wrote back (the
+ * same rule `reloadCleanTab` applies to a single event). A stub tab has no parsed document to
+ * refresh ({@link holdsPlaceholder}).
+ */
+export function cleanOpenTabPaths(): string[] {
+  const paths = new Set<string>();
+  for (const tab of workspace.tabs.values()) {
+    const path = tab.documentPath;
+    if (
+      path &&
+      !tab.doc.dirty &&
+      !isCollabPath(path) &&
+      !holdsPlaceholder(tab.capabilities.modes)
+    ) {
+      paths.add(path);
+    }
+  }
+  return [...paths];
+}
+
 export interface FsSyncContext {
   renderLeftPanel: () => void;
   /** Optional hook for an external content change to an open file (e.g. reload a clean tab). */
@@ -127,6 +295,12 @@ export interface FsSyncContext {
    * scope.
    */
   invalidateDerivedCaches?: () => void;
+  /**
+   * After a reconnect, the clean, non-collab open tabs whose files may have changed while the
+   * stream was down. The handler re-reads them; it should leave a tab whose content did not change
+   * alone, since a reconnect usually changed nothing and a reload churns undo and repaints.
+   */
+  onResyncContent?: (paths: string[]) => void;
 }
 
 /**
@@ -141,6 +315,8 @@ export function startFsSync(ctx: FsSyncContext): () => void {
   }
   let pending: FsEvent[] = [];
   let timer: ReturnType<typeof setTimeout> | null = null;
+  let resyncReason: FsResyncReason | null = null;
+  let resyncTimer: ReturnType<typeof setTimeout> | null = null;
 
   const flush = () => {
     timer = null;
@@ -163,30 +339,105 @@ export function startFsSync(ctx: FsSyncContext): () => void {
     }
   };
 
-  return platform.subscribeFileEvents((events) => {
-    // Before the echo filter, deliberately. `isRecentLocal` drops the events Studio caused, which
-    // Is right for the tree (it already repainted) and wrong for a DERIVED cache — Studio's own
-    // Write changes what the project contains exactly as much as anyone else's does.
-    //
-    // Every cache keyed on "what files exist" is dropped here, in one place, because they answer
-    // One event. Each one had an invalidator and no caller, and each stale answer is visible: the
-    // Link-target picker offering a route whose page was deleted, the layout picker attributing a
-    // Removed layout's `$head` to the open page, a `$paths` enumeration listing entries that are
-    // Gone.
-    invalidateUsages();
-    ctx.invalidateDerivedCaches?.();
-    /* A `.gitignore` governs the whole tree beneath it, so it is handled HERE rather than in the
-       batch below: the echo filter drops the events Studio caused, and an author who just edited
-       their own `.gitignore` in Studio is precisely the one waiting to see the tree change. It also
-       never reaches `applyFsEvents` — a dotfile is in no listing, so no directory reads as changed
-       and no repaint would follow. Hence the explicit one, once the rules are back. */
-    if (touchesGitignore(events.map((event) => event.path))) {
-      void reloadIgnoreCache().then(() => ctx.renderLeftPanel());
-    }
-    pending.push(...events);
-    if (timer) {
-      clearTimeout(timer);
-    }
-    timer = setTimeout(flush, 50);
-  });
+  /*
+   * A reconnect lost an unknown set of events, so it re-derives everything the events would have
+   * kept current: the caches keyed on which files exist (dropped, exactly as one event drops them),
+   * the `.gitignore` rules, every cached listing, and the open documents. A commit lost nothing —
+   * the DO simply sends no per-file events for one — so it re-reads the listings alone. An open is
+   * the stream going live after the first listings were already made; it re-reads them too, since
+   * a change broadcast before the socket joined reached nobody. (Each gap's content versions were
+   * already forgotten when it was reported — see `requestResync`.)
+   */
+  const resync = async () => {
+    resyncTimer = null;
+    const reason = resyncReason;
+    resyncReason = null;
+    const state = projectState;
+    if (!state || !reason) {
+      return;
+    }
+    /* Noted, so a commit — which makes dirty files clean — hands their versions back, and a gap's
+       re-list vouches again for the tree's share of what it forgot. */
+    const relist = relistLoadedDirs(state.dirs, (dir) =>
+      notedListing(() => platform.listDirectory(dir)),
+    );
+    if (reason === "reconnect") {
+      invalidateUsages();
+      ctx.invalidateDerivedCaches?.();
+      await Promise.all([relist, reloadIgnoreCache()]);
+    } else {
+      await relist;
+    }
+    // The project changed under the listings: they belong to a tree nobody is drawing any more.
+    if (projectState !== state) {
+      return;
+    }
+    if (reason === "reconnect") {
+      ctx.onResyncContent?.(cleanOpenTabPaths());
+    }
+    ctx.renderLeftPanel();
+  };
+
+  const requestResync = (reason: FsResyncReason) => {
+    /* A gap in the stream — a reconnect, or the first open — forgets EVERY content version, at once
+       rather than after the debounce: the events that would have forgotten single paths are gone,
+       and many versions were learned outside the tree (the Library walk, the media picker, media
+       metadata), where no re-list of the loaded directories reaches. A version Studio can no longer
+       vouch for may be answered from an immutable cache with the old bytes, so it cannot wait. The
+       floor this raises also discards any listing still in flight across the gap. The re-list
+       below, and every later listing, vouch afresh. A commit loses no events, so it keeps them. */
+    if (reason !== "commit") {
+      forgetAllVersions();
+    }
+    // A wider pass includes a narrower one's, so the widest reason wins a coalesced burst.
+    if (!resyncReason || RESYNC_RANK[reason] > RESYNC_RANK[resyncReason]) {
+      resyncReason = reason;
+    }
+    if (resyncTimer) {
+      clearTimeout(resyncTimer);
+    }
+    resyncTimer = setTimeout(() => {
+      void resync();
+    }, RESYNC_DEBOUNCE_MS);
+  };
+
+  const unsubscribe = platform.subscribeFileEvents(
+    (events) => {
+      // Before the echo filter, deliberately. `isRecentLocal` drops the events Studio caused, which
+      // Is right for the tree (it already repainted) and wrong for a DERIVED cache — Studio's own
+      // Write changes what the project contains exactly as much as anyone else's does.
+      //
+      // Every cache keyed on "what files exist" is dropped here, in one place, because they answer
+      // One event. Each one had an invalidator and no caller, and each stale answer is visible: the
+      // Link-target picker offering a route whose page was deleted, the layout picker attributing a
+      // Removed layout's `$head` to the open page, a `$paths` enumeration listing entries that are
+      // Gone.
+      invalidateUsages();
+      ctx.invalidateDerivedCaches?.();
+      // Content versions are derived state of the same kind, and Studio's own writes change bytes:
+      // A version kept past its echo would let an immutable cache answer with the old file.
+      forgetEventVersions(events);
+      /* A `.gitignore` governs the whole tree beneath it, so it is handled HERE rather than in the
+         batch below: the echo filter drops the events Studio caused, and an author who just edited
+         their own `.gitignore` in Studio is precisely the one waiting to see the tree change. It also
+         never reaches `applyFsEvents` — a dotfile is in no listing, so no directory reads as changed
+         and no repaint would follow. Hence the explicit one, once the rules are back. */
+      if (touchesGitignore(events.map((event) => event.path))) {
+        void reloadIgnoreCache().then(() => ctx.renderLeftPanel());
+      }
+      pending.push(...events);
+      if (timer) {
+        clearTimeout(timer);
+      }
+      timer = setTimeout(flush, 50);
+    },
+    { onResync: requestResync },
+  );
+  return () => {
+    if (resyncTimer) {
+      clearTimeout(resyncTimer);
+      resyncTimer = null;
+    }
+    unsubscribe();
+  };
 }

package/src/files/media-meta.ts

@@ -25,6 +25,7 @@
 
 import { getPlatform } from "../platform";
 import { baseName, dirName, normalizeProjectPath } from "./media-paths";
+import { notedListing } from "./asset-versions";
 import { extensionOf, mediaKind } from "./media-upload";
 import type { AssetKind } from "./media-upload";
 import type { DirEntry } from "../types";
@@ -126,7 +127,7 @@ export async function loadMediaMeta(path: string): Promise<MediaMeta> {
   const pending = (async (): Promise<MediaMeta> => {
     let entry: DirEntry | undefined;
     try {
-      const listing = await getPlatform().listDirectory(dirName(key));
+      const listing = await notedListing(() => getPlatform().listDirectory(dirName(key)));
       entry = listing.find((item) => normalizeProjectPath(item.path) === key);
     } catch {
       // Unreadable or not yet created — the size stays unknown rather than becoming zero.

package/src/files/media-paths.ts

@@ -38,6 +38,8 @@
 
 import { encodeProjectPath, normalizeProjectPath, PUBLIC_DIR } from "@jxsuite/schema/asset-paths";
 import { contentMountFor, hostAssetDeclarations, projectLocales } from "../canvas/asset-refs";
+import { withVersion } from "../canvas/asset-resolve";
+import { versionOf } from "./asset-versions";
 import { loopbackAssetSrc } from "../canvas/canvas-origin";
 import { projectState } from "../store";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
@@ -126,10 +128,11 @@ export function previewFileSrc(path: string): string {
     return path;
   }
   /* In repo space nothing answers a site URL, so the site URL is the wrong question entirely: the
-     host serves the FILE, at its own path, under the declared base. */
+     host serves the FILE, at its own path, under the declared base — versioned when a listing
+     vouched for its bytes, so a host that recognizes the version can let the browser cache it. */
   const { space, fileBaseUrl } = hostAssetDeclarations();
   if (space === "repo") {
-    return `${fileBaseUrl}${encodeProjectPath(normalized)}`;
+    return withVersion(`${fileBaseUrl}${encodeProjectPath(normalized)}`, versionOf(normalized));
   }
   return loopbackAssetSrc(mediaSiteUrl(normalized));
 }

package/src/files/media-upload.ts

@@ -20,6 +20,7 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { getPlatform, hasPlatform } from "../platform";
 import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
+import { forgetVersions, notedListing } from "./asset-versions";
 
 // ─── File classification ─────────────────────────────────────────────────────
 
@@ -245,7 +246,8 @@ export async function uploadAssets(
 
   let taken: Set<string>;
   try {
-    const existing = await platform.listDirectory(dir);
+    // The upload directory is a media directory, so its listing vouches for versions as well.
+    const existing = await notedListing(() => platform.listDirectory(dir));
     taken = new Set(existing.map((entry) => entry.name));
   } catch {
     taken = new Set(); // Directory doesn't exist yet — the backend mkdir -p's on write.
@@ -273,6 +275,8 @@ export async function uploadAssets(
          hash, appends a collision suffix, or normalizes a name writes somewhere else, and the
          reference that goes into the document has to name what is really there. */
       const { path } = await platform.uploadFile(requested, file);
+      // New bytes at `path`: whatever version a listing held for it no longer names them.
+      forgetVersions([path]);
       uploaded.push({ kind: mediaKind(file), name, path, ref: assetRef(path) });
     } catch (error) {
       notify.error(`Could not upload ${file.name}.`, {

package/src/new-project/add-repo-modal.ts

@@ -31,6 +31,7 @@
  * closer nothing in the app called was left over from drawing the box by hand.
  */
 
+import { actIfRequired } from "../account/action-flow";
 import { errorMessage } from "@jxsuite/schema/parse";
 import {
   getAccountStatus,
@@ -167,7 +168,11 @@ function settle(result: { root: string } | null): void {
   handle?.close();
 }
 
-async function chooseRepo(fullName: string) {
+/**
+ * Adopt the picked repository. A refusal that offers an action (desktop.md §10.4) is offered, and
+ * an action that is done runs the import again, once.
+ */
+async function chooseRepo(fullName: string, retried = false): Promise<void> {
   if (_importing) {
     return;
   }
@@ -187,6 +192,12 @@ async function chooseRepo(fullName: string) {
     _error = "This platform cannot import repositories.";
   } catch (error) {
     _error = errorMessage(error);
+    _importing = "";
+    redraw();
+    if (!retried && (await actIfRequired(error))) {
+      await chooseRepo(fullName, true);
+    }
+    return;
   }
   _importing = "";
   redraw();

package/src/new-project/new-project-modal.ts

@@ -44,6 +44,7 @@ import { enumArg, enumProperty } from "../commands/command-args";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import { getPlatform } from "../platform";
 import { installUrlOf } from "../platform-errors";
+import { actIfRequired } from "../account/action-flow";
 import { hasAiCredentials } from "../services/ai-models";
 import { setPendingAgentPrompt } from "../services/agent-seed";
 import { adoptCreatedProject } from "../services/project-adoption";
@@ -500,10 +501,17 @@ function goBack(): void {
   redraw();
 }
 
-/** Create the project from the chosen source, then run `after` with the result. */
+/**
+ * Create the project from the chosen source, then run `after` with the result.
+ *
+ * A refusal that offers an action (desktop.md §10.4) is offered over the modal, and an action that
+ * is done runs the create again — once, so a platform that still refuses afterwards leaves its
+ * error standing rather than asking forever.
+ */
 async function create(
   source: { starter: string } | { template: string },
   after: (result: { root: string; config: ProjectConfig }) => void | Promise<void>,
+  retried = false,
 ): Promise<void> {
   const destination = validateParams();
   if (!destination) {
@@ -522,6 +530,9 @@ async function create(
     _creating = false;
     captureError(error);
     redraw();
+    if (!retried && (await actIfRequired(error))) {
+      await create(source, after, true);
+    }
   }
 }
 

package/src/panels/git-panel.ts

@@ -342,8 +342,9 @@ export async function signInToGithub(): Promise<void> {
 /**
  * @param {string} action
  * @param {unknown} [body]
+ * @returns {Promise<boolean>} Whether the action succeeded — its failure is already on screen.
  */
-async function gitAction(action: string, body?: unknown) {
+async function gitAction(action: string, body?: unknown): Promise<boolean> {
   const plat = getPlatform() as Record<string, (...args: unknown[]) => Promise<unknown>> &
     StudioPlatform;
   shell.git.loading = true;
@@ -351,9 +352,23 @@ async function gitAction(action: string, body?: unknown) {
   try {
     await plat[action]!(body);
     await refreshGitStatus();
+    return true;
   } catch (error) {
     shell.git.error = errorMessage(error);
     shell.git.loading = false;
+    return false;
+  }
+}
+
+/**
+ * Put a message back in the field after the commit that took it failed — unless the user has
+ * already started typing another. The field is cleared before the call so a second click cannot
+ * commit the same text twice, which used to mean a refused commit (a conflict, a backend that asks
+ * for an action first) silently threw the message away with it.
+ */
+function restoreCommitMessage(message: string): void {
+  if (!shell.git.commitMessage) {
+    shell.git.commitMessage = message;
   }
 }
 
@@ -578,7 +593,9 @@ async function doCommit(): Promise<void> {
   // Fold co-editing sessions into the backend's tree first so the commit never misses trailing
   // Keystrokes (the mirror is debounced).
   await flushAllCollab();
-  await gitAction("gitCommit", message);
+  if (!(await gitAction("gitCommit", message))) {
+    restoreCommitMessage(message);
+  }
 }
 
 /** Commit and push, as one operation with one loading state and one error. */
@@ -592,13 +609,19 @@ async function doCommitAndSync(): Promise<void> {
   shell.git.error = null;
   await flushAllCollab();
   const plat = getPlatform();
+  let committed = false;
   try {
     await plat.gitCommit(message);
+    committed = true;
     await plat.gitPush();
     await refreshGitStatus();
   } catch (error) {
     shell.git.error = errorMessage(error);
     shell.git.loading = false;
+    // A push that failed after the commit landed must not offer the same message again.
+    if (!committed) {
+      restoreCommitMessage(message);
+    }
   }
 }