@phis/ui 0.4.2 → 0.4.4

package/components/media/phi-area-upload-widget.js

@@ -4,13 +4,13 @@ import { resolvePhiMediaAssetTypeLabel } from "./asset-type-label";
 import { PhiTagControl } from "../controls/phi-tag-control";
 import { PhiButtonControl } from "../controls/phi-button-control";
 import NextImage from "next/image";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useMemo, useRef, useState } from "react";
 import { PhiCollectionLayoutControl } from "../controls/phi-collection-layout-control";
 import { resolvePhiMediaKindFromContentType, } from "../../constants/media";
 import { normalizePhiImagePreviewTile, resolvePhiMediaAssetDisplayDimensions, } from "./phi-image-preview-data";
 import { PhiMediaKindIcon } from "./phi-media-kind-icon";
-import { PhiMediaUploadError, isPhiMediaUploadCancelled, resolvePhiMediaUploadInitOptions, runPhiMediaUploadSession, } from "./media-upload-flow";
-import { PHI_MEDIA_UPLOAD_DEFAULT_LABELS, readPhiMediaUploadErrorMessage, } from "./phi-media-upload";
+import { resolvePhiMediaUploadInitOptions, } from "./media-upload-flow";
+import { PHI_MEDIA_UPLOAD_DEFAULT_LABELS, usePhiMediaUpload, } from "./phi-media-upload";
 import { usePhiImagePreviewStore } from "./phi-image-preview-store";
 import { PHI_ASSET_CONTROLLER_STORE_KEY } from "./asset-controller-signals";
 import { applyPhiAssetCollectionData, buildPhiAssetCollectionQuery, PHI_ASSET_COLLECTION_DATA_SOURCE, } from "./asset-collection-runtime";
@@ -55,25 +55,37 @@ function resolveUploadStatusLabel(item, labels) {
     return labels.doneLabel;
 }
 /**
- * The Widget's own wording over the shared reading of every refusal.
- *
- * It used to know about duplicates and nothing else, and fell through to `error.message` -- which put a
- * control plane string in front of a person for every other refusal, including the two the Site itself
- * now states. Only the duplicate has a label of its own here; the rest come from one place.
+ * The Widget's own wording over the shared reading of every refusal: its duplicate, failure and storage
+ * texts, and the shared ones for the rest -- so no control plane string reaches a person.
  */
-function resolveUploadErrorMessage(error, labels) {
-    const typedError = error;
-    if ((error instanceof PhiMediaUploadError && error.code === "media_asset_exists") ||
-        typedError?.code === "media_asset_exists" ||
-        typedError?.message === "media_asset_exists") {
-        return labels.assetExistsLabel;
-    }
-    return readPhiMediaUploadErrorMessage(error, {
+function resolveAreaUploadLabels(labels) {
+    return {
         ...PHI_MEDIA_UPLOAD_DEFAULT_LABELS,
         errorGeneric: labels.uploadFailedText,
         errorDuplicate: labels.assetExistsLabel,
         errorStorageUnreachable: labels.uploadStorageUnreachableText,
-    });
+    };
+}
+/** A file still on its way, or one that failed, drawn as a tile like the Assets that arrived. */
+function buildPendingWallItem(item, presentationFlags) {
+    return {
+        localId: item.localId,
+        assetId: -1,
+        file: item.file,
+        title: item.file.name.replace(/\.[^.]+$/, "").trim() || item.file.name,
+        originalName: item.file.name,
+        thumbnailUrl: null,
+        previewUrl: null,
+        contentType: item.file.type,
+        kind: resolvePhiMediaKindFromContentType(item.file.type),
+        width: null,
+        height: null,
+        presentationFlags,
+        progress: item.progress,
+        status: item.status,
+        deleting: false,
+        error: item.error,
+    };
 }
 function resolveUploadWallDisplayDimensions(item) {
     return resolvePhiMediaAssetDisplayDimensions(item);
@@ -88,20 +100,6 @@ export function PhiAreaUploadBinding({ config, labels, onUploadComplete, collect
     const previewState = usePhiImagePreviewStore(PHI_ASSET_CONTROLLER_STORE_KEY);
     const activateCollectionAction = usePhiCollectionProviderAction(PHI_ASSET_COLLECTION_DATA_SOURCE);
     const dragDepth = useRef(0);
-    /*
-     * Uploads still on their way. The wall belongs to whatever shows it -- a Media picker in an Overlay
-     * more often than not -- and closing that stops them, so no Asset is finalized that nobody sees
-     * arrive. The Server is told `cancelled` and clears up what had arrived.
-     */
-    const runningUploads = useRef(new Set());
-    useEffect(() => {
-        const controllers = runningUploads.current;
-        return () => {
-            for (const controller of controllers)
-                controller.abort();
-            controllers.clear();
-        };
-    }, []);
     const [uploadWall, setUploadWall] = useState([]);
     const [isDragActive, setIsDragActive] = useState(false);
     const allowDelete = config?.allowDelete ?? true;
@@ -166,73 +164,31 @@ export function PhiAreaUploadBinding({ config, labels, onUploadComplete, collect
             showUploadMessage("error", error instanceof Error ? error.message : labels.deleteFailedText);
         }
     }
-    function startUploadWallItem(file, localId) {
-        const normalizedTitle = file.name.replace(/\.[^.]+$/, "").trim() || file.name;
-        const nextLocalId = localId ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-        setUploadWall((current) => [
-            {
-                localId: nextLocalId,
-                assetId: -1,
-                file,
-                title: normalizedTitle,
-                originalName: file.name,
-                thumbnailUrl: null,
-                previewUrl: null,
-                contentType: file.type,
-                kind: resolvePhiMediaKindFromContentType(file.type),
-                width: null,
-                height: null,
-                presentationFlags: uploadInitOptions.presentationFlags ?? 0,
-                progress: 0,
-                status: "uploading",
-                deleting: false,
-                error: null,
-            },
-            ...current.filter((item) => item.localId !== nextLocalId),
-        ]);
-        return nextLocalId;
-    }
     /*
-     * One file, transported by us.
-     *
-     * This was `customRequest`, whose `onProgress`, `onSuccess` and `onError` fed an Ant Design file
-     * list that `showUploadList={false}` never rendered -- every visible part of the progress already
-     * came from `uploadWall` below. Dropping the primitive dropped that second, invisible copy with it.
-     * A retry from the wall comes through here as well, into the tile it already has (`localId`).
+     * The transport is the shared one (`usePhiMediaUpload`): progress, refusals and their wording, retry,
+     * and stopping what is still on its way when the wall goes away -- a Media picker in an Overlay more
+     * often than not -- so no Asset is finalized that nobody sees arrive. What is this Widget's own is the
+     * wall: an Asset that arrived becomes a tile, and the listing behind it hears of it.
      */
-    async function uploadFileToWallItem(file, localId) {
-        const nextLocalId = startUploadWallItem(file, localId);
-        const controller = new AbortController();
-        runningUploads.current.add(controller);
-        try {
-            const payload = await runPhiMediaUploadSession(file, (progress) => {
-                setUploadWall((current) => current.map((item) => item.localId === nextLocalId ? { ...item, progress, status: "uploading" } : item));
-            }, uploadInitOptions, controller.signal);
-            if (controller.signal.aborted)
-                return;
-            const uploadedTile = normalizePhiImagePreviewTile(payload.asset, []);
-            setUploadWall((current) => current.map((item) => item.localId === nextLocalId ? buildUploadWallItem(uploadedTile, nextLocalId) : item));
+    const areaUploadLabels = useMemo(() => resolveAreaUploadLabels(labels), [labels]);
+    const upload = usePhiMediaUpload({
+        labels: areaUploadLabels,
+        initOptions: uploadInitOptions,
+        onUploaded: (asset, file) => {
+            const uploadedTile = normalizePhiImagePreviewTile(asset, []);
+            setUploadWall((current) => [buildUploadWallItem(uploadedTile, `asset-${uploadedTile.id}`), ...current]);
             onUploadComplete?.();
             showUploadMessage("success", labels.uploadSuccessTemplate.replace("%1", file.name));
-        }
-        catch (error) {
-            if (controller.signal.aborted || isPhiMediaUploadCancelled(error))
-                return;
-            const errorMessage = resolveUploadErrorMessage(error, labels);
-            setUploadWall((current) => current.map((item) => item.localId === nextLocalId
-                ? {
-                    ...item,
-                    progress: 100,
-                    status: "error",
-                    error: errorMessage,
-                }
-                : item));
-            showUploadMessage("error", errorMessage);
-        }
-        finally {
-            runningUploads.current.delete(controller);
-        }
-    }
+        },
+        onRejected: (message) => showUploadMessage("error", message),
+    });
+    // The shared items are on their way or failed; an arrived one is a tile in the wall instead.
+    const wallItems = [
+        ...upload.items
+            .filter((item) => item.status !== "done")
+            .map((item) => buildPendingWallItem(item, uploadInitOptions.presentationFlags ?? 0)),
+        ...uploadWall,
+    ];
     return (_jsxs(PhiFlexControl, { vertical: true, gap: 12, style: { width: "100%" }, children: [_jsx(PhiFileDropGuard, {}), _jsx("div", { "data-phi-media-dropzone": "true", onDragEnter: () => {
                     dragDepth.current += 1;
                     setIsDragActive(true);
@@ -248,7 +204,7 @@ export function PhiAreaUploadBinding({ config, labels, onUploadComplete, collect
                 }, onDrop: () => {
                     dragDepth.current = 0;
                     setIsDragActive(false);
-                }, style: { width: "100%" }, children: _jsx(PhiFileDropControl, { dropZone: true, multiple: multiple, accept: accept, onFile: (file) => void uploadFileToWallItem(file), style: {
+                }, style: { width: "100%" }, children: _jsx(PhiFileDropControl, { dropZone: true, multiple: multiple, accept: accept, onFile: (file) => void upload.upload(file), style: {
                         padding: 0,
                         width: "100%",
                         borderColor: isDragActive ? token.colorPrimary : undefined,
@@ -258,7 +214,7 @@ export function PhiAreaUploadBinding({ config, labels, onUploadComplete, collect
                             minHeight: uploadTileMinHeight,
                             justifyContent: "center",
                             cursor: isDragActive ? "copy" : "default",
-                        }, children: [_jsx(PhiIcon, { name: "upload", size: "inherit", style: { fontSize: uploadTileIconSize, color: token.colorTextSecondary } }), _jsx(PhiTypographyControl, { strong: true, children: labels.dropTitle }), _jsx(PhiTypographyControl, { type: "secondary", children: labels.dropHint })] }) }) }), _jsx(PhiCollectionLayoutControl, { mode: "grid", gap: token.paddingSM, minColumnWidth: uploadTileFrameSize, items: uploadWall.map((item) => {
+                        }, children: [_jsx(PhiIcon, { name: "upload", size: "inherit", style: { fontSize: uploadTileIconSize, color: token.colorTextSecondary } }), _jsx(PhiTypographyControl, { strong: true, children: labels.dropTitle }), _jsx(PhiTypographyControl, { type: "secondary", children: labels.dropHint })] }) }) }), _jsx(PhiCollectionLayoutControl, { mode: "grid", gap: token.paddingSM, minColumnWidth: uploadTileFrameSize, items: wallItems.map((item) => {
                     const displayDimensions = resolveUploadWallDisplayDimensions(item);
                     return (_jsxs("div", { style: {
                             border: resolvePhiThemeBorderLine(token.colorBorderSecondary),
@@ -316,7 +272,7 @@ export function PhiAreaUploadBinding({ config, labels, onUploadComplete, collect
                                         }, children: _jsx(PhiSpinControl, {}) })) : null] }), _jsxs(PhiFlexControl, { vertical: true, gap: 6, style: { padding: token.paddingSM }, children: [_jsx(PhiFlexControl, { align: "center", justify: "space-between", gap: 8, children: _jsx(PhiTypographyControl, { strong: true, ellipsis: true, title: item.title ?? item.originalName, style: { minWidth: 0 }, children: item.title ?? item.originalName }) }), _jsxs(PhiFlexControl, { align: "center", justify: "space-between", gap: 8, wrap: true, children: [_jsx(PhiTypographyControl, { type: "secondary", ellipsis: true, style: { display: "block", minWidth: 0 }, children: resolvePhiMediaAssetTypeLabel(item.kind, item.contentType, item.originalName) }), allowDelete && item.assetId > 0 ? (_jsx(PhiButtonControl, { ariaLabel: labels.deleteLabel, icon: _jsx(PhiIcon, { name: "delete", size: "inherit" }), type: "text", size: "small", danger: true, onClick: () => {
                                                     void deleteUploadedAsset(item.localId, item.assetId);
                                                 } })) : null] }), _jsxs(PhiFlexControl, { align: "center", gap: 6, wrap: true, children: [_jsx(PhiTagControl, { color: item.status === "error" ? "red" : item.status === "uploading" ? "blue" : "green", children: resolveUploadStatusLabel(item, labels) }), item.status === "error" && item.file ? (_jsx(PhiButtonControl, { type: "primary", size: "small", onClick: () => {
-                                                    void uploadFileToWallItem(item.file, item.localId);
+                                                    void upload.retry(item.localId);
                                                 }, label: labels.retryLabel })) : null] })] })] }, item.localId));
                 }) })] }));
 }

package/components/media/phi-image-preview-data.d.ts

@@ -3,6 +3,19 @@ export type PhiImagePreviewApiRecord = Omit<PhiMediaAsset, "kind"> & {
     thumbnailUrl?: string | null;
     previewUrl?: string | null;
 };
+/** The media API's Folders, read strictly; `source` names who answered. */
+export declare function readPhiMediaFolders(value: unknown, source?: string): PhiMediaAssetFolder[];
+/** The media API's Spaces, read strictly. */
+export declare function readPhiMediaSpaces(value: unknown, source?: string): PhiMediaSpaceOption[];
+/** One Space, or `null` where none is reported. */
+export declare function readPhiMediaSpace(value: unknown, source?: string): PhiMediaSpaceOption | null;
+/** The paging the media API reports, or `null` where it reports none. */
+export declare function readPhiMediaPagination(value: unknown, source?: string): PhiMediaPickerPagination | null;
+/**
+ * The tiles a media Collection carries. The provider read them from the API already; a Collection
+ * holds items of no particular type, so whoever takes them out reads them again instead of casting.
+ */
+export declare function readPhiMediaAssetTiles(value: unknown, source?: string): PhiMediaAssetTile[];
 export declare function resolvePhiMediaAssetDisplayDimensions(asset: Pick<PhiMediaAssetTile, "contentType" | "width" | "height">): {
     width: number;
     height: number;

package/components/media/phi-image-preview-data.js

@@ -1,4 +1,174 @@
-import { resolvePhiMediaKindFromContentType } from "../../constants/media";
+import { PHI_MEDIA_SPACE_KINDS } from "@phis/contracts/media";
+import { PhiImageAssetVariantKey, PhiMediaKind, resolvePhiMediaKindFromContentType } from "../../constants/media";
+import { createPhiResponseReader, requirePhiField, } from "../widgets/config/strict-config-reader";
+/*
+ * The media API's answer, read field by field.
+ *
+ * It was cast to its type on arrival, and every reader after it cast again from the Collection's untyped
+ * items. A field the server stopped sending, or sent under another name, came through as `undefined`
+ * under a type that said otherwise -- the tile type promised a `checksumSha256` the server has never
+ * sent. Now a wrong answer is an error naming the field, at the one place the answer arrives, and what a
+ * Collection carries afterwards is read with the same readers rather than cast.
+ */
+const PHI_MEDIA_LISTING = "The media listing";
+const PHI_MEDIA_VARIANT_KEYS = Object.values(PhiImageAssetVariantKey);
+const PHI_MEDIA_KINDS = Object.values(PhiMediaKind);
+const nullableInteger = (reader, key) => reader.integer(key) ?? null;
+const nullableNumber = (reader, key) => reader.number(key) ?? null;
+const nullableString = (reader, key) => reader.string(key) ?? null;
+const requiredInteger = (reader, key) => requirePhiField(reader, key, "a whole number", reader.integer);
+const requiredString = (reader, key) => requirePhiField(reader, key, "a text", reader.string);
+function readPhiMediaFolderFields(reader) {
+    const createdAt = reader.string("createdAt");
+    const updatedAt = reader.string("updatedAt");
+    return {
+        id: requiredInteger(reader, "id"),
+        siteId: requiredInteger(reader, "siteId"),
+        spaceId: requiredInteger(reader, "spaceId"),
+        parentId: nullableInteger(reader, "parentId"),
+        name: requiredString(reader, "name"),
+        sortOrder: requiredInteger(reader, "sortOrder"),
+        flags: requiredInteger(reader, "flags"),
+        ...(createdAt ? { createdAt } : {}),
+        ...(updatedAt ? { updatedAt } : {}),
+    };
+}
+function readPhiMediaSpaceFields(reader) {
+    return {
+        id: nullableInteger(reader, "id"),
+        address: requiredString(reader, "address"),
+        kind: requirePhiField(reader, "kind", "a Media Space kind", (key) => reader.oneOf(key, PHI_MEDIA_SPACE_KINDS)),
+        groupId: nullableInteger(reader, "groupId"),
+        name: nullableString(reader, "name"),
+        quotaBytes: nullableInteger(reader, "quotaBytes"),
+        usedBytes: requiredInteger(reader, "usedBytes"),
+        reservedBytes: requiredInteger(reader, "reservedBytes"),
+    };
+}
+function readPhiMediaPaginationFields(reader) {
+    const total = reader.integer("total");
+    return {
+        page: requiredInteger(reader, "page"),
+        pageSize: requiredInteger(reader, "pageSize"),
+        ...(total === undefined ? {} : { total }),
+        hasMore: requirePhiField(reader, "hasMore", "true or false", reader.boolean),
+    };
+}
+function readPhiMediaVariantFields(reader) {
+    const createdAt = reader.string("createdAt");
+    const updatedAt = reader.string("updatedAt");
+    return {
+        assetId: requiredInteger(reader, "assetId"),
+        variantKey: requirePhiField(reader, "variantKey", "an image variant key", (key) => reader.oneOf(key, PHI_MEDIA_VARIANT_KEYS)),
+        deliveryUrl: requiredString(reader, "deliveryUrl"),
+        contentType: requiredString(reader, "contentType"),
+        bytes: nullableInteger(reader, "bytes"),
+        width: requiredInteger(reader, "width"),
+        height: requiredInteger(reader, "height"),
+        blurDataUrl: nullableString(reader, "blurDataUrl"),
+        flags: requiredInteger(reader, "flags"),
+        ...(createdAt ? { createdAt } : {}),
+        ...(updatedAt ? { updatedAt } : {}),
+    };
+}
+/** One Asset as the media API sends it; `kind` is derived from the content type, not taken. */
+function readPhiMediaAssetFields(reader) {
+    const createdAt = reader.string("createdAt");
+    const updatedAt = reader.string("updatedAt");
+    const variantVersion = reader.integer("variantVersion");
+    const folder = reader.object("folder", readPhiMediaFolderFields);
+    const variants = reader.list("variants", readPhiMediaVariantFields);
+    return {
+        id: requiredInteger(reader, "id"),
+        siteId: requiredInteger(reader, "siteId"),
+        spaceId: requiredInteger(reader, "spaceId"),
+        folderId: nullableInteger(reader, "folderId"),
+        createdByUserId: nullableInteger(reader, "createdByUserId"),
+        updatedByUserId: nullableInteger(reader, "updatedByUserId"),
+        ...(variantVersion === undefined ? {} : { variantVersion }),
+        deliveryUrl: requiredString(reader, "deliveryUrl"),
+        originalName: requiredString(reader, "originalName"),
+        contentType: requiredString(reader, "contentType"),
+        bytes: nullableInteger(reader, "bytes"),
+        width: nullableNumber(reader, "width"),
+        height: nullableNumber(reader, "height"),
+        blurDataUrl: nullableString(reader, "blurDataUrl"),
+        thumbnailUrl: nullableString(reader, "thumbnailUrl"),
+        previewUrl: nullableString(reader, "previewUrl"),
+        meta: reader.value("meta", "an object", (value) => (isPlainRecord(value) ? value : undefined)) ?? null,
+        title: nullableString(reader, "title"),
+        altText: nullableString(reader, "altText"),
+        lifecycleStatus: requiredInteger(reader, "lifecycleStatus"),
+        deliveryPolicy: requiredInteger(reader, "deliveryPolicy"),
+        deliveryRevision: requiredInteger(reader, "deliveryRevision"),
+        presentationFlags: requiredInteger(reader, "presentationFlags"),
+        ...(createdAt ? { createdAt } : {}),
+        ...(updatedAt ? { updatedAt } : {}),
+        ...(folder ? { folder } : {}),
+        ...(variants ? { variants } : {}),
+    };
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The media API's Folders, read strictly; `source` names who answered. */
+export function readPhiMediaFolders(value, source = PHI_MEDIA_LISTING) {
+    return createPhiResponseReader({ folders: value }, source).list("folders", readPhiMediaFolderFields) ?? [];
+}
+/** The media API's Spaces, read strictly. */
+export function readPhiMediaSpaces(value, source = PHI_MEDIA_LISTING) {
+    return createPhiResponseReader({ spaces: value }, source).list("spaces", readPhiMediaSpaceFields) ?? [];
+}
+/** One Space, or `null` where none is reported. */
+export function readPhiMediaSpace(value, source = PHI_MEDIA_LISTING) {
+    return createPhiResponseReader({ activeSpace: value }, source).object("activeSpace", readPhiMediaSpaceFields) ?? null;
+}
+/** The paging the media API reports, or `null` where it reports none. */
+export function readPhiMediaPagination(value, source = PHI_MEDIA_LISTING) {
+    return createPhiResponseReader({ pagination: value }, source).object("pagination", readPhiMediaPaginationFields) ?? null;
+}
+/**
+ * The tiles a media Collection carries. The provider read them from the API already; a Collection
+ * holds items of no particular type, so whoever takes them out reads them again instead of casting.
+ */
+export function readPhiMediaAssetTiles(value, source = PHI_MEDIA_LISTING) {
+    return createPhiResponseReader({ assets: value }, source).list("assets", (reader) => {
+        const variantVersion = reader.integer("variantVersion");
+        const meta = reader.value("meta", "an object", (entry) => (isPlainRecord(entry) ? entry : undefined));
+        const blurDataUrl = reader.string("blurDataUrl");
+        const folder = reader.object("folder", (folderReader) => ({
+            id: requiredInteger(folderReader, "id"),
+            name: requiredString(folderReader, "name"),
+        }));
+        return {
+            id: requiredInteger(reader, "id"),
+            siteId: requiredInteger(reader, "siteId"),
+            spaceId: requiredInteger(reader, "spaceId"),
+            folderId: nullableInteger(reader, "folderId"),
+            createdByUserId: nullableInteger(reader, "createdByUserId"),
+            updatedByUserId: nullableInteger(reader, "updatedByUserId"),
+            ...(variantVersion === undefined ? {} : { variantVersion }),
+            originalName: requiredString(reader, "originalName"),
+            title: nullableString(reader, "title"),
+            altText: nullableString(reader, "altText"),
+            deliveryUrl: requiredString(reader, "deliveryUrl"),
+            thumbnailUrl: nullableString(reader, "thumbnailUrl"),
+            previewUrl: nullableString(reader, "previewUrl"),
+            contentType: requiredString(reader, "contentType"),
+            kind: requirePhiField(reader, "kind", "a media kind", (key) => reader.oneOf(key, PHI_MEDIA_KINDS)),
+            width: nullableNumber(reader, "width"),
+            height: nullableNumber(reader, "height"),
+            bytes: nullableInteger(reader, "bytes"),
+            lifecycleStatus: requiredInteger(reader, "lifecycleStatus"),
+            deliveryPolicy: requiredInteger(reader, "deliveryPolicy"),
+            deliveryRevision: requiredInteger(reader, "deliveryRevision"),
+            presentationFlags: requiredInteger(reader, "presentationFlags"),
+            ...(blurDataUrl === undefined ? {} : { blurDataUrl }),
+            ...(meta === undefined ? {} : { meta }),
+            folder: folder ?? null,
+        };
+    }) ?? [];
+}
 const PHI_SVG_MEDIA_MIN_DISPLAY_DIMENSION = 48;
 function normalizePhiImagePreviewAsset(asset) {
     return {
@@ -74,16 +244,21 @@ export function normalizePhiImagePreviewSelectionAsset(tile) {
     };
 }
 export async function readPhiImagePreviewResponse(response) {
-    const payload = (await response.json());
+    const payload = await response.json();
     if (!response.ok) {
-        throw new Error(payload.error ?? "Failed to load media assets.");
+        const error = isPlainRecord(payload) && typeof payload.error === "string" ? payload.error : null;
+        throw new Error(error ?? "Failed to load media assets.");
     }
+    const reader = createPhiResponseReader(payload, PHI_MEDIA_LISTING);
+    const folders = reader.list("folders", readPhiMediaFolderFields) ?? [];
+    const asset = reader.object("asset", readPhiMediaAssetFields);
     return {
-        activeSpace: payload.activeSpace ?? null,
-        spaces: payload.spaces ?? [],
-        assets: (payload.assets ?? []).map((asset) => normalizePhiImagePreviewTile(asset, payload.folders ?? [])),
-        folders: payload.folders ?? [],
-        pagination: payload.pagination ?? null,
-        asset: payload.asset ? normalizePhiImagePreviewAsset(payload.asset) : null,
+        activeSpace: reader.object("activeSpace", readPhiMediaSpaceFields) ?? null,
+        spaces: reader.list("spaces", readPhiMediaSpaceFields) ?? [],
+        assets: (reader.list("assets", readPhiMediaAssetFields) ?? [])
+            .map((entry) => normalizePhiImagePreviewTile(entry, folders)),
+        folders,
+        pagination: reader.object("pagination", readPhiMediaPaginationFields) ?? null,
+        asset: asset ? normalizePhiImagePreviewAsset(asset) : null,
     };
 }

package/components/media/phi-media-picker-binding.js

@@ -10,6 +10,7 @@ import { PHI_ASSET_COLLECTION_DATA_SOURCE } from "./asset-collection-runtime";
 import { buildPhiMediaFolderCascaderOptions, buildPhiMediaFolderValueById, resolvePhiMediaFolderIdFromValue, } from "./media-folder-options";
 import { PHI_ASSET_CONTROLLER_STORE_KEY, PHI_ASSET_SIGNAL_CHANNELS, } from "./asset-controller-signals";
 import { setPhiImagePreviewSelection } from "./phi-image-preview-store";
+import { readPhiMediaAssetTiles, readPhiMediaFolders, readPhiMediaSpace, readPhiMediaSpaces, } from "./phi-image-preview-data";
 import { buildPhiMediaSpaceOptions, usePhiMediaSpaceSelectionAllowed, } from "./media-space-selection";
 import { isPhiRecord } from "../../helpers/is-record";
 export function usePhiMediaPickerBinding({ config, labels, searchLabels, value: controlledValue, onAssetSelect, onAssetClear, open: controlledOpen, onOpenChange, onCommit, onDiscard, onPopupOpenChange, trigger, getPopupContainer, popupRootClassName, }) {
@@ -27,6 +28,13 @@ export function usePhiMediaPickerBinding({ config, labels, searchLabels, value:
     // Null asks for no particular Space, which the control plane answers with the Site Space. An
     // authoring surface never leaves this state, because it never renders the selector.
     const [spaceAddress, setSpaceAddress] = useState(null);
+    /*
+     * The Space the reader chose, which is what the query asks for -- kept apart from the Space the last
+     * answer served, which is what the selector shows. Writing the served Space back into the query made
+     * the first open ask twice: once for nothing in particular, and once more for the Space it had just
+     * been given.
+     */
+    const [requestedSpaceAddress, setRequestedSpaceAddress] = useState(null);
     const spaceSelectionAllowed = usePhiMediaSpaceSelectionAllowed();
     const [total, setTotal] = useState(0);
     const [loading, setLoading] = useState(false);
@@ -53,9 +61,9 @@ export function usePhiMediaPickerBinding({ config, labels, searchLabels, value:
             folderId,
             kind: mediaType,
             presentationFlags,
-            ...(spaceSelectionAllowed && spaceAddress ? { spaceId: spaceAddress } : {}),
+            ...(spaceSelectionAllowed && requestedSpaceAddress ? { spaceId: requestedSpaceAddress } : {}),
         },
-    }), [presentationFlags, folderId, mediaType, page, pageSize, searchQuery, spaceAddress, spaceSelectionAllowed]);
+    }), [presentationFlags, folderId, mediaType, page, pageSize, requestedSpaceAddress, searchQuery, spaceSelectionAllowed]);
     const querySignals = usePhiControlSignalController({ key: PHI_ASSET_SIGNAL_CHANNELS.query, signalRoutes: config?.signalRoutes, valueType: "string", typeKey: "media-picker-query", clearValue: "", onSetValue: (next) => { setSearchQuery(next); setPage(1); }, coerceValue: (next) => typeof next === "string" ? next : null });
     const pathSignals = usePhiControlSignalController({ key: PHI_ASSET_SIGNAL_CHANNELS.path, signalRoutes: config?.signalRoutes, valueType: "path", typeKey: "media-picker-path", clearValue: "/", onSetValue: (next) => { setFolderId(resolvePhiMediaFolderIdFromValue(folders, next)); setPage(1); }, coerceValue: (next) => typeof next === "string" ? next : null });
     const reloadSignals = usePhiControlSignalController({ key: PHI_ASSET_SIGNAL_CHANNELS.reload, signalRoutes: config?.signalRoutes, typeKey: "media-picker-reload", onReceiveCapability: (capabilityId) => { if (capabilityId !== "reload")
@@ -84,25 +92,19 @@ export function usePhiMediaPickerBinding({ config, labels, searchLabels, value:
                 });
                 if (abortController.signal.aborted)
                     return;
-                const nextFolders = Array.isArray(data.meta?.folders)
-                    ? data.meta.folders.filter(isPhiRecord)
-                    : [];
-                const nextAssets = data.items.filter(isPhiRecord);
+                const nextFolders = readPhiMediaFolders(data.meta?.folders);
+                const nextAssets = readPhiMediaAssetTiles(data.items);
                 setAssets(nextAssets);
                 for (const asset of nextAssets)
                     assetCacheRef.current.set(asset.id, asset);
                 setFolders(nextFolders);
-                setSpaces(Array.isArray(data.meta?.spaces)
-                    ? data.meta.spaces.filter(isPhiRecord)
-                    : []);
+                setSpaces(readPhiMediaSpaces(data.meta?.spaces));
                 // The answer says which Space it actually served, so the selector follows the control plane
                 // rather than the other way round -- including the first load, which asked for nothing.
-                const activeAddress = isPhiRecord(data.meta?.activeSpace) && typeof data.meta.activeSpace.address === "string"
-                    ? data.meta.activeSpace.address
-                    : null;
+                const activeAddress = readPhiMediaSpace(data.meta?.activeSpace)?.address ?? null;
                 if (activeAddress)
                     setSpaceAddress(activeAddress);
-                setTotal(typeof data.total === "number" ? data.total : data.items.length);
+                setTotal(data.total);
             }
             catch (error) {
                 if (!abortController.signal.aborted) {
@@ -185,6 +187,7 @@ export function usePhiMediaPickerBinding({ config, labels, searchLabels, value:
                 return;
             // Folders belong to the Space they were listed from, so switching Space starts at its root.
             setSpaceAddress(nextSpace);
+            setRequestedSpaceAddress(nextSpace);
             setFolderId(null);
             setPage(1);
         },

package/components/media/phi-media-upload.d.ts

@@ -74,7 +74,11 @@ type PhiMediaUploadItem = {
  * upload settled -- a form field that receives the Asset id in `onUploaded` -- reads it to hold back
  * whatever would act on the incomplete value.
  */
-export declare function usePhiMediaUpload(input: {
+export declare function usePhiMediaUpload<TAsset extends {
+    id: number;
+} = {
+    id: number;
+}>(input: {
     labels: PhiMediaUploadLabels;
     acceptance?: PhiMediaUploadAcceptance;
     initOptions?: PhiMediaUploadInitOptions;
@@ -85,18 +89,21 @@ export declare function usePhiMediaUpload(input: {
      * between, so it is this one thing that differs -- and everything a person sees while it happens is
      * shared rather than reimplemented alongside.
      */
-    runSession?: PhiMediaUploadSessionRunner;
-    onUploaded?: (asset: {
-        id: number;
-    }, file: File) => void | Promise<void>;
+    runSession?: (...args: Parameters<PhiMediaUploadSessionRunner>) => Promise<{
+        asset: TAsset;
+    }>;
+    /**
+     * The Asset as the session answered it. A surface that shows the new Asset at once -- a tile in the
+     * upload wall -- reads more of it than the id, and the default runner answers with the whole record.
+     */
+    onUploaded?: (asset: TAsset, file: File) => void | Promise<void>;
     onRejected?: (message: string, file: File) => void;
 }): {
     accept: string;
     items: readonly PhiMediaUploadItem[];
     uploading: boolean;
-    upload: (file: File) => Promise<{
-        id: number;
-    } | null>;
+    upload: (file: File) => Promise<TAsset | null>;
+    retry: (localId: string) => Promise<TAsset | null>;
     cancel: () => void;
     reset: () => void;
 };

package/components/media/phi-media-upload.js

@@ -120,7 +120,8 @@ export function readPhiMediaUploadErrorMessage(error, labels) {
  */
 export function usePhiMediaUpload(input) {
     const { labels, acceptance, initOptions, onUploaded, onRejected } = input;
-    const runSession = input.runSession ?? runPhiMediaUploadSession;
+    const runSession = input.runSession
+        ?? runPhiMediaUploadSession;
     const [items, setItems] = useState([]);
     const sequence = useRef(0);
     const running = useRef(new Set());
@@ -136,18 +137,20 @@ export function usePhiMediaUpload(input) {
     const patch = useCallback((localId, next) => {
         setItems((current) => current.map((item) => item.localId === localId ? { ...item, ...next } : item));
     }, []);
-    const upload = useCallback(async (file) => {
+    /** One file into one item: a new item, or -- for a retry -- the failed one it had. */
+    const run = useCallback(async (file, retryLocalId) => {
         const rejection = readPhiMediaUploadRejection(file, acceptance, labels);
         if (rejection) {
             onRejected?.(rejection, file);
             return null;
         }
-        sequence.current += 1;
-        const localId = `upload-${sequence.current}`;
-        setItems((current) => [
-            { localId, file, progress: 0, status: "uploading", error: null, assetId: null },
-            ...current,
-        ]);
+        let localId = retryLocalId;
+        if (localId == null) {
+            sequence.current += 1;
+            localId = `upload-${sequence.current}`;
+        }
+        const startedItem = { localId, file, progress: 0, status: "uploading", error: null, assetId: null };
+        setItems((current) => [startedItem, ...current.filter((item) => item.localId !== localId)]);
         const controller = new AbortController();
         running.current.add(controller);
         let asset;
@@ -182,11 +185,17 @@ export function usePhiMediaUpload(input) {
         }
         return asset;
     }, [acceptance, initOptions, labels, onRejected, onUploaded, patch, runSession]);
+    const upload = useCallback((file) => run(file), [run]);
+    /** Starts a failed item's file again, in the place it had. */
+    const retry = useCallback((localId) => {
+        const failed = items.find((item) => item.localId === localId && item.status === "error");
+        return failed ? run(failed.file, localId) : Promise.resolve(null);
+    }, [items, run]);
     const cancel = useCallback(() => {
         for (const controller of running.current)
             controller.abort();
     }, []);
     const reset = useCallback(() => setItems([]), []);
     const uploading = items.some((item) => item.status === "uploading");
-    return { accept, items, uploading, upload, cancel, reset };
+    return { accept, items, uploading, upload, retry, cancel, reset };
 }