@djangocfg/ui-tools 2.1.433 → 2.1.434

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.433",
+  "version": "2.1.434",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -334,8 +334,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.433",
-    "@djangocfg/ui-core": "^2.1.433",
+    "@djangocfg/i18n": "^2.1.434",
+    "@djangocfg/ui-core": "^2.1.434",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -418,9 +418,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.433",
-    "@djangocfg/typescript-config": "^2.1.433",
-    "@djangocfg/ui-core": "^2.1.433",
+    "@djangocfg/i18n": "^2.1.434",
+    "@djangocfg/typescript-config": "^2.1.434",
+    "@djangocfg/ui-core": "^2.1.434",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

package/src/tools/chat/CLAUDE.md

@@ -0,0 +1,51 @@
+# chat — `@djangocfg/ui-tools/chat`
+
+Decomposed, transport-agnostic chat UI: bubbles, composer, tool-call panels,
+message blocks, link previews. Consumed from npm AND vendored into cmdop
+desktop via `pnpm sync:cfg`. See `README.md` for the full API; `@docs/` for
+design + troubleshooting.
+
+## Public entry — `lazy.tsx` (the `./chat` subpath)
+
+`package.json` maps `"./chat"` → `src/tools/chat/lazy.tsx`. It does
+`export * from './messages'` (+ composer/shell/launcher) and a few **explicit**
+re-exports.
+
+**Invariant — explicit-export gotcha.** A newly added **value** export that an
+external host imports from `@djangocfg/ui-tools/chat` MUST be listed explicitly
+in `lazy.tsx` (like `MarkdownMessage`, `ToolPayloadValue`). `export *` forwards
+types but drops a fresh value export at runtime under `'use client'` + Vite →
+`does not provide an export named X`. Not a cache bug. See
+[`@docs/troubleshooting.md`](./@docs/troubleshooting.md) §1.
+
+## Shared slots — extract, don't fork
+
+A host can fork `MessageBubble` (cmdop does, to inject `@machine` chips). To
+stop forks silently losing features, bubble features are **extracted
+components** the fork re-renders, not inline code:
+
+- `ToolPayloadValue` — the one payload renderer (object→JsonTree, string→`<pre>`,
+  XSS-safe). Used by the default `ToolCalls` panel AND any host card that owns
+  the panel via `renderToolCall`. [`@docs/tool-call-rendering.md`](./@docs/tool-call-rendering.md)
+- `AutoLinkPreview` — auto-detect URL→preview slot, rendered by `MessageBubble`
+  and every fork. [`@docs/link-preview.md`](./@docs/link-preview.md)
+
+**Rule:** adding a shared bubble feature → extract a component + export it (and
+list it in `lazy.tsx` if a host imports it directly).
+
+## Producer contract — tool payloads
+
+`ChatToolCall.input`/`.output` are `unknown` so a real object flows through and
+renders as a JSON tree. A producer that sends a JSON **string** (or
+double-encodes one) gets a flat/escaped `<pre>` — the frontend never
+un-escapes (sanitization). Fix on the producer: send a value, encode once.
+[`@docs/troubleshooting.md`](./@docs/troubleshooting.md) §2-3.
+
+## Docs
+
+| Doc | Covers |
+|---|---|
+| [`@docs/tool-call-rendering.md`](./@docs/tool-call-rendering.md) | `ToolCalls` panels, `renderToolCall` vs payload props, `ToolPayloadValue`, JSON-tree contract |
+| [`@docs/link-preview.md`](./@docs/link-preview.md) | `AutoLinkPreview` auto-detect, `LinkPreviewCard`, fork-drift fix |
+| [`@docs/message-blocks.md`](./@docs/message-blocks.md) | typed `blocks[]` registry (`json`/`link`/`map`/… renderers) |
+| [`@docs/troubleshooting.md`](./@docs/troubleshooting.md) | export gotcha, double-encoding, `<pre>`-vs-tree, fork drift, sync:cfg |

package/src/tools/chat/README.md

@@ -2,6 +2,12 @@
 
 Decomposed, transport-agnostic chat. Streaming-aware, markdown-native, mobile-ready, role-aware styling, pluggable backends.
 
+> **Docs & gotchas:** [`CLAUDE.md`](./CLAUDE.md) (quick map + invariants) ·
+> [`@docs/tool-call-rendering.md`](./@docs/tool-call-rendering.md) ·
+> [`@docs/link-preview.md`](./@docs/link-preview.md) ·
+> [`@docs/message-blocks.md`](./@docs/message-blocks.md) ·
+> [`@docs/troubleshooting.md`](./@docs/troubleshooting.md)
+
 ## TL;DR
 
 ```tsx

package/src/tools/chat/lazy.tsx

@@ -85,6 +85,15 @@ export {
   type MarkdownMessageProps,
 } from '../dev/code/MarkdownMessage';
 
+// Same gotcha as above: a host that owns its own tool-call card (cmdop's
+// `<ToolResult>` via the `renderToolCall` override) imports ToolPayloadValue
+// from `@djangocfg/ui-tools/chat` → THIS file. The `export * from './messages'`
+// above re-exports it for TYPES, but under `'use client'` + Vite the runtime
+// barrel drops the freshly-added symbol — so list it explicitly, like
+// MarkdownMessage. (Symbols imported directly by MessageBubble — e.g.
+// AutoLinkPreview — ride its chunk and don't need this.)
+export { ToolPayloadValue } from './messages/ToolPayloadValue';
+
 // Bridge — AI-driven `point` directives (lightweight, no heavy deps).
 export {
   HighlightOverlay,

package/src/tools/chat/messages/AutoLinkPreview.tsx

@@ -0,0 +1,74 @@
+'use client';
+
+/**
+ * AutoLinkPreview — the auto-detect link-preview slot, extracted so EVERY
+ * bubble surface shares ONE implementation.
+ *
+ * The default `MessageBubble` and any forked bubble (e.g. cmdop's
+ * mention-aware bubble, which owns its own content `<MarkdownMessage>` to
+ * inject `@machine` chips) both render this. Before extraction the logic
+ * lived inline in `MessageBubble` only, so a fork silently lost link
+ * previews — this component is the anti-drift fix: import it, render it, done.
+ *
+ * Behaviour (unchanged from the old inline path): when the host enables
+ * `config.linkPreview.autoDetect` AND provides a `resolve`-r, surface ONE
+ * preview card under the bubble for the FIRST URL in the message text.
+ * Suppressed while streaming (text isn't final), for error turns, and when
+ * the message already carries an explicit `link` block (so we never double
+ * up). Reads everything off the chat context — the caller passes only the
+ * message + presentational flags.
+ */
+
+import { useMemo } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useChatContextOptional } from '../context';
+import { extractFirstUrl } from '../core/extractFirstUrl';
+import type { ChatMessage } from '../types';
+import type { ComposerAppearance } from '../composer/types';
+import { LinkPreviewCard } from '../../../common/link-preview';
+
+export interface AutoLinkPreviewProps {
+  message: ChatMessage;
+  /** Streaming turn → suppress (text not final yet). */
+  isStreaming?: boolean;
+  /** Error turn → suppress. */
+  isError?: boolean;
+  /** Right-align the card under a user bubble. */
+  isUser?: boolean;
+  appearance?: ComposerAppearance;
+}
+
+export function AutoLinkPreview({
+  message,
+  isStreaming = false,
+  isError = false,
+  isUser = false,
+  appearance = 'compact',
+}: AutoLinkPreviewProps) {
+  const ctx = useChatContextOptional();
+  const linkCfg = ctx?.config.linkPreview;
+
+  const url = useMemo(() => {
+    if (!linkCfg?.autoDetect || !linkCfg.resolve) return null;
+    if (isStreaming || isError) return null;
+    if (message.blocks?.some((b) => b.kind === 'link')) return null;
+    return extractFirstUrl(message.content);
+  }, [
+    linkCfg?.autoDetect,
+    linkCfg?.resolve,
+    isStreaming,
+    isError,
+    message.blocks,
+    message.content,
+  ]);
+
+  if (!url || !linkCfg?.resolve) return null;
+
+  return (
+    <div className={cn('mt-1.5 w-full', isUser && 'flex justify-end')}>
+      <LinkPreviewCard url={url} resolver={linkCfg.resolve} appearance={appearance} />
+    </div>
+  );
+}

package/src/tools/chat/messages/MessageBubble.tsx

@@ -33,8 +33,7 @@ import {
   type BubbleMenuItem,
 } from './BubbleContextMenu';
 import { MessageBlocks } from './blocks';
-import { LinkPreviewCard } from '../../../common/link-preview';
-import { extractFirstUrl } from '../core/extractFirstUrl';
+import { AutoLinkPreview } from './AutoLinkPreview';
 import type { BlockRegistry } from './blocks';
 import type { ToolCallsProps } from './ToolCalls';
 import type { ComposerAppearance } from '../composer/types';
@@ -212,18 +211,9 @@ const MessageBubbleInner = ({
   // registry when both are absent.
   const resolvedBlockRegistry = blockRegistry ?? ctx?.blockRegistry;
 
-  // Auto link-preview (Telegram-style): when the host opts in and provides a
-  // resolver, surface ONE preview card under the bubble for the first URL in
-  // the text. Suppressed while streaming (the text isn't final), for error
-  // turns, and when the message already carries an explicit `link` block (so
-  // we never double up).
-  const linkCfg = ctx?.config.linkPreview;
-  const autoPreviewUrl = useMemo(() => {
-    if (!linkCfg?.autoDetect || !linkCfg.resolve) return null;
-    if (isStreaming || isErr) return null;
-    if (message.blocks?.some((b) => b.kind === 'link')) return null;
-    return extractFirstUrl(message.content);
-  }, [linkCfg?.autoDetect, linkCfg?.resolve, isStreaming, isErr, message.blocks, message.content]);
+  // Auto link-preview (Telegram-style) is rendered below the content via the
+  // shared <AutoLinkPreview> slot (so a forked bubble shares the exact same
+  // detect+render and can't drift). See AutoLinkPreview.tsx.
 
   // URL chips (plan22): when the host opts in via `config.linkChips`, render
   // bare web URLs in the bubble as compact favicon chips (matching the
@@ -397,15 +387,13 @@ const MessageBubbleInner = ({
           />
         ) : null}
 
-        {autoPreviewUrl && linkCfg?.resolve ? (
-          <div className={cn('mt-1.5 w-full', isUser && 'flex justify-end')}>
-            <LinkPreviewCard
-              url={autoPreviewUrl}
-              resolver={linkCfg.resolve}
-              appearance={appearance}
-            />
-          </div>
-        ) : null}
+        <AutoLinkPreview
+          message={message}
+          isStreaming={isStreaming}
+          isError={isErr}
+          isUser={isUser}
+          appearance={appearance}
+        />
 
         {message.toolCalls?.length
           ? toolCallsRenderer

package/src/tools/chat/messages/ToolCalls.tsx

@@ -6,8 +6,11 @@ import { ChevronDown, ChevronRight, Loader2 } from 'lucide-react';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import type { ChatToolCall } from '../types';
+import { ToolPayloadValue, type ToolPayloadKind } from './ToolPayloadValue';
 
-export type ToolPayloadKind = 'input' | 'output' | 'streaming';
+// Re-exported for back-compat: `ToolPayloadKind` is now OWNED by
+// ToolPayloadValue (breaking the old ToolCalls↔ToolPayloadValue import cycle).
+export type { ToolPayloadKind };
 
 export interface ToolCallsProps {
   calls: ChatToolCall[];
@@ -207,26 +210,10 @@ const ToolCallItem = memo(function ToolCallItem({
   );
 });
 
+// The default payload renderer delegates to the shared <ToolPayloadValue>
+// (object → JsonTree, string/streaming → <pre>) so a host that owns its own
+// tool-call card via `renderToolCall` can render the exact same payload with
+// no duplicated routing. See ToolPayloadValue.tsx.
 function DefaultPayload({ value, kind }: { value: unknown; kind: ToolPayloadKind }) {
-  const isStreamingOrString = kind === 'streaming' || typeof value === 'string';
-  const muted = kind === 'input';
-  return (
-    <pre
-      className={cn(
-        'overflow-auto rounded bg-background/60 p-1.5 font-mono',
-        kind === 'input' ? 'max-h-32' : 'max-h-48',
-        muted ? 'text-muted-foreground' : 'text-foreground/90',
-      )}
-    >
-      {isStreamingOrString ? String(value) : safeStringify(value)}
-    </pre>
-  );
-}
-
-function safeStringify(value: unknown): string {
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
-  }
+  return <ToolPayloadValue value={value} kind={kind} />;
 }

package/src/tools/chat/messages/ToolPayloadValue.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+/**
+ * ToolPayloadValue — the single, shared renderer for a tool call's
+ * `input` / `output` / live `streaming` payload.
+ *
+ * Routing (one implementation, reused everywhere):
+ *   - object / array (and NOT streaming) → interactive collapsible
+ *     `LazyJsonTree` (the same viewer the chat `json` block + document
+ *     inspector use). It renders values as React children — never
+ *     `innerHTML` — so a tool result carrying HTML/markdown (e.g. a fetched
+ *     web page) is shown as text, not executed: XSS-safe.
+ *   - string / scalar / streaming → plain `<pre>` text. A streaming payload
+ *     arrives as a partial string and must NOT be parsed mid-flight; prose /
+ *     scalars have no tree to show.
+ *
+ * Both the default `DefaultPayload` (inside `ToolCalls`) AND a host that owns
+ * its own tool-call card (e.g. cmdop's `<ToolResult>` action card, reached via
+ * the `renderToolCall` override) render THROUGH this — so the object→tree
+ * behaviour can't drift between the two. `surfaceClassName` lets a host match
+ * its own card's surface token (the only thing that differed when the two
+ * implementations were separate).
+ */
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { LazyJsonTree } from '../../data/JsonTree/lazy';
+
+// Defined locally (NOT imported from ./ToolCalls) on purpose: ToolCalls
+// imports ToolPayloadValue, so importing the type back would form an import
+// cycle. Under the `'use client'` + subpath-barrel (`./chat` → lazy.tsx) setup
+// that cycle makes Vite drop this module's symbol from the re-export graph at
+// runtime (the export typechecks via index.ts but fails to bundle — the exact
+// `MarkdownMessage` gotcha documented in lazy.tsx). The union is the SAME shape
+// ToolCalls re-exports as `ToolPayloadKind`; keep them in sync (trivial).
+export type ToolPayloadKind = 'input' | 'output' | 'streaming';
+
+/** A structured value worth showing in the JSON tree (object or array). */
+function isStructured(value: unknown): value is object {
+  return value !== null && typeof value === 'object';
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+export interface ToolPayloadValueProps {
+  value: unknown;
+  /** Drives expand depth (input collapsed, output 1 level), muted text, and
+   *  whether a streaming partial is parsed (it never is). */
+  kind: ToolPayloadKind;
+  /** Surface token for the tree wrapper + `<pre>` background. Defaults to the
+   *  chat panel's `bg-background/60`; a host card can pass e.g. `bg-muted/40`. */
+  surfaceClassName?: string;
+  /**
+   * Show the JsonTree toolbar (search / expand / copy). Default **false**:
+   * the tool-call panel already has its own header (tool name + status), so a
+   * second toolbar is visual noise — and in `'auto'` mode JsonTree RESERVES the
+   * toolbar's height even while hidden, leaving an empty gap above the tree.
+   * Opt in (`toolbar`) only when copy/search on the raw payload is worth the
+   * extra chrome. When true the toolbar is hover-revealed (`'auto'`).
+   */
+  toolbar?: boolean;
+}
+
+export function ToolPayloadValue({
+  value,
+  kind,
+  surfaceClassName = 'bg-background/60',
+  toolbar = false,
+}: ToolPayloadValueProps) {
+  if (kind !== 'streaming' && isStructured(value)) {
+    return (
+      <div className={cn('overflow-auto rounded', surfaceClassName)}>
+        <LazyJsonTree
+          data={value}
+          bordered={false}
+          size="sm"
+          // Input collapsed, output 1 level. Toolbar OFF by default — the
+          // tool-call panel owns the header; `auto` would reserve height and
+          // leave an empty gap above the tree (see the `toolbar` prop note).
+          defaultExpandedDepth={kind === 'input' ? 0 : 1}
+          actions={['search', 'expand', 'copy']}
+          toolbar={toolbar ? 'auto' : 'never'}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <pre
+      className={cn(
+        'overflow-auto rounded p-1.5 font-mono',
+        surfaceClassName,
+        kind === 'input' ? 'max-h-32' : 'max-h-48',
+        kind === 'input' ? 'text-muted-foreground' : 'text-foreground/90',
+      )}
+    >
+      {typeof value === 'string' ? value : safeStringify(value)}
+    </pre>
+  );
+}

package/src/tools/chat/messages/blocks/renderers/MapBlock.tsx

@@ -153,6 +153,13 @@ export default function MapBlockRenderer({ block, ctx }: BlockRendererProps<MapB
       <LazyMapContainer
         initialViewport={initialViewport}
         fullscreenTitle={block.caption ?? 'Map'}
+        // A chat transcript column is < 768px, which would otherwise trip the
+        // map's width-based "mobile" collapse (gestures off, scroll-lock
+        // overlay invisible, just a static tile) even on a desktop with a fine
+        // pointer. `0` opts out of width-based collapse — the map keeps its
+        // desktop scroll-lock + controls in the narrow column, and a REAL
+        // touchscreen still degrades to the mobile preview (coarse pointer).
+        mobileBreakpoint={0}
         {...mapOptions}
       >
         {/* Filled zones first so routes/markers stack above them. */}

package/src/tools/chat/messages/index.ts

@@ -8,6 +8,9 @@ export {
   type MessageListHandle,
 } from './MessageList';
 export { MessageBubble, type MessageBubbleProps } from './MessageBubble';
+// The auto-detect link-preview slot — shared by MessageBubble and any forked
+// bubble (e.g. cmdop's mention bubble) so previews never silently drift.
+export { AutoLinkPreview, type AutoLinkPreviewProps } from './AutoLinkPreview';
 // Re-exported from the shared `common/link-preview` location (the card was
 // hoisted out of chat so the NotionEditor bookmark node can reuse it). The
 // chat public surface (`@djangocfg/ui-tools/chat`) keeps exporting it from
@@ -24,6 +27,9 @@ export {
 } from './BubbleContextMenu';
 export { Sources, type SourcesProps } from './Sources';
 export { ToolCalls, type ToolCallsProps, type ToolPayloadKind } from './ToolCalls';
+// Shared payload renderer (object → JsonTree, string/streaming → <pre>) so a
+// host that overrides `renderToolCall` renders payloads identically.
+export { ToolPayloadValue, type ToolPayloadValueProps } from './ToolPayloadValue';
 export {
   Attachments,
   AttachmentsGrid,

package/src/tools/dev/Map/components/MapContainer/MapInner.tsx

@@ -40,6 +40,7 @@ export function MapInner({
   showResetButton = false,
   scrollProtection = true,
   scrollProtectionHint = 'Click to interact',
+  mobileBreakpoint,
   fullscreenButton = true,
   fullscreenLabel = 'Expand map',
   fullscreenTitle = 'Map',
@@ -148,7 +149,11 @@ export function MapInner({
   // keeps the Google-Maps scroll-isolation. The expanded map is always
   // live. Detection is `matchMedia`-based so it reacts to DevTools device
   // emulation, real touchscreens and window resizes (see useMapTouchMode).
-  const isTouch = useMapTouchMode()
+  // `mobileBreakpoint` lets a narrow-column embed (chat transcript < md) opt
+  // out of width-based mobile collapse: pass 0 → only a real coarse pointer
+  // (touchscreen) triggers the mobile preview, not the column's width. When
+  // undefined, useMapTouchMode keeps its 768px default.
+  const isTouch = useMapTouchMode(mobileBreakpoint)
   const protectionMode = !scrollProtection || isFullscreenInstance
     ? 'off'
     : isTouch

package/src/tools/dev/Map/components/MapContainer/types.ts

@@ -94,6 +94,18 @@ export interface MapContainerProps {
   scrollProtection?: boolean
   /** Hint shown on the lock overlay while scroll-zoom is blocked. */
   scrollProtectionHint?: string
+  /**
+   * Width (px) at/under which the map collapses to the touch/"mobile"
+   * preview (gestures off, tap-to-expand) even with a fine pointer. Passed
+   * to `useMapTouchMode`. Default 768 (Tailwind `md`).
+   *
+   * Set `0` to OPT OUT of width-based collapse — the map then only goes
+   * mobile on a real coarse pointer (touchscreen), not because its column
+   * is narrow. Use this for a map embedded in a narrow column (e.g. a chat
+   * transcript < 768px) that should keep the desktop scroll-lock + controls.
+   * @default 768
+   */
+  mobileBreakpoint?: number
   /**
    * Show a button that opens the map full-screen in a large dialog
    * (Google-Maps-style "expand"). Scroll protection is off inside the

package/src/tools/dev/Map/hooks/useMapTouchMode.ts

@@ -14,7 +14,7 @@ import { useIsTouch, useMediaQuery, MEDIA_BREAKPOINTS } from '@djangocfg/ui-core
  * @param breakpoint width (px) at/under which the map is treated as mobile
  *   even with a fine pointer. Default 768 (Tailwind `md`).
  */
-export function useMapTouchMode(breakpoint = MEDIA_BREAKPOINTS.md): boolean {
+export function useMapTouchMode(breakpoint: number = MEDIA_BREAKPOINTS.md): boolean {
   const isTouch = useIsTouch()
   const isNarrow = useMediaQuery(`(max-width: ${breakpoint - 1}px)`)
   return isTouch || isNarrow