@wix/himalaya-cli 0.1317.0 → 0.1319.0

package/guides/app-config.md

@@ -115,7 +115,7 @@ with a native footprint only arrives with a new binary. `himi docs capabilities`
 loop — discover, declare, validate, ship — and `himi capabilities <id>` shows the import and which
 shells' binaries serve it.
 
-App-level capability vocabulary: `camera`, `barcode_scanner`, `biometrics`, `secure_storage`, `share`, `push`, `file_picker`, `files`, `open_url`, `pdf`, `clipboard`, `photos`, `presigned_upload`, `ui`, `calendar`, `contacts`, `tasks`, `audio_record`, `audio_record_background`, `calls`, `location`, `location_background`, `motion`, `health`, `media_playback`, `webview`, `browser_auth`, `haptic`, `himi_apps`, `iap`, `keyboard`, `wix_cashier`, `live_activity`, `local_database`, `speech`, `speaker_diarization`, `system_intents`, `on_device_ai`, `app_info`, `release_control`, `godot`, `base44`, `animation`.
+App-level capability vocabulary: `camera`, `barcode_scanner`, `biometrics`, `secure_storage`, `share`, `push`, `file_picker`, `files`, `open_url`, `pdf`, `clipboard`, `theme`, `photos`, `presigned_upload`, `ui`, `calendar`, `contacts`, `tasks`, `audio_record`, `audio_record_background`, `calls`, `location`, `location_background`, `motion`, `health`, `media_playback`, `webview`, `browser_auth`, `haptic`, `himi_apps`, `iap`, `keyboard`, `wix_cashier`, `live_activity`, `local_database`, `speech`, `speaker_diarization`, `system_intents`, `on_device_ai`, `app_info`, `release_control`, `godot`, `base44`, `animation`.
 
 ## What `himi validate` checks (7 passes)
 

package/guides/importable-sdks.md

@@ -56,6 +56,7 @@ package in one greppable file) or `GET /v1/sdk/<name>` over HTTP; in the CLI,
 - `@himalaya/speech` — Tier-5 typed binding to the platform's speech capability.
 - `@himalaya/system-intents` — Tier-5 typed binding to the platform's system-intents capability.
 - `@himalaya/tasks` — Tier-5 typed binding for reminders / to-dos.
+- `@himalaya/theme` — Tier-5 typed binding for the runtime brand overlay.
 - `@himalaya/time` — Tier-5 temporal helpers.
 - `@himalaya/ui` — Tier-5 typed binding to the platform's imperative popup capability.
 - `@himalaya/webview` — Tier-5 typed binding for the page ↔ worker message channel of a worker-backed webview screen (Part 2 / RFC 0025 composition).

package/guides/sdk-reference.json

@@ -986,7 +986,7 @@
         "name": "NavTabItem",
         "kind": "interface",
         "jsdoc": "/** A single bottom-nav tab. */",
-        "decl": "export interface NavTabItem {\n  id: string;\n  screenId?: string;\n  label?: string;\n  icon?: IconRef;            // design-system icon name\n  selectedIcon?: IconRef;    // optional filled/active variant\n  imageUrl?: string;        // optional custom asset (overrides icon)\n  imageAsset?: string;\n  badge?: NavBadge;\n  /** Live bindings resolved\n   *  against `NavigationConfig.navLogicBundle`. Each is a `$service:` sentinel,\n   * the SAME representation `NavBadge.valuePath` and `hiddenPath`\n   *  already use — not a new binding vehicle. Unset / unresolvable / no nav\n   *  worker ⇒ the sibling literal wins, so chrome degrades to static config\n   *  rather than to blank.\n   *\n   *  `hiddenPath` FILTERS the tab out (zero width, not dimmed) while KEEPING its\n   *  router stack, so unhiding restores it intact. Truthiness follows the RFC\n   *  0024 coercers exactly, so a value hides identically on every surface. */\n  hiddenPath?: string;\n  labelPath?: string;\n  iconPath?: string;\n}"
+        "decl": "export interface NavTabItem {\n  id: string;\n  screenId?: string;\n  label?: string;\n  icon?: IconRef;            // design-system icon name\n  selectedIcon?: IconRef;    // optional filled/active variant\n  imageUrl?: string;        // optional custom asset (overrides icon)\n  imageAsset?: string;\n  badge?: NavBadge;\n  /** Live bindings resolved\n   *  against `NavigationConfig.navLogicBundle`. Each is a `$service:` sentinel,\n   * the SAME representation `NavBadge.valuePath` and `hiddenPath`\n   *  already use — not a new binding vehicle. Unset / unresolvable / no nav\n   *  worker ⇒ the sibling literal wins, so chrome degrades to static config\n   *  rather than to blank.\n   *\n   *  `hiddenPath` FILTERS the tab out (zero width, not dimmed) while KEEPING its\n   *  router stack, so unhiding restores it intact. Truthiness follows the RFC\n   *  0024 coercers exactly, so a value hides identically on every surface. */\n  hiddenPath?: string;\n  labelPath?: string;\n  iconPath?: string;\n  /** With `hiddenPath`, hidden until the path resolves (fail-closed). */\n  hiddenUntilResolved?: boolean;\n}"
       },
       {
         "name": "DrawerConfig",
@@ -998,7 +998,7 @@
         "name": "DrawerItem",
         "kind": "interface",
         "jsdoc": "/** A single drawer destination (mirrors NavTabItem). */",
-        "decl": "export interface DrawerItem {\n  id: string;\n  screenId?: string;\n  label?: string;\n  icon?: IconRef;            // design-system icon name\n  badge?: NavBadge;\n  /** Non-navigable decorative rows: \"section\" → a muted section header (e.g.\n   *  \"Workspaces\"); \"note\" → a muted body line (e.g. \"No workspaces yet\"). */\n  role?: \"section\" | \"note\";\n  /** Only meaningful on a `role:\"section\"` header. When set, that header becomes a\n   *  COLLAPSIBLE FOLDER: the nav rows following it (until the next section header)\n   *  hide/show when the header is tapped, and `collapsed` is the initial state\n   *  (`true` → folded away by default). Absent → the header is a static,\n   *  non-tappable label (back-compat: existing section headers are unaffected). */\n  collapsed?: boolean;\n  /** Live bindings against `NavigationConfig.navLogicBundle` — see `NavTabItem`.\n   *  A hidden row is filtered out, taking its section-folder membership with it. */\n  hiddenPath?: string;\n  labelPath?: string;\n  iconPath?: string;\n}"
+        "decl": "export interface DrawerItem {\n  id: string;\n  screenId?: string;\n  label?: string;\n  icon?: IconRef;            // design-system icon name\n  badge?: NavBadge;\n  /** Non-navigable decorative rows: \"section\" → a muted section header (e.g.\n   *  \"Workspaces\"); \"note\" → a muted body line (e.g. \"No workspaces yet\"). */\n  role?: \"section\" | \"note\";\n  /** Only meaningful on a `role:\"section\"` header. When set, that header becomes a\n   *  COLLAPSIBLE FOLDER: the nav rows following it (until the next section header)\n   *  hide/show when the header is tapped, and `collapsed` is the initial state\n   *  (`true` → folded away by default). Absent → the header is a static,\n   *  non-tappable label (back-compat: existing section headers are unaffected). */\n  collapsed?: boolean;\n  /** Live bindings against `NavigationConfig.navLogicBundle` — see `NavTabItem`.\n   *  A hidden row is filtered out, taking its section-folder membership with it. */\n  hiddenPath?: string;\n  labelPath?: string;\n  iconPath?: string;\n  /** With `hiddenPath`, hidden until the path resolves (fail-closed). */\n  hiddenUntilResolved?: boolean;\n}"
       },
       {
         "name": "SidebarConfig",
@@ -3886,6 +3886,43 @@
       }
     ]
   },
+  {
+    "name": "@himalaya/theme",
+    "source": "core/sdk/theme/src/index.ts",
+    "description": "Tier-5 typed binding for the runtime brand overlay.",
+    "api": [
+      {
+        "name": "RuntimeBrand",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface RuntimeBrand {\n  /** #RRGGBB */\n  primaryColor: string;\n  /** #RRGGBB; absent ⇒ derived, as at build time. */\n  secondaryColor?: string;\n}"
+      },
+      {
+        "name": "ApplyBrandResult",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface ApplyBrandResult {\n  applied: boolean;\n  /** Why it was not applied: `invalid_color`, `stale_scope`, a native rejection reason. */\n  reason?: string;\n}"
+      },
+      {
+        "name": "applyBrand",
+        "kind": "function",
+        "jsdoc": "/**\n * Brand the shell with [brand]: the five accent tokens on every scheme, and the accent glow when\n * the app's tokens have one. Idempotent; the last call wins. Rejects nothing by throwing: a bad\n * colour or a refused write answers `{ applied: false, reason }`.\n */",
+        "decl": "export async function applyBrand(brand: RuntimeBrand): Promise<ApplyBrandResult>;"
+      },
+      {
+        "name": "clearBrand",
+        "kind": "function",
+        "jsdoc": "/** Drop the runtime brand: the app's registered tokens paint again. */",
+        "decl": "export async function clearBrand(): Promise<void>;"
+      },
+      {
+        "name": "version",
+        "kind": "const",
+        "jsdoc": "/** Capability version, for bundles that gate on min binary version. */",
+        "decl": "export const version = 1;"
+      }
+    ]
+  },
   {
     "name": "@himalaya/time",
     "source": "core/sdk/time/src/index.ts",

package/guides/web-page-sdk-reference.md

@@ -50,6 +50,7 @@ the SDK sources, so it matches the shipped SDKs.
 - [`speech`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fspeech?format=md) — Speech capability. 8 methods.
 - [`system_intents`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fsystem_intents?format=md) — System-intents capability. 2 methods · not in Brandy.
 - [`tasks`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Ftasks?format=md) — Reminders / to-dos. 7 methods.
+- [`theme`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Ftheme?format=md) — Runtime brand overlay. 2 methods.
 - [`ui`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fui?format=md) — Imperative popup capability. 2 methods · not in Brandy.
 - [`wix_cashier`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_cashier?format=md) — Native cashier. 2 methods.
 - [`wix_platform`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_platform?format=md) — Wix Platform SDK, worker-facing bindings. 30 methods · not in Brandy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1317.0",
+  "version": "0.1319.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "c373d9c55f28192fde803e5fb69be4c7287eba81744f007b47283ab9"
+  "falconPackageHash": "60f160d9f74860a80bb7b1bedb582949eda4352aaf8909967561bac5"
 }

package/templates/beauty-salon-owner/config.ts

@@ -37,7 +37,7 @@ export default defineApp({
     actions: "http://localhost:8190/v1/actions",
     sync: "http://localhost:8190/v1/sync",
   },
-  capabilities: ["live_activity","push","share","secure_storage","open_url","local_database","clipboard","ui","speech","camera","presigned_upload","app_info","biometrics"],
+  capabilities: ["live_activity","push","share","secure_storage","open_url","local_database","clipboard","ui","speech","camera","presigned_upload","app_info","biometrics","wix_platform"],
   designTokensPath: "./tokens.json",
   navigation: {
     "navKind": "responsive",

package/templates/beauty-salon-owner/dev/index.ts

@@ -61983,6 +61983,65 @@ const SCREENS = runtimeSetting({
                             },
                             {
                               "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "VStack",
+                                "props": {
+                                  "spacing": 4,
+                                  "children": [
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Icon",
+                                        "props": {
+                                          "name": "doc",
+                                          "size": 24,
+                                          "tint": "textSecondary"
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "accessibilityRole": "decorative"
+                                      }
+                                    },
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "$item.name",
+                                          "style": "caption",
+                                          "color": "textPrimary",
+                                          "maxLines": 2
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "height": 44
+                                      }
+                                    },
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "$item.typeLabel",
+                                          "style": "caption",
+                                          "color": "textSecondary",
+                                          "maxLines": 1
+                                        }
+                                      }
+                                    }
+                                  ]
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$item.documentHidden"
+                              }
+                            },
+                            {
+                              "id": "himi_owner_lite_aria.attachment_status_$item.id",
                               "body": {
                                 "package": "himalaya",
                                 "type": "Text",
@@ -61994,6 +62053,7 @@ const SCREENS = runtimeSetting({
                                 }
                               },
                               "modifiers": {
+                                "height": 44,
                                 "hiddenPath": "$item.statusHidden"
                               }
                             },
@@ -62009,21 +62069,22 @@ const SCREENS = runtimeSetting({
                                       "id": "himi_owner_lite_aria.attachment_retry_$item.id",
                                       "body": {
                                         "package": "himalaya",
-                                        "type": "Text",
+                                        "type": "Button",
                                         "props": {
-                                          "text": "Retry",
-                                          "style": "caption",
-                                          "color": "accentPrimary",
-                                          "maxLines": 1
+                                          "title": "Retry",
+                                          "action": {
+                                            "actionId": "tier5.himiOwnerLiteAria.retryAttachment",
+                                            "params": {
+                                              "id": "$item.id"
+                                            }
+                                          },
+                                          "style": "tertiary",
+                                          "size": "sm"
                                         }
                                       },
                                       "modifiers": {
-                                        "onTap": {
-                                          "actionId": "tier5.himiOwnerLiteAria.retryAttachment",
-                                          "params": {
-                                            "id": "$item.id"
-                                          }
-                                        },
+                                        "width": 92,
+                                        "height": 48,
                                         "hiddenPath": "$item.retryHidden"
                                       }
                                     },
@@ -62031,32 +62092,51 @@ const SCREENS = runtimeSetting({
                                       "id": "himi_owner_lite_aria.attachment_remove_$item.id",
                                       "body": {
                                         "package": "himalaya",
-                                        "type": "Icon",
+                                        "type": "Button",
                                         "props": {
-                                          "name": "close",
-                                          "size": 14,
-                                          "tint": "textSecondary"
+                                          "title": "Remove attachment",
+                                          "action": {
+                                            "actionId": "tier5.himiOwnerLiteAria.removeAttachment",
+                                            "params": {
+                                              "id": "$item.id"
+                                            }
+                                          },
+                                          "style": "tertiary",
+                                          "iconOnly": true,
+                                          "leadingIcon": "close",
+                                          "cornerRadius": 24,
+                                          "minHeight": 48
                                         }
                                       },
                                       "modifiers": {
-                                        "onTap": {
-                                          "actionId": "tier5.himiOwnerLiteAria.removeAttachment",
-                                          "params": {
-                                            "id": "$item.id"
-                                          }
-                                        },
-                                        "accessibilityLabel": "Remove photo"
+                                        "width": 48,
+                                        "height": 48,
+                                        "accessibilityLabel": "Remove attachment",
+                                        "accessibilityRole": "button"
                                       }
                                     }
                                   ]
                                 }
+                              },
+                              "modifiers": {
+                                "height": 48
                               }
                             }
                           ]
                         }
                       },
                       "modifiers": {
-                        "width": 72
+                        "width": 160,
+                        "padding": {
+                          "top": 8,
+                          "bottom": 8,
+                          "leading": 8,
+                          "trailing": 8
+                        },
+                        "background": {
+                          "token": "surfaceSecondary"
+                        },
+                        "cornerRadius": 12
                       }
                     }
                   ]
@@ -62068,7 +62148,7 @@ const SCREENS = runtimeSetting({
                   "leading": 0,
                   "trailing": 0,
                   "top": 8,
-                  "bottom": 0
+                  "bottom": 8
                 }
               }
             },
@@ -62121,6 +62201,27 @@ const SCREENS = runtimeSetting({
                         },
                         "accessibilityLabel": "Take a photo"
                       }
+                    },
+                    {
+                      "id": "himi_owner_lite_aria.attach.document",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Icon",
+                        "props": {
+                          "name": "document",
+                          "size": 22,
+                          "tint": "accentPrimary"
+                        }
+                      },
+                      "modifiers": {
+                        "onTap": {
+                          "actionId": "tier5.himiOwnerLiteAria.attach",
+                          "params": {
+                            "source": "document"
+                          }
+                        },
+                        "accessibilityLabel": "Add files"
+                      }
                     }
                   ]
                 }

package/templates/beauty-salon-owner/tier5-src/_shared/aria-attachments.ts

@@ -27,6 +27,14 @@ export const ARIA_IMAGE_TYPES: readonly string[] = [
   "image/heic",
 ];
 
+/** Document MIME types supported by the native Aria reference. */
+export const ARIA_DOCUMENT_TYPES: readonly string[] = [
+  "text/csv", "text/plain", "application/pdf", "application/msword",
+  "application/vnd.ms-excel", "application/vnd.ms-powerpoint",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+];
+
 /** At most this many attachments ride one message. The native Aria app caps at
  *  10; nothing on the wire says otherwise. */
 export const ARIA_MAX_ATTACHMENTS = 10;
@@ -40,6 +48,9 @@ export const ARIA_MAX_ATTACHMENTS = 10;
  *  Checking it HERE is what turns that refusal into a sentence the owner can act
  *  on, instead of a chip that fails for no stated reason. */
 export const ARIA_MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+// Inline documents include base64 and JSON overhead under the 4 MiB frame bridge.
+// Larger documents use the file-backed attachment follow-up.
+export const ARIA_MAX_DOCUMENT_BYTES = 2 * 1024 * 1024;
 
 /** A chip in the composer. Every field is always present — a `$item.` path that
  *  is missing on some rows does not substitute — and each `…Hidden` flag
@@ -58,6 +69,9 @@ export interface AriaAttachmentChip {
    *  runtime's frame limit. */
   thumbUrl: string;
   thumbHidden: boolean;
+  /** Filename/type card for documents (images keep the 72pt preview). */
+  documentHidden: boolean;
+  typeLabel: string;
   /** "Uploading…" / "Couldn't upload" / "" — collapses when empty. */
   statusText: string;
   statusHidden: boolean;
@@ -113,6 +127,21 @@ export function normalizeMime(mime: string): string {
   }
 }
 
+/** Native providers sometimes report a generic MIME; match the reference's
+ * extension fallback only for those values, not a conflicting explicit type. */
+export function attachmentMime(mime: string, name = ""): string {
+  const normalized = normalizeMime(mime);
+  if (normalized === "text/comma-separated-values") return "text/csv";
+  if (normalized && normalized !== "application/octet-stream") return normalized;
+  const extension = name.split(".").pop()?.toLowerCase() ?? "";
+  const types: Record<string, string> = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif", heic: "image/heic", heif: "image/heif",
+    csv: "text/csv", txt: "text/plain", pdf: "application/pdf", doc: "application/msword", xls: "application/vnd.ms-excel", ppt: "application/vnd.ms-powerpoint",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  };
+  return types[extension] ?? normalized;
+}
+
 /** A file name for an image the picker did not name, by type. The service
  *  requires one (1–255 characters), and it is what the transcript shows. */
 export function imageFileName(mimeType: string, n: number, given?: string): string {
@@ -131,8 +160,8 @@ export type AttachRefusal = "" | "type" | "size" | "count";
 
 export function refusalFor(parsed: ParsedDataUri | null, mimeType: string, attached: number): AttachRefusal {
   if (attached >= ARIA_MAX_ATTACHMENTS) return "count";
-  if (!parsed || !ARIA_IMAGE_TYPES.includes(mimeType)) return "type";
-  if (parsed.bytes > ARIA_MAX_IMAGE_BYTES) return "size";
+  if (!parsed || ![...ARIA_IMAGE_TYPES, ...ARIA_DOCUMENT_TYPES].includes(mimeType)) return "type";
+  if (parsed.bytes > (mimeType.startsWith("image/") ? ARIA_MAX_IMAGE_BYTES : ARIA_MAX_DOCUMENT_BYTES)) return "size";
   return "";
 }
 
@@ -146,10 +175,20 @@ export function chipIn(
   ref = "",
 ): AriaAttachmentChip {
   const statusText = state === "uploading" ? labels.uploading : state === "failed" ? labels.failed : "";
+  const dot = base.name.lastIndexOf(".");
+  const extension = dot > 0 && dot < base.name.length - 1 ? base.name.slice(dot + 1).toUpperCase() : "";
+  const mimeLabels: Record<string, string> = {
+    "application/pdf": "PDF", "text/csv": "CSV", "text/plain": "TXT", "application/msword": "DOC",
+    "application/vnd.ms-excel": "XLS", "application/vnd.ms-powerpoint": "PPT",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "XLSX",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "DOCX",
+  };
   return {
     ...base,
     state,
     thumbHidden: !base.thumbUrl,
+    documentHidden: base.mimeType.startsWith("image/"),
+    typeLabel: extension || mimeLabels[base.mimeType] || base.mimeType,
     statusText,
     statusHidden: !statusText,
     retryHidden: state !== "failed",

package/templates/beauty-salon-owner/tier5-src/_shared/aria-chat.ts

@@ -61,10 +61,11 @@ import {
 import {
   ARIA_MAX_ATTACHMENTS,
   ARIA_MAX_IMAGE_BYTES,
+  ARIA_MAX_DOCUMENT_BYTES,
   attachmentLine,
   chipIn,
   imageFileName,
-  normalizeMime,
+  attachmentMime,
   parseDataUri,
   refusalFor,
   sendBlocker,
@@ -480,6 +481,9 @@ export interface AriaChatLabels {
   /** Send refused while a photo is still uploading, or failed to. */
   attachWaitUploading?: Resolvable<string>;
   attachWaitFailed?: Resolvable<string>;
+  /** Send refused by a failed file that cannot be retried (a cold-start chip
+   *  whose source did not survive): Remove is the only control it offers. */
+  attachWaitRemove?: Resolvable<string>;
   /** Send refused with photos and no words. The service requires message text
    *  on every turn, so a photo alone is not a sendable message. */
   attachNeedsText?: Resolvable<string>;
@@ -535,7 +539,7 @@ export interface AriaDictationOptions {
 export interface AriaAttachmentPorts {
   /** Let the owner pick (or take) one photo. Resolves the image as a `data:`
    *  URI, or null when they cancelled. */
-  pick(source: "library" | "camera"): Promise<{ dataUri: string; name?: string; mimeType?: string } | null>;
+  pick(source: "library" | "camera" | "document"): Promise<{ dataUri: string; name?: string; mimeType?: string } | null>;
   /** PUT `base64` to a pre-signed url with `contentType`, carrying NO user
    *  credentials — the url authorizes itself. */
   put(url: string, base64: string, contentType: string): Promise<{ ok: boolean; status: number }>;
@@ -1652,23 +1656,28 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const attachUploadingText = () => res(o.labels?.attachUploading ?? "Uploading…");
   const attachFailedText = () => res(o.labels?.attachFailed ?? "Couldn't upload");
   const chipLabels = () => ({ uploading: attachUploadingText(), failed: attachFailedText() });
-  const refusalText = (why: "type" | "size" | "count"): string =>
+  const refusalText = (why: "type" | "size" | "count", maxBytes = ARIA_MAX_IMAGE_BYTES): string =>
     why === "count"
-      ? o.labels?.attachTooMany?.(ARIA_MAX_ATTACHMENTS) ?? `You can attach up to ${ARIA_MAX_ATTACHMENTS} photos.`
+      ? o.labels?.attachTooMany?.(ARIA_MAX_ATTACHMENTS) ?? `You can attach up to ${ARIA_MAX_ATTACHMENTS} files.`
       : why === "size"
-        ? o.labels?.attachTooLarge?.(ARIA_MAX_IMAGE_BYTES / (1024 * 1024))
-          ?? `That photo is too large to attach (up to ${ARIA_MAX_IMAGE_BYTES / (1024 * 1024)} MB).`
+        ? o.labels?.attachTooLarge?.(maxBytes / (1024 * 1024))
+          ?? `That file is too large to attach (up to ${maxBytes / (1024 * 1024)} MB).`
         : res(o.labels?.attachUnsupported ?? "That file type can't be attached.");
-  const waitUploadingText = () => res(o.labels?.attachWaitUploading ?? "Wait for your photo to finish uploading.");
-  const waitFailedText = () => res(o.labels?.attachWaitFailed ?? "Retry or remove the photo that didn't upload.");
-  const needsTextText = () => res(o.labels?.attachNeedsText ?? "Add a message to send with your photo.");
+  const waitUploadingText = () => res(o.labels?.attachWaitUploading ?? "Wait for your file to finish uploading.");
+  const waitFailedText = () => res(o.labels?.attachWaitFailed ?? "Retry or remove the file that didn't upload.");
+  const waitRemoveText = () => res(o.labels?.attachWaitRemove ?? "Remove the file that didn't upload, then add it again.");
+  /** The failed-file notice must name only a control the chips offer: "Retry"
+   *  while any failed chip can still retry, otherwise "Remove". */
+  const failedNotice = (): string =>
+    chips.some((c) => c.state === "failed" && !c.retryHidden) ? waitFailedText() : waitRemoveText();
+  const needsTextText = () => res(o.labels?.attachNeedsText ?? "Add a message to send with your file.");
   /** Clear the status line if what it says is an attachment notice, and only
    *  then. Every notice is advice about the composer's photos, so once the owner
    *  acts on them it is stale — but the same line also carries "Aria is
    *  typing…", which a photo edit must never erase. */
   const withoutNotice = <T extends { statusText: string }>(s: T): T => {
-    const notices = [waitUploadingText(), waitFailedText(), needsTextText(),
-      refusalText("type"), refusalText("size"), refusalText("count")];
+    const notices = [waitUploadingText(), waitFailedText(), waitRemoveText(), needsTextText(),
+      refusalText("type"), refusalText("size"), refusalText("size", ARIA_MAX_DOCUMENT_BYTES), refusalText("count")];
     return s.statusText && notices.includes(s.statusText) ? { ...s, statusText: "" } : s;
   };
   const toolFailedText = () => res(o.labels?.toolFailed ?? `${assistant()} couldn't finish that. Try again.`);
@@ -2023,16 +2032,20 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     chipsSeeded = true;
     const persisted = Array.isArray(s.attachments) ? s.attachments : [];
     // An upload does not survive the process that ran it, so a chip persisted
-    // mid-upload would say "Uploading…" forever. It still holds its bytes, so it
-    // comes back as FAILED — with the retry control — rather than being dropped.
+    // mid-upload would say "Uploading…" forever. Restore it as failed; only a
+    // chip with retained inline bytes can offer Retry until the file-backed follow-up.
     chips = persisted
       .filter((c) => c && typeof c.id === "string")
-      .map((c) => (c.state === "uploading" ? chipIn(c, "failed", chipLabels()) : c));
+      .map((c) => {
+        const chip = chipIn(c, c.state === "uploading" ? "failed" : c.state, chipLabels(), c.ref);
+        // Inline bytes were worker-owned. A cold-start document or large image
+        // has no source left: keep Remove available, never offer a dead Retry.
+        return chip.state === "failed" && !chip.thumbUrl ? { ...chip, retryHidden: true } : chip;
+      });
     for (const c of chips) {
       const n = Number(/^att-(\d+)$/.exec(c.id)?.[1] ?? 0);
       if (n > chipSeq) chipSeq = n;
-      // A rehydrated chip's bytes are whatever it kept inline. A large photo kept
-      // none, so its retry fails honestly rather than sending nothing.
+      // A rehydrated chip can retry only the source it kept inline.
       if (c.thumbUrl && !chipBytes.has(c.id)) chipBytes.set(c.id, c.thumbUrl);
     }
   };
@@ -2044,21 +2057,21 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     if (!chips.length) return null;
     const blocker = sendBlocker(chips);
     if (blocker === "uploading") return { ...s, statusText: waitUploadingText(), error: "" };
-    if (blocker === "failed") return { ...s, statusText: waitFailedText(), error: "" };
+    if (blocker === "failed") return { ...s, statusText: failedNotice(), error: "" };
     if (!content) return { ...s, statusText: needsTextText(), error: "" };
     return null;
   };
 
   /** Keep a "wait for your photo" notice true to the chips as they are NOW. An
-   *  upload that FAILED while Send was held on "Wait for your photo to finish
+   *  upload that FAILED while Send was held on "Wait for your file to finish
    *  uploading" must say to retry or remove it instead, and one that landed,
    *  with nothing else pending, clears it. Any other status line (the typing
    *  line above all) is left alone. */
   const refreshWaitNotice = (s: AriaChatState): AriaChatState => {
-    const waiting = [waitUploadingText(), waitFailedText()];
+    const waiting = [waitUploadingText(), waitFailedText(), waitRemoveText()];
     if (!s.statusText || !waiting.includes(s.statusText)) return s;
     const blocker = sendBlocker(chips);
-    const next = blocker === "uploading" ? waitUploadingText() : blocker === "failed" ? waitFailedText() : "";
+    const next = blocker === "uploading" ? waitUploadingText() : blocker === "failed" ? failedNotice() : "";
     return next === s.statusText ? s : { ...s, statusText: next };
   };
 
@@ -3794,8 +3807,8 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       const atCategories = { ...m, open: true, provider: null, query: "", items: [], itemsLoading: false, itemsFailed: "" };
       // Listed once per business. A failed list is asked again: the failure
       // may have been the network, and the next open is the retry.
-      if (m.providers !== null) { setMention(atCategories); return s; }
-      if (m.providersLoading) { setMention(atCategories); return s; }
+      if (m.providers !== null) { setMention(atCategories); return committed ?? s; }
+      if (m.providersLoading) { setMention(atCategories); return committed ?? s; }
       const site = m.site;
       setMention({ ...atCategories, providersLoading: true, providersFailed: "" });
       let providers: MentionProvider[] | null = null;
@@ -4112,7 +4125,8 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // picker whose result will be thrown away wastes the owner's time.
       if (chips.length >= ARIA_MAX_ATTACHMENTS) return { ...s, statusText: refusalText("count"), error: "" };
       const raw = typeof arg === "string" ? arg : firstString(arg?.source, arg?.value);
-      const source = raw.trim().toLowerCase() === "camera" ? "camera" : "library";
+      const source = raw.trim().toLowerCase() === "document" ? "document"
+        : raw.trim().toLowerCase() === "camera" ? "camera" : "library";
       // The picker is open for as long as the owner takes, and a poll, a reply or
       // another action can commit a NEWER state meanwhile. Returning `{ ...s }`
       // afterwards would put this pre-picker snapshot back over it: an older
@@ -4124,17 +4138,18 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       let picked: Awaited<ReturnType<AriaAttachmentPorts["pick"]>>;
       try {
         picked = await ports.pick(source);
-      } catch {
+      } catch (error) {
+        if (/too large|size limit/i.test(String(error))) return { ...latest(), statusText: refusalText("size", source === "document" ? ARIA_MAX_DOCUMENT_BYTES : ARIA_MAX_IMAGE_BYTES), error: "" };
         // A picker that could not open is not the owner's fault and there is no
         // file to talk about; say nothing rather than something misleading.
-        return latest();
+        return withoutNotice(latest());
       }
       if (!picked || !picked.dataUri) return latest();   // cancelled
       const parsed = parseDataUri(picked.dataUri);
-      const mimeType = normalizeMime(picked.mimeType || parsed?.mimeType || "");
+      const mimeType = attachmentMime(picked.mimeType || parsed?.mimeType || "", picked.name);
       // Re-checked after the await: other picks may have landed meanwhile.
       const refused = refusalFor(parsed, mimeType, chips.length);
-      if (refused) return { ...latest(), statusText: refusalText(refused), error: "" };
+      if (refused) return { ...latest(), statusText: refusalText(refused, mimeType.startsWith("image/") ? ARIA_MAX_IMAGE_BYTES : ARIA_MAX_DOCUMENT_BYTES), error: "" };
       chipSeq += 1;
       const id = `att-${chipSeq}`;
       chipBytes.set(id, picked.dataUri);
@@ -4143,7 +4158,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         name: imageFileName(mimeType, chipSeq, picked.name),
         mimeType,
         // Only a small image rides the state as its own thumbnail; see `chipBytes`.
-        thumbUrl: picked.dataUri.length <= THUMB_INLINE_MAX ? picked.dataUri : "",
+        thumbUrl: mimeType.startsWith("image/") && picked.dataUri.length <= THUMB_INLINE_MAX ? picked.dataUri : "",
       }, "uploading", chipLabels());
       chips = [...chips, chip];
       startUpload(chip);
@@ -4202,7 +4217,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     retryAttachment: (s, arg) => {
       const id = chipIdOf(arg);
       const current = chips.find((c) => c.id === id);
-      if (!current || current.state !== "failed") return s;
+      if (!current || current.state !== "failed" || (!chipBytes.get(id) && !current.thumbUrl)) return s;
       // A NEW id for the new attempt, in the same place in the strip. Keeping the
       // old one would let the first attempt's outcome, if it is still in the air,
       // settle this one.
@@ -4421,8 +4436,21 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       await probeDictation();
       return gated(r.listening && !dictationLive ? { ...r, listening: false } : r);
     },
-    submit: (s, arg) => impl.submit(s, arg).then(gated),
-    submitPrompt: (s, arg) => impl.submitPrompt(s, arg).then(gated),
+    submit: async (s, arg) => {
+      const revision = draftSeq;
+      const next = await impl.submit(s, arg);
+      // Refusals preserve a draft; an edit while the async reducer resolved
+      // belongs to the owner, including consuming a selected mention trigger.
+      // Preserve the send result and its pending turn/poll; only rebase the draft.
+      return gated(revision !== draftSeq && next.input === s.input && committed
+        ? { ...next, input: committed.input } : next);
+    },
+    submitPrompt: async (s, arg) => {
+      const revision = draftSeq;
+      const next = await impl.submitPrompt(s, arg);
+      return gated(revision !== draftSeq && next.input === s.input && committed
+        ? { ...next, input: committed.input } : next);
+    },
     newChat: (s) => impl.newChat(s).then(gated),
     typing: (s, arg) => gated(impl.typing(s, arg)),
     tick: (s) => impl.tick(s).then((r) => (r ? gated(r) : r)),