@jxsuite/studio 5.5.0 → 5.6.0

package/src/canvas/iframe-host.ts

@@ -49,6 +49,7 @@ import { DIALOG_COMMANDS, isDialog, POPOVER_COMMANDS } from "@jxsuite/schema/dia
 import { isPopover } from "@jxsuite/schema/overlays";
 import { localeDirection } from "@jxsuite/schema/locale";
 import { getPlatform, hasPlatform } from "../platform";
+import { assetVersionsEpoch, assetVersionsSnapshot } from "../files/asset-versions";
 import type {
   ApplyFormatIntent,
   CanvasMode,
@@ -90,6 +91,12 @@ interface HostState {
   canvasUrl: string;
   ready: boolean;
   pending: ParentToIframe | null;
+  /**
+   * The asset-version snapshot this frame last received (`assetVersions`), or null when it has
+   * received none since it last said `ready`. Compared by identity — the snapshot is memoized and
+   * changes identity only when a media version moves.
+   */
+  postedVersions: Readonly<Record<string, string>> | null;
   overlay: OverlayLayer;
   /** Primary selected path (mirrors `session.selection`'s last entry), for hover de-dupe. */
   selectionPath: (string | number)[] | null;
@@ -1304,6 +1311,8 @@ export function postPatchToHosts(forwardOps: WireDocOp[], tabId: string | null):
       // Only the host that originated this edit already has the DOM the patch describes. A
       // Split-view panel on the same document did NOT type it and must render normally.
       const echoPaths = echoOrigin?.host === host ? echoOrigin.paths : undefined;
+      // A patch draws nodes too, so it must not resolve media against an older map.
+      syncAssetVersions(host);
       host.channel.post(
         echoPaths
           ? { echoPaths, forwardOps, gen, kind: "patch" }
@@ -1496,6 +1505,74 @@ function ensureSelectionWatch(): void {
   selectionWatch = { stop: () => scope.stop() };
 }
 
+/**
+ * Post a ready frame the current asset-version snapshot if it holds an older one.
+ *
+ * Called before every render and patch the host sends, on `ready`, and whenever the versions move —
+ * so a frame can never draw a node against a map older than the one Studio holds, and a version
+ * that was forgotten (the bytes changed) never reaches a resolver after the forget. A frame that
+ * has received nothing and would receive an empty map is sent nothing: the frame starts empty, and
+ * a host that never versions anything (desktop, `jx dev`) should not pay a message per frame for
+ * it.
+ */
+function syncAssetVersions(host: HostState): void {
+  if (!host.ready) {
+    return;
+  }
+  const versions = assetVersionsSnapshot();
+  if (versions === host.postedVersions) {
+    return;
+  }
+  if (host.postedVersions === null && Object.keys(versions).length === 0) {
+    host.postedVersions = versions;
+    return;
+  }
+  host.postedVersions = versions;
+  host.channel.post({ kind: "assetVersions", versions });
+}
+
+let assetVersionsWatchStarted = false;
+let assetVersionsFlushQueued = false;
+
+/**
+ * Lazily start one watcher that reposts the asset versions to every ready frame when they move.
+ *
+ * Coalesced to a microtask: a Library walk notes one listing per directory, and each would
+ * otherwise post the whole map. Coalescing cannot let a render see an older map, because every
+ * render and patch syncs its own host first.
+ */
+function ensureAssetVersionsWatch(): void {
+  if (assetVersionsWatchStarted) {
+    return;
+  }
+  assetVersionsWatchStarted = true;
+  const scope = effectScope(true);
+  scope.run(() => {
+    effect(() => {
+      void assetVersionsEpoch.value;
+      if (assetVersionsFlushQueued) {
+        return;
+      }
+      assetVersionsFlushQueued = true;
+      queueMicrotask(() => {
+        assetVersionsFlushQueued = false;
+        publishAssetVersions();
+      });
+    });
+  });
+}
+
+/** Bring every ready, connected frame up to the current asset versions. */
+export function publishAssetVersions(): void {
+  for (const host of liveHosts) {
+    if (!host.iframe.isConnected) {
+      liveHosts.delete(host);
+      continue;
+    }
+    syncAssetVersions(host);
+  }
+}
+
 /** Lazily start one reactive watcher that re-measures remote peers' selections in every host. */
 let presenceWatchStarted = false;
 let presenceTimer: ReturnType<typeof setTimeout> | null = null;
@@ -1841,6 +1918,7 @@ function ensureHost(canvasEl: HTMLElement): HostState {
     overlay,
     panReqId: -1,
     pending: null,
+    postedVersions: null,
     idle: null,
     pendingEnterEdit: null,
     pendingMeasures: new Map(),
@@ -1875,6 +1953,7 @@ function ensureHost(canvasEl: HTMLElement): HostState {
   liveHosts.add(state);
   ensureSelectionWatch();
   ensurePresenceWatch();
+  ensureAssetVersionsWatch();
   return state;
 }
 
@@ -1988,6 +2067,11 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       if (table) {
         state.channel.post({ chords: table.chords, kind: "keymap", mac: table.mac });
       }
+      /* Then the asset versions, also ahead of the render: the frame resolves media while it
+         renders, and a FIFO channel makes "posted first" mean "known first". A frame that said
+         `ready` again has rebooted and lost what it was sent before. */
+      state.postedVersions = null;
+      syncAssetVersions(state);
       if (state.pending) {
         state.channel.post(state.pending);
         state.pending = null;
@@ -3088,6 +3172,7 @@ export async function mountIframeCanvas(
 function deliverRender(state: HostState, message: ParentToIframe): void {
   canvasPerf.hostRenderPosts += 1;
   if (state.ready) {
+    syncAssetVersions(state);
     state.channel.post(message);
   } else {
     state.pending = message;

package/src/canvas/iframe-protocol.ts

@@ -148,6 +148,19 @@ export type ParentToIframe =
       dialogOpen?: (string | number)[] | null;
       gen: number;
     }
+  /**
+   * The content versions of the project's media, by normalized project path — what the frame folds
+   * into every render's `assets` context so a repo-space reference resolves to `<file>?v=<version>`
+   * (specs/studio.md §3.4). A path absent here resolves unversioned.
+   *
+   * A message of its own, not a field on `render`: the map is as large as the project's media and
+   * changes far less often than the document does. The host posts it before a frame's first render
+   * and again before any render or patch that would otherwise see an older map — the channel is
+   * FIFO, so "posted before" is "applied before". Gen-less and render-free: the frame keeps the
+   * latest map and re-installs its asset resolver around it, so the next node a patch draws already
+   * uses it. A frame built before this message existed ignores it and keeps resolving unversioned.
+   */
+  | { kind: "assetVersions"; versions: Readonly<Record<string, string>> }
   // Flip the forced color-scheme preview on the iframe root without re-rendering — a document-level
   // Idempotent attribute write, deliberately gen-less (like endEdit).
   | { kind: "setColorScheme"; scheme: "light" | "dark" | null }

package/src/files/asset-versions.ts

@@ -0,0 +1,294 @@
+/**
+ * Asset versions — which project files the backend vouches for, and by what opaque version.
+ *
+ * A listing entry may carry `version` (protocol `DirEntry.version`): an opaque token for the file's
+ * bytes, equal tokens meaning identical bytes, ABSENT whenever the backend cannot vouch (an
+ * uncommitted, dirty or just-uploaded file). The cloud session sets it to the row's git blob sha.
+ * Studio appends it to a project-file URL as `?v=<version>` (`withVersion` in
+ * `canvas/asset-resolve.ts`), and a host that recognizes the version may answer that URL with an
+ * immutable cache lifetime — which is what lets a page full of images repaint from the browser
+ * cache instead of revalidating every one (specs/studio.md §3.4).
+ *
+ * That cache is only safe while the version is TRUE. A stale version names bytes the file no longer
+ * has, and an immutable response for it is never re-asked. So this map is built defensively:
+ *
+ * - **Listings feed it** ({@link beginListing} / {@link noteListing}). Every file entry of a listing
+ *   either sets its version or, when the entry has none, deletes it — a listing that says nothing
+ *   about a version is the backend withdrawing it.
+ * - **Change forgets** ({@link forgetVersions}). The file-event subscription forgets every path an
+ *   event names, before the echo filter (Studio's own writes change bytes too), and
+ *   `markLocalMutation` forgets the paths Studio is about to write.
+ * - **A listing never outlives a forget.** Nothing orders an HTTP response against the event socket,
+ *   so a listing requested BEFORE a write can be answered AFTER the forget for it, carrying the old
+ *   version. Each listing records the sequence number current when it began, every forget bumps the
+ *   sequence and stamps the paths (and directory prefixes) it dirtied, and {@link noteListing}
+ *   ignores any path dirtied after its listing began. The next listing, begun after the forget,
+ *   decides.
+ *
+ * The canvas iframe receives {@link assetVersionsSnapshot} as one `assetVersions` message whenever
+ * {@link assetVersionsEpoch} moves, rather than a copy on every render. The snapshot holds MEDIA
+ * paths only — a `.json` or `.md` file is never loaded by URL from the canvas, and leaving them out
+ * keeps that message as small as the media set.
+ *
+ * Pure module state — it imports nothing but path normalization and the reactivity re-export — so
+ * the canvas host can import it without dragging in the file layer.
+ *
+ * @docs extending/embedding/platform-adapter
+ */
+
+import { normalizeProjectPath } from "@jxsuite/schema/asset-paths";
+import { shallowRef } from "../reactivity";
+import type { DirEntry } from "../types";
+
+/**
+ * Extensions whose versions the canvas snapshot carries: images (svg included), fonts, video and
+ * audio — what a rendered document loads by URL. Documents and data (`.json`, `.md`, `.csv`) are
+ * deliberately absent.
+ */
+const MEDIA_EXTENSIONS = new Set([
+  // Images
+  ".apng",
+  ".avif",
+  ".bmp",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".png",
+  ".svg",
+  ".webp",
+  // Fonts
+  ".eot",
+  ".otf",
+  ".ttf",
+  ".woff",
+  ".woff2",
+  // Video
+  ".m4v",
+  ".mov",
+  ".mp4",
+  ".ogv",
+  ".webm",
+  // Audio
+  ".aac",
+  ".flac",
+  ".m4a",
+  ".mp3",
+  ".oga",
+  ".ogg",
+  ".opus",
+  ".wav",
+]);
+
+/** Whether a project path is media the canvas loads by URL. */
+export function isVersionedMediaPath(path: string): boolean {
+  const slash = path.lastIndexOf("/");
+  const dot = path.lastIndexOf(".");
+  return dot > slash + 1 && MEDIA_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+
+/** Every version a listing has vouched for, keyed by normalized project path. */
+const versions = new Map<string, string>();
+/** Monotonic; bumped by every forget, read by every listing as it begins. */
+let seq = 0;
+/** Listings begun before this sequence number belong to a previous project and are ignored. */
+let floor = 0;
+/** The sequence number at which each path was last forgotten. */
+const dirtiedPaths = new Map<string, number>();
+/** The sequence number at which each directory prefix (`dir/`) was last forgotten. */
+const dirtiedPrefixes = new Map<string, number>();
+/** The memoized canvas snapshot, or null once a media version changed under it. */
+let snapshot: Readonly<Record<string, string>> | null = null;
+/**
+ * The one snapshot of a map with no media in it. Shared, so emptying an already-empty map keeps the
+ * snapshot's identity and the canvas host — which compares identities — posts nothing: a host that
+ * never versions anything (desktop, `jx dev`) never pays a message for it.
+ */
+const EMPTY_SNAPSHOT: Readonly<Record<string, string>> = Object.freeze({});
+
+/**
+ * Bumped whenever the MEDIA versions change — the canvas host watches it to know when to repost
+ * {@link assetVersionsSnapshot}. A change to a non-media version does not move it: nothing the
+ * canvas holds would differ.
+ */
+export const assetVersionsEpoch = shallowRef(0);
+
+function mediaChanged(): void {
+  snapshot = null;
+  assetVersionsEpoch.value += 1;
+}
+
+/**
+ * Begin a listing, returning the sequence number to pass to {@link noteListing} with its answer.
+ * Call it BEFORE the request goes out.
+ */
+export function beginListing(): number {
+  return seq;
+}
+
+/** Whether `path` was forgotten after sequence number `since`. */
+function dirtiedSince(path: string, since: number): boolean {
+  const own = dirtiedPaths.get(path);
+  if (own !== undefined && own > since) {
+    return true;
+  }
+  for (const [prefix, at] of dirtiedPrefixes) {
+    if (at > since && path.startsWith(prefix)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Record what one listing said about its files' versions.
+ *
+ * A file entry WITH a version sets it; one without deletes any version held, since the backend no
+ * longer vouches for those bytes. Directories are ignored. A path forgotten after `since` (the
+ * value {@link beginListing} returned when this listing began) is skipped entirely: the listing may
+ * predate the change that forgot it.
+ */
+export function noteListing(entries: readonly DirEntry[], since: number): void {
+  if (since < floor) {
+    return;
+  }
+  let changed = false;
+  for (const entry of entries) {
+    if (entry.type !== "file") {
+      continue;
+    }
+    const path = normalizeProjectPath(entry.path);
+    if (path === "" || dirtiedSince(path, since)) {
+      continue;
+    }
+    const version =
+      typeof entry.version === "string" && entry.version !== "" ? entry.version : null;
+    const held = versions.get(path);
+    if (version === null) {
+      if (held === undefined) {
+        continue;
+      }
+      versions.delete(path);
+    } else if (held === version) {
+      continue;
+    } else {
+      versions.set(path, version);
+    }
+    if (isVersionedMediaPath(path)) {
+      changed = true;
+    }
+  }
+  if (changed) {
+    mediaChanged();
+  }
+}
+
+/**
+ * List through `read` with the listing's versions noted — {@link beginListing} before the request,
+ * {@link noteListing} with its answer. Resolves (or rejects) with exactly what `read` did.
+ */
+export async function notedListing<T extends readonly DirEntry[]>(
+  read: () => Promise<T>,
+): Promise<T> {
+  const since = beginListing();
+  const entries = await read();
+  noteListing(entries, since);
+  return entries;
+}
+
+/**
+ * Forget the versions of `paths`, and of every file under each of `prefixDirs`, and make sure no
+ * listing that began before this call can restore them.
+ */
+export function forgetVersions(paths: readonly string[], prefixDirs: readonly string[] = []): void {
+  seq += 1;
+  let changed = false;
+  for (const raw of paths) {
+    const path = normalizeProjectPath(raw);
+    if (path === "") {
+      continue;
+    }
+    dirtiedPaths.set(path, seq);
+    if (versions.delete(path) && isVersionedMediaPath(path)) {
+      changed = true;
+    }
+  }
+  for (const raw of prefixDirs) {
+    const dir = normalizeProjectPath(raw);
+    if (dir === "") {
+      continue;
+    }
+    const prefix = `${dir}/`;
+    dirtiedPrefixes.set(prefix, seq);
+    for (const path of versions.keys()) {
+      if (path.startsWith(prefix)) {
+        versions.delete(path);
+        if (isVersionedMediaPath(path)) {
+          changed = true;
+        }
+      }
+    }
+  }
+  if (changed) {
+    mediaChanged();
+  }
+}
+
+/** The version a listing vouched for `path`, or undefined when none is held. */
+export function versionOf(path: string): string | undefined {
+  return versions.get(normalizeProjectPath(path));
+}
+
+/**
+ * Every media path's version as a plain record, for the canvas iframe. Memoized: the same object is
+ * returned until a media version changes, so identity is a cheap "did anything move" test.
+ */
+export function assetVersionsSnapshot(): Readonly<Record<string, string>> {
+  if (snapshot) {
+    return snapshot;
+  }
+  const out: Record<string, string> = {};
+  let any = false;
+  for (const [path, version] of versions) {
+    if (isVersionedMediaPath(path)) {
+      out[path] = version;
+      any = true;
+    }
+  }
+  snapshot = any ? Object.freeze(out) : EMPTY_SNAPSHOT;
+  return snapshot;
+}
+
+/**
+ * Forget EVERY version, and ignore every listing begun before this call when it lands.
+ *
+ * For a gap in the event stream: a reconnect, or the stream's first open after listings were
+ * already noted (§9.2). The events that would have forgotten individual paths are gone, and the
+ * versions at risk are not only the file tree's — the Library walk, the media picker and media
+ * metadata note directories the tree never loaded, and a re-list of the tree cannot reach them. A
+ * version Studio can no longer vouch for has to go, because an immutable response for it is never
+ * re-asked. Listings begun after this call vouch afresh.
+ *
+ * Raising the floor, rather than stamping paths, is what covers a listing that was in flight across
+ * the gap: it has no forget recorded against it, and would otherwise put the old version back.
+ */
+export function forgetAllVersions(): void {
+  const hadMedia = assetVersionsSnapshot() !== EMPTY_SNAPSHOT;
+  versions.clear();
+  // Every record is older than the new floor, and every listing it could have guarded is below it.
+  dirtiedPaths.clear();
+  dirtiedPrefixes.clear();
+  seq += 1;
+  floor = seq;
+  if (hadMedia) {
+    mediaChanged();
+  }
+}
+
+/**
+ * Drop every version and dirt record — a project switch, and between tests. A listing begun before
+ * the reset is ignored when it lands: it lists the project that was closed.
+ */
+export function resetAssetVersions(): void {
+  forgetAllVersions();
+}

package/src/files/files.ts

@@ -47,6 +47,7 @@ import { ensureDependenciesInstalled } from "../packages/ensure-deps";
 import { maybePromptJxsuiteUpdate } from "../packages/jxsuite-update";
 import { autoSyncProjectOnOpen } from "../packages/pull-package-sync";
 import { markLocalMutation } from "./fs-events";
+import { notedListing, resetAssetVersions } from "./asset-versions";
 import { ensureIgnoreLayers, isIgnoredEntry, resetIgnoreCache } from "./gitignore";
 import { SETTINGS } from "../services/settings/definitions";
 import { readStoredSetting, setSetting } from "../services/settings/kernel";
@@ -78,6 +79,8 @@ import { runActiveReported, runReported } from "../commands/run-reported";
 import { collectionOfPath } from "../content/entry-model";
 import { confirmFileDelete, parseSourceForPath, renamePromptMessage } from "./file-ops";
 import { parseJsonDocument } from "@jxsuite/schema/json-layout";
+// The pure half of the differ: order-insensitive equality with no Yjs behind it.
+import { deepEqual } from "@jxsuite/collab/diff-core";
 import type { JsonLayout } from "@jxsuite/schema/json-layout";
 import { invalidateUsages } from "../services/references";
 import {
@@ -123,7 +126,8 @@ export async function loadDirectory(dirPath: string) {
        ignore rules synchronously while it builds rows, and a repaint that beat the rules would draw
        a `node_modules` and then take it away again. Concurrent, because neither needs the other. */
     const [entries] = await Promise.all([
-      platform.listDirectory(dirPath),
+      // Noted: a listing is where Studio learns which files' bytes the backend vouches for.
+      notedListing(() => platform.listDirectory(dirPath)),
       ensureIgnoreLayers(dirPath),
     ]);
     projectState.dirs.set(dirPath, entries);
@@ -161,6 +165,7 @@ export async function loadProject() {
     void loadFormats();
     refreshExtensionUi(platform);
     resetIgnoreCache();
+    resetAssetVersions();
 
     setProjectState({
       dirs: new Map(),
@@ -241,6 +246,7 @@ export async function openProject({
     void loadFormats();
     refreshExtensionUi(platform);
     resetIgnoreCache();
+    resetAssetVersions();
 
     setProjectState({
       .../** @type {ProjectState} */ projectState,
@@ -2431,12 +2437,6 @@ export async function openFileInPane(paneId: string, path: string): Promise<void
   await openFileInTab(path, { focus: false, paneId, preview: true });
 }
 
-/**
- * Reload an already-open tab from disk without changing the active tab. Used to refresh after AI
- * assistant writes to a file.
- *
- * @param {string} path
- */
 /** Reload an open tab from disk when an external change arrives — but only if it is not dirty. */
 export function reloadCleanTab(path: string): void {
   // Co-edited docs never reload from disk: the shared Y.Doc is ahead of the provider's write-back
@@ -2452,25 +2452,77 @@ export function reloadCleanTab(path: string): void {
   }
 }
 
-export async function reloadFileInTab(path: string) {
+/**
+ * Re-read open tabs after the file-event stream reconnected (`FsSyncContext.onResyncContent`).
+ *
+ * The paths arrive already filtered to clean, non-collab tabs. Each reload is `onlyIfChanged`
+ * because a reconnect almost always changed nothing: an unconditional reload would replace every
+ * open document with an identical one, which is a repaint per tab and an undo boundary nobody
+ * made.
+ */
+export function reloadTabsIfChanged(paths: string[]): void {
+  for (const path of paths) {
+    void reloadFileInTab(path, { onlyIfChanged: true });
+  }
+}
+
+/**
+ * Reload an already-open tab from disk without changing the active tab. Used to refresh after AI
+ * assistant writes to a file, an external change, or a reconnect.
+ *
+ * With `onlyIfChanged`, a file whose parsed document (and frontmatter) equals what the tab already
+ * holds is left alone: no assignment, so no re-render and nothing for undo to see. A JSON file's
+ * layout is still taken from the new text, because a file reformatted on disk with the same content
+ * would otherwise be written back in its old layout on the next save — and the layout renders
+ * nothing.
+ *
+ * Whether to reload is decided about the tab as it was when the read STARTED, and the read is a
+ * round trip (a network one on cloud). So the decision is re-checked after every await and before
+ * anything is assigned: a tab that was clean and took an edit in the meantime, or that joined a
+ * co-editing session, keeps what it now holds. Otherwise the disk copy would land over the author's
+ * newest keystrokes and clear `dirty` — work lost without a trace — and a reconnect resync, which
+ * re-reads every clean tab at the moment the author comes back to the window, is exactly when those
+ * keystrokes arrive. A tab that was ALREADY dirty when the read started is the caller asking for it
+ * to be replaced (an AI write, a rename's reference rewrite), and keeps that meaning.
+ */
+export async function reloadFileInTab(path: string, opts: { onlyIfChanged?: boolean } = {}) {
   for (const [, tab] of workspace.tabs.entries()) {
     if (tab.documentPath === path) {
       const platform = getPlatform();
+      const wasDirty = tab.doc.dirty;
+      const overtaken = () => (!wasDirty && tab.doc.dirty) || isCollabPath(path);
       try {
         const content = await platform.readFile(path);
         if (!content) {
           return;
         }
         await loadFormats();
+        // Everything below is synchronous except the format parse, which checks again after it.
+        if (overtaken()) {
+          return;
+        }
         if (formatForPath(path)) {
           const { document, frontmatter } = await parseSourceForPath(path, content);
+          if (overtaken()) {
+            return;
+          }
+          if (
+            opts.onlyIfChanged &&
+            deepEqual(document, tab.doc.document) &&
+            deepEqual(frontmatter, tab.doc.content.frontmatter)
+          ) {
+            return;
+          }
           tab.doc.document = document;
           tab.doc.content.frontmatter = frontmatter;
         } else if (path.endsWith(".json")) {
           // The file changed under the tab, so its layout is whatever the new text says.
           const parsed = parseJsonDocument(content);
-          tab.doc.document = parsed.document as JxMutableNode;
           tab.doc.layout = parsed.layout;
+          if (opts.onlyIfChanged && deepEqual(parsed.document, tab.doc.document)) {
+            return;
+          }
+          tab.doc.document = parsed.document as JxMutableNode;
         }
         tab.doc.dirty = false;
       } catch (error) {