@djangocfg/ui-tools 2.1.465 → 2.1.468

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.465",
+  "version": "2.1.468",
   "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.465",
-    "@djangocfg/ui-core": "^2.1.465",
+    "@djangocfg/i18n": "^2.1.468",
+    "@djangocfg/ui-core": "^2.1.468",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -418,9 +418,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.9.4"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.465",
-    "@djangocfg/typescript-config": "^2.1.465",
-    "@djangocfg/ui-core": "^2.1.465",
+    "@djangocfg/i18n": "^2.1.468",
+    "@djangocfg/typescript-config": "^2.1.468",
+    "@djangocfg/ui-core": "^2.1.468",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.9",
     "@types/node": "^25.9.5",

package/src/tools/chat/README.md

@@ -1002,6 +1002,7 @@ const PROMPTS: readonly SuggestedPromptItem[] = [
         onPick={(item) => { setValue(item.prompt); focus(); }}
         hero={<Sparkles className="size-6 text-primary" />}
         title="How can I help?"
+        titleLevel={2}
         description="Pick a starter, or just start typing."
       />
     ),
@@ -1009,7 +1010,10 @@ const PROMPTS: readonly SuggestedPromptItem[] = [
 />
 ```
 
-`renderItem` is an escape hatch for one-off chip styling without forking the component.
+The prompt collection uses native `ul`/`li` semantics while each prompt remains
+a button. `titleLevel` defaults to `2`; set it to `3` or `4` when the empty state
+is nested below an existing section heading. `renderItem` is an escape hatch for
+one-off chip styling without forking the component.
 
 ### 3. Headless
 

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

@@ -41,6 +41,7 @@ import type { ComposerAppearance } from '../composer/types';
 export interface MessageBubbleProps {
   message: ChatMessage;
   isUser?: boolean;
+  /** Show the sender avatar. Defaults to `false` for the flat transcript layout. */
   showAvatar?: boolean;
   /** Override avatar URL (skips persona resolution). */
   avatarSrc?: string;
@@ -158,9 +159,8 @@ const APPEARANCE_CLASSES: Record<ComposerAppearance, {
     avatar: 'size-10',
     avatarFallback: 'text-sm',
     content: 'max-w-[44rem]',
-    // Roomy ChatGPT-style bubble: larger text with generous line-height
-    // and padding so a full-page chat reads spacious, not just bigger.
-    bubble: 'rounded-3xl px-5 py-3.5 text-base leading-relaxed',
+    // Both roles share roomy geometry; their surfaces differ by intensity.
+    bubble: 'text-base leading-relaxed',
     meta: 'text-xs',
   },
 };
@@ -168,7 +168,7 @@ const APPEARANCE_CLASSES: Record<ComposerAppearance, {
 const MessageBubbleInner = ({
   message,
   isUser: isUserProp,
-  showAvatar = true,
+  showAvatar = false,
   avatarSrc,
   avatarFallback,
   user,
@@ -346,6 +346,7 @@ const MessageBubbleInner = ({
               // `select-text` on the prose itself: the text is the only
               // selection island, bounded to this one message.
               'inline-block max-w-full rounded-2xl px-3.5 py-2 text-sm',
+              appearance === 'full' && 'rounded-3xl px-5 py-3.5',
               ap.bubble,
               bubbleSurface,
             )}

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

@@ -0,0 +1,36 @@
+import { memo } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { formatMessageDateLabel } from './messageDate';
+
+export interface MessageDateSeparatorProps {
+  timestamp: number;
+  timeZone: string;
+  locale?: string;
+  now?: number;
+  className?: string;
+}
+
+export const MessageDateSeparator = memo(function MessageDateSeparator({
+  timestamp,
+  timeZone,
+  locale,
+  now,
+  className,
+}: MessageDateSeparatorProps) {
+  const label = formatMessageDateLabel(timestamp, { locale, timeZone, now });
+
+  return (
+    <div
+      role="separator"
+      aria-label={label}
+      className={cn(
+        'flex items-center justify-center px-3 pb-2 pt-5 text-xs font-medium text-muted-foreground',
+        className,
+      )}
+    >
+      <time dateTime={new Date(timestamp).toISOString()}>{label}</time>
+    </div>
+  );
+});

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

@@ -19,6 +19,8 @@ import { useCopy } from '@djangocfg/ui-core/hooks';
 import type { ChatMessage } from '../types';
 import { useChatContextOptional } from '../context';
 import { MessageBubble } from './MessageBubble';
+import { MessageDateSeparator } from './MessageDateSeparator';
+import { formatMessageDateLabel, getCalendarDayKey } from './messageDate';
 import type { ComposerAppearance } from '../composer/types';
 
 export interface MessageListProps {
@@ -69,6 +71,18 @@ export interface MessageListProps {
    * whole bubble up for full-page chat. Default `compact` (no change).
    * Ignored when `renderItem` is set (the host owns bubble rendering). */
   appearance?: ComposerAppearance;
+  /** Show a divider when adjacent messages fall on different calendar days. */
+  showDateSeparators?: boolean;
+  /** Locale used for divider labels. Defaults to the viewer's locale. */
+  dateSeparatorLocale?: string;
+  /**
+   * IANA timezone used for calendar grouping (for example `UTC` or
+   * `Asia/Makassar`). Defaults to the viewer's browser timezone after mount.
+   * Message timestamps remain absolute UTC epoch milliseconds.
+   */
+  dateSeparatorTimeZone?: string;
+  /** Replace the default date divider while retaining day-grouping behavior. */
+  renderDateSeparator?: (timestamp: number, label: string) => ReactNode;
 }
 
 export interface MessageListHandle {
@@ -103,6 +117,10 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
     atBottomThreshold = 120,
     scrollAnchorId,
     appearance = 'compact',
+    showDateSeparators = true,
+    dateSeparatorLocale,
+    dateSeparatorTimeZone,
+    renderDateSeparator,
   },
   ref,
 ) {
@@ -110,6 +128,22 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
   const messages = messagesProp ?? ctx?.messages ?? [];
   const isLoadingMore = isLoadingMoreProp ?? ctx?.isLoadingMore ?? false;
   const { copyToClipboard } = useCopy();
+  // Do not guess the server timezone during SSR. When the host does not pass
+  // one explicitly, resolve it in the browser after mount; this avoids a
+  // hydration mismatch around midnight while still grouping for the viewer.
+  const [browserTimeZone, setBrowserTimeZone] = useState<string | undefined>(dateSeparatorTimeZone);
+  useEffect(() => {
+    if (dateSeparatorTimeZone) {
+      setBrowserTimeZone(dateSeparatorTimeZone);
+      return;
+    }
+    setBrowserTimeZone(Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC');
+  }, [dateSeparatorTimeZone]);
+  const resolvedDateSeparatorTimeZone = dateSeparatorTimeZone ?? browserTimeZone;
+  // Keep relative labels stable for the lifetime of this list. Normal chat
+  // activity remounts/re-renders the shell often enough; more importantly,
+  // one render cannot label adjacent separators against different instants.
+  const dateLabelNow = useMemo(() => Date.now(), []);
 
   const virtuosoRef = useRef<VirtuosoHandle | null>(null);
   // Virtuoso's `atBottomStateChange` only fires when the list is
@@ -210,6 +244,50 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
   );
 
   const itemRenderer = renderItem ?? defaultRenderItem;
+  const renderTranscriptItem = useCallback(
+    (m: ChatMessage, index: number) => {
+      const item = itemRenderer(m, index);
+      if (!showDateSeparators || !resolvedDateSeparatorTimeZone) return item;
+
+      const previous = messages[index - 1];
+      const startsNewDay =
+        !previous ||
+        getCalendarDayKey(previous.createdAt, resolvedDateSeparatorTimeZone) !==
+          getCalendarDayKey(m.createdAt, resolvedDateSeparatorTimeZone);
+
+      if (!startsNewDay) return item;
+
+      const separator = (
+        <MessageDateSeparator
+          timestamp={m.createdAt}
+          timeZone={resolvedDateSeparatorTimeZone}
+          locale={dateSeparatorLocale}
+          now={dateLabelNow}
+        />
+      );
+      const label = formatMessageDateLabel(m.createdAt, {
+        locale: dateSeparatorLocale,
+        timeZone: resolvedDateSeparatorTimeZone,
+        now: dateLabelNow,
+      });
+
+      return (
+        <>
+          {renderDateSeparator ? renderDateSeparator(m.createdAt, label) : separator}
+          {item}
+        </>
+      );
+    },
+    [
+      dateLabelNow,
+      dateSeparatorLocale,
+      itemRenderer,
+      messages,
+      renderDateSeparator,
+      resolvedDateSeparatorTimeZone,
+      showDateSeparators,
+    ],
+  );
   // Jump to bottom on the first non-empty messages batch. A SINGLE rAF +
   // scrollToIndex is not enough when the list mounts with a long transcript
   // (opening / switching a contact): virtuoso measures the dynamic bubble
@@ -242,9 +320,7 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
     // self-cancel.
     const scroller = scrollerRef.current;
     const scrollerEl =
-      scroller != null && scroller !== window && scroller instanceof HTMLElement
-        ? scroller
-        : null;
+      scroller != null && scroller !== window && scroller instanceof HTMLElement ? scroller : null;
     scrollerEl?.addEventListener('wheel', cancelOnUserScroll, { passive: true });
     scrollerEl?.addEventListener('touchstart', cancelOnUserScroll, { passive: true });
     scrollerEl?.addEventListener('keydown', cancelOnUserScroll);
@@ -454,7 +530,7 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
           </div>
         ) : null}
         {messages.map((m, i) => (
-          <div key={m.id ?? i}>{itemRenderer(m, i)}</div>
+          <div key={m.id ?? i}>{renderTranscriptItem(m, i)}</div>
         ))}
         {/* Mirror the virtualized Footer spacer so the last bubble keeps
             its breathing room above the composer in the non-virtual path. */}
@@ -474,7 +550,7 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
       computeItemKey={computeItemKey}
       itemContent={(index, m) => {
         if (!m) return null;
-        const node = itemRenderer(m, index);
+        const node = renderTranscriptItem(m, index);
         // Wrap only the last bubble in a size-observed shell so we can
         // re-pin to the absolute bottom as the streaming reply grows
         // (corrects virtuoso's slight final-chunk under-scroll). The

package/src/tools/chat/messages/__tests__/messageDate.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatMessageDateLabel, getCalendarDayKey } from '../messageDate';
+
+describe('messageDate', () => {
+  it('groups an absolute timestamp by the requested timezone', () => {
+    const timestamp = Date.UTC(2026, 6, 12, 23, 30);
+
+    expect(getCalendarDayKey(timestamp, 'UTC')).toBe('2026-07-12');
+    expect(getCalendarDayKey(timestamp, 'Asia/Makassar')).toBe('2026-07-13');
+  });
+
+  it('formats today and yesterday relative to the display timezone', () => {
+    const now = Date.UTC(2026, 6, 13, 12);
+
+    expect(
+      formatMessageDateLabel(Date.UTC(2026, 6, 13, 1), {
+        locale: 'en-US',
+        timeZone: 'UTC',
+        now,
+      }),
+    ).toBe('Today');
+    expect(
+      formatMessageDateLabel(Date.UTC(2026, 6, 12, 23), {
+        locale: 'en-US',
+        timeZone: 'UTC',
+        now,
+      }),
+    ).toBe('Yesterday');
+  });
+
+  it('includes the year only when the message is outside the current year', () => {
+    const now = Date.UTC(2026, 6, 13, 12);
+
+    expect(
+      formatMessageDateLabel(Date.UTC(2026, 6, 4, 12), {
+        locale: 'en-US',
+        timeZone: 'UTC',
+        now,
+      }),
+    ).toBe('Saturday, July 4');
+    expect(
+      formatMessageDateLabel(Date.UTC(2025, 6, 4, 12), {
+        locale: 'en-US',
+        timeZone: 'UTC',
+        now,
+      }),
+    ).toBe('Friday, July 4, 2025');
+  });
+});

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

@@ -8,6 +8,13 @@ export {
   type MessageListHandle,
 } from './MessageList';
 export { MessageBubble, type MessageBubbleProps } from './MessageBubble';
+export { MessageDateSeparator, type MessageDateSeparatorProps } from './MessageDateSeparator';
+export {
+  formatMessageDateLabel,
+  getCalendarDateParts,
+  getCalendarDayKey,
+  type CalendarDateParts,
+} from './messageDate';
 // 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';

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

@@ -0,0 +1,79 @@
+/**
+ * Calendar helpers for chat timestamps.
+ *
+ * `ChatMessage.createdAt` is an epoch-millisecond value, so it represents an
+ * absolute UTC instant. Calendar grouping is deliberately performed in the
+ * viewer's display timezone: the same instant may belong to Monday in UTC and
+ * Tuesday in Asia/Makassar.
+ */
+
+export interface CalendarDateParts {
+  year: number;
+  month: number;
+  day: number;
+}
+
+export function getCalendarDateParts(timestamp: number, timeZone: string): CalendarDateParts {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).formatToParts(new Date(timestamp));
+
+  const values = Object.fromEntries(
+    parts
+      .filter((part) => part.type === 'year' || part.type === 'month' || part.type === 'day')
+      .map((part) => [part.type, Number(part.value)]),
+  );
+
+  return {
+    year: values.year,
+    month: values.month,
+    day: values.day,
+  };
+}
+
+export function getCalendarDayKey(timestamp: number, timeZone: string): string {
+  const { year, month, day } = getCalendarDateParts(timestamp, timeZone);
+  return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+
+function calendarDayNumber(timestamp: number, timeZone: string): number {
+  const { year, month, day } = getCalendarDateParts(timestamp, timeZone);
+  return Math.floor(Date.UTC(year, month - 1, day) / 86_400_000);
+}
+
+function capitalizeLabel(label: string, locale?: string): string {
+  if (!label) return label;
+  return label[0].toLocaleUpperCase(locale) + label.slice(1);
+}
+
+export function formatMessageDateLabel(
+  timestamp: number,
+  options: {
+    locale?: string;
+    timeZone: string;
+    now?: number;
+  },
+): string {
+  const { locale, timeZone, now = Date.now() } = options;
+  const dayDelta = calendarDayNumber(timestamp, timeZone) - calendarDayNumber(now, timeZone);
+
+  if (dayDelta === 0 || dayDelta === -1) {
+    return capitalizeLabel(
+      new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(dayDelta, 'day'),
+      locale,
+    );
+  }
+
+  const messageYear = getCalendarDateParts(timestamp, timeZone).year;
+  const currentYear = getCalendarDateParts(now, timeZone).year;
+  return new Intl.DateTimeFormat(locale, {
+    timeZone,
+    weekday: 'long',
+    month: 'long',
+    day: 'numeric',
+    ...(messageYear === currentYear ? {} : { year: 'numeric' as const }),
+  }).format(new Date(timestamp));
+}

package/src/tools/chat/shell/SuggestedPrompts.tsx

@@ -30,12 +30,15 @@ export type SuggestedPromptItem = {
 };
 
 export type SuggestedPromptsLayout = 'chips' | 'grid';
+export type SuggestedPromptsTitleLevel = 2 | 3 | 4;
 
 export interface SuggestedPromptsProps {
   items: readonly SuggestedPromptItem[];
   onPick: (item: SuggestedPromptItem) => void;
   /** Optional title above the chips. */
   title?: ReactNode;
+  /** Semantic title level. Defaults to `2`; set it to match the host page outline. */
+  titleLevel?: SuggestedPromptsTitleLevel;
   /** Optional subtitle/description above the chips. */
   description?: ReactNode;
   /** Optional hero element above the title (icon, logo, …). */
@@ -54,6 +57,7 @@ export function SuggestedPrompts({
   items,
   onPick,
   title,
+  titleLevel = 2,
   description,
   hero,
   layout = 'chips',
@@ -62,6 +66,7 @@ export function SuggestedPrompts({
   renderItem,
 }: SuggestedPromptsProps) {
   const hasHeader = hero != null || title != null || description != null;
+  const Title = `h${titleLevel}` as 'h2' | 'h3' | 'h4';
 
   return (
     <section
@@ -78,9 +83,9 @@ export function SuggestedPrompts({
             <div className="text-foreground/90">{hero}</div>
           ) : null}
           {title != null ? (
-            <h3 className="text-base font-semibold text-foreground">
+            <Title className="text-base font-semibold text-foreground">
               {title}
-            </h3>
+            </Title>
           ) : null}
           {description != null ? (
             <p className="max-w-md text-sm leading-snug text-muted-foreground">
@@ -91,35 +96,25 @@ export function SuggestedPrompts({
       ) : null}
 
       {layout === 'grid' ? (
-        <div
-          className="grid w-full max-w-xl grid-cols-1 gap-2 sm:grid-cols-2"
-          role="list"
-        >
-          {items.map((item, idx) =>
-            renderItem ? (
-              <span key={item.id} role="listitem">
-                {renderItem(item, idx)}
-              </span>
-            ) : (
-              <GridCard key={item.id} item={item} onPick={onPick} />
-            ),
-          )}
-        </div>
+        <ul className="m-0 grid w-full max-w-xl list-none grid-cols-1 gap-2 p-0 sm:grid-cols-2">
+          {items.map((item, idx) => (
+            <li key={item.id} className="min-w-0">
+              {renderItem
+                ? renderItem(item, idx)
+                : <GridCard item={item} onPick={onPick} />}
+            </li>
+          ))}
+        </ul>
       ) : (
-        <div
-          className="flex w-full max-w-xl flex-wrap justify-center gap-2"
-          role="list"
-        >
-          {items.map((item, idx) =>
-            renderItem ? (
-              <span key={item.id} role="listitem">
-                {renderItem(item, idx)}
-              </span>
-            ) : (
-              <Chip key={item.id} item={item} onPick={onPick} />
-            ),
-          )}
-        </div>
+        <ul className="m-0 flex w-full max-w-xl list-none flex-wrap justify-center gap-2 p-0">
+          {items.map((item, idx) => (
+            <li key={item.id}>
+              {renderItem
+                ? renderItem(item, idx)
+                : <Chip item={item} onPick={onPick} />}
+            </li>
+          ))}
+        </ul>
       )}
     </section>
   );
@@ -135,7 +130,6 @@ function Chip({
   return (
     <button
       type="button"
-      role="listitem"
       onClick={() => onPick(item)}
       className={cn(
         'inline-flex items-center gap-1.5 rounded-full border border-border',
@@ -166,10 +160,9 @@ function GridCard({
   return (
     <button
       type="button"
-      role="listitem"
       onClick={() => onPick(item)}
       className={cn(
-        'group flex flex-col gap-1 rounded-md border border-border',
+        'group flex h-full w-full flex-col gap-1 rounded-md border border-border',
         'bg-card/60 p-3 text-left',
         'transition-colors duration-150',
         'hover:border-primary/40 hover:bg-card',

package/src/tools/chat/shell/__tests__/SuggestedPrompts.test.tsx

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+
+import { act, createElement, type ComponentProps } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SuggestedPrompts, type SuggestedPromptItem } from '../SuggestedPrompts';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+const items: readonly SuggestedPromptItem[] = [
+  { id: 'one', label: 'First prompt', prompt: 'First prompt' },
+  { id: 'two', label: 'Second prompt', prompt: 'Second prompt' },
+];
+
+describe('SuggestedPrompts', () => {
+  const mounted: Array<ReturnType<typeof createRoot>> = [];
+
+  afterEach(() => {
+    act(() => mounted.splice(0).forEach((root) => root.unmount()));
+  });
+
+  function render(props: Partial<ComponentProps<typeof SuggestedPrompts>> = {}) {
+    const container = document.createElement('div');
+    const root = createRoot(container);
+    mounted.push(root);
+    act(() => {
+      root.render(createElement(SuggestedPrompts, {
+        items,
+        onPick: vi.fn(),
+        title: 'Start here',
+        ...props,
+      }));
+    });
+    return container;
+  }
+
+  it('uses native list semantics without overriding button roles', () => {
+    const container = render();
+    const list = container.querySelector('ul');
+
+    expect(list?.children).toHaveLength(2);
+    expect(Array.from(list?.children ?? []).every((item) => item.tagName === 'LI')).toBe(true);
+    expect(container.querySelectorAll('button[role]')).toHaveLength(0);
+  });
+
+  it('defaults to h2 and lets the host select the outline level', () => {
+    expect(render().querySelector('h2')?.textContent).toBe('Start here');
+    expect(render({ titleLevel: 4 }).querySelector('h4')?.textContent).toBe('Start here');
+  });
+});

package/src/tools/chat/styles/bubbleTokens.ts

@@ -15,10 +15,10 @@
 
 /** Bubble surface classes (background + text), keyed by message state. */
 export const BUBBLE_SURFACE = {
-  /** User-authored bubble — solid brand color. */
-  user: 'bg-primary text-primary-foreground rounded-tr-md',
-  /** Assistant bubble in normal state — neutral muted surface. */
-  assistant: 'bg-muted text-foreground rounded-tl-md',
+  /** User-authored bubble - a quiet neutral surface aligned to the right. */
+  user: 'bg-muted text-foreground',
+  /** Assistant replies use a lighter neutral surface than user messages. */
+  assistant: 'bg-muted/40 text-foreground',
   /** Assistant bubble when the turn failed — destructive tint. */
   error: 'bg-destructive/10 text-destructive rounded-tl-md border border-destructive/30',
 } as const;
@@ -44,23 +44,22 @@ export const BLOCK_SURFACE =
 /**
  * Anchor (link) classes for markdown content rendered inside a bubble.
  *
- * On `bg-primary` the link MUST stay legible against the cyan/brand fill —
- * `text-primary-foreground` matches the bubble's foreground token, so
- * contrast tracks the design system automatically.
+ * User and assistant prose now share neutral surfaces, so both roles use the
+ * theme's primary link color with a restrained underline.
  *
  * On the neutral assistant bubble we keep the brand-primary color so links
  * still pop without competing with the body text.
  */
 export const ANCHOR = {
   user:
-    'text-primary-foreground underline decoration-primary-foreground/60 underline-offset-2 ' +
-    'hover:decoration-primary-foreground transition-colors break-all',
+    'text-primary underline decoration-primary/50 underline-offset-2 ' +
+    'hover:text-primary/80 hover:decoration-primary transition-colors break-all',
   assistant: 'text-primary underline hover:text-primary/80 transition-colors break-all',
 } as const;
 
 /** Inline secondary action (e.g. "Show more / less"). Same logic as anchors. */
 export const TOGGLE = {
-  user: 'text-primary-foreground/80 hover:text-primary-foreground',
+  user: 'text-primary hover:text-primary/80',
   assistant: 'text-primary hover:text-primary/80',
 } as const;
 

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

@@ -20,6 +20,9 @@ We tried popular headless tree engines first. They all leak React-integration bu
 5. **CRUD = adapter, not props.** The host app describes how to delete / rename / move / etc. through a single `TreeAdapter<T>` object. Tree owns the UX (dialogs, hotkeys, menus) and calls back into the adapter. No `onDelete`/`onRename`/... prop sprawl.
 6. **Dialogs come from `<DialogProvider>`.** Tree never re-implements its own dialogs. Built-in CRUD flows resolve `window.dialog` (installed by `@djangocfg/ui-core/lib/dialog-service`). If the host app hasn't mounted it, CRUD flows silently no-op with a dev-mode warning — Tree itself still renders.
 7. **CSS-variable theming.** Density, sizes, gaps, indent — all exposed as `--tree-*` variables on the root. Override in any consumer without re-implementing components.
+8. **Honest empty semantics.** An empty collection is announced as a status and
+   does not expose an invalid, focusable ARIA tree until at least one tree item
+   exists.
 
 ## Layered architecture