@jxsuite/studio 10.1.0 → 10.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "10.1.0",
+  "version": "10.3.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -60,16 +60,16 @@
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^4.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^3.0.0",
-    "@jxsuite/ai": "^0.41.2",
+    "@jxsuite/ai": "^0.42.0",
     "@jxsuite/collab": "^0.11.4",
-    "@jxsuite/create": "^1.5.1",
+    "@jxsuite/create": "^1.5.2",
     "@jxsuite/formulas": "^0.0.26",
     "@jxsuite/markup": "^1.0.2",
-    "@jxsuite/protocol": "^6.1.0",
+    "@jxsuite/protocol": "^6.2.0",
     "@jxsuite/runtime": "^6.0.1",
     "@jxsuite/schema": "^5.0.0",
     "@jxsuite/site": "^2.2.2",
-    "@jxsuite/ui": "^0.8.2",
+    "@jxsuite/ui": "^0.9.0",
     "@vue/reactivity": "3.5.44",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/browse/library-model.ts

@@ -200,44 +200,64 @@ export function entryCollectionOf(path: string, pageExtensions?: readonly string
  */
 const SKIP_DIRS = new Set(["node_modules", ".git", ".jx", ".cache"]);
 
+/** What every branch of one scan shares. */
+interface ScanRun {
+  platform: Pick<StudioPlatform, "listDirectory">;
+  out: LibraryFile[];
+  failures: ScanFailure[];
+  i18n: ResolvedI18n | null;
+  pageExtensions: readonly string[] | undefined;
+  /**
+   * Every directory some branch has claimed, the roots included. A collection may live in an
+   * ANCESTOR of the project (a site inside the vault it publishes declares `source: "../.."`), and
+   * that walk reaches the project's own directories under the same project-relative paths the roots
+   * walk: every page was listed twice. A directory is walked by whichever branch claims it first.
+   */
+  claimed: Set<string>;
+}
+
+/**
+ * The project root as a listing names it from outside: `""` (relative to itself) or `"."`. A walk
+ * from an ancestor stops there; the project's own directories are roots of the scan already, and
+ * the rest of the root (`dist/`, `scripts/`) holds no collection's entries.
+ */
+function isProjectRoot(path: string): boolean {
+  const normalized = normalizeDir(path);
+  return normalized === "" || normalized === ".";
+}
+
 /**
  * Walk one directory tree, collecting files and recording — never swallowing — what it could not
  * read. A failure at depth is reported against the directory that failed, not the root, so the
  * Problem names the path the author can act on.
  */
-async function walk(
-  dir: string,
-  platform: Pick<StudioPlatform, "listDirectory">,
-  out: LibraryFile[],
-  failures: ScanFailure[],
-  i18n: ResolvedI18n | null,
-  optional = false,
-  pageExtensions?: readonly string[],
-): Promise<void> {
+async function walk(dir: string, run: ScanRun, optional = false): Promise<void> {
   let entries: DirEntry[];
   try {
     // Noted: the Library walks every media directory, so it is where most versions are learned.
-    entries = await notedListing(() => platform.listDirectory(dir));
+    entries = await notedListing(() => run.platform.listDirectory(dir));
   } catch (error) {
     // A declared collection's folder that does not exist yet is an empty collection, not a fault.
     if (!optional) {
-      failures.push({ dir, error: errorMessage(error) });
+      run.failures.push({ dir, error: errorMessage(error) });
     }
     return;
   }
   const subdirectories: string[] = [];
   for (const entry of entries) {
     if (entry.type === "directory") {
-      if (!SKIP_DIRS.has(entry.name)) {
+      const key = normalizeDir(entry.path);
+      if (!SKIP_DIRS.has(entry.name) && !isProjectRoot(key) && !run.claimed.has(key)) {
+        run.claimed.add(key);
         subdirectories.push(entry.path);
       }
       continue;
     }
     const ext = extensionOf(entry.name);
-    out.push({
-      collection: entryCollectionOf(entry.path, pageExtensions),
+    run.out.push({
+      collection: entryCollectionOf(entry.path, run.pageExtensions),
       ext,
-      locale: servedLocaleOfPath(entry.path, i18n) ?? undefined,
+      locale: servedLocaleOfPath(entry.path, run.i18n) ?? undefined,
       media: MEDIA_EXTENSIONS.has(ext),
       modified: entry.modified,
       name: entry.name,
@@ -248,9 +268,7 @@ async function walk(
   }
   // Siblings in parallel, depth serialized per branch: the platform counts every call as in-flight,
   // So `probe.idle()` already knows the scan is running without the Library declaring a source.
-  await Promise.all(
-    subdirectories.map((sub) => walk(sub, platform, out, failures, i18n, false, pageExtensions)),
-  );
+  await Promise.all(subdirectories.map((sub) => walk(sub, run)));
 }
 
 /**
@@ -265,16 +283,31 @@ export async function scanLibrary(
   optional: ReadonlySet<string> = new Set(),
   pageExtensions?: readonly string[],
 ): Promise<LibraryScan> {
-  const files: LibraryFile[] = [];
-  const failures: ScanFailure[] = [];
   // Resolved ONCE for the whole walk. `resolveI18n` canonicalizes every declared tag through
   // `Intl.Locale`, and a project with 300 pages would otherwise pay for that per file.
   const { i18n } = resolveI18n(projectState?.projectConfig ?? {});
+  const run: ScanRun = {
+    claimed: new Set(),
+    failures: [],
+    i18n,
+    out: [],
+    pageExtensions,
+    platform,
+  };
+  /* Every root is claimed before any walk descends: `map` runs to the end synchronously, and a walk
+     claims its subdirectories only after its own listing has been awaited. A root named twice is
+     walked once. */
   await Promise.all(
-    dirs.map((dir) =>
-      walk(dir, platform, files, failures, i18n, optional.has(dir), pageExtensions),
-    ),
+    dirs.map((dir) => {
+      const key = normalizeDir(dir);
+      if (run.claimed.has(key)) {
+        return Promise.resolve();
+      }
+      run.claimed.add(key);
+      return walk(dir, run, optional.has(dir));
+    }),
   );
+  const { failures, out: files } = run;
   files.sort((a, b) => a.path.localeCompare(b.path));
   return { failures, files };
 }

package/src/browse/library-pane.ts

@@ -44,7 +44,16 @@ import { getPlatform } from "../platform";
 import { projectState, renderOnly } from "../store";
 import { invalidateUsages } from "../services/references";
 import { confirmFileDelete, renamePromptMessage } from "../files/file-ops";
-import { openFileInTab } from "../files/files";
+import { duplicateAsset } from "../files/media-upload";
+import { renameRefusal } from "../files/new-file-name";
+import {
+  commitRename,
+  listRenameSiblings,
+  notifyMoveOutcome,
+  openFileInTab,
+  parentDirOf,
+  renameStatus,
+} from "../files/files";
 import { runActiveReported } from "../commands/run-reported";
 import {
   PAGES_COLLECTION,
@@ -680,9 +689,15 @@ function showLibraryContextMenu(path: string, x: number, y: number): void {
         },
         { dividerAbove: true },
       ),
-      row("duplicate", "Duplicate", () => {
-        void duplicateLibraryFile(file);
-      }),
+      /* Not offered without raw bytes, as in the Media workspace (studio.md §9.3): a copy made as
+         text would be a damaged copy of anything that is not UTF-8. */
+      ...(getPlatform().readFileBytes !== undefined
+        ? [
+            row("duplicate", "Duplicate", () => {
+              void duplicateLibraryFile(file);
+            }),
+          ]
+        : []),
       row(
         "delete",
         "Delete",
@@ -696,17 +711,23 @@ function showLibraryContextMenu(path: string, x: number, y: number): void {
 }
 
 /**
- * The rename dialog — the same copy, from the same helper, as the Files panel's.
+ * The rename dialog: the same copy, the same refusals and the same commit as the Files panel's.
  *
- * A rename here rewrites references exactly as one in the sidebar does, and two dialogs that
- * disagreed about that is the divergence the shared helper exists to prevent.
+ * A rename here rewrites references exactly as one in the sidebar does and replaces a destination
+ * just as silently, and an open tab has to follow the file. Two flows that disagreed about any of
+ * that is the divergence the shared helpers exist to prevent.
  */
 async function renameLibraryFile(file: LibraryFile) {
+  const path = file.path.replaceAll("\\", "/");
+  const taken = await listRenameSiblings(path, SOURCE);
+  if (taken === null) {
+    return;
+  }
   const message = await renamePromptMessage(file.path);
   const prompt: PromptDialogOptions = {
     confirmLabel: "Rename",
     select: "stem",
-    validate: (value) => (value.trim() ? "" : "Enter a file name."),
+    validate: (value) => renameRefusal(path, value, taken),
     value: file.name,
   };
   if (message !== undefined) {
@@ -716,15 +737,13 @@ async function renameLibraryFile(file: LibraryFile) {
   if (!newName || newName === file.name) {
     return;
   }
-  const normalized = file.path.replaceAll("\\", "/");
-  const parent = normalized.includes("/") ? normalized.slice(0, normalized.lastIndexOf("/")) : ".";
+  const parent = parentDirOf(path);
   const newPath = parent === "." ? newName : `${parent}/${newName}`;
   try {
-    await getPlatform().renameFile(file.path, newPath);
-    invalidateUsages();
+    const report = await commitRename(path, newPath);
     invalidateLibrary();
     await loadLibrary();
-    notify.success(`Renamed to ${newName}`);
+    notifyMoveOutcome(renameStatus(newName, report), report, newPath);
   } catch (error) {
     notify.error(`Could not rename ${file.name}.`, {
       detail: errorMessage(error),
@@ -734,25 +753,21 @@ async function renameLibraryFile(file: LibraryFile) {
   }
 }
 
+/**
+ * Copy the file beside itself, through the one copy Studio has (`duplicateAsset`): byte for byte,
+ * under a name nothing else has. A file listed here is usually text, but not provably so. A
+ * collection that declares no format lists whatever its folder holds, and a declared Markdown
+ * collection can hold a Latin-1 entry, which a read as UTF-8 would have damaged. `document` is what
+ * keeps a copy that IS text openable on a backend that files an upload as a binary.
+ */
 async function duplicateLibraryFile(file: LibraryFile) {
-  const normalized = file.path.replaceAll("\\", "/");
-  const parent = normalized.includes("/") ? normalized.slice(0, normalized.lastIndexOf("/")) : ".";
-  const stem = file.name.replace(/(\.[^.]+)$/, "");
-  const copyName = `${stem}-copy${file.ext || ""}`;
-  const copyPath = parent === "." ? copyName : `${parent}/${copyName}`;
-  try {
-    const platform = getPlatform();
-    const content = await platform.readFile(file.path);
-    await platform.writeFile(copyPath, content);
+  const copy = await duplicateAsset(file.path.replaceAll("\\", "/"), {
+    document: true,
+    source: SOURCE,
+  });
+  if (copy !== null) {
     invalidateLibrary();
     await loadLibrary();
-    notify.success(`Duplicated as ${copyName}`);
-  } catch (error) {
-    notify.error(`Could not duplicate ${file.name}.`, {
-      detail: errorMessage(error),
-      path: file.path,
-      source: SOURCE,
-    });
   }
 }
 

package/src/browse/library-preview.ts

@@ -34,7 +34,7 @@ import { assetContextFor, hostAssetDeclarations, resolveAssetRef } from "../canv
 import { canvasBaseOrigin, documentBase, hostResolveToken } from "../canvas/canvas-origin";
 import { npmModuleUrl } from "../canvas/npm-modules";
 import { projectState } from "../store";
-import { assetVersionsSnapshot } from "../files/asset-versions";
+import { assetVersionsSnapshot, localRevisionsSnapshot } from "../files/asset-versions";
 import { componentRegistry } from "../files/components";
 import { getPlatform } from "../platform";
 import { loadFormats, formatForPath } from "../format/format-host";
@@ -184,7 +184,11 @@ async function renderDocument(
      `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() };
+  const assets = context && {
+    ...context,
+    revisions: localRevisionsSnapshot(),
+    versions: assetVersionsSnapshot(),
+  };
   setCanvasAssetResolver((value) => resolveAssetRef(value, assets));
   try {
     const element = renderNode(document_, scope);

package/src/canvas/asset-refs.ts

@@ -18,7 +18,11 @@ 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 {
+  assetVersionsSnapshot,
+  hasLocalRevisions,
+  localRevisionsSnapshot,
+} from "../files/asset-versions";
 import { activeTab } from "../workspace/workspace";
 import type { AssetContext } from "./asset-resolve";
 import type { ContentSectionEntry } from "../types";
@@ -59,9 +63,10 @@ export function assetContextFor(
     projectState?.projectConfig?.content as Record<string, ContentSectionEntry> | undefined,
     projectLocales(),
   );
-  /* In site space the mount is the ONLY thing that needs doing, so no mount means no work. In repo
+  /* In site space the mount is the ONLY thing that needs doing, so no mount means no work — unless
+     Studio has just written a file in place, whose references need its repaint key (§3.4). In repo
      space every reference needs rebasing, mount or not. */
-  if (space === "site" && !mount) {
+  if (space === "site" && !mount && !hasLocalRevisions()) {
     return null;
   }
   const context: AssetContext = {
@@ -116,7 +121,11 @@ export function previewAssetSrcFor(value: string, documentPath: string | null |
     return value;
   }
   const ctx = assetContextFor(documentPath, hostAssetDeclarations());
-  const versioned = ctx && { ...ctx, versions: assetVersionsSnapshot() };
+  const versioned = ctx && {
+    ...ctx,
+    revisions: localRevisionsSnapshot(),
+    versions: assetVersionsSnapshot(),
+  };
   return loopbackAssetSrc(resolveAssetRef(value, versioned) ?? value);
 }
 

package/src/canvas/asset-resolve.ts

@@ -99,6 +99,11 @@ export interface AssetContext {
    * unversioned, exactly as before versions existed.
    */
   versions?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Studio's own repaint keys by normalized project path, appended as `?r=<key>` in BOTH spaces
+   * (see {@link withRevision}). A path appears only after Studio itself wrote its bytes.
+   */
+  revisions?: Readonly<Record<string, string>> | undefined;
 }
 
 /**
@@ -122,7 +127,27 @@ export interface AssetContext {
  * @returns {string} The versioned URL
  */
 export function withVersion(url: string, version: string | undefined): string {
-  if (!isString(version) || version === "") {
+  return withParam(url, "v", version);
+}
+
+/**
+ * `url` with `r=<revision>` in its query: Studio's own repaint key for a path it has just written
+ * (specs/studio.md §3.4). Same placement rules as {@link withVersion}, and a different name on
+ * purpose: `v` is a version the HOST issued and may answer immutably, and this is a token Studio
+ * minted, which never may be. It exists because an unversioned URL is byte-identical before and
+ * after an in-place overwrite, so without it a decoded `<img>` keeps the old pixels.
+ *
+ * @param {string} url - A URL, absolute or relative
+ * @param {string | undefined} revision - The path's repaint key, if Studio holds one
+ * @returns {string} The URL carrying the key
+ */
+export function withRevision(url: string, revision?: string): string {
+  return withParam(url, "r", revision);
+}
+
+/** `url` with one `name=value` query parameter, replacing every `name` it already had. */
+function withParam(url: string, name: "v" | "r", value: string | undefined): string {
+  if (!isString(value) || value === "") {
     return url;
   }
   const hashAt = url.indexOf("#");
@@ -131,23 +156,23 @@ export function withVersion(url: string, version: string | undefined): string {
   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)}`);
+  const kept = parts.filter((part) => part !== "" && !namesKey(part, name));
+  kept.push(`${name}=${encodeURIComponent(value)}`);
   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 {
+/** Whether one `key[=value]` query part's key decodes to `name`, the way `URLSearchParams` reads it. */
+function namesKey(part: string, name: string): boolean {
   const eq = part.indexOf("=");
   const key = eq === -1 ? part : part.slice(0, eq);
-  if (key === "v") {
+  if (key === name) {
     return true;
   }
   if (!key.includes("%")) {
     return false;
   }
   try {
-    return decodeURIComponent(key) === "v";
+    return decodeURIComponent(key) === name;
   } catch {
     // A malformed escape decodes to itself under `URLSearchParams`, which is never a bare `v`.
     return false;
@@ -292,13 +317,31 @@ export function resolveAssetRef(value: string, ctx: AssetContext | null): string
       return null;
     }
     const { suffix } = splitRefSuffix(value);
-    return withVersion(
-      `${ctx.fileBaseUrl}${encodeProjectPath(path)}${suffix}`,
-      ownVersion(ctx.versions, path),
+    return withRevision(
+      withVersion(
+        `${ctx.fileBaseUrl}${encodeProjectPath(path)}${suffix}`,
+        ownVersion(ctx.versions, path),
+      ),
+      ownVersion(ctx.revisions, path),
     );
   }
   const [mount] = ctx.mounts;
-  return mount ? mountedRefFor(value, ctx.documentDir, mount) : null;
+  const mounted = mount ? mountedRefFor(value, ctx.documentDir, mount) : null;
+  /* In site space a reference is otherwise left as written, which after an in-place overwrite is
+     the same string naming new bytes. So a path Studio has just written gets its repaint key here
+     too, on the mounted URL or on the reference as written. The lane lookup only runs when Studio
+     holds a key at all, which on most sessions is never. */
+  const revision = siteRevision(value, ctx);
+  return revision === undefined ? mounted : withRevision(mounted ?? value, revision);
+}
+
+/** The repaint key for the project file a site-space reference names, or undefined. */
+function siteRevision(value: string, ctx: AssetContext): string | undefined {
+  if (!ctx.revisions || Object.keys(ctx.revisions).length === 0) {
+    return undefined;
+  }
+  const path = projectPathForRef(value, ctx.documentDir, ctx.mounts, ctx.lanes);
+  return path === null ? undefined : ownVersion(ctx.revisions, path);
 }
 
 /**

package/src/canvas/canvas-render.ts

@@ -51,6 +51,12 @@ import { parseJsonDocument, serializeJson } from "@jxsuite/schema/json-layout";
 import { detachGridPanel, gridPanelMounted, renderGridMode } from "../grid/grid-panel";
 import { detachEntryPane, entryPaneMounted, renderEntryMode } from "../content/entry-editor";
 import { detachMediaPane, mediaPaneMounted, renderMediaMode } from "../media/media-pane";
+import {
+  IMAGE_MODE,
+  detachImageEditor,
+  imageEditorMounted,
+  renderImageMode,
+} from "../media/image-editor";
 import {
   detachVariablesView,
   renderVariablesMode,
@@ -629,6 +635,7 @@ function resetCanvasView(surface: CanvasSurface) {
   detachEntryPane(paneId);
   detachWritingBanner(paneId);
   detachMediaPane(paneId);
+  detachImageEditor(paneId);
   detachVariablesView(paneId);
   detachWorkspaceHome(paneId);
   disposeSourceCollab(surface);
@@ -1182,6 +1189,11 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
+  // Image-editor fast-path, same shape: a gesture repaints the editor through its own effect.
+  if (canvasMode === IMAGE_MODE && imageEditorMounted(surface.paneId, tab) && !modeChanged) {
+    return;
+  }
+
   // Variables fast-path, same shape: the view follows the document through its own effect.
   if (
     canvasMode === PROJECT_VARIABLES_VIEW &&
@@ -1267,6 +1279,9 @@ function renderCanvasImpl(surface: CanvasSurface) {
     // And for the media viewer, whose effect scope subscribes to the tab's path
     detachMediaPane(surface.paneId);
 
+    // And for the Image editor, whose effect scope subscribes to the tab's recipe
+    detachImageEditor(surface.paneId);
+
     // And for the Variables view, whose effect scope subscribes to the document's style
     detachVariablesView(surface.paneId);
 
@@ -1404,6 +1419,15 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
+  /* Image mode: the media viewer's editing sibling (`media/image-editor.ts`, §9.5). Same pattern;
+     its recipe lives with the tab, so a teardown here loses no unsaved work. */
+  if (canvasMode === IMAGE_MODE) {
+    canvasWrap.style.padding = "0";
+    canvasWrap.style.display = "block";
+    renderImageMode(surface, tab);
+    return;
+  }
+
   /* The Styles workspace's Variables view: `project.json`'s CSS custom properties, edited in a
      form (`style/variables-view.ts`). Like a home, it writes nothing onto the stage: its own style
      block fills it (`surfaces/styles-variables.json`). */
@@ -2003,6 +2027,7 @@ setSurfaceTeardown((surface) => {
   detachGridPanel(surface.paneId);
   detachEntryPane(surface.paneId);
   detachMediaPane(surface.paneId);
+  detachImageEditor(surface.paneId);
   detachVariablesView(surface.paneId);
   detachWorkspaceHome(surface.paneId);
   detachWritingBanner(surface.paneId);

package/src/canvas/iframe-entry.ts

@@ -145,6 +145,8 @@ const FILE_DRAG_SRC: DragSrcKind = { type: "block" };
  * every reference unversioned — the behaviour from before versions existed.
  */
 let assetVersions: Readonly<Record<string, string>> = {};
+/** Studio's repaint keys, posted beside the versions in the same message (studio.md §3.4). */
+let assetRevisions: 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
@@ -154,7 +156,7 @@ 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;
+  return assets ? { ...assets, revisions: assetRevisions, versions: assetVersions } : null;
 }
 
 /**
@@ -307,6 +309,7 @@ export function startCanvasIframe(opts: {
   const { channel, container } = opts;
   // A frame starts knowing no versions; the host posts the map before the first render.
   assetVersions = {};
+  assetRevisions = {};
   liveAssets = null;
   let handle: RenderHandle | null = null;
   // Disposer for the live render's dataScope re-post effect (see the render handler); stopped
@@ -923,6 +926,7 @@ export function startCanvasIframe(opts: {
          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;
+      assetRevisions = msg.revisions ?? {};
       const assets = versionedAssets(liveAssets);
       if (assets) {
         setCanvasAssetResolver((value) => resolveAssetRef(value, assets));

package/src/canvas/iframe-host.ts

@@ -50,7 +50,11 @@ import { isNodeObject } from "@jxsuite/schema/guards";
 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 {
+  assetVersionsEpoch,
+  assetVersionsSnapshot,
+  localRevisionsSnapshot,
+} from "../files/asset-versions";
 import type {
   ApplyFormatIntent,
   CanvasMode,
@@ -150,6 +154,8 @@ export interface HostState {
    * changes identity only when a media version moves.
    */
   postedVersions: Readonly<Record<string, string>> | null;
+  /** The repaint-key snapshot posted beside {@link HostState.postedVersions}, compared the same way. */
+  postedRevisions: Readonly<Record<string, string>> | null;
   overlay: OverlayLayer;
   /** Primary selected path (mirrors `session.selection`'s last entry), for hover de-dupe. */
   selectionPath: (string | number)[] | null;
@@ -1606,15 +1612,17 @@ function syncAssetVersions(host: HostState): void {
     return;
   }
   const versions = assetVersionsSnapshot();
-  if (versions === host.postedVersions) {
+  const revisions = localRevisionsSnapshot();
+  if (versions === host.postedVersions && revisions === host.postedRevisions) {
     return;
   }
-  if (host.postedVersions === null && Object.keys(versions).length === 0) {
-    host.postedVersions = versions;
+  const first = host.postedVersions === null;
+  host.postedVersions = versions;
+  host.postedRevisions = revisions;
+  if (first && Object.keys(versions).length === 0 && Object.keys(revisions).length === 0) {
     return;
   }
-  host.postedVersions = versions;
-  host.channel.post({ kind: "assetVersions", versions });
+  host.channel.post({ kind: "assetVersions", revisions, versions });
 }
 
 let assetVersionsWatchStarted = false;
@@ -1990,6 +1998,7 @@ function ensureHost(canvasEl: HTMLElement): HostState {
     panReqId: -1,
     pending: null,
     postedVersions: null,
+    postedRevisions: null,
     idle: null,
     pendingEnterEdit: null,
     pendingMeasures: new Map(),
@@ -2143,6 +2152,7 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
          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;
+      state.postedRevisions = null;
       syncAssetVersions(state);
       if (state.pending) {
         state.channel.post(state.pending);

package/src/canvas/iframe-protocol.ts

@@ -164,7 +164,15 @@ export type ParentToIframe =
    * 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>> }
+  | {
+      kind: "assetVersions";
+      versions: Readonly<Record<string, string>>;
+      /**
+       * Studio's own repaint keys (studio.md §3.4), for paths Studio itself just wrote in place.
+       * Optional so a host that predates them still speaks the message; absent reads as none.
+       */
+      revisions?: 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/commands/context.ts

@@ -69,6 +69,7 @@ export type EditorKind =
   | "tokens"
   | "entry"
   | "media"
+  | "image"
   | "home"
   | "none";
 
@@ -107,10 +108,14 @@ const EDITOR_KIND_BY_MODE = new Map<string, EditorKind>([
   ["content-home", "home"],
   ["media-home", "home"],
   ["publish-home", "home"],
+  ["settings-home", "home"],
   /* The Media viewer — `media/media-pane.ts`. An image, a video, a font specimen: files the studio
      can SHOW but has no document model for, which is why clicking one used to end in "No format
      class imported for …", advice that means nothing about a PNG. */
   ["media", "media"],
+  /* The Image editor — `media/image-editor.ts`'s IMAGE_MODE, the media viewer's editing sibling
+     (§9.5). A recipe over one image: nothing to paste into, so not the Canvas key scope. */
+  ["image", "image"],
   ["preview", "canvas"],
   ["source", "code"],
   ["stylebook", "config"],
@@ -142,6 +147,7 @@ export const EDITOR_KIND_LABELS: Readonly<Record<EditorKind, string>> = {
   entry: "Entry",
   grid: "Grid",
   home: "Home",
+  image: "Image",
   media: "Media",
   none: "None",
   tokens: "Variables",