@jxsuite/studio 10.2.0 → 10.3.0

package/src/files/media-upload.ts

@@ -14,7 +14,9 @@
  * {@link DEFAULT_MEDIA_DIR}, `public/media/`, which is served from the site root as `/media/`.
  *
  * {@link replaceAsset} is the one door that writes over an existing file, and it is asked for by
- * name: the Media workspace's **Replace** (studio.md §9.3).
+ * name: the Media workspace's **Replace** (studio.md §9.3). {@link duplicateAsset} is the upload
+ * core fed from the project rather than the desktop, and {@link mediaRenameRefusal} is what a new
+ * name for a media file may not be.
  *
  * @docs studio/projects/media
  */
@@ -24,7 +26,9 @@ import { getPlatform, hasPlatform } from "../platform";
 import { notify } from "../services/notify";
 import { invalidateUsages } from "../services/references";
 import { activeTab } from "../workspace/workspace";
-import { forgetVersions, notedListing } from "./asset-versions";
+import { forgetVersions, noteLocalWrite, notedListing } from "./asset-versions";
+import { markLocalMutation } from "./fs-events";
+import { renameRefusal } from "./new-file-name";
 import {
   AUDIO_EXTENSIONS,
   IMAGE_EXTENSIONS,
@@ -202,17 +206,20 @@ export function assetRef(destPath: string): string {
 
 /**
  * A filename that doesn't collide with `taken`, suffixing `-1`, `-2`, … before the extension. Never
- * overwrites existing media (the previous behaviour clobbered silently).
+ * overwrites existing media (the previous behaviour clobbered silently). Compared without regard to
+ * case: APFS and NTFS take `Hero.jpg` for `hero.jpg`, so a name that differs only in case is a name
+ * that overwrites there.
  */
 export function uniqueName(name: string, taken: ReadonlySet<string>): string {
-  if (!taken.has(name)) {
+  const lower = new Set([...taken].map((entry) => entry.toLowerCase()));
+  if (!lower.has(name.toLowerCase())) {
     return name;
   }
   const ext = extensionOf(name);
   const base = ext ? name.slice(0, -ext.length) : name;
   for (let i = 1; ; i++) {
     const candidate = `${base}-${i}${ext}`;
-    if (!taken.has(candidate)) {
+    if (!lower.has(candidate.toLowerCase())) {
       return candidate;
     }
   }
@@ -231,10 +238,17 @@ export function joinDir(dir: string, name: string): string {
  * this module doesn't import the media-picker / Manage / file-tree caches it needs to invalidate
  * (they all import from here) — the same injection pattern as the canvas host's drop handlers.
  */
-let mediaChangedHandler: ((dir: string) => void | Promise<void>) | null = null;
+let mediaChangedHandler: MediaChangedHandler | null = null;
+
+/**
+ * The post-upload cache invalidator. `overwritten` names a path whose bytes were replaced IN PLACE,
+ * which is the one change a re-list cannot show: the listing is unchanged, so anything already
+ * drawn from that path has to be drawn again (studio.md §3.4).
+ */
+export type MediaChangedHandler = (dir: string, overwritten?: string) => void | Promise<void>;
 
 /** Register the post-upload cache invalidator (see {@link mediaChangedHandler}). */
-export function setMediaChangedHandler(fn: ((dir: string) => void | Promise<void>) | null): void {
+export function setMediaChangedHandler(fn: MediaChangedHandler | null): void {
   mediaChangedHandler = fn;
 }
 
@@ -242,8 +256,10 @@ export function setMediaChangedHandler(fn: ((dir: string) => void | Promise<void
  * Say that the media in `dir` changed by some door other than {@link uploadAssets} — a replace, or
  * the Media workspace's delete — so every cache keyed on the listing is dropped the same way.
  */
-export async function announceMediaChanged(dir: string): Promise<void> {
-  await mediaChangedHandler?.(dir);
+export async function announceMediaChanged(dir: string, overwritten?: string): Promise<void> {
+  await (overwritten === undefined
+    ? mediaChangedHandler?.(dir)
+    : mediaChangedHandler?.(dir, overwritten));
 }
 
 /** The directory part of a project path, `.` for a file at the root. */
@@ -303,7 +319,16 @@ function keepListable(files: File[], only: UploadOnly): File[] {
  */
 export async function uploadAssets(
   files: Iterable<File>,
-  opts: { dir?: string; only?: UploadOnly } = {},
+  opts: {
+    dir?: string;
+    /** The destination holds a file already, so a listing that fails says nothing about it. */
+    dirExists?: boolean;
+    only?: UploadOnly;
+    quiet?: boolean;
+    source?: string;
+    /** Writes each file instead of `uploadFile`, for a caller with a better door than an upload. */
+    write?: (path: string) => Promise<{ path: string }>;
+  } = {},
 ): Promise<UploadedAsset[]> {
   const list = opts.only === undefined ? [...files] : keepListable([...files], opts.only);
   if (list.length === 0) {
@@ -311,13 +336,22 @@ export async function uploadAssets(
   }
   const platform = getPlatform();
   const dir = opts.dir ?? uploadDirFor(activeTab.value?.documentPath ?? null);
+  const source = opts.source ?? "Media";
 
   let taken: Set<string>;
   try {
     // The upload directory is a media directory, so its listing vouches for versions as well.
     const existing = await notedListing(() => platform.listDirectory(dir));
     taken = new Set(existing.map((entry) => entry.name));
-  } catch {
+  } catch (error) {
+    if (opts.dirExists === true) {
+      notify.error(`Could not write to ${dir}/.`, {
+        detail: `The folder could not be read to choose a name that overwrites nothing: ${errorMessage(error)}`,
+        path: dir,
+        source,
+      });
+      return [];
+    }
     taken = new Set(); // Directory doesn't exist yet — the backend mkdir -p's on write.
   }
 
@@ -342,7 +376,9 @@ export async function uploadAssets(
       /* The path the backend REPORTS, not the one asked for. A store that de-duplicates by content
          hash, appends a collision suffix, or normalizes a name writes somewhere else, and the
          reference that goes into the document has to name what is really there. */
-      const { path } = await platform.uploadFile(requested, file);
+      const { path } = await (opts.write
+        ? opts.write(requested)
+        : platform.uploadFile(requested, file));
       // New bytes at `path`: whatever version a listing held for it no longer names them.
       forgetVersions([path]);
       uploaded.push({ kind: mediaKind(file), name, path, ref: assetRef(path) });
@@ -350,22 +386,119 @@ export async function uploadAssets(
       notify.error(`Could not upload ${file.name}.`, {
         detail: errorMessage(error),
         path: requested,
-        source: "Media",
+        source,
       });
     }
   }
 
   if (uploaded.length > 0) {
-    notify.success(
-      uploaded.length === 1
-        ? `Uploaded ${uploaded[0]!.name} to ${dir}/`
-        : `Uploaded ${uploaded.length} files to ${dir}/`,
-    );
+    // `quiet` is a caller with its own sentence: one toast per write, and "uploaded" is not always it.
+    if (opts.quiet !== true) {
+      notify.success(
+        uploaded.length === 1
+          ? `Uploaded ${uploaded[0]!.name} to ${dir}/`
+          : `Uploaded ${uploaded.length} files to ${dir}/`,
+      );
+    }
     await mediaChangedHandler?.(dir);
   }
   return uploaded;
 }
 
+/** `bytes` as text when `writeFile` can put the same bytes back: valid UTF-8, with no BOM to lose. */
+function strictUtf8(bytes: ArrayBuffer): string | null {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    return text.startsWith("\uFEFF") ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What a copy of `name` is called before any collision: `hero.jpg` is `hero-copy.jpg`.
+ *
+ * A copy of a copy keeps counting ({@link uniqueName} adds the number) rather than growing a second
+ * `-copy`, so duplicating `hero-copy.jpg` or `hero-copy-1.jpg` asks for `hero-copy.jpg` again.
+ */
+export function duplicateName(name: string): string {
+  const stem = name.slice(0, name.length - extensionOf(name).length);
+  return `${stem.replace(/-copy(?:-\d+)?$/, "")}-copy${name.slice(stem.length)}`;
+}
+
+/**
+ * Copy the file at `path` to a new name beside it — **Duplicate**, in the Media workspace and the
+ * Content home alike.
+ *
+ * Through `readFileBytes`, because `readFile` answers UTF-8: a picture read that way comes back as
+ * replacement characters, and so does every non-UTF-8 byte of a text file, such as a Latin-1
+ * Markdown entry from an imported site. And through {@link uploadAssets}, so a copy is named,
+ * limited and announced the way any new file is and can never overwrite anything. What it copies is
+ * the file on disk: a pending image edit or an unsaved change belongs to its tab and stays there.
+ *
+ * A backend that reports the original's own path (a store that keeps identical bytes once) made no
+ * second file, which is said rather than called success.
+ *
+ * `document` is for a file that is usually a document, and it decides the write rather than the
+ * read. Studio Cloud files every upload as a binary and answers a text read of one with a 415, so
+ * an uploaded copy of a Markdown entry could never be opened. Bytes that are valid UTF-8 go through
+ * `writeFile` instead, which loses nothing, since they encode back the same. Bytes that are not
+ * stay an upload, and so does a file with a BOM: the dev server decodes a written body as a Fetch
+ * `text()` does, which drops one.
+ *
+ * @param path The file to copy.
+ * @param opts `source` names the flow in a Problem; `document` is described above.
+ * @returns The copy, or `null` when none was made; the reason has been reported.
+ */
+export async function duplicateAsset(
+  path: string,
+  opts: { document?: boolean; source?: string } = {},
+): Promise<UploadedAsset | null> {
+  const name = path.split("/").pop() ?? path;
+  const source = opts.source ?? "Media";
+  let bytes: ArrayBuffer;
+  try {
+    const platform = getPlatform();
+    if (platform.readFileBytes === undefined) {
+      throw new Error("This backend cannot read a file's raw bytes.");
+    }
+    bytes = await platform.readFileBytes(path);
+  } catch (error) {
+    notify.error(`Could not duplicate ${name}.`, {
+      detail: errorMessage(error),
+      path,
+      source,
+    });
+    return null;
+  }
+  const text = opts.document === true ? strictUtf8(bytes) : null;
+  const [copy] = await uploadAssets([new File([bytes], duplicateName(name))], {
+    dir: parentDir(path),
+    dirExists: true,
+    quiet: true,
+    source,
+    ...(text !== null && {
+      write: async (target: string) => {
+        await getPlatform().writeFile(target, text);
+        return { path: target };
+      },
+    }),
+  });
+  if (!copy) {
+    return null;
+  }
+  if (copy.path === path) {
+    notify.warn(`${name} was not duplicated.`, {
+      detail: "The backend keeps identical files once, so it made no second file.",
+      path,
+      source,
+    });
+    return null;
+  }
+  notify.success(`Duplicated ${name} as ${copy.name}`);
+  return copy;
+}
+
 /** Extensions that name one format, so either may stand in for the other. */
 const SAME_FORMAT: readonly ReadonlySet<string>[] = [
   new Set([".jpg", ".jpeg"]),
@@ -392,6 +525,29 @@ export function canReplaceWith(path: string, file: { name: string }): boolean {
   return formatSiblings(extensionOf(path)).has(extensionOf(file.name));
 }
 
+/**
+ * The refusal a new name for the media file at `path` earns, or `""` when it is usable (studio.md
+ * §9.3): every entry's rename rules, and then the one only a media file has.
+ *
+ * @param path The file being renamed.
+ * @param value What the reader typed.
+ * @param taken The names in the file's folder.
+ */
+export function mediaRenameRefusal(
+  path: string,
+  value: string,
+  taken: ReadonlySet<string>,
+): string {
+  const general = renameRefusal(path, value, taken);
+  if (general !== "") {
+    return general;
+  }
+  if (!canReplaceWith(path, { name: value.trim() })) {
+    return `Keep the ${extensionOf(path)} extension. A rename does not convert the file, so another extension would break it on every page.`;
+  }
+  return "";
+}
+
 /**
  * Write `file`'s bytes over the existing media file at `path` — the Media workspace's **Replace**.
  *
@@ -405,7 +561,11 @@ export function canReplaceWith(path: string, file: { name: string }): boolean {
  *
  * @returns Whether the bytes now at `path` are the new ones.
  */
-export async function replaceAsset(path: string, file: File): Promise<boolean> {
+export async function replaceAsset(
+  path: string,
+  file: File,
+  opts: { note?: string } = {},
+): Promise<boolean> {
   const name = path.split("/").pop() ?? path;
   /* An `accept` narrows only the chooser (and a backend's own picker may ignore it), so the format is
      checked here too: same path, other format, is every reference broken at once. */
@@ -425,6 +585,10 @@ export async function replaceAsset(path: string, file: File): Promise<boolean> {
     });
     return false;
   }
+  /* Studio's own write, marked BEFORE it happens (§3.4): the watcher's echo of it is absorbed rather
+     than reported as somebody else's change, and the path's content version is forgotten while the
+     bytes are still the old ones, so no listing in flight can vouch the old version afterwards. */
+  markLocalMutation(path);
   let written: string;
   try {
     ({ path: written } = await getPlatform().uploadFile(path, file));
@@ -437,10 +601,18 @@ export async function replaceAsset(path: string, file: File): Promise<boolean> {
     return false;
   }
   forgetVersions([path, written]);
+  /* The repaint key: on a host that vouches no version (`jx dev`, desktop) the URL of `path` is
+     otherwise byte-identical before and after, and every image already decoded keeps the old
+     pixels. Only on the path that was actually written; a second file beside it is new. */
+  if (written === path) {
+    noteLocalWrite(path);
+  }
   // The answers were about the old bytes' place in the project; the place is the same, but a stale
   // "Used on" is a list the reader acts on, so it is asked again rather than trusted.
   invalidateUsages();
-  await announceMediaChanged(parentDir(path));
+  await (written === path
+    ? announceMediaChanged(parentDir(path), path)
+    : announceMediaChanged(parentDir(path)));
   if (written !== path) {
     notify.warn(`${name} was not replaced.`, {
       detail: `The backend stored the new file as ${written}, so every reference still shows the old one.`,
@@ -451,6 +623,8 @@ export async function replaceAsset(path: string, file: File): Promise<boolean> {
     });
     return false;
   }
-  notify.success(`Replaced ${name}`);
+  /* One toast per write. A caller with something to add (the Image editor's written size) adds it
+     to the message, because a toast draws its message alone: `detail` is for Problems. */
+  notify.success(opts.note === undefined ? `Replaced ${name}` : `Replaced ${name}: ${opts.note}`);
   return true;
 }

package/src/files/new-file-name.ts

@@ -1,5 +1,6 @@
 /**
- * The rules a new file's name is held to, with no dialog and no write attached.
+ * The rules a new file's name is held to, with no dialog and no write attached, and the rules a
+ * rename's new name is held to ({@link renameRefusal}).
  *
  * `createFileIn` (`files/files.ts`) used to keep these inside one closure over its prompt, which
  * was right while the prompt was the only creation flow there was. Add new (`create/add-new.ts`,
@@ -154,3 +155,40 @@ export function validateNewFileName(
   const candidate = composeNewFileName(value, picked, choice);
   return taken.has(candidate.toLowerCase()) ? `${candidate} already exists in ${dir}/.` : "";
 }
+
+/**
+ * The refusal a new name for the file or folder at `path` earns, or `""` when it is usable
+ * (studio.md §9.1.1). The first that applies is the sentence.
+ *
+ * `taken` is every name already in the entry's folder, and it is the check that matters most: a
+ * backend's `renameFile` is a filesystem rename, which replaces its destination in silence.
+ * Compared without regard to case, since a case-insensitive disk would take `Hero.jpg` for
+ * `hero.jpg`, and the entry's own name is never in the way, so its case can change.
+ *
+ * The other two refusals are what keep that check honest. A listing answers for one folder, and a
+ * path would land in another. A dev server or desktop listing leaves out every dotfile, so `.env`
+ * looks free whether or not there is one. An entry that is itself a dotfile is exempt: a host that
+ * listed it is a host whose listing can answer.
+ *
+ * @param path The entry being renamed.
+ * @param value What the reader typed.
+ * @param taken The names in the entry's folder, in any case.
+ */
+export function renameRefusal(path: string, value: string, taken: ReadonlySet<string>): string {
+  const name = value.trim();
+  if (name === "") {
+    return "Enter a file name.";
+  }
+  if (/[/\\]/.test(name)) {
+    return "Enter a name, not a path. A rename keeps the file in its folder.";
+  }
+  const current = (path.split("/").pop() ?? path).toLowerCase();
+  if (name.startsWith(".") && !current.startsWith(".")) {
+    return "A name cannot start with a dot: hidden files are not listed, so the file could disappear.";
+  }
+  const lower = name.toLowerCase();
+  if (lower !== current && [...taken].some((entry) => entry.toLowerCase() === lower)) {
+    return `${name} already exists in this folder.`;
+  }
+  return "";
+}

package/src/media/image-bake.ts

@@ -0,0 +1,164 @@
+/**
+ * The bake: a recipe applied to an image's bytes, once, at save (studio.md §9.5).
+ *
+ * The only module in the Image editor that touches pixels. It decodes the source with the
+ * orientation tag applied (stated explicitly, so the decode and the `<img>` the author edited over
+ * cannot disagree), sizes an `OffscreenCanvas` to the output, turns and flips the context, asks for
+ * the host's best resampling rather than its default (which is its fastest, and which visibly
+ * aliases a reduction of more than about a factor of two), sets the same filter string the preview
+ * showed, draws the stored SOURCE rectangle directly, and encodes.
+ *
+ * **It verifies before anything is written, because every relevant host failure is silent.** Past
+ * the maximum drawing surface a context draws and reads back zeros; `convertToBlob` asked for a
+ * type it cannot encode returns a PNG rather than rejecting; and a surface that produced nothing
+ * still produces a blob. So the output must be within the surface, the encoded type must be the one
+ * the path promises, and the blob must be large enough to be an image. A failed check returns a
+ * reason and the caller writes nothing.
+ *
+ * The two host primitives are parameters, defaulting to the globals, so the module is exercised
+ * against fakes under happy-dom (which has neither) with no `mock.module()` of a first-party file.
+ * `OffscreenCanvas` is not a DOM node, so nothing here constructs UI.
+ *
+ * @docs studio/projects/media
+ */
+
+import { MAX_SURFACE_AREA, MAX_SURFACE_SIDE, takesQuality } from "./image-format";
+import { cropOf, filterString, outputSize, swapsAxes } from "./image-recipe";
+import type { ImageRecipe, PixelSize } from "./image-recipe";
+
+/** The part of a 2D context a bake uses — all of it, so a fake can be honest about its shape. */
+export type BakeContext = Pick<
+  OffscreenCanvasRenderingContext2D,
+  | "drawImage"
+  | "filter"
+  | "imageSmoothingEnabled"
+  | "imageSmoothingQuality"
+  | "rotate"
+  | "scale"
+  | "translate"
+>;
+
+/** The part of an `OffscreenCanvas` a bake uses. */
+export interface BakeSurface {
+  getContext: (contextId: "2d") => BakeContext | null;
+  convertToBlob: (options?: ImageEncodeOptions) => Promise<Blob>;
+}
+
+/** The two host primitives a bake needs, replaceable for a test. */
+export interface BakePorts {
+  createBitmap?: (image: Blob, options: ImageBitmapOptions) => Promise<ImageBitmap>;
+  Offscreen?: new (width: number, height: number) => BakeSurface;
+}
+
+/** A bake that produced bytes fit to write, or the reason it did not. */
+export type BakeResult = { ok: true; blob: Blob; size: PixelSize } | { ok: false; reason: string };
+
+/**
+ * The smallest encoded output accepted as an image. The smallest valid PNG a canvas writes is about
+ * seventy bytes and a JPEG well over a hundred, so anything under this is a surface that produced
+ * nothing, and it must not be written over a file that was something.
+ */
+export const MIN_ENCODED_BYTES = 64;
+
+/** Why `size` cannot be drawn on this host, or null when it can. */
+export function surfaceRefusal(size: PixelSize): string | null {
+  if (
+    size.width > MAX_SURFACE_SIDE ||
+    size.height > MAX_SURFACE_SIDE ||
+    size.width * size.height > MAX_SURFACE_AREA
+  ) {
+    return `The result would be ${size.width} × ${size.height}, past the ${MAX_SURFACE_SIDE} × ${MAX_SURFACE_SIDE} the browser can draw. Reduce the width or crop first.`;
+  }
+  return null;
+}
+
+/**
+ * Bake `recipe` over `bytes`, encoded as `mime`.
+ *
+ * @param recipe - The edit, with its crop in source coordinates
+ * @param bytes - The file's bytes, exactly as read
+ * @param mime - The type the path's extension promises, which the output must be
+ * @param ports - The host primitives; the globals when omitted
+ */
+export async function bakeImage(
+  recipe: Readonly<ImageRecipe>,
+  bytes: Uint8Array<ArrayBuffer>,
+  mime: string,
+  {
+    createBitmap = (image, options) => globalThis.createImageBitmap(image, options),
+    Offscreen = globalThis.OffscreenCanvas,
+  }: BakePorts = {},
+): Promise<BakeResult> {
+  const bitmap = await createBitmap(new Blob([bytes], { type: mime }), {
+    imageOrientation: "from-image",
+  });
+  try {
+    const source = { height: bitmap.height, width: bitmap.width };
+    const out = outputSize(recipe, source);
+    const tooLarge = surfaceRefusal(out);
+    if (tooLarge !== null) {
+      return { ok: false, reason: tooLarge };
+    }
+    /* A crop outside the bitmap draws nothing and encodes a blank image that passes every check
+       below, so a crop made against bytes that have since changed stops here. */
+    const stored = cropOf(recipe, source);
+    if (
+      stored.x < 0 ||
+      stored.y < 0 ||
+      stored.x + stored.width > source.width ||
+      stored.y + stored.height > source.height
+    ) {
+      return {
+        ok: false,
+        reason: "The crop no longer fits this image, which changed after the edit began.",
+      };
+    }
+    const canvas = new Offscreen(out.width, out.height);
+    const ctx = canvas.getContext("2d");
+    if (ctx === null) {
+      return { ok: false, reason: "The browser would not give the editor a drawing surface." };
+    }
+    ctx.imageSmoothingEnabled = true;
+    ctx.imageSmoothingQuality = "high";
+    ctx.filter = filterString(recipe) || "none";
+    /* Centre, mirror, then turn — applied to points in the reverse order, so a point is turned
+       first and mirrored in the frame the author sees, which is what the recipe's flips mean. */
+    ctx.translate(out.width / 2, out.height / 2);
+    ctx.scale(recipe.flipH ? -1 : 1, recipe.flipV ? -1 : 1);
+    ctx.rotate((recipe.turns * Math.PI) / 2);
+    const crop = cropOf(recipe, source);
+    // In the pre-turn frame the destination is the output with its sides swapped back.
+    const width = swapsAxes(recipe.turns) ? out.height : out.width;
+    const height = swapsAxes(recipe.turns) ? out.width : out.height;
+    ctx.drawImage(
+      bitmap,
+      crop.x,
+      crop.y,
+      crop.width,
+      crop.height,
+      -width / 2,
+      -height / 2,
+      width,
+      height,
+    );
+    const blob = await canvas.convertToBlob(
+      takesQuality(mime) ? { quality: recipe.quality / 100, type: mime } : { type: mime },
+    );
+    if (blob.type !== mime) {
+      return {
+        ok: false,
+        reason: `The browser encoded ${blob.type || "an unknown type"} when asked for ${mime}, and those bytes would not be what the file's extension promises.`,
+      };
+    }
+    if (blob.size < MIN_ENCODED_BYTES) {
+      return {
+        ok: false,
+        reason: `The browser produced ${blob.size} bytes, which is not an image. Nothing was written.`,
+      };
+    }
+    return { blob, ok: true, size: out };
+  } finally {
+    // The one full-resolution allocation, released as soon as the draw no longer needs it.
+    bitmap.close();
+  }
+}