@djangocfg/ui-tools 2.1.376 → 2.1.378

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.376",
+  "version": "2.1.378",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -156,8 +156,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.376",
-    "@djangocfg/ui-core": "^2.1.376",
+    "@djangocfg/i18n": "^2.1.378",
+    "@djangocfg/ui-core": "^2.1.378",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -211,10 +211,10 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.376",
+    "@djangocfg/i18n": "^2.1.378",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.376",
-    "@djangocfg/ui-core": "^2.1.376",
+    "@djangocfg/typescript-config": "^2.1.378",
+    "@djangocfg/ui-core": "^2.1.378",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/Chat/Chat.story.tsx

@@ -1283,6 +1283,107 @@ export const WailsLikeVirtualization = () => {
   );
 };
 
+// ---------------------------------------------------------------------------
+// 16) WithRenderAfterCalls — rich UI outside tool panels
+//     Demonstrates: renderAfterCalls, hideToolCalls, renderToolCall
+// ---------------------------------------------------------------------------
+
+const SEARCH_SEQUENCE: ChatStreamEvent[] = [
+  { type: 'chunk', delta: 'Searching the catalog for you.\n\n' },
+  {
+    type: 'tool_call_start',
+    toolId: 'v1',
+    name: 'search_vehicles',
+    input: { make: 'BMW', year_min: 2022 },
+  },
+  { type: 'tool_call_delta', toolId: 'v1', delta: 'querying…\n' },
+  {
+    type: 'tool_call_end',
+    toolId: 'v1',
+    output: {
+      items: [
+        { id: 'car-001', make: 'BMW', model: '5 Series', year: 2023, price: 45000 },
+        { id: 'car-002', make: 'BMW', model: 'X5', year: 2022, price: 72000 },
+      ],
+      total: 2,
+    },
+    status: 'success',
+  },
+  { type: 'chunk', delta: 'Found 2 vehicles — see the cards below.' },
+  { type: 'message_end' },
+];
+
+function MockVehicleCards({ calls }: { calls: import('./types').ChatToolCall[] }) {
+  const items: Array<{ id: string; make: string; model: string; year: number; price: number }> = [];
+  for (const call of calls) {
+    if (call.status !== 'success' || call.name !== 'search_vehicles') continue;
+    const out = call.output as { items?: typeof items } | null;
+    for (const item of out?.items ?? []) items.push(item);
+  }
+  if (items.length === 0) return null;
+  return (
+    <div className="mt-2 space-y-1.5">
+      {items.map((v) => (
+        <div
+          key={v.id}
+          className="flex items-center gap-3 rounded-md border border-border bg-card px-3 py-2 text-xs"
+        >
+          <div className="size-10 shrink-0 rounded bg-muted" />
+          <div className="min-w-0 flex-1">
+            <p className="font-semibold">{v.make} {v.model}</p>
+            <p className="text-muted-foreground">{v.year}</p>
+          </div>
+          <span className="font-mono text-sm font-semibold">${v.price.toLocaleString()}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export const WithRenderAfterCalls = () => {
+  const [hide] = useBoolean('hide-panels', { defaultValue: false, label: 'hideToolCalls (hide accordion panels)' });
+  const [useCustom] = useBoolean('custom-call', { defaultValue: false, label: 'renderToolCall (custom per-call renderer)' });
+
+  const transport = useMemo(
+    () => createMockTransport({ replies: [SEARCH_SEQUENCE, SEARCH_SEQUENCE], latencyMs: 40 }),
+    [],
+  );
+
+  const toolCallsProps = useMemo(
+    () => ({
+      hideToolCalls: hide,
+      renderAfterCalls: (calls: import('./types').ChatToolCall[]) => <MockVehicleCards calls={calls} />,
+      ...(useCustom
+        ? {
+            renderToolCall: (call: import('./types').ChatToolCall) => (
+              <div className="flex items-center gap-2 rounded border border-border bg-muted/40 px-2 py-1 text-xs">
+                <span className="font-mono text-muted-foreground">{call.name}</span>
+                <span className={`ml-auto rounded px-1 py-0.5 text-[10px] font-medium ${
+                  call.status === 'success' ? 'bg-emerald-500/10 text-emerald-600' : 'bg-amber-500/10 text-amber-600'
+                }`}>{call.status}</span>
+              </div>
+            ),
+          }
+        : {}),
+    }),
+    [hide, useCustom],
+  );
+
+  return (
+    <Frame h={560}>
+      <ChatRoot
+        transport={transport}
+        config={{
+          greeting: 'Vehicle search demo',
+          placeholder: 'Ask "find BMW vehicles"…',
+          suggestions: [{ label: 'Find BMW vehicles', prompt: 'Find BMW vehicles from 2022' }],
+        }}
+        toolCallsProps={toolCallsProps}
+      />
+    </Frame>
+  );
+};
+
 // ---------------------------------------------------------------------------
 // AutoFocusOnStreamEnd — refocus composer the moment a reply lands
 // ---------------------------------------------------------------------------

package/src/tools/Chat/README.md

@@ -168,6 +168,68 @@ import { LazyJsonTree } from '@djangocfg/ui-tools/json-tree';
 
 We don't import `LazyJsonTree` automatically — keeping the chat dep-light. The host opts in.
 
+### ToolCalls — rich UI after panels (`renderAfterCalls`)
+
+`renderAfterCalls` renders **outside and below** all collapsible panels — always visible, regardless of whether panels are expanded or hidden. It receives the full `calls` array so you can aggregate across multiple tool calls (e.g. collect all vehicle IDs from `search_vehicles` + `get_vehicle` and render cards).
+
+```tsx
+<ChatRoot
+  toolCallsProps={{
+    // Rich UI below all panels — always visible, never inside collapsed accordions
+    renderAfterCalls: (calls) => <VehicleCardList calls={calls} />,
+  }}
+/>
+```
+
+#### hideToolCalls — show only rich UI, no raw panels
+
+Set `hideToolCalls={true}` to suppress accordion panels entirely while `renderAfterCalls` still renders. Use when you want clean product UI without raw tool payloads visible.
+
+```tsx
+<ChatRoot
+  toolCallsProps={{
+    hideToolCalls: true,                             // hides accordion panels
+    renderAfterCalls: (calls) => <VehicleCards calls={calls} />,  // still runs
+  }}
+/>
+```
+
+`hideToolCalls` only affects the accordion panels — `renderAfterCalls` is always independent.
+
+#### renderToolCall — custom per-call panel renderer
+
+Replace the default `<ToolCallItem>` accordion with your own UI. Return `null` to suppress a specific call.
+
+```tsx
+<ChatRoot
+  toolCallsProps={{
+    renderToolCall: (call) => (
+      <div className="flex items-center gap-2 rounded border px-2 py-1 text-xs">
+        <span className="font-mono">{call.name}</span>
+        <span className="ml-auto">{call.status}</span>
+      </div>
+    ),
+  }}
+/>
+```
+
+#### Full example — vehicle cards from tool output
+
+```tsx
+import { buildVamcarToolCallsProps } from './chat/toolPayloads';
+
+// toolPayloads.tsx:
+export function buildVamcarToolCallsProps(): Omit<ToolCallsProps, 'calls'> {
+  return {
+    renderAfterCalls: (calls) => <VehicleCardsFromCalls calls={calls} />,
+  };
+}
+
+// In your chat component:
+const toolCallsProps = useMemo(() => buildVamcarToolCallsProps(), []);
+<ChatRoot transport={transport} toolCallsProps={toolCallsProps} />
+```
+
 ## Personas (user & assistant identity)
 
 Pass identities once on `<ChatRoot config>` — every bubble gets the right name, avatar and `aria-label`. Outgoing user messages get the `sender` field auto-stamped from `config.user`.
@@ -342,6 +404,48 @@ Options:
 The hook only fires on the `true → false` edge — flipping `enabled`
 mid-stream won't steal focus.
 
+## Draft sanitation (pre-submit)
+
+`useChatComposer.submit()` cleans the draft before handing it to your
+`onSubmit` — mirroring what ChatGPT / Claude / Telegram ship. The
+helper is also exported standalone for custom composers:
+
+```ts
+import { sanitizeDraft, isSubmittableDraft } from '@djangocfg/ui-tools'
+
+sanitizeDraft('  \n\nhello   world​\n  ')   // → 'hello   world'
+isSubmittableDraft('   \n  ')                     // → false
+```
+
+### Rules (intentionally minimal)
+
+| Rule | Action | Why |
+|---|---|---|
+| Trim outer whitespace | ✅ | Stray newlines/spaces at the edges are never intentional. |
+| Normalise `\r\n` / `\r` → `\n` | ✅ | Deterministic shape for LLM tokeniser + markdown render. |
+| Strip ZWSP / ZWNJ / ZWJ / BOM | ✅ | Pasted from rich web pages, invisible, break tokenisation. |
+| **Collapse internal whitespace runs** | ❌ | Would mangle code indentation. |
+| **Cap consecutive blank lines** | ❌ | Could be intentional separator (markdown / structured prompt). |
+| **Strip bidi overrides** (LRM/RLM/U+202A..E) | ❌ | Legitimately used in Arabic/Hebrew RTL content. |
+| Touch tabs vs spaces, emoji, mentions, URLs | ❌ | Passthrough. |
+
+Idempotent: `sanitizeDraft(sanitizeDraft(x)) === sanitizeDraft(x)`.
+
+### Escape hatch — `preserveExactValue`
+
+Niche flows (clipboard inspector, raw-prompt debug tool) want
+byte-perfect passthrough. Opt out per-composer:
+
+```ts
+const composer = useChatComposer({
+  onSubmit,
+  preserveExactValue: true,   // skip sanitation; raw textarea value goes through
+})
+```
+
+`canSubmit` still gates on `value.trim().length > 0` in this mode —
+an empty message is rarely intentional even when sanitation is off.
+
 ## Attachment renderers (registry)
 
 `<Attachments>` and `<ChatRoot>` accept a per-type renderer map. Default tile is used when no renderer matches. Plug in heavy viewers (`LazyAudioPlayer`, `LazyImageViewer`, `LazyMap`) host-side without forcing `ui-tools/Chat` to depend on them.
@@ -527,11 +631,15 @@ useChatAudioPrefs
 // Tool-payload dispatch
 dispatchToolPayload, isPlainObject, isLatLng,
 isGeoJSONFeatureCollection, isStringValue,
-type ToolPayloadMatcher, type ToolPayloadFallback
+type ToolPayloadMatcher, type ToolPayloadFallback,
+type ToolPayloadKind, type ToolCallsProps
 
 // Lightbox helpers
 collectImageAttachments
 
+// Draft sanitation (pre-submit cleanup; see "Draft sanitation" above)
+sanitizeDraft, isSubmittableDraft
+
 // Context
 ChatProvider, useChatContext, useChatContextOptional,
 type ComposerHandle
@@ -563,6 +671,12 @@ LazyChat
 | `↓`                | Recall next                             |
 | `Esc`              | (host-bound) cancel stream              |
 
+> **Custom composers built on `MarkdownEditor`:** pass `onSubmit` to
+> the editor for the same behaviour. A React `onKeyDown` wrapper does
+> NOT reliably intercept Enter before Tiptap commits the HardBreak
+> — see `MarkdownEditor/README.md#submit-on-enter` for the full
+> incident write-up and the keymap-extension fix.
+
 ## Performance
 
 - **Token coalescing.** `createTokenBuffer` aggregates stream chunks within ~16ms before dispatching → ≤1 render per frame.
@@ -623,4 +737,5 @@ Full implementation plan and rationale lives at [`@dev/@refactoring7-chat/`](../
 - `WithPersonas` — config-level `user` + `assistant` identity (avatar, name)
 - `MultiUser` — per-message `sender` overrides (multi-user / multi-bot)
 - `WithHideComposer` — `hideComposer` + `footer` approval gate (HITL / agent-pause pattern)
+- `WithRenderAfterCalls` — `renderAfterCalls` (vehicle cards outside panels), `hideToolCalls`, `renderToolCall` (custom per-call renderer) — knob-controlled
 - `Playground` — knobs (latency, streaming, suggestions)

package/src/tools/Chat/components/ToolCalls.tsx

@@ -24,6 +24,25 @@ export interface ToolCallsProps {
   renderStreaming?: (text: string, call: ChatToolCall) => ReactNode;
   /** Single override for all three; specific renderers above take precedence. */
   renderPayload?: (value: unknown, kind: ToolPayloadKind, call: ChatToolCall) => ReactNode;
+  /**
+   * Rendered once **after** all tool-call panels — always visible, outside
+   * the collapsible panels. Use for rich UI derived from tool outputs (e.g.
+   * vehicle cards, map pins, tax breakdowns). Receives the full calls array
+   * so the renderer can aggregate across multiple tool calls.
+   */
+  renderAfterCalls?: (calls: ChatToolCall[]) => ReactNode;
+  /**
+   * Custom renderer for each individual tool-call panel. When provided,
+   * replaces the default collapsible `<ToolCallItem>`. Return `null` to
+   * suppress a specific call while still letting others render.
+   */
+  renderToolCall?: (call: ChatToolCall) => ReactNode;
+  /**
+   * When `true`, the collapsible tool-call panels are not rendered at all.
+   * `renderAfterCalls` still runs — use together to show only rich UI with
+   * no raw accordion panels visible.
+   */
+  hideToolCalls?: boolean;
   className?: string;
 }
 
@@ -35,23 +54,31 @@ export function ToolCalls({
   renderOutput,
   renderStreaming,
   renderPayload,
+  renderAfterCalls,
+  renderToolCall,
+  hideToolCalls = false,
   className,
 }: ToolCallsProps) {
   if (!calls?.length) return null;
   return (
     <div className={cn('mt-2 space-y-1.5', className)}>
-      {calls.map((call) => (
-        <ToolCallItem
-          key={call.id}
-          call={call}
-          defaultExpanded={defaultExpanded}
-          expandWhileStreaming={expandWhileStreaming}
-          renderInput={renderInput}
-          renderOutput={renderOutput}
-          renderStreaming={renderStreaming}
-          renderPayload={renderPayload}
-        />
-      ))}
+      {!hideToolCalls && calls.map((call) =>
+        renderToolCall
+          ? <div key={call.id}>{renderToolCall(call)}</div>
+          : (
+              <ToolCallItem
+                key={call.id}
+                call={call}
+                defaultExpanded={defaultExpanded}
+                expandWhileStreaming={expandWhileStreaming}
+                renderInput={renderInput}
+                renderOutput={renderOutput}
+                renderStreaming={renderStreaming}
+                renderPayload={renderPayload}
+              />
+            ),
+      )}
+      {renderAfterCalls ? renderAfterCalls(calls) : null}
     </div>
   );
 }

package/src/tools/Chat/hooks/useChatComposer.ts

@@ -13,6 +13,7 @@ import {
 
 import type { ChatAttachment } from '../types';
 import { LIMITS } from '../config';
+import { sanitizeDraft } from '../utils/sanitizeDraft';
 
 export interface UseChatComposerOptions {
   onSubmit: (content: string, attachments: ChatAttachment[]) => void | Promise<void>;
@@ -34,6 +35,14 @@ export interface UseChatComposerOptions {
    * exactly as before. Plan64.
    */
   persistKey?: string;
+  /**
+   * Skip pre-submit draft sanitation (trim + line-ending normalise +
+   * zero-width strip). Default `false` — sanitation matches what
+   * ChatGPT / Claude / Telegram ship and is what consumers want 99% of
+   * the time. Set to `true` for niche flows that need byte-perfect
+   * passthrough (clipboard inspector, raw-prompt debug tool).
+   */
+  preserveExactValue?: boolean;
 }
 
 export interface UseChatComposerReturn {
@@ -73,6 +82,7 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
     history = { enabled: true, size: LIMITS.composerHistorySize },
     onPasteFiles,
     persistKey,
+    preserveExactValue = false,
   } = options;
 
   // Hydrate draft from sessionStorage on mount when a key is provided.
@@ -135,26 +145,39 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
   }, []);
 
   const submit = useCallback(async () => {
-    const trimmed = value.trim();
-    if ((!trimmed && attachments.length === 0) || isSubmitting || disabled) return;
+    // Sanitise BEFORE the empty-guard so a draft of only whitespace
+    // (`   \n\n   `) is treated as empty — saves a round trip for
+    // "send" attempts that would produce nothing.
+    //
+    // sanitizeDraft is intentionally conservative: trim outer
+    // whitespace, normalise line endings, strip zero-width chars.
+    // It does NOT collapse internal whitespace or cap blank lines
+    // (would break code indentation / intentional separators). See
+    // utils/sanitizeDraft.ts for the full ruleset + rationale.
+    //
+    // The cleaned text is what reaches `onSubmit` (matches ChatGPT /
+    // Claude / Telegram behaviour — the bubble shows what the user
+    // last saw, sans accidental trailing whitespace). Niche callers
+    // can opt out via `preserveExactValue`.
+    const cleaned = preserveExactValue ? value : sanitizeDraft(value);
+    if ((!cleaned && attachments.length === 0) || isSubmitting || disabled) return;
     setIsSubmitting(true);
     try {
-      if (history.enabled !== false && trimmed) {
+      if (history.enabled !== false && cleaned) {
         const buf = historyRef.current.items;
-        if (buf[buf.length - 1] !== trimmed) {
-          buf.push(trimmed);
+        if (buf[buf.length - 1] !== cleaned) {
+          buf.push(cleaned);
           if (buf.length > (history.size ?? LIMITS.composerHistorySize)) buf.shift();
         }
         historyRef.current.index = -1;
       }
       const snapshot = [...attachments];
-      const text = value;
       reset();
-      await onSubmit(text, snapshot);
+      await onSubmit(cleaned, snapshot);
     } finally {
       setIsSubmitting(false);
     }
-  }, [value, attachments, isSubmitting, disabled, history, onSubmit, reset]);
+  }, [value, attachments, isSubmitting, disabled, history, onSubmit, reset, preserveExactValue]);
 
   const addAttachment = useCallback(
     (a: ChatAttachment) => {
@@ -236,8 +259,17 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
     [onPasteFiles],
   );
 
+  // canSubmit mirrors what submit() will actually do — gate the Send
+  // button on the post-sanitation result so a whitespace-only draft
+  // renders Send as disabled (no false-hope affordance).
+  // preserveExactValue callers fall back to raw .trim() — they
+  // opted out of sanitation, but we still don't enable Send on a
+  // pure-whitespace draft (an empty message is rarely intentional).
   const canSubmit =
-    !disabled && !isSubmitting && (value.trim().length > 0 || attachments.length > 0);
+    !disabled && !isSubmitting && (
+      (preserveExactValue ? value.trim().length : sanitizeDraft(value).length) > 0
+      || attachments.length > 0
+    );
 
   return {
     value,

package/src/tools/Chat/index.ts

@@ -113,6 +113,11 @@ export {
 export { useChatLightbox, type UseChatLightboxReturn, type ChatLightboxState } from './hooks';
 export { collectImageAttachments } from './utils/collectImageAttachments';
 
+// Draft sanitation — trim, collapse runs, strip zero-width chars.
+// Wire into your composer's submit handler / Send-button gate so
+// empty-after-cleanup drafts don't fire bogus messages.
+export { sanitizeDraft, isSubmittableDraft } from './utils/sanitizeDraft';
+
 // Dev logger (consola-based, namespace "chat:*")
 export { getChatLogger, type ChatLogger, type ChatLogScope } from './core/logger';
 

package/src/tools/Chat/utils/sanitizeDraft.ts

@@ -0,0 +1,72 @@
+/**
+ * sanitizeDraft — minimal pre-submit cleanup for chat-composer drafts.
+ *
+ * Mirrors the conservative behaviour ChatGPT / Claude / Telegram
+ * actually ship: clean the obvious junk the user didn't intend to
+ * send, touch nothing that *could* be intentional.
+ *
+ * **What we DO touch:**
+ *
+ *   1. Trim leading/trailing whitespace (spaces, tabs, newlines,
+ *      NBSP). The user typing `\n\n   hello   \n` meant `hello`.
+ *   2. Normalise line endings — `\r\n` / `\r` → `\n`. Pasted Windows
+ *      / old-mac text gets the same internal shape, so the LLM
+ *      tokeniser and markdown renderer see one canonical form.
+ *   3. Strip zero-width / invisible characters that web-paste
+ *      smuggles in: ZWSP (U+200B), ZWNJ (U+200C), ZWJ (U+200D),
+ *      BOM / ZWNBSP (U+FEFF). They're invisible, break LLM
+ *      tokenisation, and the user never meant to type them.
+ *
+ * **What we DO NOT touch (and why):**
+ *
+ *   - **Internal whitespace runs** (3+ spaces, tabs, blank lines).
+ *     Code indentation depends on these. ChatGPT preserves them as
+ *     typed — "  if (x):\n    return" stays four-space-indented.
+ *     Collapsing them is the path to subtly broken code snippets.
+ *
+ *   - **Bidi override marks** (U+200E LRM, U+200F RLM, U+202A..U+202E).
+ *     Legitimately used in Arabic / Hebrew / mixed-direction text.
+ *     Stripping silently breaks RTL users. If a specific deployment
+ *     wants to block them as a security measure, do it at that layer
+ *     with explicit user-visible feedback.
+ *
+ *   - **Tabs vs spaces** beyond rule 1. Could be either code or
+ *     prose; without parsing markdown we can't tell.
+ *
+ *   - **Emoji, mentions, URLs, code spans** — passthrough text.
+ *
+ * The function is intentionally tiny — every rule earns its keep
+ * with a concrete "user pasted X from Y, got nonsense" story.
+ *
+ * **Idempotent**: `sanitizeDraft(sanitizeDraft(x)) === sanitizeDraft(x)`.
+ */
+export function sanitizeDraft(input: string): string {
+  if (!input) return '';
+
+  // Strip zero-width invisibles. Done FIRST so the trim below sees
+  // the real content edges — a stray ZWSP at the start would
+  // otherwise count as non-whitespace and survive the trim.
+  // U+200B ZWSP, U+200C ZWNJ, U+200D ZWJ, U+FEFF BOM/ZWNBSP.
+  let s = input.replace(/[​‌‍]/g, '');
+
+  // Normalise line endings.
+  s = s.replace(/\r\n?/g, '\n');
+
+  // Trim outer whitespace (includes \n, \t, NBSP via String.trim).
+  s = s.trim();
+
+  return s;
+}
+
+/**
+ * Convenience predicate: true when the draft is non-empty AFTER
+ * sanitation. Use to gate Send buttons / Enter submits so an empty
+ * or whitespace-only draft never produces a real message.
+ *
+ * Cheaper than sanitizeDraft(input).length > 0 only marginally —
+ * we still allocate the cleaned string. Kept as a named helper for
+ * call-site clarity.
+ */
+export function isSubmittableDraft(input: string): boolean {
+  return sanitizeDraft(input).length > 0;
+}

package/src/tools/MarkdownEditor/MarkdownEditor.tsx

@@ -13,6 +13,7 @@ import {
 } from 'lucide-react';
 import { createMentionSuggestion } from './createMentionSuggestion';
 import { mentionPresets } from './mentionPresets';
+import { SubmitOnEnter } from './submitOnEnter';
 import type { MentionAttrs, MentionConfig } from './types';
 import './styles.css';
 
@@ -68,6 +69,25 @@ export interface MarkdownEditorProps {
   mentions?: MentionConfig;
   /** Called when mentioned IDs change */
   onMentionIdsChange?: (ids: string[]) => void;
+  /**
+   * Called when the user presses Enter (without Shift, no IME
+   * composition, no mention popover open). When set, Enter submits
+   * and Shift+Enter inserts a newline — ChatGPT / Telegram chat
+   * behaviour. When omitted, Enter behaves as Tiptap default
+   * (HardBreak).
+   *
+   * Implementation lives in `submitOnEnter.ts` — it's a Tiptap
+   * keymap extension, NOT a React wrapper handler. Wrapper-level
+   * onKeyDown fires AFTER ProseMirror's keymap commits HardBreak in
+   * the same tick; routing through the extension lets us intercept
+   * before HardBreak runs.
+   *
+   * Return value (optional): truthy / undefined = consume the key
+   * (default). Return `false` from onSubmit to let Tiptap fall
+   * through to HardBreak — useful for guards like "don't submit an
+   * empty draft".
+   */
+  onSubmit?: () => boolean | void;
 }
 
 // ── Component ──
@@ -82,7 +102,15 @@ export function MarkdownEditor({
   showToolbar = true,
   mentions,
   onMentionIdsChange,
+  onSubmit,
 }: MarkdownEditorProps) {
+  // Keep the latest onSubmit in a ref so the Tiptap extension's
+  // keymap closure always calls the freshest handler — Tiptap's
+  // useEditor initialises extensions ONCE on first render. Without
+  // the ref the extension would call a stale onSubmit (e.g. one
+  // that references an outdated `value`).
+  const onSubmitRef = useRef(onSubmit);
+  onSubmitRef.current = onSubmit;
   const isExternalUpdate = useRef(false);
 
   // ── Dev-mode trap detector ──
@@ -115,6 +143,18 @@ export function MarkdownEditor({
       StarterKit.configure({ heading: { levels: [1, 2, 3] } }),
       Placeholder.configure({ placeholder }),
       Markdown,
+      // SubmitOnEnter — when the consumer wired an onSubmit, intercept
+      // Enter at the keymap level (before StarterKit's HardBreak).
+      // The extension calls through `onSubmitRef.current` so handler
+      // identity changes don't require an editor rebuild. See
+      // submitOnEnter.ts for the keymap-vs-wrapper-handler rationale.
+      SubmitOnEnter.configure({
+        onSubmit: () => {
+          const h = onSubmitRef.current;
+          if (!h) return false; // no handler → let Tiptap insert HardBreak
+          return h();
+        },
+      }),
     ];
 
     if (mentions) {

package/src/tools/MarkdownEditor/README.md

@@ -58,6 +58,7 @@ import '@djangocfg/ui-tools/dist.css';
 | `showToolbar` | `boolean` | `true` | Show formatting toolbar |
 | `mentions` | `MentionConfig` | — | `@`-mention autocomplete config |
 | `onMentionIdsChange` | `(ids: string[]) => void` | — | Called when mentioned IDs change |
+| `onSubmit` | `() => boolean \| void` | — | Enter handler — when set, Enter submits and Shift+Enter inserts a newline (ChatGPT / Telegram chat behaviour). Return `false` to fall back to default HardBreak. See [Submit on Enter](#submit-on-enter) below. |
 
 ### `MentionConfig` fields
 
@@ -142,6 +143,39 @@ Either `id` or `label` may be empty strings if upstream config didn't populate t
 
 > Mentions are write-only: the markdown isn't parsed back into mention nodes on `setContent`. After submit/reset, the editor receives a plain string — fine for chat composers.
 
+## Submit on Enter
+
+For chat composers you usually want **Enter = send**, **Shift+Enter = newline** — ChatGPT / Telegram / Slack behaviour. Pass an `onSubmit` and that's what you get:
+
+```tsx
+<MarkdownEditor
+  value={text}
+  onChange={setText}
+  onSubmit={() => {
+    if (!text.trim()) return false   // fall back to HardBreak
+    void send(text)
+    // returning undefined (or true) consumes the key — newline isn't inserted
+  }}
+/>
+```
+
+### How it works (and why a Tiptap extension, not a React onKeyDown)
+
+The implementation lives in `submitOnEnter.ts` — a Tiptap `Extension` that registers a keyboard shortcut via `addKeyboardShortcuts`. It runs **inside ProseMirror's keymap pipeline at higher priority than StarterKit's HardBreak**, so we intercept Enter **before** the hard-break transaction is dispatched.
+
+A naïve wrapper handler (`<div onKeyDownCapture={...}>` calling `preventDefault`) does NOT work reliably: ProseMirror's keymap is a plugin inside the editor, which fires its handler in the same event tick as the React capture phase but **commits the HardBreak transaction before React's stopPropagation gets a chance to matter**. The user sees a hard-break flash in, then the next Enter submits — the "first Enter inserts newline" bug we shipped before this extension landed.
+
+### Behaviour details
+
+| Key | Behaviour |
+|---|---|
+| `Enter` | Calls `onSubmit()`. Returns `true`/`undefined` ⇒ consume. Returns `false` ⇒ fall through to HardBreak. |
+| `Shift+Enter` | Always inserts a newline. Bound to `() => false` so the chain falls through cleanly. |
+| Mention popover open | Enter is given to the suggestion plugin (it picks the active item) — detected by querying `.markdown-mention-list`. |
+| IME composition | Native browser composition events are not intercepted (Tiptap handles them upstream). |
+
+The handler is captured via a ref inside `MarkdownEditor`, so swapping `onSubmit` between renders is safe — the latest closure always fires, no editor rebuild needed.
+
 ## Dependencies
 
 All Tiptap packages and `@floating-ui/dom` are direct dependencies — no extra installs needed.