@wix/himalaya-cli 0.1318.0 → 0.1320.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/capabilities.md

@@ -59,6 +59,23 @@ The screen list is enforced at runtime: a call the screen did not declare is **d
 so it must name every capability the app uses. A background variant (`location_background`,
 `audio_record_background`) is declared instead of — and grants — its foreground capability.
 
+### Local database and tenant switches
+
+On native hosts `local_database` is also scoped by the host's active tenant. On a multi-tenant host such as Himi Player, a worker is stamped with the tenant that was active when its boot started. The
+stamp travels with each dispatch; if the host switches tenants while a dispatch is in flight,
+the native handler refuses it at store or write-queue resolution instead of retargeting the
+request to the new tenant.
+
+The tenant's `dataSchema` is the allowlist for local entities and must be applied for the
+tenant whose config supplied it. A missing schema is applied as `{}` and clears the previous
+allowlist and encrypted backing configuration. Himi Player applies cached package config
+before an imported-package fetch and reapplies the fetched schema after foreground/reload
+refreshes only when the refresh still belongs to the current release and tenant; snapshot
+packages and stale or overtaken refreshes are not overwritten.
+
+The web host does not have this scoping yet: its IndexedDB `EntityStore` keys rows by
+`entity:<name>` only, so on the web Player two apps that use the same entity name share rows.
+
 ## 3. Check
 
 ```bash

package/guides/designing-himi-screens.md

@@ -408,6 +408,8 @@ nicety. Don't animate everything: if every element moves, nothing reads as impor
 - **`accessibility_label` on every non-text control, icon, and image.** This is **distinct from `id`** —
   `id` targets a node for Argus/test automation; `accessibility_label` is what a screen reader announces.
   A screen full of `id`s and no `accessibility_label`s is testable but unusable with VoiceOver/TalkBack.
+  It may be bound to worker state with `$service:<service>.<path>`; the web renderer keeps the
+  resulting `aria-label` current as that state changes.
 - **Tap targets** stay comfortably large (don't shrink `button`/`icon` hit areas below ~44pt).
 - **Contrast** comes from the token roles — pair `textPrimary`/`textSecondary` with the right surface,
   and provide the `highContrast` scheme value for load-bearing colors.

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/qa-builds.md

@@ -8,10 +8,12 @@ A **QA build** is a real, installable app you hand to QA — an enterprise/ad-ho
 distinct from the CI gates (`test:*`, `argus:*`), which only prove the code builds
 and passes flows; nothing installable comes out of those.
 
-> **QA only — not TestFlight.** `himi dist` returns an installable QA artifact and
-> install link. It never submits to App Store Connect or Google Play. In particular,
-> it is separate from Himi Player's Wix Mobile Release TestFlight route and its
-> output is not an MRE-approved upload artifact.
+> **The default is QA; customer TestFlight is an explicit BYO path.** The ordinary
+> `himi dist` request returns an installable QA artifact and install link. A customer
+> iOS request may instead use `--signing byo --destination testflight --site <id>
+> --version <x.y.z>`; the build validates the App Store IPA, and an authorized
+> `himi dist status <jobId>` read uploads it to the customer's App Store Connect account.
+> The customer path is not Himi Player's Wix Mobile Release route and does not use MRE.
 
 > **Customer request gate.** Do not dispatch `himi dist` merely because a draft preview is ready.
 > First confirm that the customer explicitly asked to download the app, identify the approved
@@ -32,8 +34,31 @@ This submits `destination: testflight`. The pool produces an IPA in the MRE-appr
 `wix-ios-app-builds` bucket; deployed serve then invokes MRE using its POCO service
 identity and persists the MRE request ID/status on the same Job Service record. It
 accepts only the `himi-player` app, `player` shell, iOS, and its own bundle identity.
-`himi dist` keeps `destination: link`, does not call MRE, and remains the QA path for
-Himi distribution apps.
+The customer BYO path below also uses `destination: testflight`, but it uploads through
+an authorized `himi dist status` read rather than MRE. The ordinary `himi dist` path
+keeps `destination: link` and remains the QA path for Himi distribution apps.
+
+### Customer App Store / TestFlight handoff
+
+For an owned app, the customer must authorize the selected site and provide the existing
+customer distribution certificate plus an **App Store** provisioning profile (not the ad-hoc
+profile the QA `--signing byo` path below selects) and an App Store Connect API key (key id,
+issuer id and private key) in the site's customer signing binding. Without that key the
+request fails with `customer_app_store_validation_key_missing`. The request is iOS-only:
+
+```bash
+himi dist --app <app> --release <published-release-id> --site <owned-site-id> \
+  --platform ios --signing byo --destination testflight \
+  --version <marketing-version> --no-wait --target wix
+himi dist status <jobId> --target wix
+```
+
+The pool records `READY_FOR_UPLOAD` after validating the IPA. The status read proves site
+ownership with the Wix credential, then claims and uploads the IPA once; repeat reads are
+safe. Without that authorization, status reports the waiting state and does not upload.
+The upload also requires customer App Store upload to be enabled on the Himi backend
+(`HIMI_DIST_CUSTOMER_APP_STORE_UPLOAD=1`); where that switch is off, the job stays at `READY_FOR_UPLOAD` with a validated IPA that is
+never uploaded.
 
 ### iOS bundle identities are channel-specific
 
@@ -147,8 +172,9 @@ The chosen policy is written to the job record (`signing`), so `himi dist status
 answer "whose certificate is on this binary" without re-deriving it from serve config that may
 have changed since.
 
-**`--signing byo`** uses an owned Wix site and its existing personal Apple distribution certificate
-and ad-hoc profile. Himi checks site ownership, the app's recorded native ID, profile
+**`--signing byo`** (QA, `destination: link`) uses an owned Wix site and its existing personal
+Apple distribution certificate and ad-hoc profile. The TestFlight handoff above uses the App Store
+profile and ASC key instead; an ad-hoc setup does not satisfy it. Himi checks site ownership, the app's recorded native ID, profile
 type, certificate match, expiry, registered devices and production APNs entitlement before dispatch.
 It selects an existing compatible ad-hoc profile; the build does not create or revoke Apple assets.
 The runner fetches the certificate and profile using both its job token and a short-lived Buildkite

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.1318.0",
+  "version": "0.1320.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": "dfd3f0fd8aa48b52c1b817a8496d8d6db5a934ad7ca0aaf6b203615f"
+  "falconPackageHash": "551309f221b2f15b7f02099f9470e8021a0e0de81fba7b30dea7434b"
 }

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",