@djangocfg/ui-tools 2.1.431 → 2.1.432

package/src/tools/chat/types/blockSchemas.ts

@@ -0,0 +1,197 @@
+/**
+ * Zod schemas for the chat `MessageBlock` discriminated union (`./block.ts`).
+ *
+ * These are the runtime VALIDATORS used at the single registry dispatch point
+ * (`messages/blocks/MessageBlocks.tsx`): every block flows through
+ * `safeParseBlock(BLOCK_SCHEMAS[kind], block)` BEFORE its renderer runs, so a
+ * malformed wire / hand-authored payload renders a safe `<BlockError>` card
+ * instead of throwing inside a renderer and blanking the transcript.
+ *
+ * Design rules (mirroring `common/blocks/schemas.ts`):
+ *  - The TS types in `./block.ts` stay the source of truth; these schemas are
+ *    kept in sync and `Extends<…>`-checked below so they can't silently drift.
+ *  - The map / link shapes are COMPOSED from the shared
+ *    `MapBlockPayloadSchema` / `LinkPreviewDataSchema` in `common/blocks` — we
+ *    never re-describe a map/link payload here.
+ *  - LENIENT where the renderer is tolerant: optional fields stay optional,
+ *    `json.data` is `unknown` (JsonTree is throw-safe), extra keys are stripped.
+ *  - STRICT on the load-bearing shape: a field whose wrong type would THROW in
+ *    the renderer is required + typed (gallery `items` must be an array;
+ *    image/video/audio `src` must be a string; map coords are finite
+ *    numbers via the shared schema).
+ *  - `custom` and the prose kinds (`text`/`markdown`) carry no schema in
+ *    `BLOCK_SCHEMAS` — `custom` is host-defined (don't over-constrain) and the
+ *    prose kinds can't throw on a wrong-typed field worth guarding. They render
+ *    as-is. (`text`/`markdown` schemas are still defined for completeness.)
+ */
+
+import { z } from 'zod';
+
+import { MapBlockPayloadSchema, LinkPreviewDataSchema } from '../../../common/blocks';
+import type {
+  TextBlock,
+  MarkdownBlock,
+  AudioBlock,
+  VideoBlock,
+  ImageBlock,
+  GalleryBlock,
+  MapBlock,
+  JsonBlock,
+  MermaidBlock,
+  CodeBlock,
+  DiffBlock,
+  LinkBlock,
+  MessageBlock,
+} from './block';
+
+/**
+ * Base fields shared by every block (`BlockBase` in `./block.ts`). We validate
+ * the WHOLE block object (incl. `kind` / `id` / `caption`), so each schema
+ * composes this. `id` is required (it is the React key + memo discriminant).
+ */
+const BlockBaseSchema = z.object({
+  id: z.string(),
+  caption: z.string().optional(),
+});
+
+const TextBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('text'),
+  text: z.string(),
+});
+
+const MarkdownBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('markdown'),
+  markdown: z.string(),
+});
+
+const AudioBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('audio'),
+  src: z.string(),
+  title: z.string().optional(),
+  artist: z.string().optional(),
+  cover: z.string().optional(),
+  variant: z.enum(['default', 'compact']).optional(),
+});
+
+const VideoBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('video'),
+  src: z.string(),
+  poster: z.string().optional(),
+  title: z.string().optional(),
+  aspectRatio: z.union([z.number(), z.literal('auto'), z.literal('fill')]).optional(),
+});
+
+const ImageBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('image'),
+  src: z.string(),
+  alt: z.string().optional(),
+  interactive: z.boolean().optional(),
+});
+
+const GalleryItemSchema = z.object({
+  id: z.string(),
+  src: z.string(),
+  thumbnail: z.string().optional(),
+  alt: z.string().optional(),
+});
+
+const GalleryBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('gallery'),
+  // STRICT: `items` must be an array — the renderer maps over it.
+  items: z.array(GalleryItemSchema),
+});
+
+/**
+ * Map block = the shared serializable map payload (`MapBlockPayloadSchema`,
+ * which already enforces finite-number `center.lat/lng` etc.) + the base block
+ * fields + the chat-only `userLocation` opt-in flag. Composed, never
+ * duplicated.
+ */
+const MapBlockSchema = MapBlockPayloadSchema.merge(BlockBaseSchema).extend({
+  kind: z.literal('map'),
+  userLocation: z.boolean().optional(),
+});
+
+const JsonBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('json'),
+  // LENIENT: JsonTree renders anything safely — accept any payload.
+  data: z.unknown(),
+  mode: z.enum(['full', 'compact', 'inline']).optional(),
+});
+
+const MermaidBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('mermaid'),
+  chart: z.string(),
+});
+
+const CodeBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('code'),
+  code: z.string(),
+  language: z.string(),
+});
+
+const DiffBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('diff'),
+  oldCode: z.string().optional(),
+  newCode: z.string().optional(),
+  patch: z.string().optional(),
+  language: z.string().optional(),
+  layout: z.enum(['split', 'unified']).optional(),
+});
+
+/**
+ * Link block = base fields + `url` + optional pre-resolved `data` (validated
+ * against the shared `LinkPreviewDataSchema`). The renderer also tolerates a
+ * resolver-only block (no `data`), so `data` stays optional.
+ */
+const LinkBlockSchema = BlockBaseSchema.extend({
+  kind: z.literal('link'),
+  url: z.string(),
+  data: LinkPreviewDataSchema.optional(),
+});
+
+// ── Drift guards ──────────────────────────────────────────────────────────
+// Type-level assertion that each schema's inferred output stays assignable to
+// the canonical block type in `./block.ts`. If a schema and the type diverge,
+// the corresponding assignment fails to compile.
+type Extends<A, B> = A extends B ? true : never;
+const _textOk: Extends<z.infer<typeof TextBlockSchema>, TextBlock> = true;
+const _markdownOk: Extends<z.infer<typeof MarkdownBlockSchema>, MarkdownBlock> = true;
+const _audioOk: Extends<z.infer<typeof AudioBlockSchema>, AudioBlock> = true;
+const _videoOk: Extends<z.infer<typeof VideoBlockSchema>, VideoBlock> = true;
+const _imageOk: Extends<z.infer<typeof ImageBlockSchema>, ImageBlock> = true;
+const _galleryOk: Extends<z.infer<typeof GalleryBlockSchema>, GalleryBlock> = true;
+const _mapOk: Extends<z.infer<typeof MapBlockSchema>, MapBlock> = true;
+const _jsonOk: Extends<z.infer<typeof JsonBlockSchema>, JsonBlock> = true;
+const _mermaidOk: Extends<z.infer<typeof MermaidBlockSchema>, MermaidBlock> = true;
+const _codeOk: Extends<z.infer<typeof CodeBlockSchema>, CodeBlock> = true;
+const _diffOk: Extends<z.infer<typeof DiffBlockSchema>, DiffBlock> = true;
+const _linkOk: Extends<z.infer<typeof LinkBlockSchema>, LinkBlock> = true;
+void [
+  _textOk, _markdownOk, _audioOk, _videoOk, _imageOk, _galleryOk, _mapOk,
+  _jsonOk, _mermaidOk, _codeOk, _diffOk, _linkOk,
+];
+
+/**
+ * `kind` → schema. Validated at the registry dispatch point. Kinds WITHOUT an
+ * entry are skipped (rendered as-is):
+ *  - `custom` — host-defined `payload`; over-constraining it would break hosts.
+ *
+ * Every built-in data block is covered so a malformed payload is caught
+ * centrally — and any FUTURE kind is guarded the moment it's added here.
+ */
+export const BLOCK_SCHEMAS: Partial<Record<MessageBlock['kind'], z.ZodType>> = {
+  text: TextBlockSchema,
+  markdown: MarkdownBlockSchema,
+  audio: AudioBlockSchema,
+  video: VideoBlockSchema,
+  image: ImageBlockSchema,
+  gallery: GalleryBlockSchema,
+  map: MapBlockSchema,
+  json: JsonBlockSchema,
+  mermaid: MermaidBlockSchema,
+  code: CodeBlockSchema,
+  diff: DiffBlockSchema,
+  link: LinkBlockSchema,
+  // `custom` intentionally omitted — host-defined, rendered as-is.
+};

package/src/tools/chat/types/config.ts

@@ -4,6 +4,7 @@
 
 import type { ChatAssistantContext, ChatUserContext } from './persona';
 import type { ChatLabels } from './labels';
+import type { ResolveLinkPreview } from '../../../common/link-preview';
 
 export type ChatDisplayMode = 'closed' | 'embedded' | 'floating' | 'sidebar' | 'fullscreen';
 
@@ -40,4 +41,36 @@ export interface ChatConfig {
   prefs?: ChatPrefs;
   /** Visual labels (i18n is the host's job). */
   labels?: Partial<ChatLabels>;
+  /** Link-preview (URL unfurl) wiring — the host owns metadata fetching. */
+  linkPreview?: ChatLinkPreviewConfig;
+  /**
+   * Render bare web URLs inside message bubbles as compact "URL chips"
+   * (favicon + domain + middle-ellipsis path, e.g.
+   * `github.com/wailsapp/…/README.md`) instead of a plain blue link —
+   * matching the composer's URL chip. Only bare `http(s)` autolinks are
+   * chipped; a `[labeled](url)` link keeps its author-chosen text as a
+   * normal link.
+   *
+   * Off by default (the host opts in). When on, the chip rule is appended
+   * AFTER any host-supplied `linkRules`, so host-specific rules win.
+   * @default false
+   */
+  linkChips?: boolean;
+}
+
+export interface ChatLinkPreviewConfig {
+  /**
+   * Host resolver that turns a URL into preview metadata. Required for any
+   * link card to appear (the browser cannot fetch meta tags cross-origin).
+   * In Wails/Go this wraps a bound `FetchLinkMetadata` method; on the web,
+   * a `/api/unfurl` route.
+   */
+  resolve?: ResolveLinkPreview;
+  /**
+   * Auto-render a preview card under a message bubble when its text
+   * contains a link (Telegram-style — at most ONE card per message).
+   * Off by default; needs `resolve` to be set.
+   * @default false
+   */
+  autoDetect?: boolean;
 }

package/src/tools/chat/types/events.ts

@@ -5,12 +5,12 @@
  * into this union by `mapPydanticAIEvent` and friends.
  */
 
-import type { ChatSource } from './attachment';
+import type { ChatMessage } from './message';
 
 /**
- * Per-run metrics block. Emitted once per assistant turn alongside the
- * terminal `message_end` event (a separate `message_metrics` event so
- * `message_end` keeps its lean `tokensIn`/`tokensOut`/`sources` shape).
+ * Per-run metrics block. Emitted once per assistant turn, carried into the
+ * message either by a non-terminal `message_metrics` event mid-run or via
+ * the terminal `message_end` event's generic `patch` slot.
  *
  * All fields optional — the backend omits anything it could not measure.
  */
@@ -54,9 +54,16 @@ export type ChatStreamEvent =
     }
   | {
       type: 'message_end';
-      tokensIn?: number;
-      tokensOut?: number;
-      sources?: ChatSource[];
+      /**
+       * Generic finalize patch merged into the message on done — the ONE
+       * slot every finalize feature rides (tokens, sources, blocks, OCR
+       * text, attachments-finalized, local-preview metadata). `content`
+       * here REPLACES the accumulated bubble body (the append-only gap).
+       * The reducer applies it as a `Partial<ChatMessage>` merge — the same
+       * mechanism `message_metrics`/`resolved_model` already use. Absent →
+       * `message_end` is a pure terminal no-op (just clears `isStreaming`).
+       */
+      patch?: Partial<ChatMessage>;
     }
   | {
       /**

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

@@ -33,13 +33,15 @@ export type {
   JsonBlock,
   MermaidBlock,
   CodeBlock,
-  LottieBlock,
+  DiffBlock,
+  LinkBlock,
   CustomBlock,
 } from './block';
+export type { LinkPreviewData, ResolveLinkPreview } from '../../../common/link-preview';
 export type { ChatMessage } from './message';
 export { DEFAULT_LABELS } from './labels';
 export type { ChatLabels } from './labels';
-export type { ChatConfig, ChatPrefs, ChatDisplayMode } from './config';
+export type { ChatConfig, ChatPrefs, ChatDisplayMode, ChatLinkPreviewConfig } from './config';
 export type { ChatStreamEvent, ChatMessageMetrics } from './events';
 export type {
   CreateSessionOptions,

package/src/tools/chat/types/message.ts

@@ -17,6 +17,13 @@ export interface ChatMessage {
   content: string;
   /** epoch ms — serializable. */
   createdAt: number;
+  /**
+   * Stable per-session transcript position, supplied by hosts whose backend
+   * keys messages by an absolute sequence (e.g. a monotonic `chat_history.seq`).
+   * The synthetic `id` is a UI key only; `seq` is the durable handle the host
+   * passes back to an authoritative edit/truncate API. Optional — engines that
+   * don't track a backend seq leave it undefined. */
+  seq?: number;
   isStreaming?: boolean;
   isError?: boolean;
   /** Bumps on edit so memo keys invalidate. */

package/src/tools/data/JsonTree/JsonViewer.tsx

@@ -104,8 +104,8 @@ const TOKEN_CLASS: Record<string, string> = {
   string: 'text-[#a31515] dark:text-emerald-400',
   number: 'text-[#098658] dark:text-sky-400',
   boolean: 'text-[#0550ae] dark:text-amber-400',
-  null: 'text-neutral-500 dark:text-muted-foreground/60',
-  punctuation: 'text-neutral-700 dark:text-muted-foreground',
+  null: 'text-muted-foreground/70 dark:text-muted-foreground/60',
+  punctuation: 'text-muted-foreground dark:text-muted-foreground',
 };
 
 function TokenSpan({
@@ -131,7 +131,7 @@ function HighlightMatch({ text, query }: { text: string; query: string }) {
   return (
     <>
       {text.slice(0, idx)}
-      <mark className="rounded-sm bg-amber-200/60 px-0.5 text-inherit dark:bg-amber-500/30">
+      <mark className="rounded-sm bg-warning/30 px-0.5 text-inherit">
         {text.slice(idx, idx + query.length)}
       </mark>
       {text.slice(idx + query.length)}
@@ -189,7 +189,7 @@ function JsonNode({
 
   const rowClass = cn(
     'group flex items-center gap-0 py-px hover:bg-muted/40 rounded-sm',
-    nodeMatches && 'bg-amber-100/40 dark:bg-amber-900/20',
+    nodeMatches && 'bg-warning/15',
   );
 
   const rowStyle: CSSProperties = { paddingLeft: `${depth * 20 + 8}px` };
@@ -264,7 +264,7 @@ function JsonNode({
           className={copyIconClass}
         >
           {pathCopied ? (
-            <CopyPlus className="size-3 text-emerald-500" />
+            <CopyPlus className="size-3 text-success" />
           ) : (
             <CopyPlus className="size-3" />
           )}
@@ -317,7 +317,7 @@ function JsonNode({
           className={copyIconClass}
         >
           {pathCopied ? (
-            <CopyPlus className="size-3 text-emerald-500" />
+            <CopyPlus className="size-3 text-success" />
           ) : (
             <CopyPlus className="size-3" />
           )}
@@ -489,7 +489,7 @@ function Toolbar({
               'copy',
               copiedAll ? 'Copied!' : 'Copy JSON',
               copiedAll ? (
-                <Check className={cn(iconCls, 'text-emerald-500')} />
+                <Check className={cn(iconCls, 'text-success')} />
               ) : (
                 <Copy className={iconCls} />
               ),