@djangocfg/ui-tools 2.1.431 → 2.1.432

package/src/common/chips/UrlChip.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+/**
+ * `<UrlChip>` — a compact, clickable "URL chip" (Chrome-omnibox style):
+ * a favicon + the domain with a middle-ellipsised path
+ * (`github.com/wailsapp/…/README.md`), monospace, with the full href on
+ * hover. Opens in a new tab.
+ *
+ * This is the SURFACE-AGNOSTIC, React counterpart of the TipTap composer's
+ * `editorChip` (`kind: 'url'`, see `forms/MarkdownEditor/chip/ChipNode.ts`).
+ * It matches that chip's look pixel-for-pixel using semantic tokens, so a
+ * URL reads identically whether it sits in the composer (being typed) or in
+ * a rendered chat bubble (`MarkdownMessage`'s `urlChipRule`).
+ *
+ * Presentational + self-contained: it imports only the pure URL detector
+ * helpers (`url/detect`) — no TipTap / ProseMirror — so it can render a
+ * known URL anywhere (chat messages, link lists, etc).
+ *
+ * Favicon degradation: the favicon `<img>` falls back to a lucide `Globe`
+ * glyph on `onError` (offline / blocked / unknown host) so the chip never
+ * shows a broken-image marker — mirroring the composer chip's behaviour.
+ */
+
+import { useState } from 'react';
+import { Globe } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+import {
+  splitUrl,
+  truncateUrlLabel,
+  faviconUrl,
+} from '../../tools/forms/MarkdownEditor/url/detect';
+
+export interface UrlChipProps {
+  /** The full, navigable href (`https://…`). */
+  href: string;
+  /**
+   * Approximate max characters for the truncated label. The domain is
+   * always preserved; only the path's middle collapses. Default 40.
+   */
+  maxChars?: number;
+  className?: string;
+}
+
+/**
+ * Render a URL as an inline, clickable chip. Favicon → globe glyph on
+ * favicon load error.
+ */
+export function UrlChip({ href, maxChars = 40, className }: UrlChipProps) {
+  const { host } = splitUrl(href);
+  const favicon = faviconUrl(host);
+  const label = truncateUrlLabel(href, { maxChars });
+
+  // Favicon load failure → swap to the globe glyph. Also covers the empty-
+  // favicon case (unparseable host → faviconUrl returns '').
+  const [imgFailed, setImgFailed] = useState(false);
+  const showGlobe = imgFailed || !favicon;
+
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      title={href}
+      className={cn(
+        // Inline pill matching the composer's `editor-chip--url`: muted
+        // surface + border, monospace, semantic tokens only. `max-w` +
+        // `truncate` (on the label) is the CSS safety net under the
+        // precomputed middle-ellipsis label. No raw blue link styling —
+        // the primary accent only lights up the border on hover + the
+        // globe glyph.
+        'inline-flex max-w-[22rem] items-center gap-1 rounded align-baseline',
+        'border border-border bg-muted px-1.5 py-0.5',
+        'font-mono text-[0.8125em] leading-tight text-foreground no-underline',
+        'cursor-pointer transition-colors hover:border-primary',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        className,
+      )}
+    >
+      <span
+        className={cn(
+          'flex size-3.5 shrink-0 items-center justify-center',
+          showGlobe && 'text-primary',
+        )}
+        aria-hidden="true"
+      >
+        {showGlobe ? (
+          <Globe className="size-3.5" />
+        ) : (
+          <img
+            src={favicon}
+            alt=""
+            width={14}
+            height={14}
+            className="size-3.5 rounded-[2px]"
+            onError={() => setImgFailed(true)}
+          />
+        )}
+      </span>
+      <span className="truncate">{label}</span>
+    </a>
+  );
+}
+
+export default UrlChip;

package/src/common/chips/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Surface-agnostic presentational "chips" — compact inline pills that
+ * render a URL or a file path with a favicon/icon + middle-ellipsis label.
+ *
+ * These match the TipTap composer's `editorChip` look (see
+ * `forms/MarkdownEditor/chip/ChipNode.ts`) but are plain React, so the same
+ * visual is reusable across every surface (composer, chat bubble, lists).
+ *
+ * - `UrlChip`      — clickable URL chip (favicon → globe fallback).
+ * - `FilePathChip` — local file-path chip (re-exported from the editor's
+ *   standalone path chip; it's already presentational/dependency-light, so
+ *   we wrap rather than duplicate).
+ */
+export { UrlChip, default as UrlChipDefault } from './UrlChip';
+export type { UrlChipProps } from './UrlChip';
+
+export {
+  FilePathChip,
+  type FilePathChipProps,
+} from '../../tools/forms/MarkdownEditor/filePath/FilePathChip';

package/src/common/link-preview/LinkPreviewCard.tsx

@@ -0,0 +1,178 @@
+'use client';
+
+/**
+ * LinkPreviewCard — a presentational URL-unfurl card (favicon + og:image +
+ * title / description / site name), Notion / Telegram style.
+ *
+ * It NEVER fetches the page itself — the browser can't read cross-origin
+ * meta tags (CORS). It either renders pre-resolved `data`, or calls the
+ * host-provided `resolver(url)` (a Wails/Go method, a Next.js API route)
+ * once on mount, showing a skeleton until it resolves. A `null` result
+ * (or a thrown resolver) renders nothing.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { LinkPreviewData, ResolveLinkPreview } from './types';
+
+export interface LinkPreviewCardProps {
+  url: string;
+  /** Pre-resolved metadata. When present, no resolver call is made. */
+  data?: LinkPreviewData;
+  /** Host resolver used when `data` is absent. */
+  resolver?: ResolveLinkPreview;
+  /** Layout — `compact` (default) is a tight horizontal card; `full` is a
+   *  roomier card with a larger cover image. */
+  appearance?: 'compact' | 'full';
+  className?: string;
+}
+
+/** Hostname for the fallback site label / favicon. */
+function hostnameOf(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, '');
+  } catch {
+    return url;
+  }
+}
+
+type LoadState =
+  | { status: 'ready'; data: LinkPreviewData }
+  | { status: 'loading' }
+  | { status: 'empty' };
+
+export function LinkPreviewCard({
+  url,
+  data,
+  resolver,
+  appearance = 'compact',
+  className,
+}: LinkPreviewCardProps) {
+  // If data is supplied we're immediately ready; else loading (resolver) or
+  // empty (nothing to do).
+  const [state, setState] = useState<LoadState>(() =>
+    data ? { status: 'ready', data } : resolver ? { status: 'loading' } : { status: 'empty' },
+  );
+
+  // Keep the latest resolver without re-running the effect on identity churn.
+  const resolverRef = useRef(resolver);
+  resolverRef.current = resolver;
+
+  useEffect(() => {
+    if (data) {
+      setState({ status: 'ready', data });
+      return;
+    }
+    const resolve = resolverRef.current;
+    if (!resolve) {
+      setState({ status: 'empty' });
+      return;
+    }
+
+    let alive = true;
+    const controller = new AbortController();
+    setState({ status: 'loading' });
+
+    resolve(url, controller.signal)
+      .then((result) => {
+        if (!alive) return;
+        setState(result ? { status: 'ready', data: result } : { status: 'empty' });
+      })
+      .catch(() => {
+        if (alive) setState({ status: 'empty' });
+      });
+
+    return () => {
+      alive = false;
+      controller.abort();
+    };
+  }, [url, data]);
+
+  if (state.status === 'empty') return null;
+
+  const host = hostnameOf(url);
+
+  // Shared frame — matches the calm media-card surface used elsewhere.
+  const frame = cn(
+    'block w-full overflow-hidden rounded-2xl border border-border bg-card shadow-sm',
+    'transition-colors hover:bg-accent/40',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+    className,
+  );
+
+  if (state.status === 'loading') {
+    return (
+      <div className={cn(frame, 'pointer-events-none')} aria-busy="true">
+        <div className="flex items-center gap-3 p-3">
+          <div className="size-9 shrink-0 animate-pulse rounded-md bg-muted" />
+          <div className="min-w-0 flex-1 space-y-2">
+            <div className="h-3 w-2/3 animate-pulse rounded bg-muted" />
+            <div className="h-2.5 w-1/3 animate-pulse rounded bg-muted" />
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  const meta = state.data;
+  const title = meta.title || host;
+  const siteName = meta.siteName || host;
+  const isFull = appearance === 'full';
+
+  return (
+    <a href={url} target="_blank" rel="noopener noreferrer" className={frame}>
+      {/* Cover image (full appearance, when present) — top banner. */}
+      {isFull && meta.image ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img
+          src={meta.image}
+          alt=""
+          loading="lazy"
+          // Fixed banner height (not just max-h) so `object-cover` actually
+          // crops to fill — with only `max-h` the image keeps its aspect and
+          // letterboxes. `h-44` is a sensible cover banner.
+          className="h-44 w-full border-b border-border object-cover"
+        />
+      ) : null}
+
+      <div className="flex items-stretch gap-3 p-3">
+        <div className="min-w-0 flex-1">
+          {/* Site row — favicon + site name. */}
+          <div className="mb-1 flex items-center gap-1.5 text-xs text-muted-foreground">
+            {meta.favicon ? (
+              // eslint-disable-next-line @next/next/no-img-element
+              <img
+                src={meta.favicon}
+                alt=""
+                loading="lazy"
+                className="size-4 shrink-0 rounded-sm"
+              />
+            ) : null}
+            <span className="truncate">{siteName}</span>
+          </div>
+
+          <div className="line-clamp-2 text-sm font-medium text-foreground">{title}</div>
+
+          {meta.description ? (
+            <div className="mt-1 line-clamp-2 text-xs text-muted-foreground">
+              {meta.description}
+            </div>
+          ) : null}
+        </div>
+
+        {/* Compact thumbnail (compact appearance, when present) — side. */}
+        {!isFull && meta.image ? (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={meta.image}
+            alt=""
+            loading="lazy"
+            className="size-16 shrink-0 self-center rounded-lg object-cover"
+          />
+        ) : null}
+      </div>
+    </a>
+  );
+}

package/src/common/link-preview/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Surface-agnostic link-preview (URL unfurl) primitives.
+ *
+ * `LinkPreviewCard` is a pure presentational card (favicon + og:image +
+ * title / description / site name) that NEVER fetches the page — it renders
+ * pre-resolved `data` or calls a host-provided `resolver(url)`. It is shared
+ * across every surface: the chat `LinkBlock` and the NotionEditor `bookmark`
+ * node both import it and supply their own resolver. No chat coupling.
+ */
+
+export { LinkPreviewCard, type LinkPreviewCardProps } from './LinkPreviewCard';
+export type { LinkPreviewData, ResolveLinkPreview } from './types';

package/src/common/link-preview/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Link-preview (URL unfurl) types — the data contract between the host's
+ * metadata fetcher and the presentational card.
+ *
+ * The browser CANNOT fetch arbitrary URLs to scrape OpenGraph/meta tags
+ * (CORS blocks cross-origin HTML reads), so resolution is ALWAYS a host
+ * concern: a server route (Next.js) or a native backend (Wails/Go). The
+ * UI never fetches — it receives already-resolved metadata, or a resolver
+ * callback the host implements.
+ */
+
+/**
+ * Resolved metadata for one URL — the unfurl result. All fields except
+ * `url` are optional: a card renders from whatever subset is available
+ * (favicon + title is enough; a bare `url` falls back to the hostname).
+ * Plain JSON so it survives history persistence + SSE transport.
+ */
+export interface LinkPreviewData {
+  /** The canonical/resolved URL the card links to. */
+  url: string;
+  /** og:title → twitter:title → <title>. */
+  title?: string;
+  /** og:description → twitter:description → <meta name=description>. */
+  description?: string;
+  /** og:image → twitter:image (absolute URL; host resolves relative ones). */
+  image?: string;
+  /** Favicon URL (host resolves <link rel=icon> / /favicon.ico). */
+  favicon?: string;
+  /** og:site_name → hostname. */
+  siteName?: string;
+}
+
+/**
+ * Host-provided resolver. Given a URL, returns its preview metadata, or
+ * `null` when nothing useful could be fetched (so the card is skipped).
+ * Implementations:
+ *  - Wails/Go desktop → a bound `FetchLinkMetadata(url)` service method.
+ *  - Next.js web → a `/api/unfurl?url=` route.
+ * The host owns caching, SSRF protection, timeouts and bot User-Agents.
+ */
+export type ResolveLinkPreview = (
+  url: string,
+  signal?: AbortSignal,
+) => Promise<LinkPreviewData | null>;

package/src/common/tiptap/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared TipTap helpers — reusable across every NotionEditor block NodeView.
+ *
+ * `useNodeAttrs` is the write-back seam an interactive NodeView uses to push UI
+ * changes (drag a pin, switch a basemap) back into the document's node attrs,
+ * so the change survives the markdown round-trip.
+ */
+
+export { useNodeAttrs } from './useNodeAttrs';
+export type { UseNodeAttrsResult } from './useNodeAttrs';

package/src/common/tiptap/useNodeAttrs.ts

@@ -0,0 +1,128 @@
+'use client';
+
+/**
+ * `useNodeAttrs` — the single write-back seam every interactive block NodeView
+ * uses to persist UI changes back into the document (→ TipTap node attrs →
+ * markdown round-trip).
+ *
+ * A NodeView is normally READ-ONLY: it renders `node.attrs` but has no path to
+ * push a user action (drag a pin, toggle a basemap) back into the node. This
+ * hook wraps TipTap's `updateAttributes` so an interactive component can do:
+ *
+ *   const { attrs, patch } = useNodeAttrs<MapBlockPayload>(props);
+ *   // …on drag-end:
+ *   patch({ markers: nextMarkers });
+ *
+ * and the new attrs land in the document — `getMarkdown()` then serialises the
+ * updated payload.
+ *
+ * ## API
+ *
+ * - `attrs` — `props.node.attrs` typed as `T`. The current committed payload.
+ * - `patch(next)` — commit a partial attr update IMMEDIATELY. `updateAttributes`
+ *   is a single ProseMirror transaction, so this is cheap; use it for DISCRETE
+ *   edits (drag-END, add/remove pin, basemap pick) — which is the recommended
+ *   design: the caller fires `patch` only when a value is final, never per
+ *   drag-frame, so no transaction spam.
+ * - `patchDebounced(next, ms?)` — coalesce HIGH-FREQUENCY updates (a live edit
+ *   firing many times: text input, a continuous slider). Rapid calls collapse
+ *   into one trailing transaction after `ms` of quiet (default 250ms). Pending
+ *   patches are MERGED so partial fields accumulate. Auto-flushes on unmount so
+ *   the last edit is never lost.
+ * - `flush()` — commit any pending debounced patch immediately (e.g. on blur).
+ *
+ * Pure + reusable: no editor-specific coupling, only the `NodeViewProps`
+ * contract (`node`, `updateAttributes`). Node attrs stay plain-JSON
+ * serializable — pass only JSON-safe values through `patch`.
+ */
+
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type { NodeViewProps } from '@tiptap/react';
+
+/** Default debounce window (ms) for `patchDebounced`. */
+const DEFAULT_DEBOUNCE_MS = 250;
+
+export interface UseNodeAttrsResult<T extends Record<string, unknown>> {
+  /** The node's current committed attrs, typed as `T`. */
+  attrs: T;
+  /** Commit a partial attr update immediately (one transaction). */
+  patch: (next: Partial<T>) => void;
+  /**
+   * Commit a partial attr update on a trailing debounce; rapid calls merge
+   * into a single transaction. For live/high-frequency edits.
+   */
+  patchDebounced: (next: Partial<T>, ms?: number) => void;
+  /** Flush any pending debounced patch now (e.g. on blur). */
+  flush: () => void;
+}
+
+/**
+ * Two-way binding between a NodeView's UI and its node attrs.
+ *
+ * @param props The `NodeViewProps` TipTap hands the React NodeView component.
+ */
+export function useNodeAttrs<T extends Record<string, unknown>>(
+  props: NodeViewProps,
+): UseNodeAttrsResult<T> {
+  const { node, updateAttributes } = props;
+  const attrs = node.attrs as T;
+
+  // Keep `updateAttributes` reachable from the debounce timer without making
+  // the debounced callback re-create on every render (it can change identity).
+  const updateRef = useRef(updateAttributes);
+  updateRef.current = updateAttributes;
+
+  // Pending merged patch + its timer, held across renders.
+  const pendingRef = useRef<Partial<T> | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const flush = useCallback(() => {
+    if (timerRef.current != null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    const pending = pendingRef.current;
+    if (pending) {
+      pendingRef.current = null;
+      updateRef.current(pending);
+    }
+  }, []);
+
+  const patch = useCallback(
+    (next: Partial<T>) => {
+      // A discrete edit supersedes any queued debounced patch: merge the
+      // pending fields in, then commit the lot as one transaction.
+      const pending = pendingRef.current;
+      if (timerRef.current != null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      pendingRef.current = null;
+      updateRef.current(pending ? { ...pending, ...next } : next);
+    },
+    [],
+  );
+
+  const patchDebounced = useCallback(
+    (next: Partial<T>, ms: number = DEFAULT_DEBOUNCE_MS) => {
+      // Merge so partial fields accumulate across rapid calls.
+      pendingRef.current = { ...(pendingRef.current ?? {}), ...next };
+      if (timerRef.current != null) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        const pending = pendingRef.current;
+        pendingRef.current = null;
+        if (pending) updateRef.current(pending);
+      }, ms);
+    },
+    [],
+  );
+
+  // Never drop the last edit: flush on unmount.
+  useEffect(() => () => flush(), [flush]);
+
+  return useMemo(
+    () => ({ attrs, patch, patchDebounced, flush }),
+    [attrs, patch, patchDebounced, flush],
+  );
+}

package/src/lib/page-snapshot/react/PageSnapshotChip.tsx

@@ -35,7 +35,7 @@ export function PageSnapshotChip({ className }: PageSnapshotChipProps) {
         className={cn(
           'inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-xs',
           isStale
-            ? 'border-amber-500/40 text-amber-600 dark:text-amber-400'
+            ? 'border-warning-border/40 text-warning'
             : 'border-border text-muted-foreground',
           className,
         )}

package/src/tools/chat/README.md

@@ -48,7 +48,8 @@ export function MyChat() {
 - **Facebook-style unread notifier.** `useChatUnreadNotifier()` prefixes `document.title` with `(N)` and paints a small red dot over the favicon while the tab is in background. Sober by default — the favicon is the attention signal, the title stays readable. Title rotation is available as opt-in (`title: { mode: 'rotate' }`) for hosts without a favicon. Cross-tab coordinated via `useActiveTab` from `@djangocfg/ui-core`: only the elected leader tab mutates title/favicon, the count is broadcast so every tab's FAB badge stays in sync. Pluggable `ChatNotifier` interface lets Wails / Electron hosts route to a native dock badge instead.
 - **Personas.** `config.user` + `config.assistant` for default identity; `message.sender` for per-message overrides.
 - **Audio.** Pass `audio: ChatAudioConfig` (sounds map) to `<ChatLauncher>` — the hook runs internally. Built on `@djangocfg/ui-core/hooks/useNotificationSounds`: Safari unlock, persisted mute, per-event toggles, reduced-motion respect. Slack/Linear-style per-event volume scale (error ≈ 0.25, mention ≈ 1.0). **Built-in sounds bundled as base64 data URLs** in the lazy chat chunk (~136KB) — `audio={{}}` just works. `silenced` + `onSoundEvent` for native hosts (cmdop_go / Tauri).
-- **Rich attachments.** `AttachmentsGrid` for thumbnails, `AttachmentsList` for custom renderers; `onAttachmentOpen` for lightbox.
+- **Rich attachments.** `AttachmentsGrid` for thumbnails, `AttachmentsList` for custom renderers; `onAttachmentOpen` for lightbox. Image tiles open a built-in fullscreen `ImageViewer` lightbox (with prev/next across the message's images) **by default** — no host wiring — and a host `onAttachmentOpen` still overrides.
+- **URL chips in bubbles.** `config.linkChips` (off by default) renders bare `http(s)` URLs in the message markdown bubble as compact favicon chips (`github.com/…/README.md`), matching the composer's URL chip. `[labeled](url)` links stay normal styled links; `www.` hosts are promoted and chipped.
 - **Unified attach pipeline.** Paperclip, `+` menu, drag-drop and ⌘V/Ctrl+V all funnel through one validated path (`useComposerAttach`); set `showAttachmentButton` / `attach` and the composer ships its own picker. Optional `uploadFn` is the only web/Wails seam.
 - **Paste-as-chunk.** A long plain-text paste (over `attach.pasteTextThreshold`, default 2000 chars — ChatGPT/Claude behaviour) becomes a `type:'text'` "Pasted text" attachment chip instead of flooding the textarea. The chip opens a read-only `PastedTextDialog` preview (rendered via `MarkdownMessage`); the exact payload rides in `ChatAttachment.text` to `onSubmit(content, attachments)`. Toggle with `attach.pasteTextAsChunk`.
 - **Tool-payload dispatcher.** `dispatchToolPayload(matchers, fallback)` — pluggable predicates render `<LazyJsonTree>` / `<LazyMap>` / etc.
@@ -537,12 +538,36 @@ function MyError() {
 }
 ```
 
+## URL chips in bubbles — `config.linkChips`
+
+Off by default. When `config.linkChips` is `true`, bare web URLs inside a
+message's **markdown bubble** render as compact `<UrlChip>`s (favicon + domain
++ middle-ellipsis path, e.g. `github.com/wailsapp/…/README.md`) instead of a
+plain blue link — matching the chip the composer shows while you type a URL.
+
+```tsx
+<ChatRoot transport={transport} config={{ linkChips: true }} />
+```
+
+It plugs in via `MessageBubble`: when on, it passes `linkRules={[urlChipRule]}`
+to `MarkdownMessage` (`urlChipRule` is the built-in `LinkRule` from
+`dev/code/MarkdownMessage`). The rule is appended **after** any host-supplied
+`linkRules`, so host rules still win. Scope and behaviour:
+
+- Only **bare** `http(s)` autolinks are chipped (link text === href).
+- `[labeled](url)` links keep their author-chosen text as a normal styled link.
+- `www.` hosts are promoted to `https://www.…` (so GFM autolinks them) and
+  then chipped — matching the composer's autolink whitelist.
+
+The chip is the same surface-agnostic `UrlChip` the composer's chip mirrors —
+see [`common/chips`](../../common/chips/README.md).
+
 ## Message blocks
 
 A message can carry typed, serializable rich content beyond its markdown
 `content`: an optional `blocks: MessageBlock[]`. `MessageBlock` is a
 discriminated union on `kind` — `text`, `markdown`, `audio`, `video`,
-`image`, `gallery`, `map`, `json`, `mermaid`, `code`, `lottie`, plus a
+`image`, `gallery`, `map`, `json`, `mermaid`, `code`, plus a
 `custom` escape hatch. Payloads are plain JSON, so blocks survive history
 persistence and SSE transport.
 
@@ -589,6 +614,55 @@ Exports (`@djangocfg/ui-tools/chat`): `MessageBlocks`,
 `createBlockRegistry`, `BUILTIN_BLOCK_REGISTRY`, and the `MessageBlock` /
 `BlockRegistry` / `BlockRenderer` / `BlockRenderContext` types.
 
+### The `map` block
+
+`MapBlock` wraps the lazy MapLibre renderer. Beyond `center` / `zoom` /
+`routes` / `polygons`, all of its tuning is plain JSON so a map survives
+history persistence and SSE transport:
+
+- **`basemap?: string`** — a built-in style key (`'light'` / `'dark'` /
+  `'streets'` · `'liberty'` / `'bright'` / `'positron'`) or a full
+  style-JSON URL. Omit for the default basemap.
+- **`terrain?: boolean`** — 3D terrain + hillshade (free AWS Terrarium DEM,
+  no key).
+- **`userLocation?: boolean`** — opt in to the toolbar "locate-me" chip
+  (default off). A plain boolean, **not** coordinates — the browser supplies
+  the live position only after the user grants permission; nothing is baked
+  into the block. Needs a secure context (HTTPS / localhost).
+- **per-marker `icon?` / `color?`** — `icon` is an image URL rendered as a
+  rounded thumbnail pin; `color` is a CSS color for the default pin (ignored
+  when `icon` is set).
+- **per-marker `card?`** — an info-card popup opened above the pin on click
+  (Google-Maps style), rendered by the map's default `MarkerCard`. Pure
+  JSON — strings/URLs only:
+
+  ```ts
+  card?: {
+    title: string;
+    description?: string;
+    image?: string;
+    badge?: string;
+    actions?: Array<{ label: string; href?: string }>;  // href-only links
+  }
+  ```
+
+  `actions` are `href`-only links (no `onClick` / `icon` — those can't cross
+  the wire). When a marker has no `card`, clicking it does nothing extra.
+
+```ts
+const map: MapBlock = {
+  kind: 'map', id: 'b3', center: { lat: 52.52, lng: 13.405 }, zoom: 12,
+  basemap: 'dark', terrain: true, userLocation: true,
+  markers: [{
+    id: 'm1', lat: 52.52, lng: 13.405, color: '#22c55e',
+    card: {
+      title: 'Berlin office', description: 'Mitte', badge: 'HQ',
+      actions: [{ label: 'Directions', href: 'https://maps.example/berlin' }],
+    },
+  }],
+};
+```
+
 ## Transport contract
 
 A single I/O seam.
@@ -692,6 +766,18 @@ function — there is no separate `renderHeader` / `renderEmpty` prop and no
 `<Composer>`; it receives `{ composer, config }` — the live composer hook
 plus the same config object. See **[Slots inventory](#slots-inventory)** below.
 
+### Image attachments — default lightbox
+
+When you **don't** wire `messages.onAttachmentOpen` (or a tile's `onClick`),
+image attachments are still clickable: each `AttachmentsGrid` / `AttachmentsList`
+mounts an `ImageLightboxProvider` that renders a single shared `ImageViewer`
+(`LazyImageViewer`) dialog for the group. Clicking an image opens a fullscreen
+gallery with prev/next across **all** the image attachments of that message,
+starting at the clicked index (non-image files are skipped). A host-supplied
+`onAttachmentOpen` / `onClick` always wins (see `useImageTileClick` in
+`messages/Attachments.tsx`), so existing lightbox wiring is unaffected. See the
+[`ImageViewer` docs](../media/ImageViewer/README.md).
+
 ## Composer slot system
 
 `<Composer>` is a single bordered input surface — textarea on top, an