@adecore/agents-react 0.24.2 → 0.25.0

package/src/chat/ui/intelligent-ui/renderers/map-view.tsx

@@ -0,0 +1,251 @@
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { useEffect, useRef, useState } from 'react';
+import { Map as MapLibreMap, Marker, setWorkerUrl } from 'maplibre-gl';
+import { Minus, Plus } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { ButtonGroup, IconButton } from '@adecore/ui';
+import { useChatHost, type UiMapSource } from '../../../../host';
+import { baseMapStyle, boundsOf, localizedTextField, MAP_MAX_ZOOM, type MapColors, type MapPoint } from './map-style';
+
+/*
+ * What the view is drawing: `base` by the source's choice, `offline` and `unavailable` as a fallback from tiles that
+ * cannot be had. `failed` is a browser that cannot start the map, `lost` one that took its graphics context back.
+ */
+export type MapViewStatus = 'loading' | 'tiles' | 'base' | 'offline' | 'unavailable' | 'failed' | 'lost';
+
+export interface MapMarker extends MapPoint {
+    number: number;
+}
+
+export interface MapViewProps {
+    markers: readonly MapMarker[];
+    source: UiMapSource;
+    /* The id of the marker drawn as picked. */
+    selected: string | null;
+    /* Called with a marker's id when it is clicked; null where the places cannot be picked. */
+    onPick: ((id: string) => void) | null;
+    onStatus: (status: MapViewStatus) => void;
+}
+
+const MARKER = 'flex size-5 items-center justify-center rounded-full bg-map-marker text-xs text-map-marker-text tabular-nums shadow-raised';
+const PICKED = 'z-1 bg-accent text-accent-text outline-2 outline-surface';
+
+// A tile that fails this many times with none loading in between leaves the map empty, so the outline stands in.
+const TILE_ERRORS_IN_A_ROW = 4;
+
+let workerReady = false;
+
+/* The worker is a file of the package, so the bundler of the app has to serve it: the default address beside the chunk would not exist. */
+function ensureBundledWorker(): void {
+    if (!workerReady) {
+        setWorkerUrl(new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url).href);
+        workerReady = true;
+    }
+}
+
+/* The grounds of the built-in map are theme tokens, which the page resolves; the style needs plain colors. */
+function readColors(element: HTMLElement): MapColors {
+    const style = getComputedStyle(element);
+    return { land: style.getPropertyValue('--map-land').trim() || 'transparent', water: style.getPropertyValue('--map-water').trim() || 'transparent' };
+}
+
+/*
+ * The map itself, in the chunk that holds MapLibre. It draws the host's tiles when the source has them
+ * and the outline of the world otherwise, also when the tiles turn out to be out of reach. Its
+ * canvas is hidden from assistive technology, since the list of places beside it says the same.
+ */
+export function MapView({ markers, source, selected, onPick, onStatus }: MapViewProps) {
+    const { t, i18n } = useTranslation('agent-chat');
+    const mode = useChatHost().code.useMode();
+    const element = useRef<HTMLDivElement>(null);
+    const [map, setMap] = useState<MapLibreMap | null>(null);
+    const [outline, setOutline] = useState(false);
+    const latest = useRef({ source, onStatus, onPick });
+    useEffect(() => {
+        latest.current = { source, onStatus, onPick };
+    });
+    const language = i18n.language.split('-')[0] ?? 'en';
+    const styleKey = `${mode}:${source.state === 'tiles' ? source.styleUrl(mode) : 'outline'}`;
+    const pointsKey = JSON.stringify(markers.map((marker) => [marker.id, marker.lat, marker.lon]));
+
+    useEffect(() => {
+        const container = element.current;
+        if (container === null) {
+            return;
+        }
+        const current = latest.current.source;
+        const colors = readColors(container);
+        const offline = current.state === 'tiles' && typeof navigator !== 'undefined' && navigator.onLine === false;
+        const tiles = current.state === 'tiles' && !offline;
+        let created: MapLibreMap;
+        try {
+            ensureBundledWorker();
+            created = new MapLibreMap({
+                container,
+                style: current.state === 'tiles' && tiles ? current.styleUrl(mode) : baseMapStyle(colors),
+                center: [0, 20],
+                zoom: 1,
+                keyboard: false,
+                cooperativeGestures: true,
+                attributionControl: false,
+                dragRotate: false,
+                pitchWithRotate: false,
+                locale: {
+                    'CooperativeGesturesHandler.WindowsHelpText': t('blocks.map.scrollHint'),
+                    'CooperativeGesturesHandler.MacHelpText': t('blocks.map.scrollHint'),
+                    'CooperativeGesturesHandler.MobileHelpText': t('blocks.map.touchHint')
+                },
+                transformRequest: (url) => {
+                    const now = latest.current.source;
+                    return now.state === 'tiles' && now.transformRequest ? now.transformRequest(url) : { url };
+                }
+            });
+        } catch {
+            latest.current.onStatus('failed');
+            return;
+        }
+        created.touchZoomRotate.disableRotation();
+        const canvas = created.getCanvas();
+        canvas.tabIndex = -1;
+        const wantsTiles = current.state === 'tiles';
+        let drawing: 'tiles' | 'outline' = tiles ? 'tiles' : 'outline';
+        // Why the outline is drawn in place of tiles that were asked for; null while the tiles are.
+        let reason: 'offline' | 'unavailable' | null = wantsTiles && !tiles ? 'offline' : null;
+        let styleLoaded = false;
+        let restoring = false;
+        let tileErrors = 0;
+        setOutline(!tiles);
+        latest.current.onStatus(tiles ? 'loading' : wantsTiles ? 'offline' : 'base');
+
+        const drawOutline = (why: 'offline' | 'unavailable'): void => {
+            if (drawing === 'outline' || !wantsTiles) {
+                return;
+            }
+            drawing = 'outline';
+            reason = why;
+            setOutline(true);
+            created.setStyle(baseMapStyle(colors));
+            latest.current.onStatus(why);
+        };
+        const drawTiles = (): void => {
+            if (current.state !== 'tiles') {
+                return;
+            }
+            drawing = 'tiles';
+            reason = null;
+            styleLoaded = false;
+            restoring = true;
+            tileErrors = 0;
+            setOutline(false);
+            created.setStyle(current.styleUrl(mode));
+            latest.current.onStatus('loading');
+        };
+        const unreachable = (): 'offline' | 'unavailable' => (typeof navigator !== 'undefined' && navigator.onLine === false ? 'offline' : 'unavailable');
+
+        created.on('style.load', () => {
+            if (drawing !== 'tiles') {
+                return;
+            }
+            styleLoaded = true;
+            if (restoring) {
+                restoring = false;
+                latest.current.onStatus('tiles');
+            }
+            const field = current.state === 'tiles' ? current.labelField?.(language) : undefined;
+            if (field === undefined) {
+                return;
+            }
+            for (const layer of created.getStyle().layers) {
+                const textField = layer.type === 'symbol' ? layer.layout?.['text-field'] : undefined;
+                if (textField !== undefined) {
+                    created.setLayoutProperty(layer.id, 'text-field', localizedTextField(textField, field) as never);
+                }
+            }
+        });
+        created.on('load', () => {
+            if (drawing === 'tiles') {
+                latest.current.onStatus('tiles');
+            }
+        });
+        created.on('sourcedata', (event) => {
+            if ('tile' in event) {
+                tileErrors = 0;
+            }
+        });
+        created.on('error', (event) => {
+            if (drawing !== 'tiles') {
+                return;
+            }
+            // Before the style is here there is nothing to draw. After it, a tile the host refuses (a ticket
+            // that ran out) or several in a row leave an empty map; a single one the map retries itself.
+            const status = (event.error as { status?: number } | undefined)?.status;
+            if (!styleLoaded || status === 401 || status === 403 || ++tileErrors >= TILE_ERRORS_IN_A_ROW) {
+                drawOutline(unreachable());
+            }
+        });
+        const goOffline = (): void => drawOutline('offline');
+        const goOnline = (): void => {
+            if (reason === 'offline') {
+                drawTiles();
+            }
+        };
+        const contextLost = (): void => latest.current.onStatus('lost');
+        if (wantsTiles) {
+            window.addEventListener('offline', goOffline);
+            window.addEventListener('online', goOnline);
+        }
+        canvas.addEventListener('webglcontextlost', contextLost);
+        setMap(created);
+        return () => {
+            window.removeEventListener('offline', goOffline);
+            window.removeEventListener('online', goOnline);
+            canvas.removeEventListener('webglcontextlost', contextLost);
+            setMap(null);
+            created.remove();
+        };
+        // The map is made again when the style it draws changes, and not for any other change of the source.
+        // oxlint-disable-next-line react-hooks/exhaustive-deps
+    }, [styleKey, language]);
+
+    useEffect(() => {
+        const bounds = boundsOf(markers);
+        if (map === null || bounds === null) {
+            return;
+        }
+        map.fitBounds(bounds, { padding: 32, maxZoom: outline ? MAP_MAX_ZOOM.outline : MAP_MAX_ZOOM.tiles, duration: 0 });
+        // The points are compared by their coordinates, so a render that rebuilt the same list does not move the map.
+        // oxlint-disable-next-line react-hooks/exhaustive-deps
+    }, [map, pointsKey, outline]);
+
+    const pickable = onPick !== null;
+    useEffect(() => {
+        if (map === null) {
+            return;
+        }
+        const drawn = markers.map((marker) => {
+            const node = document.createElement('div');
+            node.setAttribute('aria-hidden', 'true');
+            node.dataset.mapMarker = marker.id;
+            node.className = `${MARKER} ${marker.id === selected ? PICKED : ''} ${pickable ? 'cursor-pointer' : ''}`;
+            node.textContent = String(marker.number);
+            node.addEventListener('click', () => latest.current.onPick?.(marker.id));
+            return new Marker({ element: node }).setLngLat([marker.lon, marker.lat]).addTo(map);
+        });
+        return () => {
+            for (const marker of drawn) {
+                marker.remove();
+            }
+        };
+        // oxlint-disable-next-line react-hooks/exhaustive-deps
+    }, [map, pointsKey, selected, pickable]);
+
+    return (
+        <div className="absolute inset-0">
+            <div ref={element} aria-hidden className="size-full" />
+            <ButtonGroup className="absolute top-2 right-2 rounded-md border border-border bg-surface-raised shadow-raised">
+                <IconButton icon={Plus} size="sm" label={t('blocks.map.zoomIn')} onClick={() => map?.zoomIn()} />
+                <IconButton icon={Minus} size="sm" label={t('blocks.map.zoomOut')} onClick={() => map?.zoomOut()} />
+            </ButtonGroup>
+        </div>
+    );
+}

package/src/chat/ui/intelligent-ui/renderers/map.tsx

@@ -0,0 +1,226 @@
+import { useId, useState, type ReactNode } from 'react';
+import type { TFunction } from 'i18next';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import type { UiProps, UiViewNode } from '@adecore/intelligent-ui';
+import { Button, LazyBoundary, Spinner } from '@adecore/ui';
+import { useChatHost, type UiMapSource } from '../../../../host';
+import { lazyNamed } from '../../../../lazy';
+import { DiffFallbackBoundary } from '../../diff/DiffFallbackBoundary';
+import { uiChildrenOf, uiNodeLabel } from '../node-text';
+import type { UiPlacePoint, UiRendererProps } from '../render-context';
+import { placePoint } from './place-point';
+import { useInView } from '../use-in-view';
+import { useLater } from '../use-later';
+import { bindingOf, PENDING } from './binding';
+import { useMapSlot } from './map-slots';
+import type { MapMarker, MapViewStatus } from './map-view';
+
+// MapLibre and its stylesheet load with the first map that is drawn, never with the chat.
+const MapView = lazyNamed(() => import('./map-view'), 'MapView');
+
+/* A map that is still loading shows a spinner only once the wait is noticeable. */
+const LOADING_SPINNER_MS = 1000;
+
+interface ListedPlace {
+    node: UiViewNode<UiProps<'Place'>>;
+    name: string;
+    point: UiPlacePoint | null | undefined;
+}
+
+/* The number that ties a row to its marker. The list numbers itself for a screen reader, so the chip is only for the eye. */
+function NumberChip({ number, selected }: { number: number; selected: boolean }) {
+    return (
+        <span
+            aria-hidden
+            className={clsx(
+                'mt-px flex size-5 shrink-0 items-center justify-center rounded-full text-xs tabular-nums',
+                selected ? 'bg-accent text-accent-text' : 'bg-map-marker text-map-marker-text'
+            )}
+        >
+            {number}
+        </span>
+    );
+}
+
+function PlaceRow({ listed, number, selected, onPick }: { listed: ListedPlace; number: number; selected: boolean; onPick: (() => void) | null }) {
+    const { t } = useTranslation('agent-chat');
+    const { detail, address } = listed.node.props;
+    const body = (
+        <>
+            <NumberChip number={number} selected={selected} />
+            <span className="flex min-w-0 grow flex-col gap-0.5">
+                <span className="text-sm wrap-break-word text-text">{listed.name}</span>
+                {detail !== undefined && detail !== '' && <span className="text-xs wrap-break-word text-text-muted">{detail}</span>}
+                {address !== undefined && address !== '' && <span className="text-xs wrap-break-word text-text-faint">{address}</span>}
+                {listed.point === undefined && <span className="text-xs text-text-faint">{t('blocks.map.lookingUp')}</span>}
+                {listed.point === null && <span className="text-xs text-text-faint">{t('blocks.map.notFound')}</span>}
+            </span>
+        </>
+    );
+    const row = 'flex w-full min-h-8 items-start gap-2 rounded-md px-2 py-1.5 text-left';
+    return (
+        <li>
+            {onPick === null ? (
+                <div className={clsx(row, selected && 'bg-surface-hover')}>{body}</div>
+            ) : (
+                <button type="button" aria-pressed={selected} className={clsx(row, 'hover:bg-surface-hover', selected && 'bg-surface-hover')} onClick={onPick}>
+                    {body}
+                </button>
+            )}
+        </li>
+    );
+}
+
+/* Why the map is not the host's: its own reason when the source has none, or what the view found out on the way. */
+function noteFor(t: TFunction<'agent-chat'>, source: UiMapSource | null, status: MapViewStatus): string | null {
+    if (status === 'offline') {
+        return t('blocks.map.offline');
+    }
+    if (status === 'unavailable' || status === 'failed' || status === 'lost') {
+        return t('blocks.map.unavailable');
+    }
+    if (source?.state === 'off') {
+        return t(source.reason === 'disabled' ? 'blocks.map.disabled' : source.reason === 'signed-out' ? 'blocks.map.signedOut' : 'blocks.map.unavailable');
+    }
+    return source?.state === 'tiles' && status === 'tiles' ? (source.attribution ?? null) : null;
+}
+
+interface FrameProps {
+    markers: readonly MapMarker[];
+    /* Null where the host offers no tiles at all, which needs no excuse. */
+    source: UiMapSource | null;
+    selected: string | null;
+    onPick: ((id: string) => void) | null;
+}
+
+/*
+ * The picture of the places and the line under it that says whose tiles these are, or why there are none.
+ * The map is only drawn while the frame is near the viewport and holds one of the page's few map slots
+ * (`MAX_LIVE_MAPS`); one that waits for a slot, or whose graphics context the browser took back, offers a button.
+ */
+function MapFrame({ markers, source, selected, onPick }: FrameProps) {
+    const { t } = useTranslation('agent-chat');
+    const id = useId();
+    const [element, setElement] = useState<HTMLDivElement | null>(null);
+    const [status, setStatus] = useState<MapViewStatus>('loading');
+    const [attempt, setAttempt] = useState(0);
+    const inView = useInView(element);
+    const broken = status === 'failed' || status === 'lost';
+    const slot = useMapSlot(id, inView && !broken);
+    const drawn = slot.state === 'granted' && !broken;
+    const waiting = useLater(drawn && status === 'loading', LOADING_SPINNER_MS);
+    const note = noteFor(t, source, status);
+    const quiet = (text: string, action?: { label: string; run(): void }) => (
+        <div className="grid h-full place-items-center content-center justify-items-center gap-2 p-3 text-center">
+            <p className="text-xs text-text-faint">{text}</p>
+            {action !== undefined && (
+                <Button size="sm" variant="secondary" onClick={action.run}>
+                    {action.label}
+                </Button>
+            )}
+        </div>
+    );
+    const retry = () => {
+        setStatus('loading');
+        setAttempt((previous) => previous + 1);
+    };
+    let body: ReactNode = null;
+    if (status === 'failed') {
+        body = quiet(t('blocks.map.unavailable'));
+    } else if (status === 'lost') {
+        body = quiet(t('blocks.map.contextLost'), { label: t('blocks.map.show'), run: retry });
+    } else if (slot.state === 'queued') {
+        body = quiet(t('blocks.map.waiting'), { label: t('blocks.map.show'), run: slot.take });
+    } else if (drawn) {
+        body = (
+            <DiffFallbackBoundary fallback={quiet(t('blocks.map.unavailable'))} resetKeys={[]}>
+                <LazyBoundary>
+                    <MapView
+                        key={attempt}
+                        markers={markers}
+                        source={source ?? { state: 'off', reason: 'unavailable' }}
+                        selected={selected}
+                        onPick={onPick}
+                        onStatus={setStatus}
+                    />
+                </LazyBoundary>
+            </DiffFallbackBoundary>
+        );
+    }
+    return (
+        <>
+            <div ref={setElement} className="relative h-50 overflow-hidden rounded-lg border border-border bg-surface-sunken @min-[420px]:h-60">
+                {body}
+                {waiting && (
+                    <div className="pointer-events-none absolute inset-0 grid place-items-center">
+                        <Spinner size={16} />
+                    </div>
+                )}
+            </div>
+            {note !== null && <p className="px-0.5 text-xs text-text-faint">{note}</p>}
+        </>
+    );
+}
+
+/* Asks the host for its tiles in a component of its own, since a host that offers none has no hook to call. */
+function HostedFrame({ maps, scopeId, ...frame }: Omit<FrameProps, 'source'> & { maps: NonNullable<ReturnType<typeof useChatHost>['maps']>; scopeId: string }) {
+    return <MapFrame {...frame} source={maps.useSource(scopeId)} />;
+}
+
+/*
+ * The places of a map as a numbered list, which is also the form a screen reader, an offline page and a
+ * map without tiles all rely on. A place that carries a `value` is a button when the map is bound, and
+ * picking it sets the binding. A place the lookup could not place stays in the list without a marker.
+ */
+export function MapRenderer({ node, children, context }: UiRendererProps<UiProps<'Map'>>) {
+    const { t } = useTranslation('agent-chat');
+    const binding = bindingOf(node, context);
+    const current = binding?.value ?? node.props.value;
+    const maps = useChatHost().maps;
+    const places: ListedPlace[] = uiChildrenOf(node, 'Place').map((place) => ({
+        node: place,
+        name: uiNodeLabel(place),
+        point: placePoint(place.props, place.id, context)
+    }));
+    const markers = places.flatMap((listed, index) =>
+        listed.point ? [{ id: listed.node.id, number: index + 1, lat: listed.point.lat, lon: listed.point.lon }] : []
+    );
+    const selectedId = places.find((listed) => listed.node.props.value !== undefined && listed.node.props.value === current)?.node.id ?? null;
+    const pick = (id: string): void => {
+        const value = places.find((listed) => listed.node.id === id)?.node.props.value;
+        if (value !== undefined) {
+            binding?.onValueChange(value);
+        }
+    };
+    const onPick = binding !== null ? pick : null;
+    const frame = maps ? (
+        <HostedFrame maps={maps} scopeId={context.scopeId} markers={markers} selected={selectedId} onPick={onPick} />
+    ) : (
+        <MapFrame markers={markers} source={null} selected={selectedId} onPick={onPick} />
+    );
+    return (
+        <div className={clsx('@container flex flex-col gap-1.5 px-2', !node.complete && PENDING)}>
+            {frame}
+            <ol aria-label={t('blocks.map.label', { count: places.length })} className="flex flex-col">
+                {places.map((listed, index) => {
+                    const { value } = listed.node.props;
+                    return (
+                        <PlaceRow
+                            key={listed.node.id}
+                            listed={listed}
+                            number={index + 1}
+                            selected={value !== undefined && value === current}
+                            onPick={binding !== null && value !== undefined ? () => binding.onValueChange(value) : null}
+                        />
+                    );
+                })}
+            </ol>
+            {node.omitted !== undefined && node.omitted > 0 && (
+                <p className="px-2 text-xs text-text-faint">{t('blocks.map.omitted', { count: node.omitted })}</p>
+            )}
+            {/* A place the catalog refused draws as its text, which is all its node renders. */}
+            <div className="chat-ui-nodes flex flex-col gap-1.5 empty:hidden">{children}</div>
+        </div>
+    );
+}

package/src/chat/ui/intelligent-ui/renderers/place-point.ts

@@ -0,0 +1,16 @@
+import type { UiProps } from '@adecore/intelligent-ui';
+import type { UiPlacePoint, UiRenderContext } from '../render-context';
+
+/*
+ * What the host found for the address of a place wins over the coordinates the agent wrote, which stand
+ * while the lookup is on its way and when it finds nothing. An address alone waits for the host's reading.
+ */
+export function placePoint(props: UiProps<'Place'>, nodeId: string, context: Pick<UiRenderContext, 'place'>): UiPlacePoint | null | undefined {
+    const { lat, lon, address } = props;
+    const written = lat !== undefined && lon !== undefined ? { lat, lon } : undefined;
+    if (address === undefined || address.trim() === '') {
+        return written ?? null;
+    }
+    const found = context.place === undefined ? null : context.place(nodeId, address);
+    return found ?? written ?? found;
+}

package/src/chat/ui/intelligent-ui/renderers/text.tsx

@@ -6,7 +6,7 @@ import type { UiProps } from '@adecore/intelligent-ui';
 import { Icon, Meter, Pill, Spinner } from '@adecore/ui';
 import { formatNumber, formatPercent } from '@adecore/ui/format';
 import { UiHeadContext, type UiRenderContext, type UiRendererProps } from '../render-context';
-import { uiNodeLabel } from '../node-text';
+import { uiEventTime, uiNodeLabel } from '../node-text';
 import { UI_TONE_ICONS, UI_TONE_PILL, UI_TONE_SURFACE, UI_TONE_TEXT } from '../tones';
 
 type StepState = UiProps<'Step'>['state'];
@@ -132,3 +132,30 @@ export function StepRenderer({ node, children, context }: UiRendererProps<UiProp
         </li>
     );
 }
+
+export function TimelineRenderer({ children }: UiRendererProps<UiProps<'Timeline'>>) {
+    return <ol className="chat-ui-nodes flex flex-col px-2">{children}</ol>;
+}
+
+/* Each row draws its own stretch of the line, down to the next dot, so a row that failed to draw leaves the others whole. */
+export function EventRenderer({ node, children }: UiRendererProps<UiProps<'Event'>>) {
+    const { t } = useTranslation('agent-chat');
+    const { at, detail } = node.props;
+    const tone = node.props.tone ?? 'neutral';
+    const time = uiEventTime(at);
+    // A neutral dot says nothing the title does not, and a detail is part of what the row says.
+    const label = [time, uiNodeLabel(node), tone === 'neutral' ? '' : t(`blocks.event.tone.${tone}`), detail ?? ''].filter((part) => part !== '').join(', ');
+    return (
+        <li aria-label={label} className="group/event relative flex min-h-7 gap-3 pb-3 last:pb-0">
+            <span aria-hidden className={clsx('mt-1 size-2 shrink-0 rounded-full bg-current', UI_TONE_TEXT[tone])} />
+            <span aria-hidden className="absolute top-3.5 bottom-0 left-0.75 w-px bg-border group-last/event:hidden" />
+            <div className="flex min-w-0 grow flex-col gap-0.5">
+                <time dateTime={at} className="text-xs text-text-faint tabular-nums">
+                    {time}
+                </time>
+                <div className="text-sm wrap-break-word text-text">{children}</div>
+                {detail !== undefined && detail !== '' && <div className="text-xs wrap-anywhere text-text-faint">{detail}</div>}
+            </div>
+        </li>
+    );
+}

package/src/chat/ui/intelligent-ui/use-in-view.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react';
+
+/*
+ * Whether `element` is near the viewport, with `margin` to spare so it is ready by the time it scrolls in.
+ * Without an observer (a server render, a test) it counts as in view.
+ */
+export function useInView(element: Element | null, margin = '200px'): boolean {
+    const [inView, setInView] = useState(typeof IntersectionObserver === 'undefined');
+    useEffect(() => {
+        if (element === null || typeof IntersectionObserver === 'undefined') {
+            return;
+        }
+        const observer = new IntersectionObserver((entries) => setInView(entries.at(-1)?.isIntersecting ?? false), { rootMargin: margin });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [element, margin]);
+    return inView;
+}

package/src/host.ts

@@ -195,6 +195,30 @@ export interface ReplyAuthor {
     mark?: ReactNode;
 }
 
+/*
+ * Where the tiles of a Map come from. The host owns the service and whatever admits a request to it, so
+ * a chat never knows an address, a key or a vendor: it asks for the style of the theme and lets the host
+ * rewrite every address the map requests. `off` says why there are no tiles, and the map then draws its
+ * built-in outline beside the list of places.
+ */
+export type UiMapSource =
+    | {
+          state: 'tiles';
+          /* The style document of one theme. */
+          styleUrl(theme: 'light' | 'dark'): string;
+          /*
+           * Called for every address the map requests, such as to add a ticket or a header to those of the host's
+           * service. Rewrite only the addresses of your own origin and hand every other back as it came: the style
+           * and the tiles name other hosts too, and a ticket must not travel to them.
+           */
+          transformRequest?(url: string): { url: string; headers?: Record<string, string> };
+          /* The feature property that holds a label in `language` (such as `nl`); without it a label stays as the style writes it. */
+          labelField?(language: string): string;
+          /* The credit the tiles ask for, drawn under the map. */
+          attribution?: string;
+      }
+    | { state: 'off'; reason: 'disabled' | 'signed-out' | 'unavailable' };
+
 /*
  * What the app around the chat decides and the chat cannot, handed to the views by a `ChatHostProvider`.
  * Whatever an app leaves out keeps the default here, which is the chat without that part. One host may
@@ -209,6 +233,10 @@ export interface ChatHost {
         query?(scopeId: string, payload: ChatUiQueryPayload): Promise<ChatUiQueryReading>;
         sendChoice(scopeId: string, payload: ChatUiChoicePayload): Promise<'sent' | 'queued'>;
     };
+    /* The map tiles of a Map block; left out, a map draws its outline and its list of places only. */
+    maps?: {
+        useSource(scopeId: string): UiMapSource;
+    };
     /* The colors an account may wear in the order a picker offers them, the few it shows first, and their names. */
     accents: {
         all: readonly AccentChoice[];

package/src/index.ts

@@ -14,6 +14,7 @@ export {
     type VisualHost,
     type ReplyAuthor,
     type ChatHost,
+    type UiMapSource,
     ChatHostProvider,
     useChatHost,
     type AccentChoice,
@@ -32,18 +33,7 @@ export {
     isConnectionError
 } from './transport';
 export { portTransport, type PortTransport } from './port-transport';
-export {
-    onChatStorageConfiguration,
-    configureChatStorage,
-    chatStorageKey,
-    chatStorageLegacyKeys,
-    chatStorageAdapter,
-    hydrateChatStorage,
-    createChatStore,
-    type ChatStorageRecord,
-    type ChatStorageAdapter,
-    type ChatStorageOptions
-} from './storage';
+export { configureChatStorage, type ChatStorageRecord, type ChatStorageAdapter, type ChatStorageOptions } from './storage';
 export { setLazyPrefetch, onLazyOpenError } from './lazy';
 export { type MountedEntry, MountedRegistry } from './mounted-registry';
 export { type AgentsSettingsSection, PROVIDERS_SECTION, USAGE_SECTION, settingsSection } from './settings/sections';