@cardinali-studio/adminkit 2.2.21 → 2.2.23

package/dist/form/media/media-model.js

@@ -1,3 +1,11 @@
+export function mediaAltStatus(file, locales) {
+    if (file.alt?.decorative)
+        return "decorative";
+    const texts = file.alt?.texts ?? {};
+    return locales.every((locale) => typeof texts[locale] === "string" && texts[locale].trim())
+        ? "described"
+        : "missing";
+}
 /** L'unico dominio su cui "Seleziona tutto" e la relativa checkbox possono ragionare. */
 export function mediaSelectableItems({ mode, prefix, shown, subfolders, }) {
     const visibleFolders = mode === "manage" && prefix !== ""

package/dist/form/media/useMediaLibrary.d.ts

@@ -1,4 +1,4 @@
-import { api, type AssetFile, type AssetFolder } from "../../api.js";
+import { api, type AssetAltText, type AssetFile, type AssetFolder } from "../../api.js";
 import type { MediaOperationStatus } from "../../media.js";
 import { type MediaUploadJob } from "./media-upload-queue.js";
 /** D1 registra l'intera cancellazione nel preflight: non esistono né il token Git né i
@@ -7,9 +7,12 @@ import { type MediaUploadJob } from "./media-upload-queue.js";
 export declare function deleteMediaKeys(keys: string[], remove: typeof api.remove, onProgress?: (done: number) => void): Promise<{
     done: number;
     refsToken?: string;
+    operationId?: string;
+    requiresPublication?: boolean;
 }>;
-export type MediaOperationState = "idle" | "planning" | "awaiting_confirmation" | "moving" | "deleting" | "renaming" | "creating_folder" | "journal";
+export type MediaOperationState = "idle" | "planning" | "awaiting_confirmation" | "moving" | "deleting" | "renaming" | "creating_folder" | "saving_alt" | "journal";
 export type SortKey = "uploaded" | "capturedAt" | "name" | "size";
+export type AltFilter = "all" | "missing" | "described" | "decorative";
 export declare const SORT_LABELS: Record<SortKey, string>;
 export interface MediaLibrary {
     mode: "manage" | "pick";
@@ -39,6 +42,9 @@ export interface MediaLibrary {
     } | null;
     sortKey: SortKey;
     sortDir: "asc" | "desc";
+    altFilter: AltFilter;
+    altLocales: readonly string[];
+    defaultAltLocale: string;
     uploadDraft: {
         files: File[];
         destination: string | null;
@@ -55,6 +61,7 @@ export interface MediaLibrary {
     setAll(on: boolean): void;
     setSort(k: SortKey): void;
     flipDir(): void;
+    setAltFilter(filter: AltFilter): void;
     /** Accoda lo STESSO lavoro usato da Media. `destination` è esplicita nel picker; in gestione
      * il ripiego resta la cartella aperta, che è il comportamento storico. */
     upload(files: File[] | FileList, destination?: string): Promise<string | null>;
@@ -63,6 +70,7 @@ export interface MediaLibrary {
     setUploadFiles(files: File[] | FileList): void;
     setUploadDestination(destination: string | null): void;
     setAutoWebp(on: boolean): Promise<void>;
+    saveAlt(key: string, alt: AssetAltText): Promise<boolean>;
     view(i: number | null): void;
     step(delta: number): void;
     /** File e cartelle insieme: una cartella si riconosce dalla chiave, che finisce con "/". */
@@ -76,6 +84,7 @@ export interface MediaLibrary {
     /** Cestina la cartella e tutto ciò che contiene. */
     removeFolder(prefix: string): Promise<void>;
     resumeMedia(operation: MediaOperationStatus): Promise<void>;
+    publishMedia(operation: MediaOperationStatus): Promise<void>;
     cancelMedia(operation: MediaOperationStatus): Promise<void>;
     /** Il nome da mostrare per un prefisso: l'etichetta se c'è, altrimenti lo slug. */
     labelOf(prefix: string): string;

package/dist/form/media/useMediaLibrary.js

@@ -11,9 +11,9 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { api, ApiError } from "../../api.js";
 import { storageKey } from "../../config.js";
-import { contentPersistenceMode } from "../../app/site.js";
+import { contentPersistenceMode, site } from "../../app/site.js";
 import { startMediaUpload, useMediaUploadCompletions, useMediaUploads, } from "./media-upload-queue.js";
-import { invalidMediaMoveReason, isValidMediaMoveDestination, mediaFolderSlug, mediaSelectableItems, mediaSelectionState, normalizeMediaSelection, summarizeMediaSelection, tryBeginMediaMutation, } from "./media-model.js";
+import { invalidMediaMoveReason, isValidMediaMoveDestination, mediaFolderSlug, mediaAltStatus, mediaSelectableItems, mediaSelectionState, normalizeMediaSelection, summarizeMediaSelection, tryBeginMediaMutation, } from "./media-model.js";
 import { executeMediaMovePlan, mediaMoveConfirmation, mediaMoveNeedsConfirmation, } from "./media-move.js";
 /* Quanti file per richiesta nelle operazioni lunghe (cestina, sposta). Ogni file costa al
  * server tre operazioni su R2 — legge, riscrive altrove, cancella — su oggetti da qualche MB.
@@ -29,7 +29,11 @@ export async function deleteMediaKeys(keys, remove, onProgress = () => { }) {
     if (preflight.d1 === true) {
         const done = preflight.trashed ?? keys.length;
         onProgress(done);
-        return { done };
+        return {
+            done,
+            operationId: preflight.operationId,
+            requiresPublication: preflight.requiresPublication === true,
+        };
     }
     if (!preflight.refsToken) {
         throw new Error("Il server non ha confermato la verifica dei riferimenti.");
@@ -92,6 +96,9 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
     // tutti i giorni non ha motivo di azzerarsi per una riorganizzazione dei sorgenti.
     const [sortKey, setSortKey] = useState(() => localStorage.getItem(storageKey("sortKey")) || "uploaded");
     const [sortDir, setSortDir] = useState(() => localStorage.getItem(storageKey("sortDir")) || "desc");
+    const [altFilter, setAltFilter] = useState("all");
+    const altLocales = site().languages?.available ?? ["default"];
+    const defaultAltLocale = site().languages?.default ?? "default";
     /* I nomi per esteso già visti. Servono al percorso in alto: dentro `food/piatti-2024/`
      * l'elenco delle cartelle non contiene più né l'una né l'altra — `folders` ha il primo livello
      * e `subfolders` i FIGLI di dove sei — quindi senza memoria il percorso mostrerebbe gli slug,
@@ -230,13 +237,16 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
         return () => removeEventListener("beforeunload", warn);
     }, [progress]);
     const shown = useMemo(() => {
-        const list = mode === "pick" ? files.filter((f) => (f.type ?? "").startsWith("image/")) : files.slice();
+        let list = mode === "pick" ? files.filter((f) => (f.type ?? "").startsWith("image/")) : files.slice();
+        if (mode === "manage" && altFilter !== "all") {
+            list = list.filter((file) => (file.type ?? "").startsWith("image/") && mediaAltStatus(file, altLocales) === altFilter);
+        }
         const dir = sortDir === "asc" ? 1 : -1;
         return list.sort((a, b) => {
             const x = a[sortKey] ?? "", y = b[sortKey] ?? "";
             return (x < y ? -1 : x > y ? 1 : 0) * dir;
         });
-    }, [files, sortKey, sortDir, mode]);
+    }, [files, sortKey, sortDir, mode, altFilter, altLocales]);
     const selectableItems = useMemo(() => mediaSelectableItems({ mode, prefix, shown, subfolders }), [mode, prefix, shown, subfolders]);
     const selectableIds = useMemo(() => selectableItems.map((item) => item.id), [selectableItems]);
     const selectableIdSet = useMemo(() => new Set(selectableIds), [selectableIds]);
@@ -326,6 +336,29 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
             setSettingsBusy(false);
         }
     }, [autoWebp]);
+    const saveAlt = useCallback(async (key, alt) => {
+        if (!beginMutation("saving_alt"))
+            return false;
+        setBusy(true);
+        setError(null);
+        try {
+            const result = await api.saveMediaAlt(key, alt);
+            setFiles((current) => current.map((file) => file.key === key ? { ...file, alt: result.alt } : file));
+            /* Se si sta facendo audit dei mancanti, al salvataggio la foto può uscire dal filtro:
+             * chiudere il visore evita che il suo indice finisca per indicare la foto successiva. */
+            if (altFilter !== "all")
+                setViewing(null);
+            return true;
+        }
+        catch (error) {
+            setError(error instanceof ApiError ? error.message : String(error));
+            return false;
+        }
+        finally {
+            setBusy(false);
+            endMutation();
+        }
+    }, [altFilter, beginMutation, endMutation]);
     const labelOf = useCallback((p) => {
         const f = folders.find((x) => x.prefix === p) ?? subfolders.find((x) => x.prefix === p);
         return f?.label || seenLabels.current[p] || p.replace(/\/$/, "").split("/").pop() || "";
@@ -411,21 +444,17 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
                 throw new Error("Prima di eliminare queste foto devi sostituirle nel contenuto:\n"
                     + u.blockers.map((b) => `• ${b.label}: ${b.reason}`).join("\n"));
             }
-            /* LA RIGA IN PIÙ QUANDO LE FOTO SONO IN USO, e non è pignoleria.
-             *
-             * Le foto stanno nel bucket, che è uno solo: non esiste una versione "in bozza" di un
-             * file. Eliminarne una la toglie SUBITO dal sito pubblicato, mentre la ripulitura dei
-             * riferimenti nelle pagine resta sulla bozza finché non si pubblica — quindi per quel
-             * tempo le pagine online chiedono una foto che non c'è più.
-             *
-             * La finestra esisteva anche prima (durava la build, un paio di minuti); ora dura fino
-             * alla pubblicazione, cioè quanto decide chi sta lavorando. Non si aggiunge macchinario
-             * per chiuderla: si dice, e si dice SOLO quando è vero — un avviso che compare sempre
-             * smette di essere letto, e allora non avvisa più di niente. */
+            /* Quando una foto è online la conferma deve descrivere l'intera operazione: Admin
+             * pubblicherà una revisione isolata delle sole pagine coinvolte e toccherà il file
+             * soltanto dopo. Sostituire prima resta la strada raccomandata perché una rimozione
+             * valida per lo schema può comunque cambiare l'impaginazione. */
             const msg = u.count
-                ? `Eliminare ${quante}?\n\nATTENZIONE: ${u.count} di queste foto sono usate in: ${u.pages.join(", ")}.\n`
-                    + `I riferimenti verranno rimossi da quelle sorgenti.\n\n`
-                    + `Le foto spariscono subito dal sito online; le pagine si sistemano quando pubblichi.`
+                ? `Eliminare ${quante}?\n\n${u.count === 1 ? "Una delle immagini è utilizzata" : `${u.count} immagini sono utilizzate`} in:\n`
+                    + u.pages.map((page) => `• ${page}`).join("\n")
+                    + `\n\nAdmin rimuoverà le immagini da queste pagine e pubblicherà automaticamente soltanto questa modifica. `
+                    + `Gallerie, griglie o sezioni potrebbero cambiare impaginazione.\n\n`
+                    + `Ti consigliamo di annullare e sostituire prima le immagini nelle pagine indicate. `
+                    + `Confermando, procederai comunque con la rimozione e la pubblicazione.`
                 : `Eliminare ${quante}?`;
             if (!confirm(`${msg}\n\nLe foto vanno nel cestino e si possono recuperare.`))
                 return;
@@ -435,6 +464,18 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
                 const result = await deleteMediaKeys(keys, api.remove, (done) => setProgress({ done, total: keys.length, verb: "Cestino" }));
                 refsToken = result.refsToken;
                 const done = result.done;
+                if (result.operationId && result.requiresPublication) {
+                    setProgress({ done: keys.length, total: keys.length, verb: "Pubblico" });
+                    try {
+                        await api.contentPublishMedia(result.operationId);
+                    }
+                    catch (error) {
+                        const apiError = error;
+                        failure = apiError.code === "deployment_lane_busy" || apiError.code === "release_in_progress"
+                            ? "C'è già una pubblicazione in corso. L'eliminazione è al sicuro: usa «Riprova pubblicazione» quando termina."
+                            : `Eliminazione preparata, ma la pubblicazione non è partita: ${apiError.message}`;
+                    }
+                }
                 if (done < keys.length) {
                     failure = `Cestinate ${done} foto su ${keys.length}: le altre sono ancora lì, riprova.`;
                 }
@@ -641,9 +682,27 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
     }, [prefix, load, moveFolder, beginMutation, endMutation]);
     /** Cestina una cartella con tutto quello che contiene. È `remove` con una lista di uno. */
     const removeFolder = useCallback((target) => remove([target]), [remove]);
-    const resumeMedia = useCallback(async (operation) => {
-        if (!operation.releaseId)
+    const publishMedia = useCallback(async (operation) => {
+        if (!beginMutation("journal"))
             return;
+        setBusy(true);
+        setError(null);
+        let failure = null;
+        try {
+            await api.contentPublishMedia(operation.operationId);
+        }
+        catch (e) {
+            failure = e instanceof ApiError ? e.message : String(e);
+        }
+        finally {
+            setBusy(false);
+            await load(prefix);
+            endMutation();
+            if (failure)
+                setError(`Pubblicazione Media non riuscita: ${failure}`);
+        }
+    }, [beginMutation, endMutation, load, prefix]);
+    const resumeMedia = useCallback(async (operation) => {
         if (!beginMutation("journal"))
             return;
         setBusy(true);
@@ -697,7 +756,8 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
         mode, multiple, prefix, folders, subfolders, shown, selected, selectableIds,
         selectedFiles: selectionSummary.files, selectedFolders: selectionSummary.folders,
         allSelected, someSelected, busy, mutating, operationState, error, mediaOperations, progress,
-        sortKey, sortDir, uploadDraft, pickUploadJob, viewing, autoWebp, settingsBusy,
+        sortKey, sortDir, altFilter, altLocales, defaultAltLocale,
+        uploadDraft, pickUploadJob, viewing, autoWebp, settingsBusy,
         go: (p) => { if (!mutationRef.current)
             void load(p); },
         reload: () => { if (!mutationRef.current)
@@ -705,6 +765,11 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
         toggle, setAll,
         setSort: setSortKey,
         flipDir: () => setSortDir((d) => (d === "asc" ? "desc" : "asc")),
+        setAltFilter: (filter) => {
+            setAltFilter(filter);
+            setSelected(new Set());
+            setViewing(null);
+        },
         upload,
         openUpload: (files = [], destination) => {
             if (mutationRef.current)
@@ -718,12 +783,12 @@ export function useMediaLibrary({ mode, multiple = true, active = true, remember
             setUploadDraft(null); },
         setUploadFiles: (files) => setUploadDraft((draft) => (draft ? { ...draft, files: Array.from(files) } : draft)),
         setUploadDestination: (destination) => setUploadDraft((draft) => (draft ? { ...draft, destination } : draft)),
-        setAutoWebp,
+        setAutoWebp, saveAlt,
         view: setViewing,
         step,
         move,
         canMoveTo: (ids, dest) => !mutationRef.current && isValidMediaMoveDestination(ids, dest),
-        remove, newFolder, renameFolder, removeFolder, resumeMedia, cancelMedia, labelOf,
+        remove, newFolder, renameFolder, removeFolder, resumeMedia, publishMedia, cancelMedia, labelOf,
         clearError: () => setError(null),
     };
 }

package/dist/functions/_shared/d1-media.js

@@ -5,15 +5,11 @@ import {
   canonicalChecksum, canonicalJson, contentSaveRequestChecksum, D1ContentRepository,
 } from "../../persistence.js";
 import {
-  D1MediaOperationRepository, prepareMediaCopy,
+  D1MediaOperationRepository, mediaPublicUrl, prepareMediaCopy, rewriteMediaValue,
 } from "../../media.js";
 import { validateContentDocument } from "../site.js";
 import { isKey, moveToTrash, sanitizeName } from "./assets.js";
 
-const MEDIA_PREFIX = "/media/";
-
-function mediaUrl(key) { return MEDIA_PREFIX + key.split("/").map(encodeURIComponent).join("/"); }
-
 function editor(data) {
   const payload = data?.cloudflareAccess?.JWT?.payload;
   if (!payload?.sub) throw new Error("unauthenticated");
@@ -26,67 +22,7 @@ function operationId(value) {
   return value;
 }
 
-function replaceBoundedUrl(value, from, to) {
-  let cursor = 0;
-  let next = "";
-  while (cursor < value.length) {
-    const found = value.indexOf(from, cursor);
-    if (found < 0) return next + value.slice(cursor);
-    const after = value[found + from.length];
-    /* A media key is a path, not a string prefix. Query/fragment suffixes and
-     * further URL/path characters belong to a different reference and must
-     * not be rewritten accidentally. */
-    if (after && /[A-Za-z0-9._~%!$&'()*+,;=:@/?#-]/.test(after)) {
-      next += value.slice(cursor, found + from.length);
-      cursor = found + from.length;
-      continue;
-    }
-    next += value.slice(cursor, found) + to;
-    cursor = found + from.length;
-  }
-  return next;
-}
-
-function replaceText(value, replacements, removals) {
-  let next = value;
-  for (const [from, to] of Object.entries(replacements)) next = replaceBoundedUrl(next, from, to);
-  for (const from of removals) next = replaceBoundedUrl(next, from, "");
-  return next;
-}
-
-/** JSON Media values are intentionally rewritten only as complete public URLs
- * (or a URL embedded in Markdown). Arrays lose an exact removed URL; scalar
- * slots become empty strings and are then validated by the site's schema. */
-function rewriteValue(value, replacements, removals, inArray = false) {
-  if (typeof value === "string") {
-    if (removals.has(value) && inArray) return { changed: true, removed: true };
-    const next = replaceText(value, replacements, removals);
-    return { changed: next !== value, value: next };
-  }
-  if (Array.isArray(value)) {
-    let changed = false;
-    const next = [];
-    for (const item of value) {
-      const result = rewriteValue(item, replacements, removals, true);
-      changed ||= result.changed;
-      if (!result.removed) next.push(result.value);
-    }
-    return { changed, value: next };
-  }
-  if (value && typeof value === "object") {
-    let changed = false;
-    const next = {};
-    for (const [key, item] of Object.entries(value)) {
-      const result = rewriteValue(item, replacements, removals, false);
-      changed ||= result.changed;
-      if (!result.removed) next[key] = result.value;
-    }
-    return { changed, value: next };
-  }
-  return { changed: false, value };
-}
-
-async function effectiveDocuments(db) {
+async function mediaDocuments(db) {
   return ((await db.prepare(`SELECT document.document_id AS documentId, document.kind, document.locale,
     document.draft_revision_id AS draftRevisionId, published.revision_id AS publishedRevisionId,
     draft.payload_json AS draftPayload, draft.is_tombstone AS draftTombstone,
@@ -101,16 +37,33 @@ async function effectiveDocuments(db) {
 }
 
 async function rewriteDocuments({ db, data, replacements = {}, removals = [] }) {
-  const replacementUrls = Object.fromEntries(Object.entries(replacements).map(([from, to]) => [mediaUrl(from), mediaUrl(to)]));
-  const removalUrls = new Set(removals.map(mediaUrl));
   const commands = [];
-  for (const row of await effectiveDocuments(db)) {
-    const useDraft = row.draftRevisionId !== null;
-    const raw = useDraft ? row.draftPayload : row.publishedPayload;
-    if (!raw || (useDraft ? row.draftTombstone : row.publishedTombstone)) continue;
-    let payload;
-    try { payload = JSON.parse(raw); } catch { throw new Error("invalid_document"); }
-    const rewritten = rewriteValue(payload, replacementUrls, removalUrls);
+  const publishedDocuments = [];
+  for (const row of await mediaDocuments(db)) {
+    /* Validate the exact published patch now, before the operation can become
+     * ready. Publication later starts from this same immutable release side,
+     * never from an unrelated editorial draft. */
+    if (row.publishedPayload && !row.publishedTombstone) {
+      let publishedPayload;
+      try { publishedPayload = JSON.parse(row.publishedPayload); } catch { throw new Error("invalid_document"); }
+      const published = rewriteMediaValue(publishedPayload, { replacements, removals });
+      if (published.changed) {
+        validateContentDocument({
+          documentId: row.documentId, kind: row.kind, locale: row.locale, schemaVersion: row.schemaVersion,
+          tombstone: false, payload: published.value,
+        });
+        publishedDocuments.push({ documentId: row.documentId, kind: row.kind });
+      }
+    }
+
+    /* Existing drafts keep every unrelated edit but must not be able to
+     * reintroduce a source after the isolated Media release. No draft is
+     * manufactured when none existed: the detached published patch owns that
+     * side of the operation. */
+    if (row.draftRevisionId === null || !row.draftPayload || row.draftTombstone) continue;
+    let draftPayload;
+    try { draftPayload = JSON.parse(row.draftPayload); } catch { throw new Error("invalid_document"); }
+    const rewritten = rewriteMediaValue(draftPayload, { replacements, removals });
     if (!rewritten.changed) continue;
     const normalized = validateContentDocument({
       documentId: row.documentId, kind: row.kind, locale: row.locale, schemaVersion: row.schemaVersion,
@@ -118,14 +71,14 @@ async function rewriteDocuments({ db, data, replacements = {}, removals = [] })
     });
     commands.push({
       revisionId: crypto.randomUUID(), documentId: row.documentId,
-      baseRevisionId: useDraft ? row.draftRevisionId : row.publishedRevisionId,
+      baseRevisionId: row.draftRevisionId,
       expectedDraftRevisionId: row.draftRevisionId, kind: row.kind, locale: row.locale,
       schemaVersion: row.schemaVersion, tombstone: false, payload: normalized.payload,
     });
   }
   /* Nessun riferimento è un esito valido: l'operazione Media deve proseguire
    * senza costruire una transazione editoriale vuota, che `saveMany` rifiuta. */
-  if (!commands.length) return { documents: [] };
+  if (!commands.length) return { documents: [], publishedDocuments };
   const who = editor(data);
   const repository = new D1ContentRepository(db);
   /* Every command was fully parsed and site-validated before the first write.
@@ -136,7 +89,10 @@ async function rewriteDocuments({ db, data, replacements = {}, removals = [] })
     ...command, payloadChecksum: await canonicalChecksum(command.payload), requestChecksum: await contentSaveRequestChecksum(command),
     now, authorSubject: who.subject, authorLabel: who.label,
   }))));
-  return { documents: commands.map((command) => ({ documentId: command.documentId, kind: command.kind })) };
+  return {
+    documents: commands.map((command) => ({ documentId: command.documentId, kind: command.kind })),
+    publishedDocuments,
+  };
 }
 
 function keys(input) {
@@ -205,14 +161,22 @@ export async function d1MoveMedia({ env, data, body }) {
     const stored = await journal.entries(id);
     return {
       operationId: id, repeated: true, moved: stored.length,
-      urlMap: Object.fromEntries(stored.filter((entry) => entry.destinationKey).map((entry) => [mediaUrl(entry.sourceKey), mediaUrl(entry.destinationKey)])),
-      documents: [],
+      urlMap: Object.fromEntries(stored.filter((entry) => entry.destinationKey).map((entry) => [mediaPublicUrl(entry.sourceKey), mediaPublicUrl(entry.destinationKey)])),
+      documents: [], publishedDocuments: [], requiresPublication: true,
     };
   }
   try {
     for (const entry of entries) await prepareMediaCopy({ bucket: env.MEDIA, journal, operationId: id, entryId: entry.entryId, sourceKey: entry.sourceKey, destinationKey: entry.destinationKey, now: Date.now() });
     const rewritten = await rewriteDocuments({ db: env.CONTENT_DB, data, replacements: Object.fromEntries(entries.map((entry) => [entry.sourceKey, entry.destinationKey])) });
-    return { operationId: id, repeated: false, moved: entries.length, urlMap: Object.fromEntries(entries.map((entry) => [mediaUrl(entry.sourceKey), mediaUrl(entry.destinationKey)])), documents: rewritten.documents };
+    const immediate = rewritten.publishedDocuments.length
+      ? { requiresPublication: true }
+      : await finalizeUnpublishedD1MediaOperation({ env, operationId: id });
+    return {
+      operationId: id, repeated: false, moved: entries.length,
+      urlMap: Object.fromEntries(entries.map((entry) => [mediaPublicUrl(entry.sourceKey), mediaPublicUrl(entry.destinationKey)])),
+      documents: rewritten.documents, publishedDocuments: rewritten.publishedDocuments,
+      ...immediate,
+    };
   } catch (error) {
     await journal.cancel(id, Date.now()).catch(() => null);
     throw error;
@@ -225,12 +189,22 @@ export async function d1DeleteMedia({ env, data, body }) {
   const id = operationId(body.operationId);
   const entries = sourceKeys.map((sourceKey) => ({ entryId: crypto.randomUUID(), sourceKey }));
   const { journal, created } = await createOperation({ db: env.CONTENT_DB, data, type: "delete", id, entries, clientChecksum: body.requestChecksum });
-  if (created === "repeated") return { operationId: id, repeated: true, trashed: (await journal.entries(id)).length, documents: [] };
+  if (created === "repeated") return {
+    operationId: id, repeated: true, trashed: (await journal.entries(id)).length,
+    documents: [], publishedDocuments: [], requiresPublication: true,
+  };
   try {
     const inspected = await Promise.all(entries.map((entry) => inspectSource(env.MEDIA, entry)));
     const rewritten = await rewriteDocuments({ db: env.CONTENT_DB, data, removals: sourceKeys });
     for (const entry of inspected) await journal.readyDeleteEntry({ ...entry, operationId: id, now: Date.now() });
-    return { operationId: id, repeated: false, trashed: entries.length, documents: rewritten.documents };
+    const immediate = rewritten.publishedDocuments.length
+      ? { requiresPublication: true }
+      : await finalizeUnpublishedD1MediaOperation({ env, operationId: id });
+    return {
+      operationId: id, repeated: false, trashed: entries.length,
+      documents: rewritten.documents, publishedDocuments: rewritten.publishedDocuments,
+      ...immediate,
+    };
   } catch (error) {
     await journal.cancel(id, Date.now()).catch(() => null);
     throw error;
@@ -246,28 +220,42 @@ export async function d1PendingSourceKeys(db) {
 export async function d1MediaUsage(db, sourceKeys) {
   const keys = [...new Set(sourceKeys.filter(isKey))];
   if (!keys.length) return { usage: {}, pages: [], count: 0, selectedCount: 0, blockers: [] };
-  const rows = (await db.prepare(`SELECT document.kind, document.document_id AS documentId, revision.payload_json AS payload
+  const rows = (await db.prepare(`SELECT document.kind, document.document_id AS documentId,
+      revision.payload_json AS payload, 0 AS locationRank
     FROM content_documents document
     JOIN content_revisions revision ON revision.document_id = document.document_id AND revision.revision_id = document.draft_revision_id
     UNION
-    SELECT document.kind, document.document_id AS documentId, revision.payload_json AS payload
+    SELECT document.kind, document.document_id AS documentId,
+      revision.payload_json AS payload, 1 AS locationRank
     FROM content_site_state state
     JOIN content_release_entries entry ON entry.release_id = state.current_release_id
     JOIN content_documents document ON document.document_id = entry.document_id
     JOIN content_revisions revision ON revision.document_id = entry.document_id AND revision.revision_id = entry.revision_id
     UNION
-    SELECT document.kind, document.document_id AS documentId, revision.payload_json AS payload
+    SELECT document.kind, document.document_id AS documentId,
+      revision.payload_json AS payload, 2 AS locationRank
     FROM content_releases release
     JOIN content_release_entries entry ON entry.release_id = release.release_id
     JOIN content_documents document ON document.document_id = entry.document_id
     JOIN content_revisions revision ON revision.document_id = entry.document_id AND revision.revision_id = entry.revision_id
-    WHERE release.status = 'publishing'`).all()).results ?? [];
+    WHERE release.status = 'publishing'
+    ORDER BY locationRank, documentId`).all()).results ?? [];
   const usage = {};
   const pages = new Set();
   for (const key of keys) {
-    const url = mediaUrl(key);
-    const locations = [...new Set(rows.filter((row) => typeof row.payload === "string" && row.payload.includes(url))
-      .map((row) => `${row.kind} · ${row.documentId}`))];
+    const url = mediaPublicUrl(key);
+    const documents = new Map();
+    for (const row of rows) {
+      if (documents.has(row.documentId) || typeof row.payload !== "string" || !row.payload.includes(url)) continue;
+      let payload;
+      try { payload = JSON.parse(row.payload); } catch { payload = null; }
+      const candidate = payload && typeof payload === "object" && !Array.isArray(payload)
+        ? [payload.title, payload.name, payload.label, payload.slug]
+          .find((value) => typeof value === "string" && value.trim())
+        : null;
+      documents.set(row.documentId, candidate ? String(candidate).trim().slice(0, 200) : `${row.kind} · ${row.documentId}`);
+    }
+    const locations = [...documents.values()];
     if (locations.length) { usage[key] = locations; locations.forEach((location) => pages.add(location)); }
   }
   return { usage, pages: [...pages], count: Object.keys(usage).length, selectedCount: keys.length, blockers: [] };
@@ -302,10 +290,36 @@ export async function finalizeD1MediaRelease({ env, releaseId, now = Date.now()
   return { completed, failed };
 }
 
+async function finalizeUnpublishedD1MediaOperation({ env, operationId: id, now = Date.now(), resume = false }) {
+  if (!env.CONTENT_DB || !env.MEDIA) throw new Error("content_unavailable");
+  const journal = new D1MediaOperationRepository(env.CONTENT_DB);
+  if (resume) await journal.resumeUnboundFinalization(id, now);
+  else if (!await journal.beginUnpublishedFinalization(id, now)) return { requiresPublication: true, completed: 0, failed: 0 };
+  const entries = await journal.unboundFinalizationWork(id);
+  let completed = 0;
+  let failed = 0;
+  for (const entry of entries) {
+    try {
+      if (entry.type === "delete") await moveToTrash(env.MEDIA, entry.sourceKey);
+      else await env.MEDIA.delete(entry.sourceKey);
+      await journal.recordFinalizedEntry({ operationId: id, entryId: entry.entryId, now, outcome: "completed" });
+      completed += 1;
+    } catch {
+      await journal.recordFinalizedEntry({
+        operationId: id, entryId: entry.entryId, now, outcome: "failed",
+        safeError: "La pulizia del Media verrà ritentata.",
+      });
+      failed += 1;
+    }
+  }
+  return { requiresPublication: false, completed, failed };
+}
+
 export async function resumeD1MediaOperation({ env, data, operationId: id, releaseId }) {
   if (!env.CONTENT_DB || !env.MEDIA) throw new Error("content_unavailable");
   editor(data);
-  if (typeof id !== "string" || typeof releaseId !== "string") throw new Error("invalid_media_operation");
+  if (typeof id !== "string" || !(releaseId === null || releaseId === undefined || typeof releaseId === "string")) throw new Error("invalid_media_operation");
+  if (!releaseId) return finalizeUnpublishedD1MediaOperation({ env, operationId: id, now: Date.now(), resume: true });
   const journal = new D1MediaOperationRepository(env.CONTENT_DB);
   await journal.resumeFinalization(id, releaseId, Date.now());
   return finalizeD1MediaRelease({ env, releaseId, now: Date.now() });

package/dist/functions/_shared/media-alt.js

@@ -0,0 +1,61 @@
+/* Testi alternativi associati al file Media.
+ *
+ * Vivono nei custom metadata dell'oggetto R2: in questo modo seguono già le copie usate da
+ * spostamento, cestino e ripristino, senza una seconda tabella da tenere sincronizzata con le
+ * chiavi del bucket. Il valore è JSON perché R2 accetta solo stringhe nei custom metadata.
+ */
+
+export const MEDIA_ALT_METADATA_KEY = "adminkitAlt";
+export const MEDIA_UPLOADED_METADATA_KEY = "adminkitUploadedAt";
+
+const EMPTY = Object.freeze({ decorative: false, texts: Object.freeze({}) });
+
+export function altLocales(languageConfig) {
+  return languageConfig?.available?.length ? [...languageConfig.available] : ["default"];
+}
+
+/** Legge in modo difensivo anche metadati scritti da una versione futura o incompleta. */
+export function mediaAltFromMetadata(customMetadata, locales = null) {
+  const raw = customMetadata?.[MEDIA_ALT_METADATA_KEY];
+  if (!raw) return EMPTY;
+  let value;
+  try { value = JSON.parse(raw); } catch { return EMPTY; }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return EMPTY;
+  const allowed = locales ? new Set(locales) : null;
+  const texts = {};
+  if (value.texts && typeof value.texts === "object" && !Array.isArray(value.texts)) {
+    for (const [locale, text] of Object.entries(value.texts)) {
+      if ((!allowed || allowed.has(locale)) && typeof text === "string" && text.trim()) {
+        texts[locale] = text.trim();
+      }
+    }
+  }
+  return { decorative: value.decorative === true, texts };
+}
+
+/** Valida il comando editoriale. Il limite è solo tecnico (dimensione dei metadata R2), non
+ * una falsa regola SEO: l'interfaccia non impone un maxlength al testo. */
+export function normalizeMediaAlt(value, locales) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.decorative !== "boolean") {
+    throw new Error("invalid_media_alt");
+  }
+  if (!value.texts || typeof value.texts !== "object" || Array.isArray(value.texts)) {
+    throw new Error("invalid_media_alt");
+  }
+  const allowed = new Set(locales);
+  const texts = {};
+  for (const [locale, text] of Object.entries(value.texts)) {
+    if (!allowed.has(locale) || typeof text !== "string") throw new Error("invalid_media_alt");
+    const normalized = text.trim();
+    if (normalized) texts[locale] = normalized;
+  }
+  const result = { decorative: value.decorative, texts: value.decorative ? {} : texts };
+  if (new TextEncoder().encode(JSON.stringify(result)).byteLength > 1600) {
+    throw new Error("media_alt_too_large");
+  }
+  return result;
+}
+
+export function mediaAltMetadataValue(value) {
+  return value.decorative || Object.keys(value.texts).length ? JSON.stringify(value) : null;
+}