@@ -188,7 +188,7 @@ To extend the anatomy above, pass `triggers={triggers}` to `Composer` and insert
 </ComposerPopup>
 ```
 
-Configure only the triggers you need. Queries can contain spaces: `@sam r` finds Sam Rivera. A space immediately after the trigger closes the suggestions. Selecting an item inserts a token into the draft; it does not send the message or execute an action.
+Configure only the triggers you need. Queries can contain spaces: `@sam r` finds Sam Rivera. A space immediately after the trigger closes the suggestions. By default, selecting an item inserts a token into the draft; it does not send the message or execute an action. Supply `onAction` to handle items with `type: "action"` as commands: Composer removes the active query and calls your handler without inserting a token or submitting. Your application owns execution.
 
 To open a trigger from a button inside `ComposerActions`, call `useComposerContext().insertTrigger("@")` or `insertTrigger("/")`. The trigger is inserted at the caret and opens the same suggestions as typing it.
 
@@ -207,7 +207,7 @@ By default, selected mentions and actions appear as `text-primary font-medium` t
 
 <ComponentPreview name="p-composer-6" />
 
-The selected item's `kind` reaches `renderToken`, so a person and a team selected from the same `@` menu can use different icons or styles. The structured draft keeps `type`, `kind`, `id`, `label`, and `trigger`; `getComposerText(value)` still returns text such as `@Sam Rivera` when a chip hides the trigger visually. An item's `icon` is available to the suggestion list renderer but is not stored in the draft. A native textarea remains plain text and does not render tokens.
+The selected item's `kind` reaches `renderToken`, so a person and a team selected from the same `@` menu can use different icons or styles. The structured draft keeps `type`, `kind`, `id`, `label`, `trigger`, and optional `data` and `text`; `getComposerText(value)` returns the explicit `text` or defaults to text such as `@Sam Rivera`, even when a chip hides the trigger visually. An item's `icon` is available to the suggestion list renderer but is not stored in the draft. A native textarea remains plain text and does not render tokens.
 
 ### Custom filtering
 
@@ -217,13 +217,15 @@ The default filter ignores case and accents. Set a trigger's `filter` to customi
 
 ### Async results
 
-Fetch results in response to `onQueryChange`. Use `filter: null` for prefiltered results and `itemsFor` to identify the query they belong to. A completed query with no matches closes the popup.
+Fetch results in response to `onQueryChange`. Use `filter: null` for prefiltered results and `itemsFor` to identify their query text. For caret-sensitive results, return the opaque `ComposerQuery.key` as the trigger’s `queryKey`; results from a different query position cannot be selected even when the text matches. Do not persist or parse the key.
+
+A completed query with no matches closes the popup by default. Set `showEmpty: true` to keep it open and render an empty state with `ComposerStatus`. `maxQueryLength` optionally limits the query text after the trigger. When a popup has no selectable results, Enter is blocked by default; `submitOnEmptySuggestions` lets Enter follow the normal submission policy, including during loading or error states.
 
 <ComponentPreview name="p-composer-2" />
 
 ### Keyboard shortcuts
 
-While suggestions are open, ↑ and ↓ navigate, Enter selects, Escape dismisses, and Tab moves focus normally. Otherwise, Enter submits and Shift+Enter inserts a line break in the native contenteditable input or textarea. Set `submitOnEnter="desktop"` to submit only with a fine pointer, or `"never"` to let Enter insert a line break.
+While suggestions are open, ↑ and ↓ navigate, Enter selects, Escape dismisses, and Tab moves focus normally. Shift+Enter dismisses suggestions and inserts a line break. Otherwise, Enter submits and Shift+Enter inserts a line break in the native contenteditable input or textarea. Set `submitOnEnter="desktop"` to submit only with a fine pointer, or `"never"` to let Enter insert a line break.
 
 ## In a drawer
 
@@ -246,7 +248,9 @@ The styled frame and state owner for one input. It renders a form by default and
 | `defaultValue` | `ComposerValue` | `[]` | Initial uncontrolled draft |
 | `onValueChange` | `(value: ComposerValue, details: ComposerChangeDetails) => void` | — | Called with the next draft and the change reason |
 | `triggers` | `readonly ComposerTrigger[]` | `[]` | Suggestion sources for contenteditable; omit for plain text |
-| `onQueryChange` | `(query: { character: string; text: string } \| null) => void` | — | Active suggestion query |
+| `onQueryChange` | `(query: ComposerQuery \| null) => void` | — | Active suggestion query |
+| `onAction` | `(item: ComposerItemValue, query: ComposerQuery) => void` | — | Removes the query and reports an action selection without inserting a token or submitting |
+| `submitOnEmptySuggestions` | `boolean` | `false` | Allows Enter to follow the submission policy when the open popup has no selectable results |
 | `submitOnEnter` | `"desktop" \| "always" \| "never"` | `"always"` | Enter behavior for either input |
 | `layout` | `"stacked" \| "adaptive"` | `"stacked"` | Keep actions below the input, or place them beside a one-line draft and move them below when it wraps |
 | `disabled` | `boolean` | `false` | Disables editing, suggestions, and submission |
@@ -417,7 +421,7 @@ type ComposerValue = readonly ComposerPart[]
 
 type ComposerPart =
   | { type: "text"; text: string }
-  | { type: "mention" | "action"; id: string; label: string; trigger: string; kind?: string }
+  | { type: "mention" | "action"; id: string; label: string; trigger: string; kind?: string; data?: string; text?: string }
 
 type ComposerTokenPart = Exclude<ComposerPart, { type: "text" }>
 
@@ -429,10 +433,14 @@ type ComposerItemValue = {
   icon?: ReactNode
   type?: "mention" | "action"
   kind?: string
+  data?: string
+  text?: string
 }
+
+type ComposerQuery = { character: string; text: string; key: string }
 ```
 
-Item IDs must be unique within each trigger. Set `disabled: true` on an item to skip it during keyboard navigation and prevent selection. `type` defaults to `"mention"`; set `"action"` for slash actions. Use `kind` for your own categories, such as `"person"` and `"team"`, even when both come from `@`. The selected part retains `kind`. `getComposerText(value)` returns the plain-text representation with trigger characters, including when chips hide them visually.
+Item IDs must be unique within each trigger. Set `disabled: true` on an item to skip it during keyboard navigation and prevent selection. `type` defaults to `"mention"`; set `"action"` for slash actions. Use `kind` for your own categories, such as `"person"` and `"team"`, even when both come from `@`. The selected part retains `kind`. `getComposerText(value)` uses a token’s optional `text` field, or falls back to its trigger and label. Optional `data` is an opaque string preserved through editing, undo/redo, and supported structured copy/paste; the editor never interprets it as HTML. Keep domain validation and authorization in your application.
 
 `ComposerTrigger` configures one source:
 
@@ -442,11 +450,14 @@ Item IDs must be unique within each trigger. Set `disabled: true` on an item to
 | `items` | `readonly ComposerItemValue[]` | required | Candidate results |
 | `filter` | `((item, query) => boolean) \| null` | label contains query | Custom matching; `null` uses prefiltered results |
 | `itemsFor` | `string` | — | Query the async items belong to |
-| `status` | `"ready" \| "loading" \| "error"` | `"ready"` | Loading/error feedback keeps the popup open; zero ready matches hide it |
+| `queryKey` | `string` | — | Opaque query identity returned by `onQueryChange`; mismatched results cannot be selected |
+| `showEmpty` | `boolean` | `false` | Keeps the popup open when there are no ready matches |
+| `maxQueryLength` | `number` | Unlimited | Maximum query text length after the trigger |
+| `status` | `"ready" \| "loading" \| "error"` | `"ready"` | Loading/error feedback keeps the popup open; zero ready matches hide it unless `showEmpty` is enabled |
 
 ### Draft lifecycle
 
-Copying or cutting a token includes its trigger in plain text, even when a chip hides it. Pasted or dropped text stays plain text and never acquires a mention ID. Keep application records keyed by the token's `id` and `kind`; display icons are not part of the submitted document.
+Copying or cutting includes the token’s `text`, or its trigger and label by default, in plain text. It also writes `application/x-coss-composer` data so compatible composers can preserve tokens and metadata. Structured paste validates the document shape and accepts at most 1,000 parts and 100,000 serialized characters; unsupported or invalid structured data falls back to plain text. External text, HTML, and dropped text do not acquire mention IDs. Clipboard metadata is untrusted input and never grants access to application records. Display icons are not part of the submitted document.
 
 Contenteditable edits have a local undo history, including token insertion, paste, and cut. Replacing the draft externally or resetting it starts a new history. Selection is preserved and clamped to the updated draft. If an external value changes during IME composition, it is applied after composition finishes. A native textarea keeps its browser editing history.
 
 
@@ -0,0 +1,15 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "composer-clipboard",
+  "registryDependencies": [
+    "@coss/composer-document"
+  ],
+  "files": [
+    {
+      "path": "registry/default/lib/composer-clipboard.ts",
+      "content": "import type { ComposerPart, ComposerValue } from \"./composer-document\";\n\nexport const COMPOSER_CLIPBOARD_TYPE = \"application/x-coss-composer\";\n\nexport function parseComposerClipboard(raw: string): ComposerValue | null {\n  if (!raw || raw.length > 100_000) return null;\n  try {\n    const value: unknown = JSON.parse(raw);\n    if (!Array.isArray(value) || value.length > 1_000) return null;\n    const parts: ComposerPart[] = [];\n    for (const part of value) {\n      if (!part || typeof part !== \"object\") return null;\n      if (part.type === \"text\" && typeof part.text === \"string\") {\n        parts.push({ type: \"text\", text: part.text });\n        continue;\n      }\n      if (\n        (part.type !== \"mention\" && part.type !== \"action\") ||\n        typeof part.id !== \"string\" ||\n        typeof part.label !== \"string\" ||\n        typeof part.trigger !== \"string\"\n      )\n        return null;\n      parts.push({\n        type: part.type,\n        id: part.id,\n        label: part.label,\n        trigger: part.trigger,\n        ...(typeof part.kind === \"string\" ? { kind: part.kind } : {}),\n        ...(typeof part.data === \"string\" ? { data: part.data } : {}),\n        ...(typeof part.text === \"string\" ? { text: part.text } : {}),\n      });\n    }\n    return parts;\n  } catch {\n    return null;\n  }\n}\n",
+      "type": "registry:lib"
+    }
+  ],
+  "type": "registry:lib"
+}