@jxsuite/studio 5.5.0 → 5.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -61,12 +61,12 @@
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^4.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^3.0.0",
-    "@jxsuite/ai": "^0.39.0",
-    "@jxsuite/collab": "^0.10.0",
+    "@jxsuite/ai": "^0.39.1",
+    "@jxsuite/collab": "^0.11.0",
     "@jxsuite/create": "^1.3.12",
     "@jxsuite/formulas": "^0.0.19",
     "@jxsuite/markup": "^0.4.11",
-    "@jxsuite/protocol": "^2.5.0",
+    "@jxsuite/protocol": "^2.6.0",
     "@jxsuite/runtime": "^4.0.2",
     "@jxsuite/schema": "^2.3.0",
     "@jxsuite/site": "^2.0.2",
@@ -76,7 +76,7 @@
     "ajv-formats": "^3.0.1",
     "lit-html": "^3.3.3",
     "monaco-editor": "^0.57.0",
-    "tabulator-tables": "^6.5.3",
+    "tabulator-tables": "^6.6.0",
     "yaml": "^2.9.1"
   },
   "devDependencies": {

package/src/account/action-flow.ts

@@ -0,0 +1,294 @@
+/// <reference lib="dom" />
+/**
+ * Action-flow.ts — what Studio does when the backend refuses something and offers what to do.
+ *
+ * A backend answers an action it will not allow yet with `action-required` (desktop.md §10.4): its
+ * own heading, its own sentence, the actions it offers and what to do once one is done. Studio does
+ * not know why — a role, a policy, a plan, a quota — and does not need to. This module shows the
+ * refusal in one dialog, runs the chosen action through `platform.performAction`, and follows the
+ * backend's `retry` hint. `surfaces/dialog.ts` draws each phase; every word about the refusal
+ * itself is the backend's, and the few this module supplies ("Not now", "Waiting…") are about the
+ * dialog.
+ *
+ * **One dialog at a time.** A refused project open is a burst — `activate`, `project-info`, a
+ * directory listing — and every one of them reports. Callers that ask while a dialog is up join
+ * it.
+ *
+ * **Declining is remembered for the page.** The reports that arrive by themselves
+ * ({@link wireActionReports}) stop offering once the user has said "Not now", because a session
+ * whose every request is refused would otherwise reopen the dialog on each one. An action the user
+ * takes on purpose — a commit, a New Project — still asks, because that is a new question.
+ *
+ * @docs studio/interface/welcome-screen
+ */
+
+import { hydrateAccountStatus, takeToastNotices } from "../account-status";
+import { getPlatform, hasPlatform } from "../platform";
+import { platformErrorInfo } from "../platform-errors";
+import { notify } from "../services/notify";
+import { resetModelCache } from "../services/ai-models";
+import { openDialogSurface } from "../surfaces/dialog";
+import { layerHost } from "../ui/layers";
+import { onActionRequired } from "./action-required";
+import type { ActionRequiredReport } from "./action-required";
+import type { ActionOutcome, OfferedAction, RetryHint } from "../types";
+
+/** A refusal to offer: what the backend offered, in its own words. */
+export interface ActionPrompt {
+  actions: OfferedAction[];
+  heading?: string | undefined;
+  detail?: string | undefined;
+  retry?: RetryHint | undefined;
+}
+
+/** Whether this platform can perform an offered action at all. */
+export function canPerformActions(): boolean {
+  return hasPlatform() && typeof getPlatform().performAction === "function";
+}
+
+/** The action a surface leads with — the one marked primary, else the first — and one other. */
+export function leadingActions(
+  actions: readonly OfferedAction[],
+): { lead: OfferedAction; other?: OfferedAction } | null {
+  const lead = actions.find((action) => action.primary) ?? actions[0];
+  if (!lead) {
+    return null;
+  }
+  const other = actions.find((action) => action !== lead);
+  return other ? { lead, other } : { lead };
+}
+
+/** The dialog currently up, joined by every caller that asks while it is. */
+let running: Promise<boolean> | null = null;
+
+/** Set once the user declines; silences the reports that arrive on their own until reload. */
+let declined = false;
+
+/**
+ * Offer a refusal's actions, and resolve whether one of them is now done.
+ *
+ * Resolves false at once on a platform that cannot perform actions, or for a refusal that offers
+ * nothing, and when the user declines or closes the dialog. Never rejects: an action that failed is
+ * drawn in the dialog, which stays up so the user can try again or give up.
+ */
+export function promptAction(prompt: ActionPrompt): Promise<boolean> {
+  const leading = leadingActions(prompt.actions);
+  if (!canPerformActions() || !leading) {
+    return Promise.resolve(false);
+  }
+  running ??= offer(prompt, leading).finally(() => {
+    running = null;
+  });
+  return running;
+}
+
+/**
+ * A caught error, offered when it is an `action-required` refusal with something to offer. Resolves
+ * whether the caller should now try again: false for any other error (nothing was offered) and for
+ * an offer declined.
+ */
+export async function actIfRequired(error: unknown): Promise<boolean> {
+  const info = platformErrorInfo(error);
+  if (info.code !== "action-required" || !info.actions?.length) {
+    return false;
+  }
+  return promptAction({
+    actions: info.actions,
+    detail: error instanceof Error ? error.message : undefined,
+    heading: info.heading,
+    retry: info.retry,
+  });
+}
+
+/**
+ * Everything a done action may have changed, re-read: the account rows and Start-pane notices read
+ * the status cache, and the assistant's gate reads the models probe. Then whatever the platform now
+ * wants announced is announced — in its words, not Studio's.
+ */
+async function settleDone(): Promise<void> {
+  resetModelCache();
+  await hydrateAccountStatus();
+  showToastNotices();
+}
+
+/** Run one dialog to its end. */
+function offer(
+  prompt: ActionPrompt,
+  leading: { lead: OfferedAction; other?: OfferedAction },
+): Promise<boolean> {
+  const message = prompt.detail ?? "This needs one more step first.";
+  return new Promise<boolean>((resolve) => {
+    let phase: "offer" | "waiting" | "done" = "offer";
+    const finish = (done: boolean) => {
+      if (phase === "done") {
+        return;
+      }
+      phase = "done";
+      handle.close();
+      resolve(done);
+    };
+    const offerAgain = (sentence: string) => {
+      phase = "offer";
+      handle.update({
+        cancelLabel: "Not now",
+        confirmLabel: leading.lead.label,
+        message: sentence,
+        secondaryLabel: leading.other?.label ?? "",
+      });
+    };
+
+    const begin = (action: OfferedAction) => {
+      if (phase !== "offer") {
+        return;
+      }
+      phase = "waiting";
+      /* Called straight from the click, with nothing awaited first: `performAction` opens its
+         window synchronously, and only code still inside the click may. */
+      let flow: Promise<ActionOutcome | null>;
+      try {
+        flow = getPlatform().performAction!(action);
+      } catch (error) {
+        offerAgain(error instanceof Error ? error.message : String(error));
+        return;
+      }
+      handle.update({
+        cancelLabel: "Cancel",
+        confirmLabel: "Waiting…",
+        message: "Finish in the window that opened. This closes by itself once it is done.",
+        secondaryLabel: "",
+      });
+      void flow.then(
+        async (outcome) => {
+          /* A done action is re-read even when the dialog is already gone — the user may have
+             dismissed the waiting dialog and finished in the window anyway, and the account must
+             not go on saying otherwise. */
+          if (outcome?.status === "done") {
+            await settleDone();
+            finish(true);
+            return;
+          }
+          if (phase !== "waiting" || !outcome || outcome.status === "redirect") {
+            // Dismissed meanwhile, or the page is navigating to the action: nothing to draw.
+            return;
+          }
+          // Closed without saying: the account may have changed anyway, so re-read it, and offer again.
+          void hydrateAccountStatus();
+          offerAgain(message);
+        },
+        (error: unknown) => {
+          if (phase === "waiting") {
+            offerAgain(error instanceof Error ? error.message : String(error));
+          }
+        },
+      );
+    };
+
+    const { lead, other } = leading;
+    const handle = openDialogSurface({
+      cancelLabel: "Not now",
+      confirmLabel: lead.label,
+      headline: prompt.heading ?? "One more step",
+      layer: layerHost("dialog"),
+      message,
+      onCancel: () => {
+        declined = true;
+        finish(false);
+      },
+      onClosed: () => {
+        finish(false);
+      },
+      onConfirm: () => {
+        begin(lead);
+      },
+      region: "account/action",
+      ...(other
+        ? {
+            onSecondary: () => {
+              begin(other);
+            },
+            secondaryLabel: other.label,
+          }
+        : {}),
+    });
+  });
+}
+
+/** Follow a done refusal's retry hint: reload a session it broke, or ask for the action again. */
+function afterDone(retry: RetryHint | undefined): void {
+  if (retry === "reload") {
+    location.reload();
+  } else if (retry === "repeat") {
+    notify.info("Done. Run that again now.", { key: "account.action.retry", source: "Account" });
+  }
+}
+
+/**
+ * Offer the actions of every refusal the platform adapter reports by itself — the refusals no
+ * caller asked to handle. Returns the unsubscribe. Called once, at boot.
+ */
+export function wireActionReports(): () => void {
+  return onActionRequired((report: ActionRequiredReport) => {
+    if (declined || running) {
+      return;
+    }
+    void promptAction(report).then((done) => {
+      if (done) {
+        afterDone(report.retry);
+      }
+    });
+  });
+}
+
+/**
+ * Run an action offered outside a refusal — on a Start-pane notice or an account row. Resolves
+ * whether it is done; either way the account status is re-read, because an action is how it
+ * changes. Synchronous up to `performAction`, which opens its window from inside the click.
+ */
+export async function runOfferedAction(action: OfferedAction): Promise<boolean> {
+  if (!canPerformActions()) {
+    return false;
+  }
+  const pending = getPlatform().performAction!(action);
+  let outcome: ActionOutcome | null;
+  try {
+    outcome = await pending;
+  } catch (error) {
+    // A toast, not a Problems entry: it answers the click, and nothing is left standing to fix.
+    notify.error(error instanceof Error ? error.message : String(error), {
+      key: "account.action",
+      source: "Account",
+      tier: "toast",
+    });
+    return false;
+  }
+  if (outcome?.status === "done") {
+    await settleDone();
+    return true;
+  }
+  if (outcome?.status !== "redirect") {
+    await hydrateAccountStatus();
+  }
+  return false;
+}
+
+/**
+ * Show the platform's one-time notices — how an action that left the page ended, or anything else
+ * it wants said once. Called at boot after the account status is read, and after every done
+ * action.
+ */
+export function showToastNotices(): void {
+  for (const notice of takeToastNotices()) {
+    const options = { key: `account.notice.${notice.id}`, source: "Account" };
+    if (notice.level === "warning") {
+      notify.warn(notice.message, options);
+    } else {
+      notify.info(notice.message, options);
+    }
+  }
+}
+
+/** Forget the dialog and the decline — tests only. */
+export function resetActionFlow(): void {
+  running = null;
+  declined = false;
+}

package/src/account/action-required.ts

@@ -0,0 +1,68 @@
+/**
+ * Action-required.ts — the channel a platform adapter raises an `action-required` refusal on.
+ *
+ * A backend refuses the session's own requests with `action-required` (HTTP 403, desktop.md §10.4),
+ * and those requests are made deep inside an adapter by callers that have no business knowing about
+ * access rules: a file read, a directory listing, the boot-time `activate`. Each of them still
+ * throws its ordinary error, and this is the side channel that says, once, "and here is what the
+ * user can do about it" — to the one listener that can offer it (`action-flow.ts`).
+ *
+ * No DOM and no imports beyond types, so an adapter can raise on it from anywhere without pulling
+ * the dialog layer into its module graph.
+ *
+ * **A report raised before anyone listens is kept.** The boot-time `activate` runs as the studio
+ * module evaluates, and its refusal can land before the flow has subscribed; dropping it would be
+ * exactly the silent failure this channel exists to prevent. Only the latest one is kept — they all
+ * say the same thing.
+ */
+
+import type { OfferedAction, RetryHint } from "@jxsuite/protocol";
+
+/** One refusal, in the backend's words. */
+export interface ActionRequiredReport {
+  /** What the backend offers. A report is raised only when it offers something. */
+  actions: OfferedAction[];
+  /** The refusal's heading. */
+  heading?: string;
+  /** The refusal's `detail`. */
+  detail?: string;
+  /** What to do once an action is done. */
+  retry?: RetryHint;
+}
+
+type Listener = (report: ActionRequiredReport) => void;
+
+const listeners = new Set<Listener>();
+
+/** The latest report raised while nobody was listening; delivered to the first subscriber. */
+let pending: ActionRequiredReport | null = null;
+
+/** Raise a refusal. Every listener hears it; with none yet, the first one to subscribe will. */
+export function reportActionRequired(report: ActionRequiredReport): void {
+  if (listeners.size === 0) {
+    pending = report;
+    return;
+  }
+  for (const listener of listeners) {
+    listener(report);
+  }
+}
+
+/** Hear every refusal from now on, and the one raised before this call, if any. */
+export function onActionRequired(listener: Listener): () => void {
+  listeners.add(listener);
+  const missed = pending;
+  pending = null;
+  if (missed) {
+    listener(missed);
+  }
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Drop every listener and any kept report — tests only. */
+export function resetActionReports(): void {
+  listeners.clear();
+  pending = null;
+}

package/src/account-status.ts

@@ -5,7 +5,7 @@
  * "install the GitHub App" when the user has no repository access yet.
  */
 import { getPlatform, hasPlatform } from "./platform";
-import type { AccountStatus } from "./types";
+import type { AccountEntry, AccountNotice, AccountStatus } from "./types";
 
 let cache: AccountStatus | null = null;
 
@@ -62,7 +62,35 @@ export function getRepoAccessLinks(): RepoAccessLinks | null {
   return { manage, ...(cache.appInstallUrl ? { installUrl: cache.appInstallUrl } : {}) };
 }
 
+/** The rows the platform adds to Preferences › Accounts (desktop.md §10.4); none when absent. */
+export function getAccountEntries(): AccountEntry[] {
+  return cache?.entries ?? [];
+}
+
+/** The platform's notices to draw on the Start pane: every one that is not a one-time toast. */
+export function getBannerNotices(): AccountNotice[] {
+  return (cache?.notices ?? []).filter((notice) => notice.display !== "toast");
+}
+
+/** Toast notices already shown, by id, so a repeated hydrate does not announce one twice. */
+const shownToasts = new Set<string>();
+
+/**
+ * The platform's one-time notices not yet shown, marked shown as they are taken. A platform that
+ * keeps sending one after it was shown — before it hears it was seen — does not repeat itself.
+ */
+export function takeToastNotices(): AccountNotice[] {
+  const fresh = (cache?.notices ?? []).filter(
+    (notice) => notice.display === "toast" && !shownToasts.has(notice.id),
+  );
+  for (const notice of fresh) {
+    shownToasts.add(notice.id);
+  }
+  return fresh;
+}
+
 /** Reset seam for tests. */
 export function resetAccountStatus(): void {
   cache = null;
+  shownToasts.clear();
 }

package/src/browse/library-model.ts

@@ -20,6 +20,7 @@
 
 import { MEDIA_EXTENSIONS, extensionOf } from "../files/media-upload";
 import { projectState } from "../store";
+import { notedListing } from "../files/asset-versions";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { resolveI18n, servedLocaleOfPath } from "@jxsuite/schema/locale";
 import type { ResolvedI18n } from "@jxsuite/schema/locale";
@@ -174,7 +175,8 @@ async function walk(
 ): Promise<void> {
   let entries: DirEntry[];
   try {
-    entries = await platform.listDirectory(dir);
+    // Noted: the Library walks every media directory, so it is where most versions are learned.
+    entries = await notedListing(() => platform.listDirectory(dir));
   } catch (error) {
     failures.push({ dir, error: errorMessage(error) });
     return;

package/src/browse/library-preview.ts

@@ -26,6 +26,7 @@ import {
   setSkipServerFunctions,
 } from "@jxsuite/runtime";
 import { assetContextFor, hostAssetDeclarations, resolveAssetRef } from "../canvas/asset-refs";
+import { assetVersionsSnapshot } from "../files/asset-versions";
 import { componentRegistry } from "../files/components";
 import { getPlatform } from "../platform";
 import { loadFormats, formatForPath } from "../format/format-host";
@@ -121,7 +122,7 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
   try {
     const content = await getPlatform().readFile(filePath);
     setSkipServerFunctions(true);
-    const assets = assetContextFor(filePath, hostAssetDeclarations());
+    const context = assetContextFor(filePath, hostAssetDeclarations());
     await loadFormats();
     let document_: JxDocument;
     if (formatForPath(filePath)) {
@@ -134,7 +135,10 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
     /* This render lands in the PARENT document, so an `<img src="/hero.jpg">` inside it resolves
        against `index.html` — which is the shell, not the site. Same hook the canvas installs, same
        context, restored afterwards because the next preview is a different document and a stale
-       `documentDir` would resolve its relative refs against the wrong entry. */
+       `documentDir` would resolve its relative refs against the wrong entry. The version map is
+       read as the render starts, after the reads above: the Library is the many-images screen,
+       and a versioned src is what lets its cards repaint from the browser cache. */
+    const assets = context && { ...context, versions: assetVersionsSnapshot() };
     setCanvasAssetResolver((value) => resolveAssetRef(value, assets));
     try {
       const element = renderNode(document_, scope);

package/src/canvas/asset-refs.ts

@@ -18,6 +18,7 @@ import { contentMountFor, resolveAssetRef } from "./asset-resolve";
 import { documentBase, loopbackAssetSrc } from "./canvas-origin";
 import { getPlatform, hasPlatform } from "../platform";
 import { projectState } from "../store";
+import { assetVersionsSnapshot } from "../files/asset-versions";
 import { activeTab } from "../workspace/workspace";
 import type { AssetContext } from "./asset-resolve";
 import type { ContentSectionEntry } from "../types";
@@ -94,7 +95,8 @@ export function previewAssetSrc(value: string): string {
     return value;
   }
   const ctx = assetContextFor(activeTab.value?.documentPath, hostAssetDeclarations());
-  return loopbackAssetSrc(resolveAssetRef(value, ctx) ?? value);
+  const versioned = ctx && { ...ctx, versions: assetVersionsSnapshot() };
+  return loopbackAssetSrc(resolveAssetRef(value, versioned) ?? value);
 }
 
 /**

package/src/canvas/asset-resolve.ts

@@ -98,6 +98,81 @@ export interface AssetContext {
    * editing servers actually use, and why the two differ.
    */
   lanes: readonly AssetLane[];
+  /**
+   * Content versions by normalized project path, for repo-space URLs (`?v=<version>`, see
+   * {@link withVersion}). Only paths the backend vouches for appear; a path absent here resolves
+   * unversioned, exactly as before versions existed.
+   */
+  versions?: Readonly<Record<string, string>> | undefined;
+}
+
+/**
+ * `url` with `v=<version>` in its query — appended to an existing query, inserted before any
+ * `#fragment`, and replacing every `v` parameter the URL already had. The host reads ONE `v`, and
+ * it decodes the key to find it (`URLSearchParams.get("v")` returns the FIRST match), so when
+ * Studio appends its own, an authored `v` — `?v=2`, `?v`, or a percent-encoded `?%76=…` — is
+ * dropped by its DECODED name rather than left to shadow it.
+ *
+ * With no version the URL comes back EXACTLY as given, authored `v` and all: an unversioned
+ * reference keeps working precisely as it did before versions existed. That is safe because a host
+ * may answer a `v` immutably only when it is a version the host issued, with exactly the bytes it
+ * names (specs/studio.md §3.4), so an authored cache-buster like `?v=2` gets the ordinary
+ * revalidating response. A version that is not a non-empty string is no version.
+ *
+ * The version is opaque and equal versions mean identical bytes, so a host that recognizes it may
+ * answer the URL with an immutable cache lifetime (specs/studio.md §3.4).
+ *
+ * @param {string} url - A URL, absolute or relative
+ * @param {string | undefined} version - The file's content version, if any
+ * @returns {string} The versioned URL
+ */
+export function withVersion(url: string, version: string | undefined): string {
+  if (typeof version !== "string" || version === "") {
+    return url;
+  }
+  const hashAt = url.indexOf("#");
+  const fragment = hashAt === -1 ? "" : url.slice(hashAt);
+  const beforeHash = hashAt === -1 ? url : url.slice(0, hashAt);
+  const queryAt = beforeHash.indexOf("?");
+  const base = queryAt === -1 ? beforeHash : beforeHash.slice(0, queryAt);
+  const parts = queryAt === -1 ? [] : beforeHash.slice(queryAt + 1).split("&");
+  const kept = parts.filter((part) => part !== "" && !namesV(part));
+  kept.push(`v=${encodeURIComponent(version)}`);
+  return `${base}?${kept.join("&")}${fragment}`;
+}
+
+/** Whether one `key[=value]` query part's key decodes to `v`, the way `URLSearchParams` reads it. */
+function namesV(part: string): boolean {
+  const eq = part.indexOf("=");
+  const key = eq === -1 ? part : part.slice(0, eq);
+  if (key === "v") {
+    return true;
+  }
+  if (!key.includes("%")) {
+    return false;
+  }
+  try {
+    return decodeURIComponent(key) === "v";
+  } catch {
+    // A malformed escape decodes to itself under `URLSearchParams`, which is never a bare `v`.
+    return false;
+  }
+}
+
+/**
+ * The version `versions` holds for `path`, or undefined. Own keys only: the map is a plain object
+ * (and a structured clone of one inside the canvas iframe), so a path named `constructor` or
+ * `__proto__` would otherwise read a member of `Object.prototype` as its version.
+ */
+function ownVersion(
+  versions: Readonly<Record<string, string>> | undefined,
+  path: string,
+): string | undefined {
+  if (!versions || !Object.hasOwn(versions, path)) {
+    return undefined;
+  }
+  const version: unknown = versions[path];
+  return typeof version === "string" ? version : undefined;
 }
 
 /**
@@ -221,7 +296,10 @@ export function resolveAssetRef(value: string, ctx: AssetContext | null): string
       return null;
     }
     const { suffix } = splitRefSuffix(value);
-    return `${ctx.fileBaseUrl}${encodeProjectPath(path)}${suffix}`;
+    return withVersion(
+      `${ctx.fileBaseUrl}${encodeProjectPath(path)}${suffix}`,
+      ownVersion(ctx.versions, path),
+    );
   }
   const [mount] = ctx.mounts;
   return mount ? mountedRefFor(value, ctx.documentDir, mount) : null;

package/src/canvas/iframe-entry.ts

@@ -53,8 +53,11 @@ import {
   reapplyStyle,
   redefineElement,
   resetDocumentStyles,
+  setCanvasAssetResolver,
   setResolveToken,
 } from "@jxsuite/runtime";
+import { resolveAssetRef } from "./asset-resolve";
+import type { AssetContext } from "./asset-resolve";
 import { KIT_LOADERS } from "@jxsuite/ui/loaders";
 import type { IframeChannel } from "./iframe-channel";
 import type {
@@ -121,6 +124,25 @@ export function isExternalFileDrag(e: DragEvent): boolean {
  */
 const FILE_DRAG_SRC: DragSrcKind = { type: "block" };
 
+/**
+ * The project's media versions, as the host last posted them (`assetVersions`). Module-level: one
+ * frame per realm, and the map describes the PROJECT, not any one render. Folded into every
+ * render's asset context by {@link versionedAssets}; empty until the host sends one, which resolves
+ * every reference unversioned — the behaviour from before versions existed.
+ */
+let assetVersions: Readonly<Record<string, string>> = {};
+/**
+ * The asset context of the newest render accepted, WITHOUT versions — kept so a later
+ * `assetVersions` can rebuild the resolver around the new map. Null when that render resolves
+ * nothing.
+ */
+let liveAssets: AssetContext | null = null;
+
+/** A render's asset context with the current versions folded in, or null for no resolution. */
+function versionedAssets(assets: AssetContext | null): AssetContext | null {
+  return assets ? { ...assets, versions: assetVersions } : null;
+}
+
 /**
  * Describe the node under a file drag for the parent: its path, rect, and resolved tag. The tag
  * comes from the SHADOW DOC (the document's own `tagName`) when the path resolves there, because
@@ -240,6 +262,9 @@ export function startCanvasIframe(opts: {
   container: HTMLElement;
 }): () => void {
   const { channel, container } = opts;
+  // A frame starts knowing no versions; the host posts the map before the first render.
+  assetVersions = {};
+  liveAssets = null;
   let handle: RenderHandle | null = null;
   // Disposer for the live render's dataScope re-post effect (see the render handler); stopped
   // Alongside the handle so a superseded render's refs can't keep posting.
@@ -869,6 +894,17 @@ export function startCanvasIframe(opts: {
       stopAutoScroll();
       return;
     }
+    if (msg.kind === "assetVersions") {
+      /* Replaced wholesale, like the keymap. The resolver the last render installed closed over the
+         old map, and a patch draws through that resolver — so it is rebuilt around the new one
+         here, not left for the next render. */
+      assetVersions = msg.versions;
+      const assets = versionedAssets(liveAssets);
+      if (assets) {
+        setCanvasAssetResolver((value) => resolveAssetRef(value, assets));
+      }
+      return;
+    }
     if (msg.kind === "keymap") {
       // Replaced wholesale, never merged: the host sends the whole live table, so a chord the
       // Author unbound disappears here rather than lingering as a key the canvas still swallows.
@@ -946,6 +982,7 @@ export function startCanvasIframe(opts: {
       stopEditing();
     }
     latestGen = msg.gen;
+    liveAssets = msg.assets ?? null;
     // Adopt the document's caret vocabulary BEFORE rendering: which tags hold a caret depends on
     // The format class, and a `.md` page and a native `.json` component do not agree. Absent means
     // A document with no format, where the studio's own element metadata answers on its own.
@@ -966,7 +1003,7 @@ export function startCanvasIframe(opts: {
            element per render. */
         resetDocumentStyles(container.ownerDocument);
         handle = await renderResolvedDocument({
-          assets: msg.assets ?? null,
+          assets: versionedAssets(msg.assets ?? null),
           container,
           doc: msg.doc as JxDocument,
           docBase: msg.docBase,