@taprootio/espalier 6.1.0 → 6.2.0

package/custom-elements.json

@@ -19461,87 +19461,71 @@
     },
     {
       "kind": "javascript-module",
-      "path": "dist/empty-state/esp-empty-state.js",
+      "path": "dist/file-upload/esp-file-upload.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "A centered empty-state layout for list, grid, and page-level\nzero-item states.\n\n```html\n<esp-empty-state icon=\"photo-up\">\n  <span slot=\"heading\">No images yet</span>\n  Upload the first image to start building this library.\n  <esp-button slot=\"action\" label=\"Upload Image\"></esp-button>\n</esp-empty-state>\n\n<esp-empty-state size=\"large\" icon=\"users\">\n  <span slot=\"heading\">No members yet</span>\n  Invite teammates when you are ready to collaborate.\n</esp-empty-state>\n```",
-          "name": "EspalierEmptyState",
-          "slots": [
-            {
-              "description": "Primary empty-state message.",
-              "name": "heading"
-            },
-            {
-              "description": "Supporting body text.",
-              "name": ""
-            },
-            {
-              "description": "Optional custom icon. When provided, it overrides the generated SVG from the `icon` attribute.",
-              "name": "icon"
-            },
-            {
-              "description": "Optional call-to-action button or link.",
-              "name": "action"
-            }
-          ],
+          "description": "Used to upload files.\n\n```html\n<esp-file-upload choose-text=\"Upload Document\"></esp-file-upload>\n<script>\n  const theFileUpload = findByTagName(\"esp-file-upload\")[0];\n  theFileUpload.addEventListener(\"esp-file-upload-files-selected\", () => {\n    showToast({\n      message: `You selected a file!`,\n      icon: \"info-i\",\n      duration: 2,\n      onClosed: () => {\n        theFileUpload.finishedProcessingFiles();\n      },\n    });\n  });\n</script>\n```",
+          "name": "EspalierFileUpload",
           "members": [
             {
               "kind": "field",
-              "name": "iconSlot",
-              "privacy": "private",
-              "default": "new SlottedIconController(this)"
-            },
-            {
-              "kind": "field",
-              "name": "actionSlot",
+              "name": "uploadInput",
               "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "sizeBacker",
+              "name": "processingFiles",
               "type": {
-                "text": "EspalierEmptyStateSize"
+                "text": "boolean"
               },
               "privacy": "private",
-              "default": "\"medium\""
+              "default": "false"
             },
             {
               "kind": "field",
-              "name": "hasSlottedAction",
+              "name": "accept",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "false"
+              "privacy": "public",
+              "default": "\"*\"",
+              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
+              "attribute": "accept"
             },
             {
               "kind": "field",
-              "name": "icon",
+              "name": "chooseText",
               "type": {
                 "text": "string"
               },
               "privacy": "public",
-              "default": "\"\"",
-              "description": "Optional icon name from the Espalier SVG sprite.",
-              "attribute": "icon"
+              "default": "\"Choose File\"",
+              "description": "The text to display on the button.",
+              "attribute": "choose-text"
             },
             {
               "kind": "field",
-              "name": "size",
+              "name": "multiple",
               "type": {
-                "text": "EspalierEmptyStateSize"
+                "text": "boolean"
               },
               "privacy": "public",
-              "description": "Empty-state scale.",
-              "attribute": "size",
-              "reflects": true
+              "default": "false",
+              "description": "Allow multiple files to be selected.",
+              "attribute": "multiple"
             },
             {
               "kind": "field",
-              "name": "handleActionSlotChange",
+              "name": "filesSelected",
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "finishedProcessingFiles",
+              "privacy": "public",
+              "description": "The `esp-file-upload-files-selected` event sets the file upload to a processing state.\nCall this method when you have finished processing the selected files\nto reset the file upload."
+            },
             {
               "kind": "field",
               "name": "seedColorBacker",
@@ -20267,23 +20251,42 @@
               }
             }
           ],
+          "events": [
+            {
+              "type": {
+                "text": "CustomEvent<FileList>"
+              },
+              "description": "Fired after the user selects one or more files.",
+              "name": "esp-file-upload-files-selected"
+            }
+          ],
           "attributes": [
             {
-              "name": "icon",
+              "name": "accept",
               "type": {
                 "text": "string"
               },
-              "default": "\"\"",
-              "description": "Optional icon name from the Espalier SVG sprite.",
-              "fieldName": "icon"
+              "default": "\"*\"",
+              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
+              "fieldName": "accept"
             },
             {
-              "name": "size",
+              "name": "choose-text",
               "type": {
-                "text": "EspalierEmptyStateSize"
+                "text": "string"
               },
-              "description": "Empty-state scale.",
-              "fieldName": "size"
+              "default": "\"Choose File\"",
+              "description": "The text to display on the button.",
+              "fieldName": "chooseText"
+            },
+            {
+              "name": "multiple",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Allow multiple files to be selected.",
+              "fieldName": "multiple"
             },
             {
               "name": "scheme",
@@ -20327,28 +20330,28 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
+          "tagName": "esp-file-upload",
+          "customElement": true,
           "docPageTitle": {
-            "name": "Empty",
-            "description": "State"
+            "name": "File",
+            "description": "Upload"
           },
           "docUrl": {
-            "name": "/components/empty-state",
+            "name": "/components/file-upload",
             "description": ""
           },
           "menuGroup": {
-            "name": "Feedback",
-            "description": ""
+            "name": "Form",
+            "description": "Controls"
           },
           "menuLabel": {
-            "name": "Empty",
-            "description": "State"
+            "name": "File",
+            "description": "Upload"
           },
           "menuIcon": {
-            "name": "box",
+            "name": "upload",
             "description": ""
           },
-          "tagName": "esp-empty-state",
-          "customElement": true,
           "cssProperties": [
             {
               "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
@@ -20406,96 +20409,111 @@
                 "module": "dist/shared/esp-element-base.js"
               }
             }
-          ],
-          "events": []
+          ]
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierEmptyState",
+          "name": "EspalierFileUpload",
           "declaration": {
-            "name": "EspalierEmptyState",
-            "module": "dist/empty-state/esp-empty-state.js"
+            "name": "EspalierFileUpload",
+            "module": "dist/file-upload/esp-file-upload.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-empty-state",
+          "name": "esp-file-upload",
           "declaration": {
-            "name": "EspalierEmptyState",
-            "module": "dist/empty-state/esp-empty-state.js"
+            "name": "EspalierFileUpload",
+            "module": "dist/file-upload/esp-file-upload.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "dist/file-upload/esp-file-upload.js",
+      "path": "dist/empty-state/esp-empty-state.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to upload files.\n\n```html\n<esp-file-upload choose-text=\"Upload Document\"></esp-file-upload>\n<script>\n  const theFileUpload = findByTagName(\"esp-file-upload\")[0];\n  theFileUpload.addEventListener(\"esp-file-upload-files-selected\", () => {\n    showToast({\n      message: `You selected a file!`,\n      icon: \"info-i\",\n      duration: 2,\n      onClosed: () => {\n        theFileUpload.finishedProcessingFiles();\n      },\n    });\n  });\n</script>\n```",
-          "name": "EspalierFileUpload",
+          "description": "A centered empty-state layout for list, grid, and page-level\nzero-item states.\n\n```html\n<esp-empty-state icon=\"photo-up\">\n  <span slot=\"heading\">No images yet</span>\n  Upload the first image to start building this library.\n  <esp-button slot=\"action\" label=\"Upload Image\"></esp-button>\n</esp-empty-state>\n\n<esp-empty-state size=\"large\" icon=\"users\">\n  <span slot=\"heading\">No members yet</span>\n  Invite teammates when you are ready to collaborate.\n</esp-empty-state>\n```",
+          "name": "EspalierEmptyState",
+          "slots": [
+            {
+              "description": "Primary empty-state message.",
+              "name": "heading"
+            },
+            {
+              "description": "Supporting body text.",
+              "name": ""
+            },
+            {
+              "description": "Optional custom icon. When provided, it overrides the generated SVG from the `icon` attribute.",
+              "name": "icon"
+            },
+            {
+              "description": "Optional call-to-action button or link.",
+              "name": "action"
+            }
+          ],
           "members": [
             {
               "kind": "field",
-              "name": "uploadInput",
+              "name": "iconSlot",
+              "privacy": "private",
+              "default": "new SlottedIconController(this)"
+            },
+            {
+              "kind": "field",
+              "name": "actionSlot",
               "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "processingFiles",
+              "name": "sizeBacker",
               "type": {
-                "text": "boolean"
+                "text": "EspalierEmptyStateSize"
               },
               "privacy": "private",
-              "default": "false"
+              "default": "\"medium\""
             },
             {
               "kind": "field",
-              "name": "accept",
+              "name": "hasSlottedAction",
               "type": {
-                "text": "string"
+                "text": "boolean"
               },
-              "privacy": "public",
-              "default": "\"*\"",
-              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
-              "attribute": "accept"
+              "privacy": "private",
+              "default": "false"
             },
             {
               "kind": "field",
-              "name": "chooseText",
+              "name": "icon",
               "type": {
                 "text": "string"
               },
               "privacy": "public",
-              "default": "\"Choose File\"",
-              "description": "The text to display on the button.",
-              "attribute": "choose-text"
+              "default": "\"\"",
+              "description": "Optional icon name from the Espalier SVG sprite.",
+              "attribute": "icon"
             },
             {
               "kind": "field",
-              "name": "multiple",
+              "name": "size",
               "type": {
-                "text": "boolean"
+                "text": "EspalierEmptyStateSize"
               },
               "privacy": "public",
-              "default": "false",
-              "description": "Allow multiple files to be selected.",
-              "attribute": "multiple"
+              "description": "Empty-state scale.",
+              "attribute": "size",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "filesSelected",
+              "name": "handleActionSlotChange",
               "privacy": "private"
             },
-            {
-              "kind": "method",
-              "name": "finishedProcessingFiles",
-              "privacy": "public",
-              "description": "The `esp-file-upload-files-selected` event sets the file upload to a processing state.\nCall this method when you have finished processing the selected files\nto reset the file upload."
-            },
             {
               "kind": "field",
               "name": "seedColorBacker",
@@ -21221,42 +21239,23 @@
               }
             }
           ],
-          "events": [
-            {
-              "type": {
-                "text": "CustomEvent<FileList>"
-              },
-              "description": "Fired after the user selects one or more files.",
-              "name": "esp-file-upload-files-selected"
-            }
-          ],
           "attributes": [
             {
-              "name": "accept",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"*\"",
-              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
-              "fieldName": "accept"
-            },
-            {
-              "name": "choose-text",
+              "name": "icon",
               "type": {
                 "text": "string"
               },
-              "default": "\"Choose File\"",
-              "description": "The text to display on the button.",
-              "fieldName": "chooseText"
+              "default": "\"\"",
+              "description": "Optional icon name from the Espalier SVG sprite.",
+              "fieldName": "icon"
             },
             {
-              "name": "multiple",
+              "name": "size",
               "type": {
-                "text": "boolean"
+                "text": "EspalierEmptyStateSize"
               },
-              "default": "false",
-              "description": "Allow multiple files to be selected.",
-              "fieldName": "multiple"
+              "description": "Empty-state scale.",
+              "fieldName": "size"
             },
             {
               "name": "scheme",
@@ -21300,28 +21299,28 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "tagName": "esp-file-upload",
-          "customElement": true,
           "docPageTitle": {
-            "name": "File",
-            "description": "Upload"
+            "name": "Empty",
+            "description": "State"
           },
           "docUrl": {
-            "name": "/components/file-upload",
+            "name": "/components/empty-state",
             "description": ""
           },
           "menuGroup": {
-            "name": "Form",
-            "description": "Controls"
+            "name": "Feedback",
+            "description": ""
           },
           "menuLabel": {
-            "name": "File",
-            "description": "Upload"
+            "name": "Empty",
+            "description": "State"
           },
           "menuIcon": {
-            "name": "upload",
+            "name": "box",
             "description": ""
           },
+          "tagName": "esp-empty-state",
+          "customElement": true,
           "cssProperties": [
             {
               "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
@@ -21379,24 +21378,25 @@
                 "module": "dist/shared/esp-element-base.js"
               }
             }
-          ]
+          ],
+          "events": []
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierFileUpload",
+          "name": "EspalierEmptyState",
           "declaration": {
-            "name": "EspalierFileUpload",
-            "module": "dist/file-upload/esp-file-upload.js"
+            "name": "EspalierEmptyState",
+            "module": "dist/empty-state/esp-empty-state.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-file-upload",
+          "name": "esp-empty-state",
           "declaration": {
-            "name": "EspalierFileUpload",
-            "module": "dist/file-upload/esp-file-upload.js"
+            "name": "EspalierEmptyState",
+            "module": "dist/empty-state/esp-empty-state.js"
           }
         }
       ]
@@ -36826,6 +36826,14 @@
               "description": "Space between the headline and supporting copy in a copy stack; the action sits twice as far below. Defaults to `var(--esp-size-small)`.",
               "name": "--esp-image-overlay-gap"
             },
+            {
+              "description": "A soft height cap for a banner: the ratio-sized height is the smaller of the ratio height and this length, and copy that would not fit (spacing included) grows the banner past it. In the compact band it caps only the image box. Unlike `max-block-size`, it never clips copy. Defaults to none.",
+              "name": "--esp-image-banner-max-block-size"
+            },
+            {
+              "description": "A soft height target for a banner: it replaces the ratio as the banner height (viewport-fill banners), and copy that would not fit grows the banner past it. In the compact band it sizes only the image box. Unlike `block-size`, it never clips copy. Defaults to none.",
+              "name": "--esp-image-banner-block-size"
+            },
             {
               "description": "Read only by the static `banner-static.css` stylesheet before upgrade: the `ratio` value, e.g. `3 / 1`. A server sets it inline beside the attribute.",
               "name": "--esp-image-static-ratio"
@@ -37266,6 +37274,16 @@
               "default": "false",
               "description": "Whether the overlay copy outgrew the ratio's frame; see `syncGrowth`."
             },
+            {
+              "kind": "field",
+              "name": "softHeight",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether a soft height (`--esp-image-banner-max-block-size` or\n`--esp-image-banner-block-size`) sizes this banner; see `readSoftHeight`."
+            },
             {
               "kind": "field",
               "name": "growthWidth",
@@ -37637,6 +37655,28 @@
               ],
               "description": "Whether the copy's own boxes reach past the frame's padding box, so text\nis cut off. Padding and margins that do not fit only bring the copy\ncloser to the edge, and a banner laid out that way keeps its ratio\nexactly as it always has. (A grown banner gives its ratio back only\nonce everything, spacing included, fits again; see syncGrowth.)"
             },
+            {
+              "kind": "method",
+              "name": "readSoftHeight",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "A soft height puts an overlay-mode banner in the grown geometry for good:\nthe spacer takes the ratio, capped by the soft cap or replaced by the\nsoft target, and copy grows the frame past it in plain CSS, so the\ngrowth state machine has nothing to do. A banner with neither property\nkeeps the ratio on the host. Read from computed style, so a media query\nor script can set either one; see the re-reads in measureScrimReach and\nhandleWindowResize."
+            },
+            {
+              "kind": "method",
+              "name": "syncSoftHeight",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "Re-read the soft height; returns whether it changed (an update follows)."
+            },
             {
               "kind": "method",
               "name": "grownActive",
@@ -39119,24 +39159,24 @@
     },
     {
       "kind": "javascript-module",
-      "path": "dist/image-upload/esp-image-preview.js",
+      "path": "dist/image-picker/esp-image-picker.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "An image preview for the upload component.\n\nRemoval and retry requests are private coordination events consumed by\nthe owning `esp-image-upload`.",
-          "name": "EspalierImagePreview",
+          "description": "A form-associated image picker with large image choices and a selected preview.\n\nThe component is controlled: set `images` and `value` from consumer state,\nthen use `esp-value-changed` to persist a user's next selection. An empty\n`value` means the Automatic choice. Labels are optional; unlabeled images use\ntheir alternative text or a numbered name. Images are shown without cropping.\n\nThe large preview sits above the control by default. Set\n`preview-placement=\"beside\"` for a compact preview beside the control.\nSize the preview and option images with the CSS properties below.\n\n```html\n<esp-form-item label=\"Page cover\">\n  <esp-image-picker name=\"cover\" value=\"field\"></esp-image-picker>\n</esp-form-item>\n<script>\n  const picker = document.querySelector(\"esp-image-picker\");\n  picker.images = [\n    { id: \"field\", src: \"/assets/focus-picker-unsplash.jpg\" },\n    { id: \"paper\", src: \"/assets/espalier-paper-texture.png\" },\n  ];\n  picker.addEventListener(\"esp-value-changed\", (event) => {\n    picker.value = event.detail;\n  });\n</script>\n```",
+          "name": "EspalierImagePicker",
           "cssProperties": [
             {
-              "description": "The border color of the preview.",
-              "name": "--esp-image-preview-border-color"
+              "description": "Height of the large preview above the control. Default 16rem.",
+              "name": "--esp-image-picker-preview-height"
             },
             {
-              "description": "The text color of the remove button.",
-              "name": "--esp-image-preview-remove-color"
+              "description": "Width of dropdown images, capped at 40vw on narrow screens. Default 12rem.",
+              "name": "--esp-image-picker-option-width"
             },
             {
-              "description": "The text color used by upload and failure overlays.",
-              "name": "--esp-image-preview-overlay-text"
+              "description": "Height of dropdown images. Images retain their aspect ratio. Default 8rem.",
+              "name": "--esp-image-picker-option-height"
             },
             {
               "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
@@ -39198,218 +39238,197 @@
           "members": [
             {
               "kind": "field",
-              "name": "image"
-            },
-            {
-              "kind": "field",
-              "name": "url",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "attribute": "url"
-            },
-            {
-              "kind": "field",
-              "name": "alt",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "description": "Alternative text for the preview image (typically the file name).",
-              "attribute": "alt"
-            },
-            {
-              "kind": "field",
-              "name": "progress",
+              "name": "formAssociated",
               "type": {
-                "text": "number | null | undefined"
+                "text": "boolean"
               },
-              "description": "Upload progress for this image.\n- `undefined` — no overlay (not uploading)\n- `null` — indeterminate spinner (upload started, no progress yet)\n- `0–100` — determinate progress ring",
-              "attribute": "progress"
+              "static": true,
+              "default": "true"
             },
             {
               "kind": "field",
-              "name": "failed",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Whether the upload for this image has failed.\nShows an error overlay with a retry button.",
-              "attribute": "failed"
+              "name": "internals",
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "sourceToken",
-              "type": {
-                "text": "number"
-              },
+              "name": "formCtrl",
               "privacy": "private",
-              "default": "0",
-              "description": "The source token keys a fresh image element for every exact-URL retry."
+              "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => (this.selectedImage ? this.value : null), getValidity: () => null, onReset: () => { this.value = \"\"; }, onRestore: (state: string) => { this.value = state; }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
             {
               "kind": "field",
-              "name": "admittedUrl",
-              "type": {
-                "text": "string"
-              },
+              "name": "formItemRelay",
               "privacy": "private",
-              "default": "\"\"",
-              "description": "The remote URL currently assigned to an admitted image element."
+              "default": "new FormItemRelay(() => this.picker as EspalierFormField | undefined)"
             },
             {
               "kind": "field",
-              "name": "remoteImageLoaded",
+              "name": "synchronizingPicker",
               "type": {
                 "text": "boolean"
               },
               "privacy": "private",
-              "default": "false",
-              "description": "A successful image stays rendered without holding a shared queue slot."
+              "default": "true"
             },
             {
               "kind": "field",
-              "name": "imageLoadFailed",
+              "name": "pickerSyncGeneration",
               "type": {
-                "text": "boolean"
+                "text": "number"
               },
               "privacy": "private",
-              "default": "false",
-              "description": "True after automatic retries are exhausted, until the user retries the image."
+              "default": "0"
             },
             {
               "kind": "field",
-              "name": "automaticRetryCount",
+              "name": "images",
               "type": {
-                "text": "number"
+                "text": "ImagePickerImage[]"
               },
-              "privacy": "private",
-              "default": "0",
-              "description": "Number of automatic retries already scheduled for the current URL."
+              "privacy": "public",
+              "default": "[]",
+              "description": "Image candidates, kept in the supplied order.",
+              "attribute": "images"
             },
             {
               "kind": "field",
-              "name": "remotePreviewVisible",
+              "name": "value",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "false",
-              "description": "Whether IntersectionObserver currently considers this preview visible."
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "Selected image ID. An empty string selects Automatic.",
+              "attribute": "value"
             },
             {
               "kind": "field",
-              "name": "visibilityObserver",
+              "name": "previewPlacement",
               "type": {
-                "text": "IntersectionObserver | null"
+                "text": "\"above\" | \"beside\""
               },
-              "privacy": "private",
-              "default": "null"
+              "privacy": "public",
+              "default": "\"above\"",
+              "description": "Preview placement: above (default, large) or beside (compact).",
+              "attribute": "preview-placement",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "queuedLoadCancel",
+              "name": "disabled",
               "type": {
-                "text": "(() => void) | null"
+                "text": "boolean"
               },
-              "privacy": "private",
-              "default": "null"
+              "privacy": "public",
+              "default": "false",
+              "description": "Disables the picker trigger.",
+              "attribute": "disabled",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "loadSlotRelease",
+              "name": "loading",
               "type": {
-                "text": "(() => void) | null"
+                "text": "boolean"
               },
-              "privacy": "private",
-              "default": "null"
+              "privacy": "public",
+              "default": "false",
+              "description": "Shows a loading state while candidates are being fetched.",
+              "attribute": "loading",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "retryTimer",
+              "name": "emptyMessage",
               "type": {
-                "text": "ReturnType<typeof setTimeout> | null"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "null"
+              "privacy": "public",
+              "default": "\"No images available.\"",
+              "description": "Message shown when no image candidates are available.",
+              "attribute": "empty-message"
             },
             {
               "kind": "field",
-              "name": "loadTimeoutTimer",
+              "name": "automaticLabel",
               "type": {
-                "text": "ReturnType<typeof setTimeout> | null"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "null"
+              "privacy": "public",
+              "default": "\"Automatic\"",
+              "description": "Label for the empty-value choice.",
+              "attribute": "automatic-label"
             },
             {
               "kind": "field",
-              "name": "activeSourceToken",
+              "name": "name",
               "type": {
-                "text": "number | null"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "null"
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "The name used when this picker participates in a `<form>`.",
+              "attribute": "name",
+              "reflects": true
             },
             {
               "kind": "method",
-              "name": "startCurrentPreview",
-              "privacy": "private",
+              "name": "focus",
+              "privacy": "public",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "FocusOptions"
+                  }
+                }
+              ],
+              "description": "Focus the composed picker trigger."
             },
             {
               "kind": "method",
-              "name": "stopVisibilityObserver",
-              "privacy": "private",
+              "name": "validate",
+              "privacy": "public",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              }
-            },
+              },
+              "description": "Re-run form validation."
+            },
             {
               "kind": "method",
-              "name": "requestRemoteLoad",
-              "privacy": "private",
+              "name": "checkValidity",
+              "privacy": "public",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "boolean"
                 }
-              }
+              },
+              "description": "Check form validity."
             },
             {
               "kind": "method",
-              "name": "handleImageLoad",
-              "privacy": "private",
+              "name": "formResetCallback",
+              "privacy": "public",
               "return": {
                 "type": {
                   "text": "void"
                 }
               },
-              "parameters": [
-                {
-                  "name": "event",
-                  "type": {
-                    "text": "Event"
-                  }
-                },
-                {
-                  "name": "token",
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ]
+              "description": "Called by the browser when the owning form resets."
             },
             {
               "kind": "method",
-              "name": "handleImageError",
-              "privacy": "private",
+              "name": "formStateRestoreCallback",
+              "privacy": "public",
               "return": {
                 "type": {
                   "text": "void"
@@ -39417,55 +39436,69 @@
               },
               "parameters": [
                 {
-                  "name": "event",
-                  "type": {
-                    "text": "Event"
-                  }
-                },
-                {
-                  "name": "token",
+                  "name": "state",
                   "type": {
-                    "text": "number"
+                    "text": "string"
                   }
                 }
-              ]
+              ],
+              "description": "Called by the browser when form state is restored."
             },
             {
               "kind": "method",
-              "name": "isActiveImageEvent",
-              "privacy": "private",
+              "name": "formDisabledCallback",
+              "privacy": "public",
               "return": {
                 "type": {
-                  "text": "boolean"
+                  "text": "void"
                 }
               },
               "parameters": [
                 {
-                  "name": "event",
-                  "type": {
-                    "text": "Event"
-                  }
-                },
-                {
-                  "name": "token",
+                  "name": "isDisabled",
                   "type": {
-                    "text": "number"
+                    "text": "boolean"
                   }
                 }
-              ]
+              ],
+              "description": "Called by the browser when an ancestor fieldset changes disabled state."
+            },
+            {
+              "kind": "field",
+              "name": "picker",
+              "type": {
+                "text": "EspalierPickOne | undefined"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "selectedImage",
+              "type": {
+                "text": "ImagePickerImage | undefined"
+              },
+              "privacy": "private",
+              "readonly": true
             },
             {
               "kind": "method",
-              "name": "handleImageFailure",
+              "name": "imageLabel",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "string"
                 }
               },
               "parameters": [
                 {
-                  "name": "token",
+                  "name": "image",
+                  "type": {
+                    "text": "ImagePickerImage"
+                  }
+                },
+                {
+                  "name": "index",
                   "type": {
                     "text": "number"
                   }
@@ -39473,69 +39506,41 @@
               ]
             },
             {
-              "kind": "method",
-              "name": "completeActiveLoad",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "abandonActiveLoad",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "kind": "field",
+              "name": "pickerItems",
+              "type": {
+                "text": "PickerItem[]"
               },
-              "description": "Cancel an in-flight browser request before returning its shared slot.\nA settled image never reaches this path, so its successfully loaded source\nremains visible through a disconnect or later update."
-            },
-            {
-              "kind": "method",
-              "name": "releaseActiveLoad",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "cancelQueuedLoad",
               "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
+              "readonly": true
             },
             {
               "kind": "method",
-              "name": "cancelRemoteWork",
+              "name": "thumbnailNode",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "HTMLImageElement"
                 }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "retryImage",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
+              },
+              "parameters": [
+                {
+                  "name": "image",
+                  "type": {
+                    "text": "ImagePickerImage"
+                  }
+                },
+                {
+                  "name": "alt",
+                  "type": {
+                    "text": "string"
+                  }
                 }
-              }
+              ]
             },
             {
-              "kind": "method",
-              "name": "renderImage",
+              "kind": "field",
+              "name": "handlePickerValueChanged",
               "privacy": "private"
             },
             {
@@ -40263,41 +40268,94 @@
               }
             }
           ],
-          "events": [],
+          "events": [
+            {
+              "type": {
+                "text": "CustomEvent<string>"
+              },
+              "description": "Fired when a user chooses an image or Automatic. The detail is the selected image ID, or an empty string for Automatic.",
+              "name": "esp-value-changed"
+            },
+            {
+              "type": {
+                "text": "CustomEvent<{ valid: boolean; message: string }>"
+              },
+              "description": "Fired whenever form validation runs.",
+              "name": "esp-validity-changed"
+            }
+          ],
           "attributes": [
             {
-              "name": "url",
+              "name": "images",
               "type": {
-                "text": "string"
+                "text": "ImagePickerImage[]"
               },
-              "default": "\"\"",
-              "fieldName": "url"
+              "default": "[]",
+              "description": "Image candidates, kept in the supplied order.",
+              "fieldName": "images"
             },
             {
-              "name": "alt",
+              "name": "value",
               "type": {
                 "text": "string"
               },
               "default": "\"\"",
-              "description": "Alternative text for the preview image (typically the file name).",
-              "fieldName": "alt"
+              "description": "Selected image ID. An empty string selects Automatic.",
+              "fieldName": "value"
             },
             {
-              "name": "progress",
+              "name": "preview-placement",
               "type": {
-                "text": "number | null | undefined"
+                "text": "\"above\" | \"beside\""
               },
-              "description": "Upload progress for this image.\n- `undefined` — no overlay (not uploading)\n- `null` — indeterminate spinner (upload started, no progress yet)\n- `0–100` — determinate progress ring",
-              "fieldName": "progress"
+              "default": "\"above\"",
+              "description": "Preview placement: above (default, large) or beside (compact).",
+              "fieldName": "previewPlacement"
             },
             {
-              "name": "failed",
+              "name": "disabled",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the upload for this image has failed.\nShows an error overlay with a retry button.",
-              "fieldName": "failed"
+              "description": "Disables the picker trigger.",
+              "fieldName": "disabled"
+            },
+            {
+              "name": "loading",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Shows a loading state while candidates are being fetched.",
+              "fieldName": "loading"
+            },
+            {
+              "name": "empty-message",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"No images available.\"",
+              "description": "Message shown when no image candidates are available.",
+              "fieldName": "emptyMessage"
+            },
+            {
+              "name": "automatic-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"Automatic\"",
+              "description": "Label for the empty-value choice.",
+              "fieldName": "automaticLabel"
+            },
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The name used when this picker participates in a `<form>`.",
+              "fieldName": "name"
             },
             {
               "name": "scheme",
@@ -40341,41 +40399,65 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "tagName": "esp-image-preview",
-          "customElement": true
+          "tagName": "esp-image-picker",
+          "customElement": true,
+          "docPageTitle": {
+            "name": "Image",
+            "description": "Picker"
+          },
+          "docUrl": {
+            "name": "/components/image-picker",
+            "description": ""
+          },
+          "menuGroup": {
+            "name": "Form",
+            "description": "Controls"
+          },
+          "menuLabel": {
+            "name": "Image",
+            "description": "Picker"
+          }
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierImagePreview",
+          "name": "EspalierImagePicker",
           "declaration": {
-            "name": "EspalierImagePreview",
-            "module": "dist/image-upload/esp-image-preview.js"
+            "name": "EspalierImagePicker",
+            "module": "dist/image-picker/esp-image-picker.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-image-preview",
+          "name": "esp-image-picker",
           "declaration": {
-            "name": "EspalierImagePreview",
-            "module": "dist/image-upload/esp-image-preview.js"
+            "name": "EspalierImagePicker",
+            "module": "dist/image-picker/esp-image-picker.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "dist/image-upload/esp-image-upload.js",
+      "path": "dist/image-upload/esp-image-preview.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to upload images.\n\n```html\n<esp-image-upload></esp-image-upload>\n```\n\n**Uploading new images**\n\nThe `esp-image-upload-file-selected` event detail provides the `image`\nreference (the actual object in `uploadedImages`) plus\n`onProgress`, `onComplete`, and `onFailed` callbacks\nbound to it, and a `signal` that aborts if the user removes\nthe image while it is still uploading. The same shape is\nused for `esp-image-upload-retry`.\n\n```html\n<script>\n  // Stubs — replace with your real upload/delete logic.\n  function uploadToServer(file, opts) {\n    let pct = 0;\n    const id = setInterval(() => {\n      pct = Math.min(pct + 20, 100);\n      if (opts.onProgress) opts.onProgress(pct);\n      if (pct >= 100) { clearInterval(id); }\n    }, 200);\n    return new Promise((r) => setTimeout(() => r(\"id-\" + file.name), 1200));\n  }\n  function deleteFromServer(id) { console.log(\"delete\", id); }\n\n  const uploader = findByTagName(\"esp-image-upload\")[0];\n  uploader.addEventListener(\"esp-image-upload-file-selected\", (e) => {\n    const { image, signal, onProgress, onComplete, onFailed } = e.detail;\n    // Pass `signal` to fetch/XHR so removing the image cancels the upload.\n    uploadToServer(image.file, {\n      signal,\n      onProgress: (pct) => onProgress(pct),\n    }).then((id) => onComplete(id))\n      .catch(() => onFailed());\n  });\n  uploader.addEventListener(\"esp-image-upload-retry\", (e) => {\n    const { image, signal, onProgress, onComplete } = e.detail;\n    uploadToServer(image.file, {\n      signal,\n      onProgress: (pct) => onProgress(pct),\n    }).then((id) => onComplete(id));\n  });\n  uploader.addEventListener(\"esp-image-upload-file-removed\", (e) => {\n    deleteFromServer(e.detail.uploadedId);\n  });\n</script>\n<esp-image-upload></esp-image-upload>\n```\n\n**Simulated upload progress demo**\n\nSelect images to see simulated progress. The second file\nwill fail — click Retry to re-upload it.\n\n```html\n<script>\n  const uploader = findByTagName(\"esp-image-upload\")[0];\n  let fileIndex = 0;\n\n  function simulateUpload(detail, shouldFail) {\n    let progress = 0;\n    const interval = setInterval(() => {\n      progress += Math.floor(Math.random() * 11) + 5;\n      if (shouldFail && progress >= 45) {\n        clearInterval(interval);\n        detail.onFailed();\n        return;\n      }\n      if (progress >= 100) {\n        clearInterval(interval);\n        detail.onProgress(100);\n        setTimeout(() => detail.onComplete(\"id-\" + detail.image.file.name), 500);\n        return;\n      }\n      detail.onProgress(progress);\n    }, 300 + Math.random() * 300);\n  }\n\n  uploader.addEventListener(\"esp-image-upload-file-selected\", (e) => {\n    const idx = fileIndex++;\n    simulateUpload(e.detail, idx === 1);\n  });\n\n  uploader.addEventListener(\"esp-image-upload-retry\", (e) => {\n    simulateUpload(e.detail, false);\n  });\n</script>\n<esp-image-upload></esp-image-upload>\n```\n\n**Editing with existing images**\n\nPre-populate with server images via `setExistingImages`.\nExisting images never show upload overlays.\n\n```html\n<script>\n  const uploader = findByTagName(\"esp-image-upload\")[0];\n  uploader.setExistingImages([\n    { url: \"https://picsum.photos/id/29/1200/800\", width: 1200, height: 800, uploadedId: \"img-1\" },\n    { url: \"https://picsum.photos/id/15/900/1200\", width: 900,  height: 1200, uploadedId: \"img-2\" },\n  ]);\n  uploader.addEventListener(\"esp-image-upload-file-removed\", (e) => {\n    if (e.detail.source === \"existing\") {\n      console.log(\"Mark for deletion:\", e.detail.uploadedId);\n    }\n  });\n</script>\n<esp-image-upload></esp-image-upload>\n```",
-          "name": "EspalierImageUpload",
+          "description": "An image preview for the upload component.\n\nRemoval and retry requests are private coordination events consumed by\nthe owning `esp-image-upload`.",
+          "name": "EspalierImagePreview",
           "cssProperties": [
             {
-              "description": "The background color of the image preview area.",
-              "name": "--esp-image-upload-preview-background"
+              "description": "The border color of the preview.",
+              "name": "--esp-image-preview-border-color"
+            },
+            {
+              "description": "The text color of the remove button.",
+              "name": "--esp-image-preview-remove-color"
+            },
+            {
+              "description": "The text color used by upload and failure overlays.",
+              "name": "--esp-image-preview-overlay-text"
             },
             {
               "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
@@ -40437,580 +40519,388 @@
           "members": [
             {
               "kind": "field",
-              "name": "uploadInput",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "previewsDiv",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "dropAreaDiv",
-              "privacy": "private"
+              "name": "image"
             },
             {
               "kind": "field",
-              "name": "draggingOver",
+              "name": "url",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "false"
+              "default": "\"\"",
+              "attribute": "url"
             },
             {
               "kind": "field",
-              "name": "uploadedImages",
+              "name": "alt",
               "type": {
-                "text": "Array<EspalierUploadImage>"
+                "text": "string"
               },
-              "default": "[]"
+              "default": "\"\"",
+              "description": "Alternative text for the preview image (typically the file name).",
+              "attribute": "alt"
             },
             {
               "kind": "field",
-              "name": "accept",
+              "name": "progress",
               "type": {
-                "text": "string"
+                "text": "number | null | undefined"
               },
-              "default": "\"image/jpeg, image/png, image/webp\"",
-              "description": "Comma-separated list of accepted file types, in the same format as the\nnative input `accept` attribute: MIME types (`image/png`), MIME\nwildcards (`image/*`), or extensions (`.png`). Files outside this list\nare skipped and reported via the `esp-image-upload-files-rejected` event.",
-              "attribute": "accept"
+              "description": "Upload progress for this image.\n- `undefined` — no overlay (not uploading)\n- `null` — indeterminate spinner (upload started, no progress yet)\n- `0–100` — determinate progress ring",
+              "attribute": "progress"
             },
             {
               "kind": "field",
-              "name": "maxImagesPerRow",
+              "name": "failed",
               "type": {
-                "text": "number"
+                "text": "boolean"
               },
-              "description": "Maximum number of image previews in each justified row. Positive integers\ncreate a hard row boundary; omitted, non-finite, non-integer, and\nnonpositive values leave rows unlimited.",
-              "attribute": "max-images-per-row"
+              "default": "false",
+              "description": "Whether the upload for this image has failed.\nShows an error overlay with a retry button.",
+              "attribute": "failed"
             },
             {
               "kind": "field",
-              "name": "maxRowHeightVh",
-              "default": "DEFAULT_ALBUM_MAX_ROW_HEIGHT_VH",
-              "description": "Maximum preview-row height as a percentage of the layout viewport. Values\noutside the inclusive integer range `1…100` fall back to 90.",
+              "name": "sourceToken",
               "type": {
                 "text": "number"
               },
-              "attribute": "max-row-height-vh"
+              "privacy": "private",
+              "default": "0",
+              "description": "The source token keys a fresh image element for every exact-URL retry."
             },
             {
               "kind": "field",
-              "name": "_rejectionNotice",
+              "name": "admittedUrl",
               "type": {
                 "text": "string"
               },
               "privacy": "private",
               "default": "\"\"",
-              "description": "Transient inline message describing skipped files."
+              "description": "The remote URL currently assigned to an admitted image element."
             },
             {
               "kind": "field",
-              "name": "_noticeTimer",
+              "name": "remoteImageLoaded",
               "type": {
-                "text": "ReturnType<typeof setTimeout> | undefined"
+                "text": "boolean"
               },
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "_uploadState",
               "privacy": "private",
-              "default": "new WeakMap<EspalierUploadImage, UploadTrackingState>()"
+              "default": "false",
+              "description": "A successful image stays rendered without holding a shared queue slot."
             },
             {
               "kind": "field",
-              "name": "_selectionGeneration",
+              "name": "imageLoadFailed",
               "type": {
-                "text": "number"
+                "text": "boolean"
               },
               "privacy": "private",
-              "default": "0",
-              "description": "Bumped whenever the image list is replaced or the component unmounts so\nstill-decoding selections from before the change are discarded instead\nof landing in the new list."
+              "default": "false",
+              "description": "True after automatic retries are exhausted, until the user retries the image."
             },
             {
               "kind": "field",
-              "name": "_chromeWidth",
+              "name": "automaticRetryCount",
               "type": {
-                "text": "number | null"
+                "text": "number"
               },
               "privacy": "private",
-              "default": "null",
-              "description": "Cached horizontal chrome (previews padding + field border); re-measured after resize."
-            },
-            {
-              "kind": "field",
-              "name": "_resizeObserver",
-              "privacy": "private",
-              "default": "new ResizeObserver(() => { this._chromeWidth = null; this.requestUpdate(); })"
-            },
-            {
-              "kind": "field",
-              "name": "_handleViewportResize",
-              "privacy": "private",
-              "description": "Recalculate the viewport-derived row ceiling when only height changes."
+              "default": "0",
+              "description": "Number of automatic retries already scheduled for the current URL."
             },
             {
               "kind": "field",
-              "name": "_dragPointerId",
+              "name": "remotePreviewVisible",
               "type": {
-                "text": "number | null"
+                "text": "boolean"
               },
               "privacy": "private",
-              "default": "null",
-              "description": "The pointerId that initiated the drag — ignore events from other pointers."
+              "default": "false",
+              "description": "Whether IntersectionObserver currently considers this preview visible."
             },
             {
               "kind": "field",
-              "name": "_dragSourceIndex",
+              "name": "visibilityObserver",
               "type": {
-                "text": "number | null"
+                "text": "IntersectionObserver | null"
               },
               "privacy": "private",
               "default": "null"
             },
             {
               "kind": "field",
-              "name": "_dragOverIndex",
+              "name": "queuedLoadCancel",
               "type": {
-                "text": "number | null"
+                "text": "(() => void) | null"
               },
               "privacy": "private",
               "default": "null"
             },
             {
               "kind": "field",
-              "name": "_dragStartX",
+              "name": "loadSlotRelease",
               "type": {
-                "text": "number"
+                "text": "(() => void) | null"
               },
               "privacy": "private",
-              "default": "0"
+              "default": "null"
             },
             {
               "kind": "field",
-              "name": "_dragStartY",
+              "name": "retryTimer",
               "type": {
-                "text": "number"
+                "text": "ReturnType<typeof setTimeout> | null"
               },
               "privacy": "private",
-              "default": "0"
+              "default": "null"
             },
             {
               "kind": "field",
-              "name": "_dragActive",
+              "name": "loadTimeoutTimer",
               "type": {
-                "text": "boolean"
+                "text": "ReturnType<typeof setTimeout> | null"
               },
               "privacy": "private",
-              "default": "false"
+              "default": "null"
             },
             {
               "kind": "field",
-              "name": "_ghostEl",
+              "name": "activeSourceToken",
               "type": {
-                "text": "HTMLElement | null"
+                "text": "number | null"
               },
               "privacy": "private",
               "default": "null"
             },
             {
-              "kind": "field",
-              "name": "_ghostHalfW",
-              "type": {
-                "text": "number"
-              },
+              "kind": "method",
+              "name": "startCurrentPreview",
               "privacy": "private",
-              "default": "0",
-              "description": "Cached ghost half-width/height so pointermove avoids offsetWidth/Height."
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             },
             {
-              "kind": "field",
-              "name": "_ghostHalfH",
-              "type": {
-                "text": "number"
-              },
+              "kind": "method",
+              "name": "stopVisibilityObserver",
               "privacy": "private",
-              "default": "0"
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             },
             {
-              "kind": "field",
-              "name": "_arrowEl",
-              "type": {
-                "text": "HTMLElement | null"
-              },
+              "kind": "method",
+              "name": "requestRemoteLoad",
               "privacy": "private",
-              "default": "null"
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             },
             {
-              "kind": "field",
-              "name": "_cachedPreviews",
-              "type": {
-                "text": "{ el: HTMLElement; rect: DOMRect }[] | null"
-              },
+              "kind": "method",
+              "name": "handleImageLoad",
               "privacy": "private",
-              "default": "null",
-              "description": "Cached preview elements + bounding rects, set once when drag activates."
-            },
-            {
-              "kind": "field",
-              "name": "_lastDropHit",
-              "type": {
-                "text": "{ index: number; after: boolean } | null"
-              },
-              "privacy": "private",
-              "default": "null",
-              "description": "Last drop-target state to avoid redundant DOM updates in pointermove."
-            },
-            {
-              "kind": "field",
-              "name": "_savedBodyUserSelect",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "private",
-              "default": "\"\"",
-              "description": "Saved body userSelect value to restore after drag."
-            },
-            {
-              "kind": "field",
-              "name": "_DRAG_THRESHOLD",
-              "type": {
-                "text": "number"
-              },
-              "privacy": "private",
-              "static": true,
-              "readonly": true,
-              "default": "8"
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event"
+                  }
+                },
+                {
+                  "name": "token",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
             },
             {
               "kind": "method",
-              "name": "_getPreviewIndex",
+              "name": "handleImageError",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "number | null"
+                  "text": "void"
                 }
               },
               "parameters": [
                 {
-                  "name": "ev",
+                  "name": "event",
                   "type": {
                     "text": "Event"
                   }
+                },
+                {
+                  "name": "token",
+                  "type": {
+                    "text": "number"
+                  }
                 }
-              ],
-              "description": "Find the preview index from a composedPath."
-            },
-            {
-              "kind": "field",
-              "name": "_handleDragPointerDown",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "_onDocPointerMove",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "_onDocPointerUp",
-              "privacy": "private"
-            },
-            {
-              "kind": "method",
-              "name": "_clearDragState",
-              "privacy": "private"
+              ]
             },
             {
               "kind": "method",
-              "name": "_createGhost",
+              "name": "isActiveImageEvent",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
               "parameters": [
                 {
-                  "name": "x",
+                  "name": "event",
                   "type": {
-                    "text": "number"
+                    "text": "Event"
                   }
                 },
                 {
-                  "name": "y",
+                  "name": "token",
                   "type": {
                     "text": "number"
                   }
                 }
-              ],
-              "description": "Create a ghost thumbnail that follows the cursor."
-            },
-            {
-              "kind": "field",
-              "name": "_arrowColor",
-              "type": {
-                "text": "string | null"
-              },
-              "privacy": "private",
-              "default": "null",
-              "description": "Cached arrow color so we don't call getComputedStyle on every update."
+              ]
             },
             {
               "kind": "method",
-              "name": "_updateDropTargets",
+              "name": "handleImageFailure",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
               "parameters": [
                 {
-                  "name": "previews",
-                  "type": {
-                    "text": "HTMLElement[]"
-                  }
-                },
-                {
-                  "name": "hitIndex",
+                  "name": "token",
                   "type": {
                     "text": "number"
                   }
-                },
-                {
-                  "name": "insertAfter",
-                  "type": {
-                    "text": "boolean"
-                  }
                 }
-              ],
-              "description": "Show a drop-target overlay on the hovered preview."
+              ]
             },
             {
               "kind": "method",
-              "name": "_clearDropTargets",
+              "name": "completeActiveLoad",
               "privacy": "private",
-              "description": "Clear all drop-target overlays."
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             },
             {
               "kind": "method",
-              "name": "getContainerWidth",
+              "name": "abandonActiveLoad",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "number"
+                  "text": "void"
                 }
               },
-              "description": "Gets the container width for layout calculation based on responsive breakpoints.\nBreakpoints chosen to maintain consistent visual appearance across devices:\n- Mobile (< 640px): Full width minus padding\n- Tablet (640px - 1024px): 90% width\n- Desktop (> 1024px): 85% width with max 1400px"
+              "description": "Cancel an in-flight browser request before returning its shared slot.\nA settled image never reaches this path, so its successfully loaded source\nremains visible through a disconnect or later update."
             },
             {
               "kind": "method",
-              "name": "_isAccepted",
+              "name": "releaseActiveLoad",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "boolean"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "file",
-                  "type": {
-                    "text": "File"
-                  }
+                  "text": "void"
                 }
-              ],
-              "description": "Check a file against the `accept` list (MIME, MIME wildcard, or extension)."
+              }
             },
             {
-              "kind": "field",
-              "name": "filesSelected",
-              "privacy": "private"
+              "kind": "method",
+              "name": "cancelQueuedLoad",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             },
             {
               "kind": "method",
-              "name": "_addSelectedImage",
+              "name": "cancelRemoteWork",
               "privacy": "private",
-              "parameters": [
-                {
-                  "name": "batch",
-                  "type": {
-                    "text": "(SelectedUploadImage | null)[]"
-                  }
-                },
-                {
-                  "name": "index",
-                  "type": {
-                    "text": "number"
-                  }
-                },
-                {
-                  "name": "image",
-                  "type": {
-                    "text": "SelectedUploadImage"
-                  }
+              "return": {
+                "type": {
+                  "text": "void"
                 }
-              ],
-              "description": "Insert a processed image at its selection-order position. Anchors on\nalready-inserted batch neighbors so concurrent completions, removals,\nand reorders mid-batch cannot scramble the order."
+              }
             },
             {
               "kind": "method",
-              "name": "_reportRejectedFiles",
+              "name": "retryImage",
               "privacy": "private",
-              "parameters": [
-                {
-                  "name": "detail",
-                  "type": {
-                    "text": "FilesRejectedDetail"
-                  }
+              "return": {
+                "type": {
+                  "text": "void"
                 }
-              ],
-              "description": "Dispatch `esp-image-upload-files-rejected` and show the transient inline notice."
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderImage",
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "_makeCallbacks",
+              "name": "seedColorBacker",
+              "type": {
+                "text": "string"
+              },
               "privacy": "private",
-              "description": "Create upload callbacks bound to a specific image.\nClosures capture the image reference directly — no filename lookup."
+              "default": "\"oklch(0.7 0.125 216)\"",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             },
             {
               "kind": "field",
-              "name": "_THUMBNAIL_UPSCALE_SLACK",
+              "name": "espRoot",
               "type": {
-                "text": "number"
+                "text": "EspalierRoot | null"
               },
               "privacy": "private",
-              "static": true,
-              "readonly": true,
-              "default": "1.1",
-              "description": "Allowed upscale factor before a preview switches to its full-resolution source."
+              "default": "null",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             },
             {
               "kind": "field",
-              "name": "_fullPreviewUrls",
+              "name": "contextBacker",
+              "type": {
+                "text": "string"
+              },
               "privacy": "private",
-              "default": "new Map<SelectedUploadImage, string>()",
-              "description": "Full-resolution object URLs for selected images rendered beyond thumbnail capacity."
+              "default": "\"\"",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             },
             {
-              "kind": "method",
-              "name": "_previewUrlFor",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "string"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "image",
-                  "type": {
-                    "text": "EspalierUploadImage"
-                  }
-                },
-                {
-                  "name": "renderedHeight",
-                  "type": {
-                    "text": "number"
-                  }
-                },
-                {
-                  "name": "renderedWidth",
-                  "optional": true,
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ],
-              "description": "Resolve the URL needed to cover both dimensions of the rendered cell.\nThumbnails cover rows near the target height; images stretched well\nbeyond thumbnail capacity (clamped tall rows, single images) lazily\nswitch to a full-resolution object URL so they don't upscale blurry."
-            },
-            {
-              "kind": "method",
-              "name": "_pickExistingPreviewUrl",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "string"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "image",
-                  "type": {
-                    "text": "ExistingUploadImage"
-                  }
-                },
-                {
-                  "name": "renderedHeight",
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ],
-              "description": "For a server image, pick the smallest responsive variant that covers the\npreview's rendered box (× DPR), falling back to the largest variant — and to\nthe single `url` when no responsive set was supplied. The supplied height is the full source height\nrequired for cover (including any clipped overflow), so the required width\nis `renderedHeight × aspect`."
-            },
-            {
-              "kind": "method",
-              "name": "_releaseFullPreviewUrl",
-              "privacy": "private",
-              "parameters": [
-                {
-                  "name": "image",
-                  "type": {
-                    "text": "EspalierUploadImage"
-                  }
-                }
-              ],
-              "description": "Revoke the full-resolution preview URL for one image, if it exists."
-            },
-            {
-              "kind": "method",
-              "name": "_releaseSelectedImages",
-              "privacy": "private",
-              "description": "Abort in-flight uploads and revoke preview object URLs for selected images."
-            },
-            {
-              "kind": "field",
-              "name": "setExistingImages",
-              "privacy": "public",
-              "description": "Populate the component with images that already exist on the server.\nEach entry must provide a display URL, dimensions for layout, and\nan `uploadedId` that identifies the server-side image.\n\nEntries with missing `url`/`uploadedId` or non-finite/non-positive\ndimensions are silently filtered out."
-            },
-            {
-              "kind": "field",
-              "name": "seedColorBacker",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "private",
-              "default": "\"oklch(0.7 0.125 216)\"",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "kind": "field",
-              "name": "espRoot",
-              "type": {
-                "text": "EspalierRoot | null"
-              },
-              "privacy": "private",
-              "default": "null",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "kind": "field",
-              "name": "contextBacker",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "private",
-              "default": "\"\"",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "kind": "field",
-              "name": "scopedTokenOriginalValues",
+              "kind": "field",
+              "name": "scopedTokenOriginalValues",
               "privacy": "private",
               "readonly": true,
               "default": "new Map< string, { generatedPriority: string; generatedValue: string; originalPriority: string; originalValue: string | null; } >()",
@@ -41694,69 +41584,41 @@
               }
             }
           ],
-          "events": [
-            {
-              "type": {
-                "text": "CustomEvent<EspalierUploadImage>"
-              },
-              "description": "Fired when an image has been removed by the user. Narrow on `detail.source` to distinguish newly selected images from pre-existing server images. If the image's upload was still in flight, its `signal` aborts.",
-              "name": "esp-image-upload-file-removed"
-            },
-            {
-              "type": {
-                "text": "CustomEvent<UploadEventDetail>"
-              },
-              "description": "Fired when an image has been selected by the user. `detail.image` is the actual object stored in `uploadedImages`; `detail.onProgress`, `detail.onComplete`, and `detail.onFailed` are callbacks bound to that image. `detail.signal` aborts if the image is removed mid-upload — pass it to fetch/XHR.",
-              "name": "esp-image-upload-file-selected"
-            },
-            {
-              "type": {
-                "text": "CustomEvent<UploadEventDetail>"
-              },
-              "description": "Fired when the user clicks Retry on a failed upload. `detail.image` is the same object reference; fresh callbacks and a fresh `signal` are provided. The component automatically resets the image to indeterminate progress.",
-              "name": "esp-image-upload-retry"
-            },
+          "events": [],
+          "attributes": [
             {
+              "name": "url",
               "type": {
-                "text": "CustomEvent<ImagesReorderedDetail>"
+                "text": "string"
               },
-              "description": "Fired after the user drags an image to a new position. `detail.images` is the reordered array (same references, new order).",
-              "name": "esp-image-upload-images-reordered"
+              "default": "\"\"",
+              "fieldName": "url"
             },
             {
-              "type": {
-                "text": "CustomEvent<FilesRejectedDetail>"
-              },
-              "description": "Fired when selected files are skipped, either because their type is not accepted (`detail.unsupported`) or because they could not be read or decoded (`detail.unreadable`). The component also shows a transient inline notice.",
-              "name": "esp-image-upload-files-rejected"
-            }
-          ],
-          "attributes": [
-            {
-              "name": "accept",
+              "name": "alt",
               "type": {
                 "text": "string"
               },
-              "default": "\"image/jpeg, image/png, image/webp\"",
-              "description": "Comma-separated list of accepted file types, in the same format as the\nnative input `accept` attribute: MIME types (`image/png`), MIME\nwildcards (`image/*`), or extensions (`.png`). Files outside this list\nare skipped and reported via the `esp-image-upload-files-rejected` event.",
-              "fieldName": "accept"
+              "default": "\"\"",
+              "description": "Alternative text for the preview image (typically the file name).",
+              "fieldName": "alt"
             },
             {
-              "name": "max-images-per-row",
+              "name": "progress",
               "type": {
-                "text": "number"
+                "text": "number | null | undefined"
               },
-              "description": "Maximum number of image previews in each justified row. Positive integers\ncreate a hard row boundary; omitted, non-finite, non-integer, and\nnonpositive values leave rows unlimited.",
-              "fieldName": "maxImagesPerRow"
+              "description": "Upload progress for this image.\n- `undefined` — no overlay (not uploading)\n- `null` — indeterminate spinner (upload started, no progress yet)\n- `0–100` — determinate progress ring",
+              "fieldName": "progress"
             },
             {
-              "name": "max-row-height-vh",
-              "default": "DEFAULT_ALBUM_MAX_ROW_HEIGHT_VH",
-              "description": "Maximum preview-row height as a percentage of the layout viewport. Values\noutside the inclusive integer range `1…100` fall back to 90.",
+              "name": "failed",
               "type": {
-                "text": "number"
+                "text": "boolean"
               },
-              "fieldName": "maxRowHeightVh"
+              "default": "false",
+              "description": "Whether the upload for this image has failed.\nShows an error overlay with a retry button.",
+              "fieldName": "failed"
             },
             {
               "name": "scheme",
@@ -41800,173 +41662,56 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "docPageTitle": {
-            "name": "Image",
-            "description": "Upload"
-          },
-          "docUrl": {
-            "name": "/components/image-upload",
-            "description": ""
-          },
-          "menuGroup": {
-            "name": "Form",
-            "description": "Controls"
-          },
-          "menuLabel": {
-            "name": "Image",
-            "description": "Upload"
-          },
-          "menuIcon": {
-            "name": "photo-up",
-            "description": ""
-          },
-          "tagName": "esp-image-upload",
+          "tagName": "esp-image-preview",
           "customElement": true
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierImageUpload",
+          "name": "EspalierImagePreview",
           "declaration": {
-            "name": "EspalierImageUpload",
-            "module": "dist/image-upload/esp-image-upload.js"
+            "name": "EspalierImagePreview",
+            "module": "dist/image-upload/esp-image-preview.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-image-upload",
+          "name": "esp-image-preview",
           "declaration": {
-            "name": "EspalierImageUpload",
-            "module": "dist/image-upload/esp-image-upload.js"
+            "name": "EspalierImagePreview",
+            "module": "dist/image-upload/esp-image-preview.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "dist/image-upload/image-helpers.js",
+      "path": "dist/image-upload/esp-image-upload.js",
       "declarations": [
         {
-          "kind": "function",
-          "name": "getImageDetails",
-          "return": {
-            "type": {
-              "text": "Promise<SelectedUploadImage>"
-            }
-          },
-          "parameters": [
+          "kind": "class",
+          "description": "Used to upload images.\n\n```html\n<esp-image-upload></esp-image-upload>\n```\n\n**Uploading new images**\n\nThe `esp-image-upload-file-selected` event detail provides the `image`\nreference (the actual object in `uploadedImages`) plus\n`onProgress`, `onComplete`, and `onFailed` callbacks\nbound to it, and a `signal` that aborts if the user removes\nthe image while it is still uploading. The same shape is\nused for `esp-image-upload-retry`.\n\n```html\n<script>\n  // Stubs — replace with your real upload/delete logic.\n  function uploadToServer(file, opts) {\n    let pct = 0;\n    const id = setInterval(() => {\n      pct = Math.min(pct + 20, 100);\n      if (opts.onProgress) opts.onProgress(pct);\n      if (pct >= 100) { clearInterval(id); }\n    }, 200);\n    return new Promise((r) => setTimeout(() => r(\"id-\" + file.name), 1200));\n  }\n  function deleteFromServer(id) { console.log(\"delete\", id); }\n\n  const uploader = findByTagName(\"esp-image-upload\")[0];\n  uploader.addEventListener(\"esp-image-upload-file-selected\", (e) => {\n    const { image, signal, onProgress, onComplete, onFailed } = e.detail;\n    // Pass `signal` to fetch/XHR so removing the image cancels the upload.\n    uploadToServer(image.file, {\n      signal,\n      onProgress: (pct) => onProgress(pct),\n    }).then((id) => onComplete(id))\n      .catch(() => onFailed());\n  });\n  uploader.addEventListener(\"esp-image-upload-retry\", (e) => {\n    const { image, signal, onProgress, onComplete } = e.detail;\n    uploadToServer(image.file, {\n      signal,\n      onProgress: (pct) => onProgress(pct),\n    }).then((id) => onComplete(id));\n  });\n  uploader.addEventListener(\"esp-image-upload-file-removed\", (e) => {\n    deleteFromServer(e.detail.uploadedId);\n  });\n</script>\n<esp-image-upload></esp-image-upload>\n```\n\n**Simulated upload progress demo**\n\nSelect images to see simulated progress. The second file\nwill fail — click Retry to re-upload it.\n\n```html\n<script>\n  const uploader = findByTagName(\"esp-image-upload\")[0];\n  let fileIndex = 0;\n\n  function simulateUpload(detail, shouldFail) {\n    let progress = 0;\n    const interval = setInterval(() => {\n      progress += Math.floor(Math.random() * 11) + 5;\n      if (shouldFail && progress >= 45) {\n        clearInterval(interval);\n        detail.onFailed();\n        return;\n      }\n      if (progress >= 100) {\n        clearInterval(interval);\n        detail.onProgress(100);\n        setTimeout(() => detail.onComplete(\"id-\" + detail.image.file.name), 500);\n        return;\n      }\n      detail.onProgress(progress);\n    }, 300 + Math.random() * 300);\n  }\n\n  uploader.addEventListener(\"esp-image-upload-file-selected\", (e) => {\n    const idx = fileIndex++;\n    simulateUpload(e.detail, idx === 1);\n  });\n\n  uploader.addEventListener(\"esp-image-upload-retry\", (e) => {\n    simulateUpload(e.detail, false);\n  });\n</script>\n<esp-image-upload></esp-image-upload>\n```\n\n**Editing with existing images**\n\nPre-populate with server images via `setExistingImages`.\nExisting images never show upload overlays.\n\n```html\n<script>\n  const uploader = findByTagName(\"esp-image-upload\")[0];\n  uploader.setExistingImages([\n    { url: \"https://picsum.photos/id/29/1200/800\", width: 1200, height: 800, uploadedId: \"img-1\" },\n    { url: \"https://picsum.photos/id/15/900/1200\", width: 900,  height: 1200, uploadedId: \"img-2\" },\n  ]);\n  uploader.addEventListener(\"esp-image-upload-file-removed\", (e) => {\n    if (e.detail.source === \"existing\") {\n      console.log(\"Mark for deletion:\", e.detail.uploadedId);\n    }\n  });\n</script>\n<esp-image-upload></esp-image-upload>\n```",
+          "name": "EspalierImageUpload",
+          "cssProperties": [
             {
-              "name": "file",
-              "type": {
-                "text": "File"
-              }
+              "description": "The background color of the image preview area.",
+              "name": "--esp-image-upload-preview-background"
             },
             {
-              "name": "options",
-              "optional": true,
-              "type": {
-                "text": "ImageDetailsOptions"
+              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "name": "--esp-field-background",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
               }
-            }
-          ],
-          "description": "Measure a selected file and produce a `SelectedUploadImage` whose `url`\nis a lightweight object URL suitable for previews (downscaled for large\nraster images). Rejects when the file cannot be read or decoded.\n\nThe returned `url` is an object URL owned by the caller — release it\nwith releasePreviewUrl when the image is discarded."
-        },
-        {
-          "kind": "function",
-          "name": "releasePreviewUrl",
-          "return": {
-            "type": {
-              "text": "void"
-            }
-          },
-          "parameters": [
+            },
             {
-              "name": "image",
-              "type": {
-                "text": "EspalierUploadImage"
-              }
-            }
-          ],
-          "description": "Release the object URL backing a selected image's preview. Safe to call\non existing images — server URLs are never revoked."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "getImageDetails",
-          "declaration": {
-            "name": "getImageDetails",
-            "module": "dist/image-upload/image-helpers.js"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "releasePreviewUrl",
-          "declaration": {
-            "name": "releasePreviewUrl",
-            "module": "dist/image-upload/image-helpers.js"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "dist/image-upload/preview-load-queue.js",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "previewLoadQueue",
-          "default": "new PreviewLoadQueue(4)",
-          "description": "Four remote downloads is enough to fill a row without overwhelming an image service."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "previewLoadQueue",
-          "declaration": {
-            "name": "previewLoadQueue",
-            "module": "dist/image-upload/preview-load-queue.js"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "dist/image-picker/esp-image-picker.js",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "A form-associated image picker with large image choices and a selected preview.\n\nThe component is controlled: set `images` and `value` from consumer state,\nthen use `esp-value-changed` to persist a user's next selection. An empty\n`value` means the Automatic choice. Labels are optional; unlabeled images use\ntheir alternative text or a numbered name. Images are shown without cropping.\n\nThe large preview sits above the control by default. Set\n`preview-placement=\"beside\"` for a compact preview beside the control.\nSize the preview and option images with the CSS properties below.\n\n```html\n<esp-form-item label=\"Page cover\">\n  <esp-image-picker name=\"cover\" value=\"field\"></esp-image-picker>\n</esp-form-item>\n<script>\n  const picker = document.querySelector(\"esp-image-picker\");\n  picker.images = [\n    { id: \"field\", src: \"/assets/focus-picker-unsplash.jpg\" },\n    { id: \"paper\", src: \"/assets/espalier-paper-texture.png\" },\n  ];\n  picker.addEventListener(\"esp-value-changed\", (event) => {\n    picker.value = event.detail;\n  });\n</script>\n```",
-          "name": "EspalierImagePicker",
-          "cssProperties": [
-            {
-              "description": "Height of the large preview above the control. Default 16rem.",
-              "name": "--esp-image-picker-preview-height"
-            },
-            {
-              "description": "Width of dropdown images, capped at 40vw on narrow screens. Default 12rem.",
-              "name": "--esp-image-picker-option-width"
-            },
-            {
-              "description": "Height of dropdown images. Images retain their aspect ratio. Default 8rem.",
-              "name": "--esp-image-picker-option-height"
-            },
-            {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
-              "name": "--esp-field-background",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Border color of the shared field shell. Defaults to `var(--esp-color-border)`.",
-              "name": "--esp-field-border-color",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
+              "description": "Border color of the shared field shell. Defaults to `var(--esp-color-border)`.",
+              "name": "--esp-field-border-color",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
               }
             },
             {
@@ -42013,252 +41758,490 @@
           "members": [
             {
               "kind": "field",
-              "name": "formAssociated",
-              "type": {
-                "text": "boolean"
-              },
-              "static": true,
-              "default": "true"
+              "name": "uploadInput",
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "internals",
+              "name": "previewsDiv",
               "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "formCtrl",
-              "privacy": "private",
-              "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => (this.selectedImage ? this.value : null), getValidity: () => null, onReset: () => { this.value = \"\"; }, onRestore: (state: string) => { this.value = state; }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
+              "name": "dropAreaDiv",
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "formItemRelay",
+              "name": "draggingOver",
+              "type": {
+                "text": "boolean"
+              },
               "privacy": "private",
-              "default": "new FormItemRelay(() => this.picker as EspalierFormField | undefined)"
+              "default": "false"
             },
             {
               "kind": "field",
-              "name": "synchronizingPicker",
+              "name": "uploadedImages",
               "type": {
-                "text": "boolean"
+                "text": "Array<EspalierUploadImage>"
               },
-              "privacy": "private",
-              "default": "true"
+              "default": "[]"
             },
             {
               "kind": "field",
-              "name": "pickerSyncGeneration",
+              "name": "accept",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"image/jpeg, image/png, image/webp\"",
+              "description": "Comma-separated list of accepted file types, in the same format as the\nnative input `accept` attribute: MIME types (`image/png`), MIME\nwildcards (`image/*`), or extensions (`.png`). Files outside this list\nare skipped and reported via the `esp-image-upload-files-rejected` event.",
+              "attribute": "accept"
+            },
+            {
+              "kind": "field",
+              "name": "maxImagesPerRow",
               "type": {
                 "text": "number"
               },
-              "privacy": "private",
-              "default": "0"
+              "description": "Maximum number of image previews in each justified row. Positive integers\ncreate a hard row boundary; omitted, non-finite, non-integer, and\nnonpositive values leave rows unlimited.",
+              "attribute": "max-images-per-row"
             },
             {
               "kind": "field",
-              "name": "images",
+              "name": "maxRowHeightVh",
+              "default": "DEFAULT_ALBUM_MAX_ROW_HEIGHT_VH",
+              "description": "Maximum preview-row height as a percentage of the layout viewport. Values\noutside the inclusive integer range `1…100` fall back to 90.",
               "type": {
-                "text": "ImagePickerImage[]"
+                "text": "number"
               },
-              "privacy": "public",
-              "default": "[]",
-              "description": "Image candidates, kept in the supplied order.",
-              "attribute": "images"
+              "attribute": "max-row-height-vh"
             },
             {
               "kind": "field",
-              "name": "value",
+              "name": "_rejectionNotice",
               "type": {
                 "text": "string"
               },
-              "privacy": "public",
+              "privacy": "private",
               "default": "\"\"",
-              "description": "Selected image ID. An empty string selects Automatic.",
-              "attribute": "value"
+              "description": "Transient inline message describing skipped files."
             },
             {
               "kind": "field",
-              "name": "previewPlacement",
+              "name": "_noticeTimer",
               "type": {
-                "text": "\"above\" | \"beside\""
+                "text": "ReturnType<typeof setTimeout> | undefined"
               },
-              "privacy": "public",
-              "default": "\"above\"",
-              "description": "Preview placement: above (default, large) or beside (compact).",
-              "attribute": "preview-placement",
-              "reflects": true
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "disabled",
+              "name": "_uploadState",
+              "privacy": "private",
+              "default": "new WeakMap<EspalierUploadImage, UploadTrackingState>()"
+            },
+            {
+              "kind": "field",
+              "name": "_selectionGeneration",
               "type": {
-                "text": "boolean"
+                "text": "number"
               },
-              "privacy": "public",
-              "default": "false",
-              "description": "Disables the picker trigger.",
-              "attribute": "disabled",
-              "reflects": true
+              "privacy": "private",
+              "default": "0",
+              "description": "Bumped whenever the image list is replaced or the component unmounts so\nstill-decoding selections from before the change are discarded instead\nof landing in the new list."
             },
             {
               "kind": "field",
-              "name": "loading",
+              "name": "_chromeWidth",
               "type": {
-                "text": "boolean"
+                "text": "number | null"
               },
-              "privacy": "public",
-              "default": "false",
-              "description": "Shows a loading state while candidates are being fetched.",
-              "attribute": "loading",
-              "reflects": true
+              "privacy": "private",
+              "default": "null",
+              "description": "Cached horizontal chrome (previews padding + field border); re-measured after resize."
             },
             {
               "kind": "field",
-              "name": "emptyMessage",
+              "name": "_resizeObserver",
+              "privacy": "private",
+              "default": "new ResizeObserver(() => { this._chromeWidth = null; this.requestUpdate(); })"
+            },
+            {
+              "kind": "field",
+              "name": "_handleViewportResize",
+              "privacy": "private",
+              "description": "Recalculate the viewport-derived row ceiling when only height changes."
+            },
+            {
+              "kind": "field",
+              "name": "_dragPointerId",
               "type": {
-                "text": "string"
+                "text": "number | null"
               },
-              "privacy": "public",
-              "default": "\"No images available.\"",
-              "description": "Message shown when no image candidates are available.",
-              "attribute": "empty-message"
+              "privacy": "private",
+              "default": "null",
+              "description": "The pointerId that initiated the drag — ignore events from other pointers."
             },
             {
               "kind": "field",
-              "name": "automaticLabel",
+              "name": "_dragSourceIndex",
               "type": {
-                "text": "string"
+                "text": "number | null"
               },
-              "privacy": "public",
-              "default": "\"Automatic\"",
-              "description": "Label for the empty-value choice.",
-              "attribute": "automatic-label"
+              "privacy": "private",
+              "default": "null"
             },
             {
               "kind": "field",
-              "name": "name",
+              "name": "_dragOverIndex",
               "type": {
-                "text": "string"
+                "text": "number | null"
               },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "The name used when this picker participates in a `<form>`.",
-              "attribute": "name",
-              "reflects": true
+              "privacy": "private",
+              "default": "null"
             },
             {
-              "kind": "method",
-              "name": "focus",
-              "privacy": "public",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "kind": "field",
+              "name": "_dragStartX",
+              "type": {
+                "text": "number"
               },
-              "parameters": [
-                {
-                  "name": "options",
-                  "optional": true,
-                  "type": {
-                    "text": "FocusOptions"
-                  }
-                }
-              ],
-              "description": "Focus the composed picker trigger."
+              "privacy": "private",
+              "default": "0"
             },
             {
-              "kind": "method",
-              "name": "validate",
-              "privacy": "public",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+              "kind": "field",
+              "name": "_dragStartY",
+              "type": {
+                "text": "number"
               },
-              "description": "Re-run form validation."
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "_dragActive",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_ghostEl",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_ghostHalfW",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Cached ghost half-width/height so pointermove avoids offsetWidth/Height."
+            },
+            {
+              "kind": "field",
+              "name": "_ghostHalfH",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "_arrowEl",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_cachedPreviews",
+              "type": {
+                "text": "{ el: HTMLElement; rect: DOMRect }[] | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "Cached preview elements + bounding rects, set once when drag activates."
+            },
+            {
+              "kind": "field",
+              "name": "_lastDropHit",
+              "type": {
+                "text": "{ index: number; after: boolean } | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "Last drop-target state to avoid redundant DOM updates in pointermove."
+            },
+            {
+              "kind": "field",
+              "name": "_savedBodyUserSelect",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "\"\"",
+              "description": "Saved body userSelect value to restore after drag."
+            },
+            {
+              "kind": "field",
+              "name": "_DRAG_THRESHOLD",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "static": true,
+              "readonly": true,
+              "default": "8"
             },
             {
               "kind": "method",
-              "name": "checkValidity",
-              "privacy": "public",
+              "name": "_getPreviewIndex",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "boolean"
+                  "text": "number | null"
                 }
               },
-              "description": "Check form validity."
+              "parameters": [
+                {
+                  "name": "ev",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ],
+              "description": "Find the preview index from a composedPath."
+            },
+            {
+              "kind": "field",
+              "name": "_handleDragPointerDown",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_onDocPointerMove",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_onDocPointerUp",
+              "privacy": "private"
             },
             {
               "kind": "method",
-              "name": "formResetCallback",
-              "privacy": "public",
+              "name": "_clearDragState",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_createGhost",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "x",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "y",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Create a ghost thumbnail that follows the cursor."
+            },
+            {
+              "kind": "field",
+              "name": "_arrowColor",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "Cached arrow color so we don't call getComputedStyle on every update."
+            },
+            {
+              "kind": "method",
+              "name": "_updateDropTargets",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "previews",
+                  "type": {
+                    "text": "HTMLElement[]"
+                  }
+                },
+                {
+                  "name": "hitIndex",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "insertAfter",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Show a drop-target overlay on the hovered preview."
+            },
+            {
+              "kind": "method",
+              "name": "_clearDropTargets",
+              "privacy": "private",
+              "description": "Clear all drop-target overlays."
+            },
+            {
+              "kind": "method",
+              "name": "getContainerWidth",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "number"
                 }
               },
-              "description": "Called by the browser when the owning form resets."
+              "description": "Gets the container width for layout calculation based on responsive breakpoints.\nBreakpoints chosen to maintain consistent visual appearance across devices:\n- Mobile (< 640px): Full width minus padding\n- Tablet (640px - 1024px): 90% width\n- Desktop (> 1024px): 85% width with max 1400px"
             },
             {
               "kind": "method",
-              "name": "formStateRestoreCallback",
-              "privacy": "public",
+              "name": "_isAccepted",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "boolean"
                 }
               },
               "parameters": [
                 {
-                  "name": "state",
+                  "name": "file",
                   "type": {
-                    "text": "string"
+                    "text": "File"
                   }
                 }
               ],
-              "description": "Called by the browser when form state is restored."
+              "description": "Check a file against the `accept` list (MIME, MIME wildcard, or extension)."
+            },
+            {
+              "kind": "field",
+              "name": "filesSelected",
+              "privacy": "private"
             },
             {
               "kind": "method",
-              "name": "formDisabledCallback",
-              "privacy": "public",
-              "return": {
-                "type": {
-                  "text": "void"
+              "name": "_addSelectedImage",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "batch",
+                  "type": {
+                    "text": "(SelectedUploadImage | null)[]"
+                  }
+                },
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "image",
+                  "type": {
+                    "text": "SelectedUploadImage"
+                  }
                 }
-              },
+              ],
+              "description": "Insert a processed image at its selection-order position. Anchors on\nalready-inserted batch neighbors so concurrent completions, removals,\nand reorders mid-batch cannot scramble the order."
+            },
+            {
+              "kind": "method",
+              "name": "_reportRejectedFiles",
+              "privacy": "private",
               "parameters": [
                 {
-                  "name": "isDisabled",
+                  "name": "detail",
                   "type": {
-                    "text": "boolean"
+                    "text": "FilesRejectedDetail"
                   }
                 }
               ],
-              "description": "Called by the browser when an ancestor fieldset changes disabled state."
+              "description": "Dispatch `esp-image-upload-files-rejected` and show the transient inline notice."
             },
             {
               "kind": "field",
-              "name": "picker",
-              "type": {
-                "text": "EspalierPickOne | undefined"
-              },
+              "name": "_makeCallbacks",
               "privacy": "private",
-              "readonly": true
+              "description": "Create upload callbacks bound to a specific image.\nClosures capture the image reference directly — no filename lookup."
             },
             {
               "kind": "field",
-              "name": "selectedImage",
+              "name": "_THUMBNAIL_UPSCALE_SLACK",
               "type": {
-                "text": "ImagePickerImage | undefined"
+                "text": "number"
               },
               "privacy": "private",
-              "readonly": true
+              "static": true,
+              "readonly": true,
+              "default": "1.1",
+              "description": "Allowed upscale factor before a preview switches to its full-resolution source."
+            },
+            {
+              "kind": "field",
+              "name": "_fullPreviewUrls",
+              "privacy": "private",
+              "default": "new Map<SelectedUploadImage, string>()",
+              "description": "Full-resolution object URLs for selected images rendered beyond thumbnail capacity."
+            },
+            {
+              "kind": "method",
+              "name": "_previewUrlFor",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "image",
+                  "type": {
+                    "text": "EspalierUploadImage"
+                  }
+                },
+                {
+                  "name": "renderedHeight",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "renderedWidth",
+                  "optional": true,
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Resolve the URL needed to cover both dimensions of the rendered cell.\nThumbnails cover rows near the target height; images stretched well\nbeyond thumbnail capacity (clamped tall rows, single images) lazily\nswitch to a full-resolution object URL so they don't upscale blurry."
             },
             {
               "kind": "method",
-              "name": "imageLabel",
+              "name": "_pickExistingPreviewUrl",
               "privacy": "private",
               "return": {
                 "type": {
@@ -42269,54 +42252,43 @@
                 {
                   "name": "image",
                   "type": {
-                    "text": "ImagePickerImage"
+                    "text": "ExistingUploadImage"
                   }
                 },
                 {
-                  "name": "index",
+                  "name": "renderedHeight",
                   "type": {
                     "text": "number"
                   }
                 }
-              ]
-            },
-            {
-              "kind": "field",
-              "name": "pickerItems",
-              "type": {
-                "text": "PickerItem[]"
-              },
-              "privacy": "private",
-              "readonly": true
+              ],
+              "description": "For a server image, pick the smallest responsive variant that covers the\npreview's rendered box (× DPR), falling back to the largest variant — and to\nthe single `url` when no responsive set was supplied. The supplied height is the full source height\nrequired for cover (including any clipped overflow), so the required width\nis `renderedHeight × aspect`."
             },
             {
               "kind": "method",
-              "name": "thumbnailNode",
+              "name": "_releaseFullPreviewUrl",
               "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "HTMLImageElement"
-                }
-              },
               "parameters": [
                 {
                   "name": "image",
                   "type": {
-                    "text": "ImagePickerImage"
-                  }
-                },
-                {
-                  "name": "alt",
-                  "type": {
-                    "text": "string"
+                    "text": "EspalierUploadImage"
                   }
                 }
-              ]
+              ],
+              "description": "Revoke the full-resolution preview URL for one image, if it exists."
+            },
+            {
+              "kind": "method",
+              "name": "_releaseSelectedImages",
+              "privacy": "private",
+              "description": "Abort in-flight uploads and revoke preview object URLs for selected images."
             },
             {
               "kind": "field",
-              "name": "handlePickerValueChanged",
-              "privacy": "private"
+              "name": "setExistingImages",
+              "privacy": "public",
+              "description": "Populate the component with images that already exist on the server.\nEach entry must provide a display URL, dimensions for layout, and\nan `uploadedId` that identifies the server-side image.\n\nEntries with missing `url`/`uploadedId` or non-finite/non-positive\ndimensions are silently filtered out."
             },
             {
               "kind": "field",
@@ -43046,91 +43018,66 @@
           "events": [
             {
               "type": {
-                "text": "CustomEvent<string>"
-              },
-              "description": "Fired when a user chooses an image or Automatic. The detail is the selected image ID, or an empty string for Automatic.",
-              "name": "esp-value-changed"
-            },
-            {
-              "type": {
-                "text": "CustomEvent<{ valid: boolean; message: string }>"
-              },
-              "description": "Fired whenever form validation runs.",
-              "name": "esp-validity-changed"
-            }
-          ],
-          "attributes": [
-            {
-              "name": "images",
-              "type": {
-                "text": "ImagePickerImage[]"
+                "text": "CustomEvent<EspalierUploadImage>"
               },
-              "default": "[]",
-              "description": "Image candidates, kept in the supplied order.",
-              "fieldName": "images"
+              "description": "Fired when an image has been removed by the user. Narrow on `detail.source` to distinguish newly selected images from pre-existing server images. If the image's upload was still in flight, its `signal` aborts.",
+              "name": "esp-image-upload-file-removed"
             },
             {
-              "name": "value",
               "type": {
-                "text": "string"
+                "text": "CustomEvent<UploadEventDetail>"
               },
-              "default": "\"\"",
-              "description": "Selected image ID. An empty string selects Automatic.",
-              "fieldName": "value"
+              "description": "Fired when an image has been selected by the user. `detail.image` is the actual object stored in `uploadedImages`; `detail.onProgress`, `detail.onComplete`, and `detail.onFailed` are callbacks bound to that image. `detail.signal` aborts if the image is removed mid-upload — pass it to fetch/XHR.",
+              "name": "esp-image-upload-file-selected"
             },
             {
-              "name": "preview-placement",
               "type": {
-                "text": "\"above\" | \"beside\""
+                "text": "CustomEvent<UploadEventDetail>"
               },
-              "default": "\"above\"",
-              "description": "Preview placement: above (default, large) or beside (compact).",
-              "fieldName": "previewPlacement"
+              "description": "Fired when the user clicks Retry on a failed upload. `detail.image` is the same object reference; fresh callbacks and a fresh `signal` are provided. The component automatically resets the image to indeterminate progress.",
+              "name": "esp-image-upload-retry"
             },
             {
-              "name": "disabled",
               "type": {
-                "text": "boolean"
+                "text": "CustomEvent<ImagesReorderedDetail>"
               },
-              "default": "false",
-              "description": "Disables the picker trigger.",
-              "fieldName": "disabled"
+              "description": "Fired after the user drags an image to a new position. `detail.images` is the reordered array (same references, new order).",
+              "name": "esp-image-upload-images-reordered"
             },
             {
-              "name": "loading",
               "type": {
-                "text": "boolean"
+                "text": "CustomEvent<FilesRejectedDetail>"
               },
-              "default": "false",
-              "description": "Shows a loading state while candidates are being fetched.",
-              "fieldName": "loading"
-            },
+              "description": "Fired when selected files are skipped, either because their type is not accepted (`detail.unsupported`) or because they could not be read or decoded (`detail.unreadable`). The component also shows a transient inline notice.",
+              "name": "esp-image-upload-files-rejected"
+            }
+          ],
+          "attributes": [
             {
-              "name": "empty-message",
+              "name": "accept",
               "type": {
                 "text": "string"
               },
-              "default": "\"No images available.\"",
-              "description": "Message shown when no image candidates are available.",
-              "fieldName": "emptyMessage"
+              "default": "\"image/jpeg, image/png, image/webp\"",
+              "description": "Comma-separated list of accepted file types, in the same format as the\nnative input `accept` attribute: MIME types (`image/png`), MIME\nwildcards (`image/*`), or extensions (`.png`). Files outside this list\nare skipped and reported via the `esp-image-upload-files-rejected` event.",
+              "fieldName": "accept"
             },
             {
-              "name": "automatic-label",
+              "name": "max-images-per-row",
               "type": {
-                "text": "string"
+                "text": "number"
               },
-              "default": "\"Automatic\"",
-              "description": "Label for the empty-value choice.",
-              "fieldName": "automaticLabel"
+              "description": "Maximum number of image previews in each justified row. Positive integers\ncreate a hard row boundary; omitted, non-finite, non-integer, and\nnonpositive values leave rows unlimited.",
+              "fieldName": "maxImagesPerRow"
             },
             {
-              "name": "name",
+              "name": "max-row-height-vh",
+              "default": "DEFAULT_ALBUM_MAX_ROW_HEIGHT_VH",
+              "description": "Maximum preview-row height as a percentage of the layout viewport. Values\noutside the inclusive integer range `1…100` fall back to 90.",
               "type": {
-                "text": "string"
+                "text": "number"
               },
-              "default": "\"\"",
-              "description": "The name used when this picker participates in a `<form>`.",
-              "fieldName": "name"
+              "fieldName": "maxRowHeightVh"
             },
             {
               "name": "scheme",
@@ -43174,14 +43121,12 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "tagName": "esp-image-picker",
-          "customElement": true,
           "docPageTitle": {
             "name": "Image",
-            "description": "Picker"
+            "description": "Upload"
           },
           "docUrl": {
-            "name": "/components/image-picker",
+            "name": "/components/image-upload",
             "description": ""
           },
           "menuGroup": {
@@ -43190,25 +43135,120 @@
           },
           "menuLabel": {
             "name": "Image",
-            "description": "Picker"
-          }
+            "description": "Upload"
+          },
+          "menuIcon": {
+            "name": "photo-up",
+            "description": ""
+          },
+          "tagName": "esp-image-upload",
+          "customElement": true
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierImagePicker",
+          "name": "EspalierImageUpload",
           "declaration": {
-            "name": "EspalierImagePicker",
-            "module": "dist/image-picker/esp-image-picker.js"
+            "name": "EspalierImageUpload",
+            "module": "dist/image-upload/esp-image-upload.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-image-picker",
+          "name": "esp-image-upload",
           "declaration": {
-            "name": "EspalierImagePicker",
-            "module": "dist/image-picker/esp-image-picker.js"
+            "name": "EspalierImageUpload",
+            "module": "dist/image-upload/esp-image-upload.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "dist/image-upload/image-helpers.js",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "getImageDetails",
+          "return": {
+            "type": {
+              "text": "Promise<SelectedUploadImage>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "file",
+              "type": {
+                "text": "File"
+              }
+            },
+            {
+              "name": "options",
+              "optional": true,
+              "type": {
+                "text": "ImageDetailsOptions"
+              }
+            }
+          ],
+          "description": "Measure a selected file and produce a `SelectedUploadImage` whose `url`\nis a lightweight object URL suitable for previews (downscaled for large\nraster images). Rejects when the file cannot be read or decoded.\n\nThe returned `url` is an object URL owned by the caller — release it\nwith releasePreviewUrl when the image is discarded."
+        },
+        {
+          "kind": "function",
+          "name": "releasePreviewUrl",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "image",
+              "type": {
+                "text": "EspalierUploadImage"
+              }
+            }
+          ],
+          "description": "Release the object URL backing a selected image's preview. Safe to call\non existing images — server URLs are never revoked."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "getImageDetails",
+          "declaration": {
+            "name": "getImageDetails",
+            "module": "dist/image-upload/image-helpers.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "releasePreviewUrl",
+          "declaration": {
+            "name": "releasePreviewUrl",
+            "module": "dist/image-upload/image-helpers.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "dist/image-upload/preview-load-queue.js",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "previewLoadQueue",
+          "default": "new PreviewLoadQueue(4)",
+          "description": "Four remote downloads is enough to fill a row without overwhelming an image service."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "previewLoadQueue",
+          "declaration": {
+            "name": "previewLoadQueue",
+            "module": "dist/image-upload/preview-load-queue.js"
           }
         }
       ]