@wix/himalaya-cli 0.1030.0 → 0.1031.0

package/guides/sdk-reference.json

@@ -16748,7 +16748,25 @@
         "name": "ConversationMessage",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface ConversationMessage {\n  id?: string;\n  content?: string;\n  role?: MessageRole;\n  createdDate?: string;\n  status?: MessageStatus;\n  /** Client tools this assistant turn asks the CALLER to run — see `FunctionCall`. */\n  functionCalls?: FunctionCall[];\n}"
+        "decl": "export interface ConversationMessage {\n  id?: string;\n  content?: string;\n  role?: MessageRole;\n  createdDate?: string;\n  status?: MessageStatus;\n  /** Files the owner attached to this turn, as the service stored them. */\n  attachments?: Attachment[];\n  /** Client tools this assistant turn asks the CALLER to run — see `FunctionCall`. */\n  functionCalls?: FunctionCall[];\n}"
+      },
+      {
+        "name": "Attachment",
+        "kind": "interface",
+        "jsdoc": "/** A file on a message — the service's `Attachment` entity.\n *\n *  `url` is the service's own REFERENCE to an uploaded file\n *  (`genie-upload://<id>`, see `genieUploadRef`), not a fetchable address: no\n *  route that resolves it to a download url is published, so a client can name a\n *  sent attachment but not show it again from the server's copy. `viewUrl` is\n *  whatever preview the SENDING client chose to store, and is not trusted to\n *  resolve anywhere else. */",
+        "decl": "export interface Attachment {\n  /** Original file name including extension. The service caps it at 255. */\n  fileName: string;\n  /** e.g. `\"image/jpeg\"`. The service caps it at 100. */\n  mimeType: string;\n  url?: string;\n  viewUrl?: string;\n}"
+      },
+      {
+        "name": "CreateFileUploadResponse",
+        "kind": "interface",
+        "jsdoc": "/** The mint of an upload: where to send the bytes, and the record's id. */",
+        "decl": "export interface CreateFileUploadResponse { upload?: { uploadUrl?: string; id?: string } }"
+      },
+      {
+        "name": "CreateFileUploadOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface CreateFileUploadOptions {\n  /** The same client-declared scoping flag every other chat-service request\n   *  takes. Omitted unless given — the dashboard sends it only when its own\n   *  account-scoping gate is on. */\n  enforceAccountScopedConversations?: boolean;\n}"
       },
       {
         "name": "FunctionCall",
@@ -16820,7 +16838,7 @@
         "name": "SendMessageOptions",
         "kind": "interface",
         "jsdoc": "/** Optional wire flags on `sendMessage`. `communicationMode` /\n *  `enableRealtimeEvents` were in the original captured payload; only POLLING is\n *  verified end-to-end. The rest were added from the 2026-09-19 re-capture. */",
-        "decl": "export interface SendMessageOptions {\n  communicationMode?: CommunicationMode;\n  enableRealtimeEvents?: boolean;\n  metadata?: UserMessageMetadata;\n  /** The dashboard sends `true`. Optional: verified to answer either way. */\n  enforceAccountScopedConversations?: boolean;\n  /** Tag the turn with the same origin the conversation was created under. */\n  origin?: string;\n}"
+        "decl": "export interface SendMessageOptions {\n  communicationMode?: CommunicationMode;\n  enableRealtimeEvents?: boolean;\n  metadata?: UserMessageMetadata;\n  /** The dashboard sends `true`. Optional: verified to answer either way. */\n  enforceAccountScopedConversations?: boolean;\n  /** Tag the turn with the same origin the conversation was created under. */\n  origin?: string;\n  /** Files already UPLOADED (see `createFileUpload`) to store with the turn.\n   *  Rides step 1 only — the trigger names the stored turn, which carries them. */\n  attachments?: Attachment[];\n}"
       },
       {
         "name": "ConversationUserMessageResponse",
@@ -16870,6 +16888,30 @@
         "jsdoc": "/** Ask the service to abandon the assistant reply it is generating for\n *  `userMessageId` — the \"stop\" a chat surface puts beside a reply in progress.\n *\n *  Addressed by USER message, not by conversation: the thing being abandoned is\n *  one turn, and the id comes from that turn's own send response\n *  (`userMessageIdOf`). There is no route that looks it up afterwards, so a\n *  caller that did not keep it cannot abort.\n *\n *  Resolving means the service ACCEPTED the abort, not that generation had not\n *  already finished — a reply that was already written still lands in the\n *  transcript. Rejecting means the turn is still running: treat it as \"could\n *  not stop\", never as \"stopped\". */",
         "decl": "export function abortAssistantMessageGeneration(userMessageId: string): Promise<AbortAssistantMessageGenerationResponse>;"
       },
+      {
+        "name": "createFileUpload",
+        "kind": "function",
+        "jsdoc": "/** Mint an upload for one file: a pre-signed url to send its bytes to, and the\n *  id the message will reference it by (`genieUploadRef`).\n *\n *  Only the MINT goes through the chat-service; the bytes go straight to\n *  `upload.uploadUrl` (see the file header). Resolving is not proof the file\n *  exists — nothing is stored until those bytes land, so a caller must not\n *  attach the reference before its upload has succeeded. */",
+        "decl": "export function createFileUpload(\n  fileName: string,\n  mimeType: string,\n  opts: CreateFileUploadOptions = {},\n): Promise<CreateFileUploadResponse>;"
+      },
+      {
+        "name": "GENIE_UPLOAD_SCHEME",
+        "kind": "const",
+        "jsdoc": "/** The scheme every first-party creator uses to reference an uploaded file from\n *  a message attachment. */",
+        "decl": "export const GENIE_UPLOAD_SCHEME = \"genie-upload://\";"
+      },
+      {
+        "name": "genieUploadRef",
+        "kind": "function",
+        "jsdoc": "/** `genie-upload://<id>`, or \"\" for no id — never a reference to nothing. */",
+        "decl": "export function genieUploadRef(id: string | undefined): string;"
+      },
+      {
+        "name": "uploadTargetUrl",
+        "kind": "function",
+        "jsdoc": "/** Where the bytes actually go: `uploadUrl` with `path` and `acl=private` set.\n *\n *  Mirrors the Media Platform browser uploader every first-party client relies\n *  on. The service rewrites the storage key itself, so `path` is advisory; it is\n *  sent anyway, for parity with the clients whose uploads are known to work.\n *\n *  String surgery rather than `new URL`, because the worker runtimes (JSContext,\n *  Hermes, QuickJS) do not all ship the URL constructor — and MERGED rather than\n *  appended, because the signed url may already carry a query, and a second `?`\n *  would corrupt the signature it carries. An existing `path` / `acl` is\n *  replaced rather than duplicated; everything else, the fragment included, is\n *  kept byte for byte. */",
+        "decl": "export function uploadTargetUrl(uploadUrl: string, fileName: string): string;"
+      },
       {
         "name": "getConversationMessages",
         "kind": "function",
@@ -16906,6 +16948,12 @@
         "jsdoc": "/** A message's text. `content` is normally a string, but can arrive as an object\n *  carrying `text`; anything else is stringified rather than dropped. */",
         "decl": "export function messageText(m: ConversationMessage | null | undefined): string;"
       },
+      {
+        "name": "attachmentsOf",
+        "kind": "function",
+        "jsdoc": "/** A message's attachments that name a file, in order. Anything that is not an\n *  object with a non-empty `fileName` is dropped rather than rendered as a blank\n *  entry — the list is display-only, so a malformed row has nothing to show. */",
+        "decl": "export function attachmentsOf(m: ConversationMessage | null | undefined): Attachment[];"
+      },
       {
         "name": "lastAssistantMessage",
         "kind": "function",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1030.0",
+  "version": "0.1031.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": [
@@ -65,5 +65,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "490de5e74662e1485d41c6fbcf35c5211cea45af726de33892022b39"
+  "falconPackageHash": "b2432c45ff8926fa8325d6f05d7cfaddf683708c33a4537c34b9fa45"
 }

package/templates/beauty-salon/tier5-src/_shared/owner-load-error.ts

@@ -1,6 +1,12 @@
 import { copyParam } from "./himi-copy.js";
 
-/** Host-owned preview input. Absent on native and older hosts. */
+/** Host-owned preview input. Absent on native and older hosts.
+ *
+ *  `"sample"` — the built-in demo records; `"live"` — the viewer's own business over the
+ *  owner rung; `"fixtures"` — a DEV web host over a sealed hermetic gateway, where
+ *  the dev fixtures are the sample data. `"fixtures"` is neither live nor demo, so a
+ *  worker READS through the bridge as it does on a device; it is still a preview host
+ *  (`isOwnerPreviewHost`), so failure copy may name the web preview. */
 function ownerPreviewMode(): unknown {
   return (globalThis as unknown as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input?.__himiOwnerPreview;
 }

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"],
+  capabilities: ["live_activity","push","share","secure_storage","open_url","local_database","clipboard","ui","camera","presigned_upload"],
   designTokensPath: "./tokens.json",
   navigation: {
     "navKind": "responsive",

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

@@ -50387,7 +50387,7 @@ const SCREENS = runtimeSetting({
                           "itemsPath": "$service:himiOwnerLiteManage.recents",
                           "items": [
                             {
-                              "id": "",
+                              "id": "himi_owner_lite.manage.recent.$item.id",
                               "body": {
                                 "package": "himalaya",
                                 "type": "VStack",
@@ -50532,7 +50532,7 @@ const SCREENS = runtimeSetting({
                                           "spacing": 14,
                                           "children": [
                                             {
-                                              "id": "",
+                                              "id": "himi_owner_lite.manage.recent.create.$item.id",
                                               "body": {
                                                 "package": "himalaya",
                                                 "type": "Text",
@@ -50557,7 +50557,7 @@ const SCREENS = runtimeSetting({
                                               }
                                             },
                                             {
-                                              "id": "",
+                                              "id": "himi_owner_lite.manage.recent.handoff.$item.id",
                                               "body": {
                                                 "package": "himalaya",
                                                 "type": "Text",
@@ -50693,7 +50693,7 @@ const SCREENS = runtimeSetting({
                                   "itemsPath": "$item.areas",
                                   "items": [
                                     {
-                                      "id": "",
+                                      "id": "himi_owner_lite.manage.area.$item.id",
                                       "body": {
                                         "package": "himalaya",
                                         "type": "VStack",
@@ -50838,7 +50838,7 @@ const SCREENS = runtimeSetting({
                                                   "spacing": 14,
                                                   "children": [
                                                     {
-                                                      "id": "",
+                                                      "id": "himi_owner_lite.manage.area.create.$item.id",
                                                       "body": {
                                                         "package": "himalaya",
                                                         "type": "Text",
@@ -50863,7 +50863,7 @@ const SCREENS = runtimeSetting({
                                                       }
                                                     },
                                                     {
-                                                      "id": "",
+                                                      "id": "himi_owner_lite.manage.area.handoff.$item.id",
                                                       "body": {
                                                         "package": "himalaya",
                                                         "type": "Text",
@@ -51643,7 +51643,7 @@ const SCREENS = runtimeSetting({
                 "props": {
                   "items": [
                     {
-                      "id": "",
+                      "id": "ol_drawer_nav.$item.id",
                       "body": {
                         "package": "himalaya",
                         "type": "ListItem",
@@ -51695,7 +51695,7 @@ const SCREENS = runtimeSetting({
                         "props": {
                           "items": [
                             {
-                              "id": "",
+                              "id": "ol_drawer_attention.$item.id",
                               "body": {
                                 "package": "himalaya",
                                 "type": "ListItem",
@@ -55256,6 +55256,45 @@ const SCREENS = runtimeSetting({
                                 }
                               }
                             },
+                            {
+                              "id": "himi_owner_lite_aria.msg_attach_$item.id",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "HStack",
+                                "props": {
+                                  "spacing": 0,
+                                  "children": [
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Spacer",
+                                        "props": {}
+                                      },
+                                      "modifiers": {
+                                        "hiddenPath": "$item.notUser"
+                                      }
+                                    },
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "$item.attachText",
+                                          "style": "footnote",
+                                          "color": "textSecondary",
+                                          "maxLines": 3
+                                        }
+                                      }
+                                    }
+                                  ]
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$item.attachHidden"
+                              }
+                            },
                             {
                               "id": "himi_owner_lite_aria.msg_$item.id.link1",
                               "body": {
@@ -58836,6 +58875,203 @@ const SCREENS = runtimeSetting({
                 }
               }
             },
+            {
+              "id": "himi_owner_lite_aria.attachments.bound",
+              "body": {
+                "package": "himalaya",
+                "type": "LazyList",
+                "props": {
+                  "itemsPath": "$service:himiOwnerLiteAria.attachments",
+                  "horizontal": true,
+                  "spacing": 8,
+                  "items": [
+                    {
+                      "id": "himi_owner_lite_aria.attachment_$item.id",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "VStack",
+                        "props": {
+                          "spacing": 4,
+                          "children": [
+                            {
+                              "id": "himi_owner_lite_aria.attachment_thumb_$item.id",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Image",
+                                "props": {
+                                  "url": "$item.thumbUrl",
+                                  "width": 72,
+                                  "height": 72,
+                                  "contentMode": "fill",
+                                  "shape": "rounded",
+                                  "contentDescription": "$item.name"
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$item.thumbHidden"
+                              }
+                            },
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "$item.statusText",
+                                  "style": "caption",
+                                  "color": "textSecondary",
+                                  "maxLines": 2
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$item.statusHidden"
+                              }
+                            },
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "HStack",
+                                "props": {
+                                  "spacing": 8,
+                                  "children": [
+                                    {
+                                      "id": "himi_owner_lite_aria.attachment_retry_$item.id",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "Retry",
+                                          "style": "caption",
+                                          "color": "accentPrimary",
+                                          "maxLines": 1
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "onTap": {
+                                          "actionId": "tier5.himiOwnerLiteAria.retryAttachment",
+                                          "params": {
+                                            "id": "$item.id"
+                                          }
+                                        },
+                                        "hiddenPath": "$item.retryHidden"
+                                      }
+                                    },
+                                    {
+                                      "id": "himi_owner_lite_aria.attachment_remove_$item.id",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Icon",
+                                        "props": {
+                                          "name": "close",
+                                          "size": 14,
+                                          "tint": "textSecondary"
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "onTap": {
+                                          "actionId": "tier5.himiOwnerLiteAria.removeAttachment",
+                                          "params": {
+                                            "id": "$item.id"
+                                          }
+                                        },
+                                        "accessibilityLabel": "Remove photo"
+                                      }
+                                    }
+                                  ]
+                                }
+                              }
+                            }
+                          ]
+                        }
+                      },
+                      "modifiers": {
+                        "width": 72
+                      }
+                    }
+                  ]
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteAria.attachmentsHidden",
+                "padding": {
+                  "leading": 0,
+                  "trailing": 0,
+                  "top": 8,
+                  "bottom": 0
+                }
+              }
+            },
+            {
+              "id": "",
+              "body": {
+                "package": "himalaya",
+                "type": "HStack",
+                "props": {
+                  "spacing": 16,
+                  "children": [
+                    {
+                      "id": "himi_owner_lite_aria.attach.library",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Icon",
+                        "props": {
+                          "name": "image",
+                          "size": 22,
+                          "tint": "accentPrimary"
+                        }
+                      },
+                      "modifiers": {
+                        "onTap": {
+                          "actionId": "tier5.himiOwnerLiteAria.attach",
+                          "params": {
+                            "source": "library"
+                          }
+                        },
+                        "accessibilityLabel": "Add a photo"
+                      }
+                    },
+                    {
+                      "id": "himi_owner_lite_aria.attach.camera",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Icon",
+                        "props": {
+                          "name": "camera",
+                          "size": 22,
+                          "tint": "accentPrimary"
+                        }
+                      },
+                      "modifiers": {
+                        "onTap": {
+                          "actionId": "tier5.himiOwnerLiteAria.attach",
+                          "params": {
+                            "source": "camera"
+                          }
+                        },
+                        "accessibilityLabel": "Take a photo"
+                      }
+                    },
+                    {
+                      "id": "",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Spacer",
+                        "props": {}
+                      }
+                    }
+                  ]
+                }
+              },
+              "modifiers": {
+                "padding": {
+                  "leading": 0,
+                  "trailing": 0,
+                  "top": 8,
+                  "bottom": 0
+                }
+              }
+            },
             {
               "id": "form_aria",
               "body": {
@@ -58921,7 +59157,9 @@ const SCREENS = runtimeSetting({
         "wix_api",
         "open_url",
         "clipboard",
-        "ui"
+        "ui",
+        "camera",
+        "presigned_upload"
       ],
       "minBinaryVersion": "0.1.0",
       "bundleVersion": "0.0.1"

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

@@ -0,0 +1,179 @@
+// Photo attachments for the Aria composer — the pure half.
+//
+// Everything here is a decision that can be made without touching the device
+// or the network: which files may be attached, how many, how large, what a chip
+// in the composer says in each of its three states, and how a picked image is
+// turned into the bytes an upload sends. The half that DOES touch the world —
+// minting the upload, sending the bytes, picking — lives in `aria-chat.ts`
+// (the mint, through `@himalaya/wix-genie-chat`) and in each app's adapter (the
+// picker and the byte transfer, which are device capabilities the adapter's
+// screen has to declare).
+//
+// This file is copied verbatim into every generated starter app, so it explains
+// itself without pointing at anything only this repo has.
+
+/** Image types the composer accepts. The first-party clients' own allowlist
+ *  for images: png, jpeg (and the non-standard `image/jpg` some pickers still
+ *  report), webp, gif and heic. Anything else is REFUSED with a line saying so,
+ *  never silently dropped — the native Aria app drops unsupported files without a
+ *  word, and an owner who picked something and sees nothing happen assumes the
+ *  button is broken. */
+export const ARIA_IMAGE_TYPES: readonly string[] = [
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/webp",
+  "image/gif",
+  "image/heic",
+];
+
+/** 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;
+
+/** The largest image the composer will try to send, in bytes.
+ *
+ *  Not a product choice: it is the ceiling of the transfer this slice uses. A
+ *  picked photo crosses the worker bridge as a base64 string and is sent inline,
+ *  and the inline upload refuses anything over 8 MiB (the `MAX_INLINE_BASE64_BYTES`
+ *  bound of the pre-signed upload capability, which it enforces on every arm).
+ *  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;
+
+/** 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
+ *  collapses the part it names. */
+export interface AriaAttachmentChip {
+  /** Minted by the worker, never derived from the file. The native Aria app keyed
+   *  concurrent uploads by file NAME and collided on the second `IMG_0001.jpg`. */
+  id: string;
+  name: string;
+  mimeType: string;
+  state: "uploading" | "ready" | "failed";
+  /** The chip's thumbnail as a `data:` URI, set only when the picked image is
+   *  small; "" otherwise, which collapses the preview. The full bytes an upload
+   *  and a retry send are held by the worker, never in the chip, because the chip
+   *  rides the service state and a large photo there would exceed the web
+   *  runtime's frame limit. */
+  thumbUrl: string;
+  thumbHidden: boolean;
+  /** "Uploading…" / "Couldn't upload" / "" — collapses when empty. */
+  statusText: string;
+  statusHidden: boolean;
+  /** The retry control shows ONLY on a failed chip. */
+  retryHidden: boolean;
+  /** `genie-upload://<id>` once the bytes have landed; "" until then. The send
+   *  carries a chip only when this is set. */
+  ref: string;
+}
+
+/** What an upload reports back, delivered as a fresh action so it lands on the
+ *  CURRENT state rather than on the snapshot the upload started from. */
+export interface AriaAttachmentOutcome {
+  id: string;
+  ok: boolean;
+  /** Set when `ok`. */
+  ref?: string;
+}
+
+export interface ParsedDataUri { mimeType: string; base64: string; bytes: number }
+
+/** `data:<mime>;base64,<payload>` → its parts, or null for anything else.
+ *
+ *  Only the base64 form: every picker this composer is wired to returns it, and
+ *  a percent-encoded `data:` URI would need decoding the bridge cannot do. The
+ *  byte count is computed from the payload length, so a multi-megabyte photo is
+ *  sized without being decoded. */
+export function parseDataUri(uri: string): ParsedDataUri | null {
+  const m = /^data:([^;,]*)((?:;[^;,]*)*?);base64,/i.exec(uri ?? "");
+  if (!m) return null;
+  const base64 = uri.slice(m[0].length).replace(/\s+/g, "");
+  const pad = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+  const bytes = Math.max(0, Math.floor((base64.length * 3) / 4) - pad);
+  return { mimeType: (m[1] || "").trim().toLowerCase(), base64, bytes };
+}
+
+/** Normalize a MIME type a picker reported.
+ *
+ *  Some pickers hand back a platform type identifier where a MIME type belongs
+ *  (`public.jpeg`, `public.heic`), and the service validates the field as a MIME
+ *  type. Mapped for the image identifiers this composer accepts; anything else
+ *  is returned lowercased and left for the allowlist to judge. */
+export function normalizeMime(mime: string): string {
+  const v = (mime ?? "").trim().toLowerCase();
+  switch (v) {
+    case "public.jpeg": return "image/jpeg";
+    case "public.png": return "image/png";
+    case "public.heic": return "image/heic";
+    case "com.compuserve.gif": return "image/gif";
+    case "org.webmproject.webp": return "image/webp";
+    case "image/jpg": return "image/jpeg";
+    default: return v;
+  }
+}
+
+/** 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 {
+  const name = (given ?? "").trim();
+  if (name) return name.slice(0, 255);
+  const ext = mimeType === "image/png" ? "png"
+    : mimeType === "image/webp" ? "webp"
+    : mimeType === "image/gif" ? "gif"
+    : mimeType === "image/heic" ? "heic"
+    : "jpg";
+  return `photo-${n}.${ext}`;
+}
+
+/** Why a picked file cannot be attached, or "" when it can. */
+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";
+  return "";
+}
+
+/** A chip in a given state. One constructor so the flags can never disagree
+ *  with the state they describe — a failed chip without its retry control is
+ *  the shape of bug this rules out. */
+export function chipIn(
+  base: Pick<AriaAttachmentChip, "id" | "name" | "mimeType" | "thumbUrl">,
+  state: AriaAttachmentChip["state"],
+  labels: { uploading: string; failed: string },
+  ref = "",
+): AriaAttachmentChip {
+  const statusText = state === "uploading" ? labels.uploading : state === "failed" ? labels.failed : "";
+  return {
+    ...base,
+    state,
+    thumbHidden: !base.thumbUrl,
+    statusText,
+    statusHidden: !statusText,
+    retryHidden: state !== "failed",
+    ref: state === "ready" ? ref : "",
+  };
+}
+
+/** Why Send is refused while attachments are pending, or "" when it is not.
+ *
+ *  An upload still running would be dropped from the message, and a failed one
+ *  would be sent as if the owner had never picked it — in both cases the
+ *  assistant answers about a photo it never received. So the send waits, and
+ *  says what it is waiting for. */
+export function sendBlocker(chips: readonly AriaAttachmentChip[]): "" | "uploading" | "failed" {
+  if (chips.some((c) => c.state === "uploading")) return "uploading";
+  if (chips.some((c) => c.state === "failed")) return "failed";
+  return "";
+}
+
+/** The one line a bubble shows for its attachments: a paperclip and the file
+ *  names. Text, not thumbnails, and not by choice: a `genie-upload://`
+ *  reference has no published download url, so a sent photo cannot be shown
+ *  again from the server's copy — and a resumed conversation has nothing else. */
+export function attachmentLine(names: readonly string[]): string {
+  const shown = names.map((n) => n.trim()).filter(Boolean);
+  return shown.length ? `📎 ${shown.join(", ")}` : "";
+}