@djangocfg/ui-tools 2.1.430 → 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} />
               ),

package/src/tools/data/Tree/README.md

@@ -376,6 +376,7 @@ Defaults are English. Function-shaped entries (`confirmDeleteTitle(count)`, `con
 ```tsx
 <TreeRoot
   appearance={{
+    variant: 'explorer',      // 'explorer' (default) | 'list'
     density: 'cozy',          // 'compact' | 'cozy' | 'comfortable'
     accent: 'default',        // 'subtle' | 'default' | 'strong'
     radius: 'sm',             // 'none' | 'sm' | 'md'
@@ -387,6 +388,35 @@ Defaults are English. Function-shaped entries (`confirmDeleteTitle(count)`, `con
 />
 ```
 
+### Variant — `explorer` vs `list`
+
+`variant` is a high-level look that sets sensible defaults for three
+fields (`hideLeafIcons`, `hideFolderIcons`, `rowSizing`,
+`showActiveIndicator`); any of those passed explicitly still wins.
+
+| Variant | Look | Defaults |
+| --- | --- | --- |
+| `'explorer'` (default) | Classic file/folder tree | leaf + folder icons, **fixed** single-line rows, active bar on |
+| `'list'` | macOS-sidebar / **chat-history** list | **no icons** (chevron only on groups), **auto-height** rows (multi-line label friendly), quiet selection (no active bar) |
+
+```tsx
+// A grouped chat-history sidebar (date / topic buckets → sessions),
+// multi-line rows (title + dimmed meta), no file glyphs:
+<TreeRoot<Payload>
+  data={groupedSessions}
+  getItemName={(n) => label(n)}
+  appearance={{ variant: 'list', indent: 10 }}
+  showIndentGuides={false}
+  renderLabel={({ node }) => /* title + meta */ null}
+/>
+```
+
+Fine-grained fields (override the variant):
+
+- `hideLeafIcons` / `hideFolderIcons` — drop the per-row icon (chevron stays).
+- `rowSizing: 'fixed' | 'auto'` — `auto` turns `rowHeight` into a *minimum*
+  so a multi-line label grows the row instead of overflowing.
+
 The resolved appearance is exposed on the root container as CSS variables:
 
 ```

package/src/tools/data/Tree/components/TreeRow.tsx

@@ -175,7 +175,16 @@ function TreeRowRaw<T>({ row, className }: TreeRowProps<T>) {
       tabIndex={-1}
       style={{
         paddingLeft: 6 + level * appearance.indent,
-        height: 'var(--tree-row-height)',
+        // `auto` sizing lets a multi-line label (e.g. title + meta in a
+        // chat-history list) grow the row instead of overflowing a fixed
+        // height. `fixed` keeps the classic single-line explorer row.
+        ...(appearance.rowSizing === 'auto'
+          ? {
+              minHeight: 'var(--tree-row-height)',
+              paddingTop: 4,
+              paddingBottom: 4,
+            }
+          : { height: 'var(--tree-row-height)' }),
         gap: 'var(--tree-gap)',
       }}
       {...(dnd.active ? draggable.listeners : {})}
@@ -234,7 +243,7 @@ function TreeRowRaw<T>({ row, className }: TreeRowProps<T>) {
         />
       ) : renderIcon ? (
         renderIcon(slot)
-      ) : (
+      ) : (isFolder ? appearance.hideFolderIcons : appearance.hideLeafIcons) ? null : (
         <TreeIcon isFolder={isFolder} isExpanded={isExpanded} />
       )}
 

package/src/tools/data/Tree/context/menu/render.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { useState } from 'react';
 import {
   ContextMenu,
   ContextMenuContent,
@@ -14,6 +15,60 @@ import type {
   TreeRowRenderProps,
 } from '../../types';
 
+interface RowContextMenuProps<T> {
+  rowProps: TreeRowRenderProps<T>;
+  items: TreeContextMenuItem<T>[];
+  trigger: React.ReactNode;
+}
+
+/**
+ * Per-row context menu.
+ *
+ * PERF: every visible row wraps its trigger in a `<ContextMenu>`, so a
+ * large tree mounts hundreds of these. Building the full
+ * `<ContextMenuContent>` item subtree for each of them on every render is
+ * what made right-click feel laggy (the selection change on right-click
+ * re-renders all rows, each rebuilding its menu body). We now render the
+ * content body ONLY while this row's menu is actually open — closed rows
+ * cost just the lightweight `ContextMenu` + `Trigger` shell.
+ */
+function RowContextMenu<T>({
+  rowProps,
+  items,
+  trigger,
+}: RowContextMenuProps<T>) {
+  const [open, setOpen] = useState(false);
+  return (
+    <ContextMenu onOpenChange={setOpen}>
+      <ContextMenuTrigger asChild>{trigger}</ContextMenuTrigger>
+      {open ? (
+        <ContextMenuContent>
+          {items.map((item, idx) => {
+            if (item === 'separator') {
+              return <ContextMenuSeparator key={`sep-${idx}`} />;
+            }
+            const Icon = item.icon;
+            return (
+              <ContextMenuItem
+                key={item.id}
+                disabled={item.disabled}
+                variant={item.destructive ? 'destructive' : undefined}
+                onSelect={() => item.onSelect(rowProps)}
+              >
+                {Icon ? <Icon /> : null}
+                {item.label}
+                {item.shortcut ? (
+                  <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
+                ) : null}
+              </ContextMenuItem>
+            );
+          })}
+        </ContextMenuContent>
+      ) : null}
+    </ContextMenu>
+  );
+}
+
 /**
  * Render an array of declarative menu items as a themed `<ContextMenu>`
  * wrapped around the supplied trigger element. Pure presentational layer
@@ -24,33 +79,7 @@ export function renderItemsAsContextMenu<T>(
   items: TreeContextMenuItem<T>[],
   trigger: React.ReactNode,
 ): React.ReactNode {
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger asChild>{trigger}</ContextMenuTrigger>
-      <ContextMenuContent>
-        {items.map((item, idx) => {
-          if (item === 'separator') {
-            return <ContextMenuSeparator key={`sep-${idx}`} />;
-          }
-          const Icon = item.icon;
-          return (
-            <ContextMenuItem
-              key={item.id}
-              disabled={item.disabled}
-              variant={item.destructive ? 'destructive' : undefined}
-              onSelect={() => item.onSelect(rowProps)}
-            >
-              {Icon ? <Icon /> : null}
-              {item.label}
-              {item.shortcut ? (
-                <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
-              ) : null}
-            </ContextMenuItem>
-          );
-        })}
-      </ContextMenuContent>
-    </ContextMenu>
-  );
+  return <RowContextMenu rowProps={rowProps} items={items} trigger={trigger} />;
 }
 
 /**

package/src/tools/data/Tree/data/appearance.ts

@@ -6,6 +6,20 @@ export type TreeDensity = 'compact' | 'cozy' | 'comfortable';
 export type TreeAccentIntensity = 'subtle' | 'default' | 'strong';
 export type TreeRadius = 'none' | 'sm' | 'md';
 
+/**
+ * High-level look. Sets sensible defaults for icons / row sizing / the
+ * active indicator; any individual `TreeAppearance` field still overrides.
+ *
+ *  - `'explorer'` (default) — classic file/folder tree: leaf + folder
+ *    icons, fixed single-line rows, VSCode active-bar.
+ *  - `'list'` — macOS-sidebar / chat-history look: no icons (chevron
+ *    only on groups), auto-height rows (multi-line label friendly), quiet
+ *    selection (no active-bar).
+ */
+export type TreeVariant = 'explorer' | 'list';
+
+export type TreeRowSizing = 'fixed' | 'auto';
+
 /**
  * Cosmetic configuration. Every field is optional; missing values fall
  * back to the `cozy` preset (a comfortable VSCode-Explorer-like density).
@@ -38,6 +52,21 @@ export interface TreeAppearance {
    * Mimics the VSCode active-tab indicator. Default: `true`.
    */
   showActiveIndicator?: boolean;
+  /**
+   * High-level look. Default: `'explorer'`. Sets defaults for the three
+   * fields below; pass any of them explicitly to override the variant.
+   */
+  variant?: TreeVariant;
+  /** Hide per-leaf icons (chevron + label only). Variant default. */
+  hideLeafIcons?: boolean;
+  /** Hide folder icons too (chevron stays). Variant default. */
+  hideFolderIcons?: boolean;
+  /**
+   * `'fixed'` — every row is exactly `rowHeight` (single-line explorer).
+   * `'auto'` — `rowHeight` is a *minimum*; rows grow to fit a multi-line
+   * label (title + meta). Variant default.
+   */
+  rowSizing?: TreeRowSizing;
 }
 
 export interface ResolvedAppearance {
@@ -52,6 +81,9 @@ export interface ResolvedAppearance {
   radius: TreeRadius;
   indentGuideOpacity: number;
   showActiveIndicator: boolean;
+  hideLeafIcons: boolean;
+  hideFolderIcons: boolean;
+  rowSizing: TreeRowSizing;
 }
 
 const DENSITY_PRESETS: Record<
@@ -63,6 +95,31 @@ const DENSITY_PRESETS: Record<
   comfortable: { rowHeight: 32, iconSize: 16, fontSize: 14, gap: 8 },
 };
 
+/**
+ * Per-variant defaults for the icon / sizing / indicator fields. The
+ * `'list'` variant is the macOS-sidebar / chat-history look.
+ */
+const VARIANT_DEFAULTS: Record<
+  TreeVariant,
+  Pick<
+    ResolvedAppearance,
+    'hideLeafIcons' | 'hideFolderIcons' | 'rowSizing' | 'showActiveIndicator'
+  >
+> = {
+  explorer: {
+    hideLeafIcons: false,
+    hideFolderIcons: false,
+    rowSizing: 'fixed',
+    showActiveIndicator: true,
+  },
+  list: {
+    hideLeafIcons: true,
+    hideFolderIcons: true,
+    rowSizing: 'auto',
+    showActiveIndicator: false,
+  },
+};
+
 export const DEFAULT_TREE_APPEARANCE: ResolvedAppearance = {
   density: 'cozy',
   ...DENSITY_PRESETS.cozy,
@@ -71,7 +128,7 @@ export const DEFAULT_TREE_APPEARANCE: ResolvedAppearance = {
   accent: 'default',
   radius: 'sm',
   indentGuideOpacity: 0.4,
-  showActiveIndicator: true,
+  ...VARIANT_DEFAULTS.explorer,
 };
 
 /**
@@ -88,6 +145,9 @@ export function resolveAppearance(
 
   const density: TreeDensity = input?.density ?? 'cozy';
   const preset = DENSITY_PRESETS[density];
+  // Variant sets the icon/sizing/indicator defaults; explicit fields win.
+  const variant: TreeVariant = input?.variant ?? 'explorer';
+  const v = VARIANT_DEFAULTS[variant];
 
   return {
     density,
@@ -101,8 +161,10 @@ export function resolveAppearance(
     radius: input?.radius ?? DEFAULT_TREE_APPEARANCE.radius,
     indentGuideOpacity:
       input?.indentGuideOpacity ?? DEFAULT_TREE_APPEARANCE.indentGuideOpacity,
-    showActiveIndicator:
-      input?.showActiveIndicator ?? DEFAULT_TREE_APPEARANCE.showActiveIndicator,
+    showActiveIndicator: input?.showActiveIndicator ?? v.showActiveIndicator,
+    hideLeafIcons: input?.hideLeafIcons ?? v.hideLeafIcons,
+    hideFolderIcons: input?.hideFolderIcons ?? v.hideFolderIcons,
+    rowSizing: input?.rowSizing ?? v.rowSizing,
   };
 }
 

package/src/tools/data/Tree/data/index.ts

@@ -40,4 +40,6 @@ export type {
   TreeDensity,
   TreeAccentIntensity,
   TreeRadius,
+  TreeVariant,
+  TreeRowSizing,
 } from './appearance';

package/src/tools/data/Tree/index.tsx

@@ -101,6 +101,8 @@ export type {
   TreeDensity,
   TreeAccentIntensity,
   TreeRadius,
+  TreeVariant,
+  TreeRowSizing,
 } from './data';
 
 export { DEFAULT_TREE_LABELS } from './types';