@jxsuite/studio 10.2.0 → 10.3.0

package/src/media/media-commands.ts

@@ -6,7 +6,11 @@
  *   arrived, and what a script or the palette runs to ask "what is unused".
  * - `media.upload` shows the Media home and opens its Upload picker.
  * - `media.replace { path }` selects a file and opens its Replace picker: the one overwrite.
+ * - `media.rename { path }` renames a file, through the dialog that counts what will be rewritten.
+ * - `media.duplicate { path }` copies a file to a new name beside it, and selects the copy.
  * - `media.delete { path }` deletes a file, through the confirmation that states its usage.
+ * - `media.edit { path }` opens an image in its Image editor (§9.5), the only way that mode is
+ *   entered by a verb.
  *
  * Every one runs the flow, never a copy of it: the surface's Upload label and Replace input are the
  * same controls these open (`HTMLInputElement.showPicker()`), and Delete is the detail pane's own.
@@ -31,13 +35,17 @@ import type { MediaBrowseRequest } from "./media-library";
 import type { CommandArgValues } from "../commands/command-args";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type * as MediaLibraryModule from "./media-library";
+import type * as MediaOpenModule from "./media-open";
 import type * as WorkspaceHomeModule from "../workspace/workspace-home";
 
 /** The ids, which Add new and the Site panel run. */
 export const MEDIA_BROWSE = "media.browse";
 export const MEDIA_UPLOAD = "media.upload";
 export const MEDIA_REPLACE = "media.replace";
+export const MEDIA_RENAME = "media.rename";
+export const MEDIA_DUPLICATE = "media.duplicate";
 export const MEDIA_DELETE = "media.delete";
+export const MEDIA_EDIT = "media.edit";
 
 /**
  * The flow and the home opener, each imported once. One cached promise per module: two dynamic
@@ -45,6 +53,7 @@ export const MEDIA_DELETE = "media.delete";
  */
 let _library: Promise<typeof MediaLibraryModule> | null = null;
 let _home: Promise<typeof WorkspaceHomeModule> | null = null;
+let _open: Promise<typeof MediaOpenModule> | null = null;
 
 function library(): Promise<typeof MediaLibraryModule> {
   _library ??= import("./media-library");
@@ -56,6 +65,11 @@ function home(): Promise<typeof WorkspaceHomeModule> {
   return _home;
 }
 
+function opener(): Promise<typeof MediaOpenModule> {
+  _open ??= import("./media-open");
+  return _open;
+}
+
 /** A path argument that must name a media file. Refused with the sentence a person can act on. */
 function mediaPathArg(commandId: string, args: CommandArgValues, key: string): string {
   const path = stringArg(commandId, args, key).replace(/^\.\//, "");
@@ -91,7 +105,7 @@ async function showHome(): Promise<void> {
 
 const PATH_DESCRIPTION = "The media file's project path, such as public/media/hero.jpg.";
 
-/** The four records. */
+/** The seven records. */
 export function mediaCommands(): AnyCommand[] {
   const base = {
     category: "Project",
@@ -154,6 +168,56 @@ export function mediaCommands(): AnyCommand[] {
       title: "Replace Media File…",
       undo: "none",
     },
+    {
+      ...base,
+      args: argsSchema(
+        { path: stringProperty(`The image to edit: a PNG, JPEG or WebP. ${PATH_DESCRIPTION}`) },
+        ["path"],
+      ),
+      icon: "crop",
+      id: MEDIA_EDIT,
+      requires: "an open project, on a backend that can read a file's raw bytes",
+      run: async (_ctx, args) => {
+        const path = mediaPathArg(MEDIA_EDIT, args, "path");
+        const flow = await opener();
+        flow.openImageEditor(path);
+      },
+      title: "Edit Image…",
+      undo: "none",
+      /* Not gated on `collab.readOnly`: that is the FOCUSED tab's session, and this record takes a
+         path that may be another file. The refusal asks the path's own tab, in the flow. */
+      when: (ctx) => ctx.project.open && ctx.capability.readFileBytes,
+    },
+    {
+      ...base,
+      args: argsSchema({ path: stringProperty(`The file to rename. ${PATH_DESCRIPTION}`) }, [
+        "path",
+      ]),
+      icon: "pencil-simple",
+      id: MEDIA_RENAME,
+      run: async (_ctx, args) => {
+        const path = mediaPathArg(MEDIA_RENAME, args, "path");
+        const flow = await library();
+        await flow.renameMediaFile(path);
+      },
+      title: "Rename Media File…",
+      undo: "none",
+    },
+    {
+      ...base,
+      args: argsSchema({ path: stringProperty(`The file to copy. ${PATH_DESCRIPTION}`) }, ["path"]),
+      icon: "copy",
+      id: MEDIA_DUPLICATE,
+      requires: "an open project, on a backend that can read a file's raw bytes",
+      run: async (_ctx, args) => {
+        const path = mediaPathArg(MEDIA_DUPLICATE, args, "path");
+        const flow = await library();
+        await flow.duplicateMediaFile(path);
+      },
+      title: "Duplicate Media File",
+      undo: "none",
+      when: (ctx) => ctx.project.open && ctx.capability.readFileBytes,
+    },
     {
       ...base,
       args: argsSchema({ path: stringProperty(`The file to delete. ${PATH_DESCRIPTION}`) }, [

package/src/media/media-library-model.ts

@@ -97,7 +97,7 @@ export function passesFilter(
  * says. Not its path: every path starts `public/` or `content/`, so a one-letter search for "b" or
  * "c" kept the whole library and looked broken.
  */
-export function matchesQuery(file: LibraryMediaFile, query: string): boolean {
+export function matchesQuery(file: Pick<LibraryMediaFile, "name">, query: string): boolean {
   const needle = query.trim().toLowerCase();
   return needle === "" || file.name.toLowerCase().includes(needle);
 }

package/src/media/media-library.ts

@@ -4,9 +4,10 @@
  *
  * One flow, two modes (studio.md §22.6). In **manage** mode it is the Media home tab: filters on
  * the left, a grid of tiles in the middle, and the selected file's detail on the right, with
- * **Replace**, **Open in viewer** and **Delete**. In **pick** mode it is the full-size media picker
- * (§9.3), the same surface inside a `jx-dialog` whose footer answers Cancel or Use <file>; the
- * compact popover's **Browse all media…** opens it (`ui/media-picker.ts`).
+ * **Replace**, **Open in viewer**, **Rename**, **Duplicate** and **Delete**. In **pick** mode it is
+ * the full-size media picker (§9.3), the same surface inside a `jx-dialog` whose footer answers
+ * Cancel or Use <file>; the compact popover's **Browse all media…** opens it
+ * (`ui/media-picker.ts`).
  *
  * **What it lists is `ui/media-picker.ts`'s listing**, `public/**` and every collection's
  * `images/**`, so the workspace, the pickers and the Site panel cannot disagree about what exists.
@@ -27,8 +28,10 @@
  * drop, only files the listing will show are uploaded, and the first upload is selected at once, so
  * the detail pane describes it, and its tile scrolls into view, the moment the re-read listing has
  * it. **Replace** is the one overwrite (`replaceAsset`), offered only files of the replaced one's
- * own type; **Delete** goes through the same confirmation as every delete, which states the usage
- * line (`files/file-ops.ts`), and a delete that empties an upload destination (`public/media/`, a
+ * own type; **Rename** keeps the file's folder and format and refuses a name already taken, and
+ * **Duplicate** copies the bytes on disk to a new name beside it (both studio.md §9.3); **Delete**
+ * goes through the same confirmation as every delete, which states the usage line
+ * (`files/file-ops.ts`), and a delete that empties an upload destination (`public/media/`, a
  * collection's `images/`) takes the folder the upload created with it.
  *
  * **This module is the flow; `surfaces/media-library.json` is the markup.** Every decision is made
@@ -42,14 +45,17 @@ import { getPlatform } from "../platform";
 import { notify } from "../services/notify";
 import { invalidateUsages, onUsagesInvalidated, usagesSupported } from "../services/references";
 import { overlayRegion, paneRegion } from "../ui/regions";
-import { layerHost } from "../ui/layers";
+import { layerHost, showPromptDialog } from "../ui/layers";
 import { rectOf } from "../utils/geometry";
 import { activeTab, closeTab, workspace } from "../workspace/workspace";
 import { createPreviewObserver } from "../browse/library-preview";
 import {
   DEFAULT_MEDIA_DIR,
   announceMediaChanged,
+  duplicateAsset,
   isUploadDestination,
+  joinDir,
+  mediaRenameRefusal,
   replaceAccept,
   replaceAsset,
   uploadAccept,
@@ -63,12 +69,19 @@ import {
   peekMediaMeta,
   recordImageSize,
 } from "../files/media-meta";
-import { dirName, previewFileSrc } from "../files/media-paths";
+import { baseName, dirName, previewFileSrc } from "../files/media-paths";
 import { forgetVersions } from "../files/asset-versions";
 import { loadMediaUsages, peekMediaUsages } from "../files/media-usage";
 import { onProjectMediaChange, projectMediaFiles } from "../ui/media-picker";
 import { openMenu } from "../surfaces/menu";
-import { openMediaTab } from "./media-open";
+import {
+  canDuplicateMedia,
+  canEditImage,
+  mediaWriteRefused,
+  openImageEditor,
+  openMediaTab,
+} from "./media-open";
+import { imageEditorAllowsReplace, imageFileChanged } from "./image-editor";
 import { factsLine, mediaStageFor, specimenOf, usageOf } from "./media-pane";
 import {
   MEDIA_FILTERS,
@@ -247,6 +260,11 @@ interface LibraryMount {
    * hold yet when it is selected, and which a sort can place anywhere in the grid.
    */
   reveal: string | null;
+  /**
+   * Whether {@link reveal}'s tile also takes the keyboard. A rename and a duplicate draw a NEW tile
+   * for the file the reader was on, and the focus they left on the old one is gone with it.
+   */
+  revealFocus: boolean;
   /**
    * Whether the keyboard is owed to this library's tab stop ({@link focusMediaHome}) and no tile
    * has been drawn to take it yet: a home mounted before its listing has arrived has no tiles.
@@ -319,6 +337,10 @@ function revealPending(mount: LibraryMount): void {
   if (tile?.isConnected) {
     mount.reveal = null;
     tile.scrollIntoView({ block: "nearest" });
+    if (mount.revealFocus) {
+      mount.revealFocus = false;
+      tile.focus();
+    }
   }
 }
 
@@ -578,6 +600,8 @@ function detailView(
   | "previewSpecimen"
   | "previewSpecimenFamily"
   | "replaceAccept"
+  | "editable"
+  | "duplicable"
   | "usageState"
   | "usageHeadline"
   | "usageFiles"
@@ -597,6 +621,8 @@ function detailView(
       previewSpecimenFamily: "",
       previewSrc: "",
       replaceAccept: "",
+      editable: "no",
+      duplicable: "no",
       selectedFile: "",
       usageFiles: [],
       usageHeadline: "",
@@ -638,6 +664,8 @@ function detailView(
     previewSpecimenFamily: specimen.specimenFamily,
     previewSrc: previewKind === "glyph" ? "" : previewFileSrc(entry.file),
     replaceAccept: replaceAccept(entry.file),
+    editable: canEditImage(entry.file) ? "yes" : "no",
+    duplicable: canDuplicateMedia() ? "yes" : "no",
     selectedFile: entry.file,
     ...usageOf(usage),
   };
@@ -778,6 +806,99 @@ async function pruneEmptiedDestination(
   }
 }
 
+/**
+ * Rename a media file, in the dialog every rename goes through (studio.md §9.3): the references the
+ * refactor pass will rewrite are counted before the field opens, and the field refuses a name the
+ * file cannot take, a taken name above all, because the backend would overwrite it in silence.
+ *
+ * Whatever showed the file goes on showing it: the selection follows it, and an open tab keeps its
+ * state under the new path.
+ *
+ * @returns The new path, or `null` when nothing was renamed.
+ */
+export async function renameMediaFile(path: string): Promise<string | null> {
+  if (mediaWriteRefused(path, "renamed")) {
+    return null;
+  }
+  const name = baseName(path);
+  const dir = dirName(path);
+  const { commitRename, listRenameSiblings, notifyMoveOutcome, renameStatus } = await filesModule();
+  const taken = await listRenameSiblings(path, "Media");
+  if (taken === null) {
+    return null;
+  }
+  const { renamePromptMessage } = await fileOpsModule();
+  const message = await renamePromptMessage(path);
+  const entered = await showPromptDialog("Rename", {
+    confirmLabel: "Rename",
+    select: "stem",
+    validate: (value) => mediaRenameRefusal(path, value, taken),
+    value: name,
+    ...(message !== undefined && { message }),
+  });
+  if (!entered || entered === name) {
+    return null;
+  }
+  const to = joinDir(dir, entered);
+  const measured = peekMediaMeta(path);
+  try {
+    const report = await commitRename(path, to);
+    if (homeChoice.selected === path) {
+      landOnNewFile(to);
+    }
+    await announceMediaChanged(dir);
+    /* The announcement drops every measurement, and a viewer already showing the picture will not
+       load it again to measure it. A rename changes no bytes, so what was true of them still is. */
+    if (measured?.width != null && measured.height != null) {
+      recordImageSize(to, measured.width, measured.height);
+    }
+    notifyMoveOutcome(renameStatus(entered, report), report, to);
+    return to;
+  } catch (error) {
+    notify.error(`Could not rename ${name}.`, {
+      detail: errorMessage(error),
+      path,
+      source: "Media",
+    });
+    return null;
+  }
+}
+
+/**
+ * Duplicate a media file (studio.md §9.3), and select the copy in the Media home, as an upload is.
+ *
+ * @returns The copy's path, or `null` when none was made.
+ */
+export async function duplicateMediaFile(path: string): Promise<string | null> {
+  if (mediaWriteRefused(path, "duplicated")) {
+    return null;
+  }
+  const copy = await duplicateAsset(path);
+  if (copy === null) {
+    return null;
+  }
+  landOnNewFile(copy.path);
+  redrawAll();
+  return copy.path;
+}
+
+/**
+ * Put the Media home's selection on a file a rename or a duplicate has just made: on screen, and
+ * holding the keyboard once its tile is drawn. Neither verb changes a file's kind, and a file just
+ * renamed or copied is as unused as it was, so the filter still keeps it; only a search the new
+ * name does not match has to go.
+ */
+function landOnNewFile(file: string): void {
+  homeChoice.selected = file;
+  if (!matchesQuery({ name: baseName(file) }, homeChoice.query)) {
+    homeChoice.query = "";
+  }
+  for (const { mount } of _panes.values()) {
+    mount.reveal = file;
+    mount.revealFocus = true;
+  }
+}
+
 function actionsFor(mount: LibraryMount) {
   return {
     activate: (file: string) => {
@@ -857,22 +978,45 @@ function actionsFor(mount: LibraryMount) {
         openMediaTab(selected);
       }
     },
+    editImage: () => {
+      const { selected } = mount.choice;
+      if (selected !== null) {
+        openImageEditor(selected);
+      }
+    },
     remove: () => {
       const { selected } = mount.choice;
       if (selected !== null) {
         void deleteMediaFile(selected);
       }
     },
+    rename: () => {
+      const { selected } = mount.choice;
+      if (selected !== null) {
+        void renameMediaFile(selected);
+      }
+    },
+    duplicate: () => {
+      const { selected } = mount.choice;
+      if (selected !== null) {
+        void duplicateMediaFile(selected);
+      }
+    },
     replace: (input: HTMLInputElement) => {
       const [chosen] = input.files ?? [];
       // Cleared first: a file input that keeps its value refuses the same file twice.
       input.value = "";
       const { selected } = mount.choice;
-      if (chosen && selected !== null) {
+      if (chosen && selected !== null && imageEditorAllowsReplace(selected)) {
         /* No metadata invalidation here: `replaceAsset` announces the change, whose handler drops
            the listing AND its metadata and re-reads them in that order. A second drop after it
            lands would wipe the fresh facts of every other tile, and nothing would re-seed them. */
-        void replaceAsset(selected, chosen).then(redrawAll);
+        void replaceAsset(selected, chosen).then((replaced) => {
+          if (replaced) {
+            imageFileChanged(selected);
+          }
+          redrawAll();
+        });
       }
     },
     reset: () => {
@@ -932,10 +1076,9 @@ let _tileMenu: MenuHandle | null = null;
 /**
  * A right-click on a tile: select it, then offer the detail pane's actions at the pointer.
  *
- * The same four verbs as the detail pane's (studio.md §22.6), in the order the pane draws them, and
- * each calls what the pane's control calls, so the menu cannot drift from the pane. Selecting first
- * is what makes the pane describe the file the menu acts on, as a right-click on a row does in the
- * Content workspace.
+ * The same verbs as the detail pane's (studio.md §22.6), and each calls what the pane's control
+ * calls, so the menu cannot drift from the pane. Selecting first is what makes the pane describe
+ * the file the menu acts on, as a right-click on a row does in the Content workspace.
  */
 function showTileMenu(mount: LibraryMount, file: string, x: number, y: number): void {
   select(mount, file);
@@ -969,8 +1112,24 @@ function showTileMenu(mount: LibraryMount, file: string, x: number, y: number):
     region: "media-tile",
     rows: [
       row("open", "Open in Viewer", () => openMediaTab(file)),
+      ...(canEditImage(file) ? [row("edit", "Edit Image", () => openImageEditor(file))] : []),
       row("copy-url", "Copy Site URL", () => copySiteUrl(entry)),
-      row("replace", "Replace…", () => requestMediaReplace(file), { dividerAbove: true }),
+      row(
+        "rename",
+        "Rename…",
+        () => {
+          void renameMediaFile(file);
+        },
+        { dividerAbove: true },
+      ),
+      ...(canDuplicateMedia()
+        ? [
+            row("duplicate", "Duplicate", () => {
+              void duplicateMediaFile(file);
+            }),
+          ]
+        : []),
+      row("replace", "Replace…", () => requestMediaReplace(file)),
       row(
         "delete",
         "Delete",
@@ -1055,6 +1214,7 @@ function createMount(
     onSelect: null,
     paneId,
     reveal: null,
+    revealFocus: false,
     focusOwed: false,
     region,
     sweepTimer: null,

package/src/media/media-open.ts

@@ -18,9 +18,16 @@
  * @docs studio/projects/media
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
 import { activateTab, openTab, workspace } from "../workspace/workspace";
 import { extensionOf, isMediaFile } from "../files/media-upload";
+import { getPlatform, hasPlatform } from "../platform";
+import { notify } from "../services/notify";
+import { collabReadOnly } from "../collab/collab-session";
+import { toRaw } from "../reactivity";
 import { MEDIA_MODE } from "./media-pane";
+import { IMAGE_MODE } from "./image-editor";
+import { editRefusal, isEditableExtension } from "./image-format";
 import type { Tab } from "../tabs/tab";
 
 /** Placeholder document for a media tab — the viewer never reads it, and there is nothing to save. */
@@ -31,9 +38,21 @@ export function isViewableMedia(path: string): boolean {
   return isMediaFile(path);
 }
 
-/** The modes a media tab offers. SVG is also text, so it keeps a source alternate. */
+/**
+ * The modes a media tab offers, as far as the path can say. SVG is also text, so it keeps a source
+ * alternate; a still raster in a format the host can encode gets the Image editor (studio.md §9.5)
+ * on a host that can hand Studio a file's raw bytes. A refused format is not offered rather than
+ * offered and then refused, and the half of that the extension cannot answer (an animated `.png` or
+ * `.webp`, say) is {@link withdrawRefusedEditor}'s.
+ */
 export function mediaTabModes(path: string): string[] {
-  return extensionOf(path) === ".svg" ? [MEDIA_MODE, "source"] : [MEDIA_MODE];
+  if (extensionOf(path) === ".svg") {
+    return [MEDIA_MODE, "source"];
+  }
+  if (isEditableExtension(path) && hasPlatform() && isFunction(getPlatform().readFileBytes)) {
+    return [MEDIA_MODE, IMAGE_MODE];
+  }
+  return [MEDIA_MODE];
 }
 
 /**
@@ -57,7 +76,7 @@ export function openMediaTab(
     activateTab(path, { focus: opts.focus !== false });
     return existing;
   }
-  return openTab({
+  const tab = openTab({
     capabilities: { modes: mediaTabModes(path) },
     document: structuredClone(MEDIA_STUB_DOCUMENT),
     documentPath: path,
@@ -67,4 +86,138 @@ export function openMediaTab(
     ...(opts.preview === true && { preview: true }),
     ...(opts.focus === false && { focus: false }),
   });
+  void withdrawRefusedEditor(tab, path);
+  return tab;
+}
+
+/** Why a tab's Image editor was withdrawn, so a later attempt can say so again. */
+const _withdrawn = new WeakMap<Tab, string>();
+
+/**
+ * Take the Image editor off a tab whose bytes refuse it: an extension is a claim about the bytes,
+ * and a still `.png` and an animated one share an extension (studio.md §9.5).
+ *
+ * The extension already answered for every file the mode could never write, so this reads only a
+ * file the path says is editable, and the viewer is drawing those same bytes anyway. A read that
+ * fails decides nothing: the editor reports it if the author goes there. A tab already in the mode
+ * goes back to the viewer and says why, because a mode that vanished in silence would look like a
+ * click that did nothing.
+ */
+async function withdrawRefusedEditor(tab: Tab, path: string): Promise<void> {
+  if (!tab.capabilities.modes.includes(IMAGE_MODE)) {
+    return;
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = new Uint8Array(await getPlatform().readFileBytes!(path));
+  } catch {
+    return;
+  }
+  const refusal = editRefusal(path, bytes);
+  /* Through the workspace's own face of the tab: `openTab` hands back the raw object, and a write to
+     that changes the value without telling the Editor control. It also answers a tab the read
+     outlived, which has nothing left to withdraw from. */
+  const live = workspace.tabs.get(path);
+  if (refusal === null || !live) {
+    return;
+  }
+  _withdrawn.set(toRaw(live), refusal);
+  live.capabilities.modes = live.capabilities.modes.filter((mode) => mode !== IMAGE_MODE);
+  if (live.session.ui.canvasMode === IMAGE_MODE) {
+    live.session.ui.canvasMode = MEDIA_MODE;
+    notify.warn(refusal, { key: `image.refused:${path}`, path, source: "Image" });
+  }
+}
+
+/**
+ * Whether to offer the Image editor for a file in a list of them: what the path says, and what its
+ * open tab has since learned. The palette's `media.edit` cannot ask this (its context describes the
+ * focused tab), so it is the flow's refusal there.
+ */
+export function canEditImage(path: string): boolean {
+  if (!mediaTabModes(path).includes(IMAGE_MODE)) {
+    return false;
+  }
+  const tab = workspace.tabs.get(path);
+  return !tab || (tab.capabilities.modes.includes(IMAGE_MODE) && !collabReadOnly(tab));
+}
+
+/**
+ * Whether this host can copy a media file: a copy needs its raw bytes (studio.md §9.3), and a
+ * backend that cannot read them is not offered Duplicate rather than offered it and then refused.
+ */
+export function canDuplicateMedia(): boolean {
+  return hasPlatform() && isFunction(getPlatform().readFileBytes);
+}
+
+/**
+ * Whether a collaborator with read access to this file's session is the one asking to write it, and
+ * if so say so. Asks the PATH's own tab, as {@link openImageEditor} does: a record's context
+ * describes the focused tab, which may be another file.
+ *
+ * @param path The file.
+ * @param done How the sentence ends: "renamed", "duplicated".
+ */
+export function mediaWriteRefused(path: string, done: string): boolean {
+  const tab = workspace.tabs.get(path);
+  if (!tab || !collabReadOnly(tab)) {
+    return false;
+  }
+  const name = path.split("/").pop() ?? path;
+  notify.warn(`You have read access to this session, so ${name} cannot be ${done}.`, {
+    key: `media.readOnly:${path}`,
+    path,
+    source: "Collaboration",
+  });
+  return true;
+}
+
+/**
+ * Open a media file in its Image editor (studio.md §9.5) — `media.edit`, and the Media workspace's
+ * Edit action. The mode is entered by choosing a subject, never by name through `canvas.setMode`.
+ *
+ * Refused, with the reason, for a file the editor cannot write (the tab would not offer the mode)
+ * and for a collaborator who cannot write the file: the gate asks the PATH's own tab, which is why
+ * it lives here rather than on the command record, whose context describes the focused tab.
+ *
+ * @returns The tab, now in the Image editor, or null when it was refused.
+ */
+export function openImageEditor(
+  path: string,
+  opts: { paneId?: string; focus?: boolean } = {},
+): Tab | null {
+  const name = path.split("/").pop() ?? path;
+  if (!mediaTabModes(path).includes(IMAGE_MODE)) {
+    notify.warn(`${name} cannot be edited here.`, {
+      detail:
+        "The Image editor writes PNG, JPEG and WebP, on a backend that can hand Studio a file's raw bytes.",
+      key: `image.notEditable:${path}`,
+      path,
+      source: "Image",
+    });
+    return null;
+  }
+  openMediaTab(path, opts);
+  // Through the workspace's face of the tab, so the pane redraws (see withdrawRefusedEditor).
+  const tab = workspace.tabs.get(path)!;
+  /* Asked of the tab as it stands, after the open: a session may have attached in it, and bytes read
+     earlier may have withdrawn the mode. Either leaves the tab in its viewer, saying why. */
+  if (collabReadOnly(tab)) {
+    notify.warn(`You have read access to this session, so ${name} cannot be edited.`, {
+      key: `image.readOnly:${path}`,
+      path,
+      source: "Collaboration",
+    });
+    return null;
+  }
+  if (!tab.capabilities.modes.includes(IMAGE_MODE)) {
+    notify.warn(_withdrawn.get(toRaw(tab)) ?? `${name} cannot be edited here.`, {
+      key: `image.refused:${path}`,
+      path,
+      source: "Image",
+    });
+    return null;
+  }
+  tab.session.ui.canvasMode = IMAGE_MODE;
+  return tab;
 }

package/src/media/media-pane.ts

@@ -16,8 +16,9 @@
  * confirmation_: you could only learn what an image was used for by trying to remove it. This is
  * the surface that query was waiting for.
  *
- * Read-only, deliberately. Rename, delete and reveal are the file tree's, and a second set of
- * buttons for them here would be a second place to keep them right.
+ * Read-only, deliberately. Rename, duplicate, replace and delete are the Media home's and reveal is
+ * the file tree's, and a second set of buttons for them here would be a second place to keep them
+ * right.
  *
  * **This module is the flow; `surfaces/media-pane.json` is the markup.** Everything below decides
  * something — which pane holds which tab, which of the six stages a file belongs in, when the
@@ -30,6 +31,7 @@
 import { effect, effectScope } from "../reactivity";
 import { paneRegion } from "../ui/regions";
 import { localDay } from "../utils/local-day";
+import { assetVersionsEpoch } from "../files/asset-versions";
 import { mediaSiteUrl, previewFileSrc } from "../files/media-paths";
 import {
   formatBytes,
@@ -208,7 +210,6 @@ export function renderMediaMode(surface: CanvasSurface, tab: Tab): void {
   detachMediaPane(paneId);
 
   const path = tab.documentPath ?? "";
-  const src = previewFileSrc(path);
   const ref = mediaSiteUrl(path);
   const ext = extensionOf(path);
   const kind = mediaStageFor(path);
@@ -244,7 +245,9 @@ export function renderMediaMode(surface: CanvasSurface, tab: Tab): void {
       region: paneRegion(paneId, "media"),
       specimen: specimen.specimen,
       specimenFamily: specimen.specimenFamily,
-      src,
+      /* Asked on every paint: bytes written in place give the URL a new repaint key (§3.4), and a
+         viewer holding the old URL would go on showing the picture they replaced. */
+      src: previewFileSrc(path),
       ...usageOf(usage),
     };
   };
@@ -285,6 +288,7 @@ export function renderMediaMode(surface: CanvasSurface, tab: Tab): void {
          browser's problem, and its metadata repaints through `redraw`. Reading it here is what
          makes a rename repaint the viewer rather than leave it pointing at a name that is gone. */
       void tab.documentPath;
+      void assetVersionsEpoch.value;
       draw();
     });
   });

package/src/panels/pane-context.ts

@@ -800,7 +800,12 @@ function editorAxis(tab: Tab): Partial<PaneContextView> {
   const current = editorKindOf(tab);
   const kinds = IMPLICIT_EDITOR_KINDS.has(current)
     ? [current]
-    : editorKindsOf(tab).filter((kind) => !IMPLICIT_EDITOR_KINDS.has(kind));
+    : editorKindsOf(tab).filter(
+        (kind) =>
+          !IMPLICIT_EDITOR_KINDS.has(kind) &&
+          // A collaborator who cannot write is not offered the editor that exists to write (§9.5).
+          (kind !== "image" || kind === current || !collabState(tab).readOnly),
+      );
   if (kinds.length < 2) {
     // One kind is not a choice. Rendering it as a segmented group would be a control that cannot move —
     // Which is the defect this axis exists to remove, in miniature.