Wallpaper from Library: CORP + shell-token wallpaper path, image thumbnails, Set as Desktop Background

capsules/home-gui/browser/home-gui.js

@@ -18,6 +18,7 @@ import {
   toolbarInboxButton,
   toolbarSignOutButton,
   ensureHomeGuiDom,
+  fetchBlob,
   initializeRecentTargets,
   initializeShellLayout,
   rememberSharedUiPreferences,
@@ -900,11 +901,52 @@ export function syncHomeGuiAppearance(summary) {
   }
   desktopBackdrop.dataset.overlay = overlayEnabled ? "true" : "false";
   desktopBackdrop.style.setProperty("--desktop-overlay-opacity", String(overlayOpacity));
+  void applyDesktopWallpaper(imageUrl);
+}
+
+// The summary URL carries `v=` so it changes whenever the user uploads or
+// resets the image; that string is the cache key for the loaded object URL.
+const wallpaperLoad = { sourceUrl: "", objectUrl: "" };
+
+function clearDesktopWallpaper() {
+  desktopBackdrop.style.removeProperty("--desktop-wallpaper");
+  if (wallpaperLoad.objectUrl) {
+    URL.revokeObjectURL(wallpaperLoad.objectUrl);
+  }
+  wallpaperLoad.objectUrl = "";
+}
+
+async function applyDesktopWallpaper(imageUrl) {
+  if (wallpaperLoad.sourceUrl === imageUrl) {
+    return;
+  }
+  wallpaperLoad.sourceUrl = imageUrl;
   if (!imageUrl) {
-    desktopBackdrop.style.removeProperty("--desktop-wallpaper");
+    clearDesktopWallpaper();
     return;
   }
-  desktopBackdrop.style.setProperty("--desktop-wallpaper", `url("${imageUrl}")`);
+  let objectUrl = "";
+  try {
+    objectUrl = URL.createObjectURL(await fetchBlob(imageUrl));
+  } catch (error) {
+    // Fail closed to the default wallpaper instead of a broken image. The
+    // source URL stays recorded so summary refreshes do not retry until the
+    // Runtime advertises a new image version.
+    if (wallpaperLoad.sourceUrl === imageUrl) {
+      clearDesktopWallpaper();
+    }
+    console.warn("home-gui wallpaper unavailable", error);
+    return;
+  }
+  if (wallpaperLoad.sourceUrl !== imageUrl) {
+    URL.revokeObjectURL(objectUrl);
+    return;
+  }
+  if (wallpaperLoad.objectUrl) {
+    URL.revokeObjectURL(wallpaperLoad.objectUrl);
+  }
+  wallpaperLoad.objectUrl = objectUrl;
+  desktopBackdrop.style.setProperty("--desktop-wallpaper", `url("${objectUrl}")`);
 }
 
 function targetsChanged(previous, next) {

capsules/home-gui/browser/shell-core.js

@@ -287,6 +287,23 @@ export async function fetchJson(url, init) {
   return response.json();
 }
 
+/**
+ * Fetch a binary Home resource with the launch token. Home GUI runs in an
+ * opaque sandboxed frame, so cookie-authenticated CSS `url()` loads cannot be
+ * relied on; this is the same authenticated path every other Home request uses.
+ */
+export async function fetchBlob(url) {
+  const response = await fetch(url, {
+    headers: homeGuiLaunchToken ? { "x-elastos-home-token": homeGuiLaunchToken } : {},
+  });
+  if (!response.ok) {
+    const error = new Error(`request failed: ${response.status} ${response.statusText}`);
+    error.status = response.status;
+    throw error;
+  }
+  return response.blob();
+}
+
 export function allVisibleTargets(summary) {
   if (!summary || !Array.isArray(summary.targets)) {
     return [];

capsules/home/browser/home-shell-host.js

@@ -107,6 +107,9 @@ const SHELL_MESSAGE_DELIVER_TARGET_SOURCES = Object.freeze({
   documents: new Set(["chat-room"]),
   library: new Set(["archive-manager", "browser", "chat-room"]),
 });
+// Apps that may ask Home to make one of the person's own objects the wallpaper.
+const SHELL_MESSAGE_DESKTOP_BACKGROUND_SOURCES = new Set(["library"]);
+const DESKTOP_BACKGROUND_SOURCE_URI_MAX_LENGTH = 2048;
 const PASSKEY_STEP_UP_TARGETS = new Set(["inbox", SYSTEM_APP_ID, "wallet"]);
 const launchedAppContexts = new Map();
 const pendingBrowserAuthorityRenewals = new Map();
@@ -1974,6 +1977,10 @@ window.addEventListener("message", (event) => {
     });
     return;
   }
+  if (data.type === "home:set-desktop-background") {
+    handleSetDesktopBackgroundMessage(event, context, data);
+    return;
+  }
   if (data.type === "home:deliver-to-target") {
     const target = typeof data.target === "string" ? data.target.trim() : "";
     if (!target || !canDeliverTargetFromHomeMessage(context, target)) {
@@ -2334,6 +2341,62 @@ function canOpenTargetFromHomeMessage(context, target) {
   return policy.has(target);
 }
 
+// The app expresses intent; Home performs the change with its own appearance
+// authority, so the app never gains one. Home carries only the single-use
+// ticket the Library frame asked Runtime for (one object, one minute), never
+// Library's launch token, and Runtime reads the object under Library's scope,
+// Trash, and protection rules. Home never reads or decrypts the object itself.
+const DESKTOP_BACKGROUND_TICKET_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const DESKTOP_BACKGROUND_MESSAGE_MAX_LENGTH = 600;
+
+function handleSetDesktopBackgroundMessage(event, context, data) {
+  const requestId = typeof data.requestId === "string" ? data.requestId.trim() : "";
+  const uri = typeof data.uri === "string" ? data.uri.trim() : "";
+  const ticket = typeof data.ticket === "string" ? data.ticket : "";
+  if (
+    context.kind !== "app-frame" ||
+    !SHELL_MESSAGE_DESKTOP_BACKGROUND_SOURCES.has(context.targetId) ||
+    !hasExactMessageKeys(data, ["type", "requestId", "homeToken", "uri", "ticket"]) ||
+    !requestId ||
+    requestId.length > 128 ||
+    !uri.startsWith("localhost://Users/") ||
+    uri.length > DESKTOP_BACKGROUND_SOURCE_URI_MAX_LENGTH ||
+    !DESKTOP_BACKGROUND_TICKET_PATTERN.test(ticket)
+  ) {
+    console.warn("home ignored unauthorized set-desktop-background message", context.targetId);
+    replyToShellRequest(event, requestId, null, new Error("Home denied the desktop background change"));
+    return;
+  }
+  fetch("/api/apps/home/appearance/background-image", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ source_uri: uri, library_ticket: ticket }),
+  })
+    .then(async (response) => {
+      if (response.ok) {
+        requestShellSummaryRefresh({ reason: "desktop-background" });
+        replyToShellRequest(event, requestId, { accepted: true });
+        return;
+      }
+      // Runtime answers 400 with a plain sentence that tells the person what
+      // to do next (for example, which protected file to move back). Only
+      // that sentence goes back to Library; Library checks it again.
+      const detail = response.status === 400 ? (await response.text().catch(() => "")).trim() : "";
+      console.warn("home could not set the desktop background", response.status);
+      replyToShellRequest(
+        event,
+        requestId,
+        detail && detail.length <= DESKTOP_BACKGROUND_MESSAGE_MAX_LENGTH
+          ? { accepted: false, message: detail }
+          : { accepted: false },
+      );
+    })
+    .catch((error) => {
+      console.warn("home could not set the desktop background", error);
+      replyToShellRequest(event, requestId, { accepted: false });
+    });
+}
+
 function canDeliverTargetFromHomeMessage(context, target) {
   if (context.kind !== "app-frame" && context.kind !== "shell-frame") {
     return false;

capsules/library/browser/index.html

@@ -45,7 +45,6 @@ <h2 class="window-sidebar-title">Favorites</h2>
           </section>
         </div>
         <div class="toolbar-right">
-          <span id="status-text" class="subtitle hidden">Loading Library...</span>
           <div id="toolbar-search" class="toolbar-search">
             <button
               id="search-toggle-button"
@@ -87,6 +86,7 @@ <h2 class="window-sidebar-title">Favorites</h2>
       <section id="content" class="content" data-view="list" aria-label="Items"></section>
       <footer class="statusbar explorer-footer">
         <span id="footer-left">0 items</span>
+        <span id="status-text" class="subtitle hidden" aria-live="polite">Loading Library...</span>
         <span id="footer-right">On this device</span>
       </footer>
     </main>

capsules/library/browser/library.css

@@ -731,6 +731,19 @@
       display: block;
     }
 
+    /* Image files show their own thumbnail in place of the generic icon. */
+    .item--thumbnail .file-icon img {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      border-radius: 3px;
+    }
+
+    .content[data-view="grid"] .item--thumbnail .file-icon {
+      overflow: hidden;
+      border-radius: 4px;
+    }
+
     .item-name {
       max-width: 100%;
       overflow: hidden;
@@ -1009,6 +1022,14 @@
       white-space: nowrap;
     }
 
+    /* Transient status lives in the footer so it can never push toolbar
+       controls; it takes the spare middle space and truncates first. */
+    .statusbar #status-text {
+      flex: 1 1 auto;
+      text-align: center;
+      color: var(--muted);
+    }
+
     .context-menu {
       position: fixed;
       z-index: 80;

capsules/library/browser/src/actions.js

@@ -5,6 +5,7 @@ import {
   childUri,
   contentCid,
   decimalIntegerToHexQuantity,
+  desktopBackgroundRefusalMessage,
   hasCapability,
   inTrash,
   isArchiveObject,
@@ -35,6 +36,7 @@ export function createLibraryActions({
   providerApi,
   renderUploads,
   selectedObjects,
+  setDesktopBackground,
   setStatus,
   setUploadProgress,
   showMenuForObject,
@@ -266,6 +268,16 @@ export function createLibraryActions({
     saveDownloadBlob(data.blob, data.filename || object.name || "download");
   }
 
+  async function setObjectAsDesktopBackground(object) {
+    setStatus("Setting desktop background...");
+    const result = await setDesktopBackground(object.uri);
+    if (result?.accepted) {
+      setStatus("Desktop background updated.");
+      return;
+    }
+    setStatus(desktopBackgroundRefusalMessage(result) || "Could not set this image as the desktop background.");
+  }
+
   async function downloadObjectAsZip(object) {
     if (!isDirectory(object)) return;
     const data = await downloadObjectRaw({ uri: object.uri, archive: "zip" });
@@ -731,6 +743,7 @@ export function createLibraryActions({
     restoreObject,
     restoreSelectedObjects,
     setClipboard,
+    setObjectAsDesktopBackground,
     shareObject,
     showStatusObject,
     trashObject,

capsules/library/browser/src/api.js

@@ -265,6 +265,56 @@ export function createLibraryRuntime({ getHomeToken }) {
     });
   }
 
+  // Library only expresses the intent; Home holds the appearance authority.
+  // Library first asks Runtime, with its own launch token, for a single-use
+  // ticket for this one object, and gives Home only that ticket, never its
+  // launch token. Resolves once Home has answered.
+  async function requestDesktopBackgroundTicket(uri, token) {
+    try {
+      const response = await fetch("/api/apps/library/desktop-background-ticket", {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-elastos-home-token": token,
+        },
+        body: JSON.stringify({ source_uri: uri }),
+      });
+      const payload = await response.json().catch(() => ({}));
+      return response.ok && typeof payload.ticket === "string" ? payload.ticket : "";
+    } catch (_error) {
+      return "";
+    }
+  }
+
+  // Resolves to { accepted, message }. `message` is Runtime's reason for a
+  // refusal as Home passed it on (the caller checks it before showing it),
+  // or "" when there is none.
+  async function setDesktopBackground(uri) {
+    const requestId = crypto.randomUUID();
+    const token = getHomeToken();
+    const ticket = await requestDesktopBackgroundTicket(uri, token);
+    if (!ticket) return { accepted: false, message: "" };
+    return new Promise((resolve) => {
+      const finish = (accepted, message = "") => {
+        window.clearTimeout(timer);
+        window.removeEventListener("message", receive);
+        resolve({ accepted, message: accepted ? "" : message });
+      };
+      const receive = (event) => {
+        if (event.source !== window.top || event.origin !== homeParentOrigin ||
+            event.data?.type !== "home:shell-response" || event.data.requestId !== requestId) return;
+        const sameSession = getHomeToken() === token;
+        finish(
+          sameSession && event.data.result?.accepted === true && !event.data.error,
+          sameSession && typeof event.data.result?.message === "string" ? event.data.result.message : "",
+        );
+      };
+      const timer = window.setTimeout(() => finish(false), 20_000);
+      window.addEventListener("message", receive);
+      if (!shellMessage({ type: "home:set-desktop-background", uri, requestId, ticket })) finish(false);
+    });
+  }
+
   function closeSelf() {
     return shellMessage({ type: "home:close-self" });
   }
@@ -276,6 +326,7 @@ export function createLibraryRuntime({ getHomeToken }) {
     openTarget,
     openPublishedUri,
     deliverToTarget,
+    setDesktopBackground,
     closeSelf,
   };
 }

capsules/library/browser/src/app.js

@@ -6,6 +6,7 @@ import {
   hasCapability,
   inTrash,
   isBlockedObject,
+  isDesktopBackgroundCandidate,
   isDirectory,
   isRuntimeCustodyProtectableVideo,
   isTrashRootUri,
@@ -27,6 +28,7 @@ import { createLibraryPreview } from "./preview.js";
 import { createLibraryRealtime } from "./realtime.js";
 import { createLibraryRenderer, iconPlaceholder } from "./render.js?v=library-20260711d";
 import { createLibrarySelection } from "./selection.js";
+import { createLibraryThumbnails } from "./thumbnails.js";
 import {
   MUTATING_PROVIDER_OPS,
   cacheFolderListing,
@@ -72,6 +74,7 @@ import {
       openTarget,
       openPublishedUri,
       deliverToTarget,
+      setDesktopBackground,
       closeSelf,
     } = createLibraryRuntime({ getHomeToken: () => state.homeToken });
 
@@ -145,6 +148,7 @@ import {
     let restoreObject = async () => {};
     let restoreSelectedObjects = async () => {};
     let setClipboard = () => {};
+    let setObjectAsDesktopBackground = async () => {};
     let shareObject = async () => {};
     let showStatusObject = async () => {};
     let trashObject = async () => {};
@@ -245,6 +249,10 @@ import {
       perf,
       selectedObjects,
       state,
+      thumbnails: createLibraryThumbnails({
+        readObjectBlob: (uri) => downloadObjectRaw({ uri }).then((result) => result.blob),
+        root: elements.content,
+      }),
       visibleObjects,
     }));
     ({
@@ -297,6 +305,7 @@ import {
       restoreObject,
       restoreSelectedObjects,
       setClipboard,
+      setObjectAsDesktopBackground,
       shareObject,
       showStatusObject,
       trashObject,
@@ -320,6 +329,7 @@ import {
       providerApi,
       renderUploads,
       selectedObjects,
+      setDesktopBackground,
       setStatus,
       setUploadProgress,
       showMenuForObject,
@@ -991,6 +1001,9 @@ import {
             children: viewers.map((viewer) => menuAction(viewer.label || viewer.id, () => openWithViewer(object, viewer.id))),
           }));
         }
+        if (!isAttachMode() && isDesktopBackgroundCandidate(object)) {
+          actions.push(menuAction("Set as Desktop Background", () => setObjectAsDesktopBackground(object)));
+        }
       }
       if (hasCapability(object, "download")) {
         actions.push(menuAction("Download", () => downloadObject(object)));