@columenlabs/lumen-ui 0.1.80 → 0.1.82

package/dist/api-fetch.js

@@ -2,10 +2,12 @@
  * One JSON fetch for the assistant, workspaces and joins. A failure throws `ApiError` with the
  * method, address, status and the server's `error` and `code`, so a caller shows what failed and
  * Workers Logs keep it: a server fault (5xx) or a network failure is reported to
- * `/api/client-error` with `where` naming the caller. A 4xx is the server saying why it refused,
+ * `/api/client-error` with `where` naming the caller. Every failure is also a `fetch_fail`
+ * telemetry point (its route with ids folded, status and request id) once `useLumenTelemetry` runs. A 4xx is the server saying why it refused,
  * shown to the person and not logged as a fault.
  */
 import { reportError } from './route-error.js';
+import { apiRoute, reportFailedFetch } from './telemetry.js';
 export class ApiError extends Error {
     method;
     url;
@@ -39,6 +41,7 @@ export async function apiJson(url, init = {}, where = 'api') {
             throw err;
         const e = new ApiError(`Couldn't reach the server (${method} ${url})`, method, url, 0);
         reportError(e, 'shown', where);
+        reportFailedFetch(apiRoute(url), 0);
         throw e;
     }
     const text = await res.text();
@@ -54,6 +57,7 @@ export async function apiJson(url, init = {}, where = 'api') {
         const e = new ApiError(b.error ?? `${method} ${url} answered ${res.status}`, method, url, res.status, b.code);
         if (res.status >= 500)
             reportError(e, 'shown', where);
+        reportFailedFetch(apiRoute(url), res.status, res.headers.get('x-request-id'));
         throw e;
     }
     return body;

package/dist/assistant/copy.d.ts

@@ -0,0 +1,14 @@
+import type { ChatItem } from '@columenlabs/lumen-ui-types/assistant';
+/** The whole chat, its title as the heading. */
+export declare function chatMarkdown(title: string, items: ChatItem[], name: string): string;
+/** One turn: a message and everything the assistant did for it. */
+export declare function turnMarkdown(items: ChatItem[], name: string): string;
+/** Splits a chat into turns: each starts at a message from the person. */
+export declare function chatTurns<T extends {
+    kind: string;
+}>(items: T[]): {
+    from: number;
+    items: T[];
+}[];
+/** Puts Markdown on the clipboard and says so. */
+export declare function copyMarkdown(md: string, what: string): void;

package/dist/assistant/copy.js

@@ -0,0 +1,74 @@
+import { lumenToast } from '../lumen-toast.js';
+/** The whole chat, its title as the heading. */
+export function chatMarkdown(title, items, name) {
+    return [`# ${title || `${name} chat`}`, ...items.map((i) => itemMarkdown(i, 2, name))]
+        .filter(Boolean)
+        .join('\n\n')
+        .concat('\n');
+}
+/** One turn: a message and everything the assistant did for it. */
+export function turnMarkdown(items, name) {
+    return `${items
+        .map((i) => itemMarkdown(i, 2, name))
+        .filter(Boolean)
+        .join('\n\n')}\n`;
+}
+/** Splits a chat into turns: each starts at a message from the person. */
+export function chatTurns(items) {
+    const starts = items.flatMap((x, i) => (x.kind === 'user' || i === 0 ? [i] : []));
+    return starts.map((from, t) => ({
+        from,
+        items: items.slice(from, starts[t + 1] ?? items.length),
+    }));
+}
+/** Puts Markdown on the clipboard and says so. */
+export function copyMarkdown(md, what) {
+    void navigator.clipboard.writeText(md).then(() => lumenToast(`${what} copied as Markdown`), () => lumenToast.error(`Couldn't copy the ${what.toLowerCase()}`));
+}
+const fence = (body) => {
+    const ticks = body.includes('```') ? '````' : '```';
+    return `${ticks}json\n${body}\n${ticks}`;
+};
+function itemMarkdown(i, depth, name) {
+    const h = '#'.repeat(Math.min(depth, 6));
+    switch (i.kind) {
+        case 'user': {
+            const refs = i.refs?.length
+                ? `\n\nPointing at: ${i.refs.map((r) => r.label).join(', ')}`
+                : '';
+            return `${h} You\n\n${i.text}${refs}`;
+        }
+        case 'text':
+            return `${h} ${name}\n\n${i.text}`;
+        case 'step': {
+            const facts = [
+                i.rows !== undefined ? `${i.rows} rows` : '',
+                `${(i.ms / 1000).toFixed(1)} s`,
+                i.write ? i.write.status : '',
+            ].filter(Boolean);
+            return `**${i.ok ? 'Tool' : 'Failed'}: ${i.title}** (${facts.join(', ')})${i.error ? `\n\nError: ${i.error}` : ''}`;
+        }
+        case 'draft':
+            return [
+                `**Card: ${i.title}** (${i.status})`,
+                fence(JSON.stringify(i.args, null, 2)),
+                i.error ? `Error: ${i.error}` : '',
+            ]
+                .filter(Boolean)
+                .join('\n\n');
+        case 'handoff':
+            return [
+                `${h} ${i.label} (${i.why})`,
+                `Task: ${i.task}`,
+                ...i.items.map((x) => itemMarkdown(x, depth + 1, i.label)),
+            ].join('\n\n');
+        case 'advice':
+            return `_${i.error ? 'Could not ask' : 'Asked'} ${i.label} for advice._`;
+        case 'compacted':
+            return '_Compacted._';
+        case 'stopped':
+            return '_Stopped._';
+        case 'error':
+            return `**Error${i.code ? ` (${i.code})` : ''}:** ${i.text}`;
+    }
+}

package/dist/assistant/lumen-assistant.d.ts

@@ -52,8 +52,10 @@ export interface ComposerExtra {
  * triggers list what can follow them as it is typed: `/` at the start a command, `@` a tier for
  * this message, `#` a thing to point at (the `sources`); a picked tier or thing shows as a chip.
  */
-export declare function LumenComposer({ name, busy, queued, disabled, commands, tiers, sources, onSend, onStop, }: {
+export declare function LumenComposer({ name, busy, queued, disabled, commands, tiers, sources, page, onSend, onStop, }: {
     name: string;
+    /** The page's name for `#` This page; the document's title by default. */
+    page?: string;
     busy: boolean;
     queued: string | null;
     disabled?: boolean;

package/dist/assistant/lumen-assistant.js

@@ -1,6 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useQuery, useQueryClient } from '@tanstack/react-query';
-import { ArrowUpIcon, CheckIcon, ChevronRightIcon, CircleAlertIcon, CornerDownRightIcon, LightbulbIcon, PencilIcon, PlusIcon, SparklesIcon, SquareIcon, Undo2Icon, WrenchIcon, XIcon, } from 'lucide-react';
+import { ArrowUpIcon, CheckIcon, ChevronRightIcon, CircleAlertIcon, CopyIcon, CornerDownRightIcon, CrosshairIcon, FileTextIcon, LightbulbIcon, PencilIcon, PlusIcon, SparklesIcon, SquareIcon, Undo2Icon, WrenchIcon, XIcon, } from 'lucide-react';
 import { createContext, useContext, useEffect, useRef, useState } from 'react';
 import Markdown from 'react-markdown';
 import { LumenAssistantButton, LumenAssistantChats, LumenAssistantPanel, assistantOpen, useAssistantHotkey, } from '../assistant-panel.js';
@@ -9,13 +9,15 @@ import { errorText } from '../integrations.js';
 import { cn } from '../lib/utils.js';
 import { LumenSelector, LumenSelectorList, } from '../lumen-selector.js';
 import { lumenToast } from '../lumen-toast.js';
+import { cardsOnScreen, kindName, pointAt, sectionsOnScreen, targetEl, textOf, } from '../spotlight.js';
 import { Alert, AlertDescription } from '../ui/alert.js';
 import { Button } from '../ui/button.js';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../ui/collapsible.js';
 import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover.js';
 import { Spinner } from '../ui/spinner.js';
 import { Textarea } from '../ui/textarea.js';
-import { selectionRef, useComposeRequest, usePageSelection, useShownAssistantSources, } from './sources.js';
+import { chatMarkdown, chatTurns, copyMarkdown, turnMarkdown } from './copy.js';
+import { composeAssistant, selectionRef, useComposeRequest, usePageSelection, useShownAssistantSources, } from './sources.js';
 import { useAssistantChat } from './use-assistant-chat.js';
 /** The main model's context drawn full (tokens); the mark sits where the assistant compacts. */
 const CONTEXT_MAX = 200_000;
@@ -48,6 +50,7 @@ export function LumenAssistant({ client, context, onSettings, keepDays = 30, onC
         enabled: false,
     });
     const s = status.data;
+    const name = s?.name ?? 'Assistant';
     // A finished answer changes the spend and the chats list.
     useEffect(() => {
         if (chat.busy)
@@ -71,6 +74,16 @@ export function LumenAssistant({ client, context, onSettings, keepDays = 30, onC
             about: 'Summarise the chat so far to free up context',
             run: () => '/compact',
         },
+        {
+            name: 'copy',
+            about: 'Copy the last turn as Markdown',
+            run: () => {
+                const last = chatTurns(chat.items).at(-1);
+                if (last)
+                    copyMarkdown(turnMarkdown(last.items, name), 'Turn');
+                return undefined;
+            },
+        },
         {
             name: 'clear',
             about: 'Start a new chat',
@@ -126,7 +139,7 @@ export function LumenAssistant({ client, context, onSettings, keepDays = 30, onC
                             id: c.id,
                             title: c.title,
                             updated_at: new Date(c.at).toISOString(),
-                        })) ?? (chats.isFetched ? [] : null), value: chat.chatId ?? undefined, note: `Chats are kept ${keepDays} days after their last message.`, onRefresh: () => void chats.refetch(), onOpen: (c) => void chat.open(c.id) }), _jsx(IconButton, { icon: PlusIcon, label: "New chat", disabled: !chat.items.length, onClick: chat.reset }), onClose && (_jsx(IconButton, { icon: XIcon, label: `Close ${s?.name ?? 'assistant'}`, onClick: onClose }))] }), _jsx(Messages, { chat: chat, status: s, onSettings: onSettings }), _jsx(LumenComposer, { name: s?.name ?? 'the assistant', busy: chat.busy, queued: chat.queued, disabled: !s || !!s.wait, commands: allCommands, tiers: tiers, sources: allSources, onSend: (text, extra) => chat.send(text, { ...(context ? { context } : {}), ...extra }), onStop: chat.stop }), _jsx(UsageLine, { usage: chat.usage })] }));
+                        })) ?? (chats.isFetched ? [] : null), value: chat.chatId ?? undefined, note: `Chats are kept ${keepDays} days after their last message.`, onRefresh: () => void chats.refetch(), onOpen: (c) => void chat.open(c.id) }), _jsx(IconButton, { icon: CopyIcon, label: "Copy chat", disabled: !chat.items.length, onClick: () => copyMarkdown(chatMarkdown(chat.title, chat.items, name), 'Chat') }), _jsx(IconButton, { icon: PlusIcon, label: "New chat", disabled: !chat.items.length, onClick: chat.reset }), onClose && (_jsx(IconButton, { icon: XIcon, label: `Close ${s?.name ?? 'assistant'}`, onClick: onClose }))] }), _jsx(AssistantName.Provider, { value: name, children: _jsx(Messages, { chat: chat, status: s, onSettings: onSettings }) }), _jsx(LumenComposer, { name: s?.name ?? 'the assistant', busy: chat.busy, queued: chat.queued, disabled: !s || !!s.wait, commands: allCommands, tiers: tiers, sources: allSources, page: context?.label, onSend: (text, extra) => chat.send(text, { ...(context ? { context } : {}), ...extra }), onStop: chat.stop }), _jsx(UsageLine, { usage: chat.usage })] }));
 }
 function Messages({ chat, status, onSettings, }) {
     const end = useRef(null);
@@ -135,7 +148,7 @@ function Messages({ chat, status, onSettings, }) {
     useEffect(() => {
         end.current?.scrollIntoView({ block: 'end' });
     }, [count]);
-    return (_jsxs("div", { className: "min-h-0 flex-1 overflow-y-auto px-3 py-3", children: [status?.wait && (_jsxs(Alert, { className: "mb-3", children: [_jsx(CircleAlertIcon, {}), _jsxs(AlertDescription, { className: "flex flex-col items-start gap-2", children: [WAIT[status.wait](status.admin, status.providers.find((p) => p.id === status.wait_provider)?.label ?? 'API'), onSettings && (_jsx(Button, { size: "sm", variant: "outline", onClick: onSettings, children: "Open Settings" }))] })] })), chat.loading ? (_jsxs("p", { className: "flex items-center gap-2 text-muted-foreground text-sm", children: [_jsx(Spinner, {}), " Loading the chat\u2026"] })) : chat.items.length === 0 && !status?.wait ? (_jsxs("p", { className: "pt-8 text-center text-muted-foreground text-sm", children: ["Ask ", status?.name ?? 'the assistant', " anything."] })) : (_jsx(TierNames.Provider, { value: (id) => status?.tiers.find((t) => t.id === id)?.label ?? id, children: _jsx(UndoWrite.Provider, { value: chat.undo, children: _jsx(Items, { items: chat.items, onSettle: chat.settle, busy: chat.busy }) }) })), chat.busy && !chat.items.some(isLive) && (_jsxs("p", { className: "flex items-center gap-2 py-1 text-muted-foreground text-sm", children: [_jsx(Spinner, {}), " Thinking\u2026"] })), _jsx("div", { ref: end })] }));
+    return (_jsxs("div", { className: "min-h-0 flex-1 overflow-y-auto px-3 py-3", children: [status?.wait && (_jsxs(Alert, { className: "mb-3", children: [_jsx(CircleAlertIcon, {}), _jsxs(AlertDescription, { className: "flex flex-col items-start gap-2", children: [WAIT[status.wait](status.admin, status.providers.find((p) => p.id === status.wait_provider)?.label ?? 'API'), onSettings && (_jsx(Button, { size: "sm", variant: "outline", onClick: onSettings, children: "Open Settings" }))] })] })), chat.loading ? (_jsxs("p", { className: "flex items-center gap-2 text-muted-foreground text-sm", children: [_jsx(Spinner, {}), " Loading the chat\u2026"] })) : chat.items.length === 0 && !status?.wait ? (_jsxs("p", { className: "pt-8 text-center text-muted-foreground text-sm", children: ["Ask ", status?.name ?? 'the assistant', " anything."] })) : (_jsx(TierNames.Provider, { value: (id) => status?.tiers.find((t) => t.id === id)?.label ?? id, children: _jsx(UndoWrite.Provider, { value: chat.undo, children: _jsx(Items, { items: chat.items, onSettle: chat.settle, busy: chat.busy, turns: true }) }) })), chat.busy && !chat.items.some(isLive) && (_jsxs("p", { className: "flex items-center gap-2 py-1 text-muted-foreground text-sm", children: [_jsx(Spinner, {}), " Thinking\u2026"] })), _jsx("div", { ref: end })] }));
 }
 const isLive = (i) => !!i.live || (i.kind === 'handoff' && i.items.some(isLive));
 const WAIT = {
@@ -145,11 +158,19 @@ const WAIT = {
     app_cap: () => "You reached this month's cap on the shared keys. Add your own key, or wait for next month.",
     own_cap: () => 'Your own keys reached their monthly cap. Raise it in Settings ▸ Model providers.',
 };
+/** The assistant's name, for a copied turn's headings. */
+const AssistantName = createContext('Assistant');
 /** A tier's name for a message's `@` chip. */
 const TierNames = createContext((id) => id);
 /** Takes back a change made at once (Undo on its line). */
 const UndoWrite = createContext(null);
-function Items({ items, onSettle, busy, }) {
+function Items({ items, onSettle, busy, turns, }) {
+    const name = useContext(AssistantName);
+    if (turns)
+        return (_jsx("div", { className: "flex flex-col gap-3", children: chatTurns(items).map((t) => {
+                const open = busy && t.from + t.items.length === items.length;
+                return (_jsxs("div", { "data-slot": "assistant-turn", className: "group/turn flex flex-col gap-3", children: [_jsx(Items, { items: t.items, onSettle: onSettle, busy: busy }), !open && (_jsx("div", { className: "-mt-2 flex justify-end opacity-0 transition-opacity group-hover/turn:opacity-100 focus-within:opacity-100 [@media(hover:none)]:opacity-100", children: _jsx(IconButton, { icon: CopyIcon, label: "Copy this turn", className: "size-6 text-muted-foreground", onClick: () => copyMarkdown(turnMarkdown(t.items, name), 'Turn') }) }))] }, t.from));
+            }) }));
     // Cards drafted one after another sit in one stack, so many of them skim as lines.
     const rows = [];
     items.forEach((item, at) => {
@@ -306,7 +327,7 @@ function ComposerChip({ sign, label, onRemove, }) {
  * triggers list what can follow them as it is typed: `/` at the start a command, `@` a tier for
  * this message, `#` a thing to point at (the `sources`); a picked tier or thing shows as a chip.
  */
-export function LumenComposer({ name, busy, queued, disabled, commands = [], tiers = [], sources = [], onSend, onStop, }) {
+export function LumenComposer({ name, busy, queued, disabled, commands = [], tiers = [], sources = [], page, onSend, onStop, }) {
     const [text, setText] = useState('');
     const [caret, setCaret] = useState(0);
     const [closed, setClosed] = useState(null);
@@ -340,11 +361,7 @@ export function LumenComposer({ name, busy, queued, disabled, commands = [], tie
     const asked = word?.[3] ?? '';
     const open = closed !== `${text}|${caret}`;
     const slash = m && commands.length ? (m[2] === undefined ? 'command' : cmd?.options ? 'arg' : null) : null;
-    const at = trigger === '@' && tiers.length > 1
-        ? '@'
-        : trigger === '#' && (sources.length || selection)
-            ? '#'
-            : null;
+    const at = trigger === '@' && tiers.length > 1 ? '@' : trigger === '#' ? '#' : null;
     const picking = open ? (slash ?? at) : null;
     const extra = () => ({
         ...(tier ? { tier } : {}),
@@ -404,10 +421,70 @@ export function LumenComposer({ name, busy, queued, disabled, commands = [], tie
             box.current?.setSelectionRange(start, start);
         });
     };
+    // Each `#` row makes its chip when picked, so what it carries (a card's words) is read then.
     const sourceItems = new Map();
     const picked = selection ? selectionRef(selection) : null;
+    const added = (r) => refs.some((x) => sameRef(x, r)) ? { disabled: 'Added' } : {};
+    const onPage = [];
+    if (picking === '#') {
+        const pageRef = () => ({
+            kind: 'page',
+            label: page || document.title || 'This page',
+            path: location.pathname + location.search,
+            text: textOf(document.querySelector('main') ?? document.body, 6000),
+        });
+        sourceItems.set('page', pageRef);
+        onPage.push({
+            value: 'page',
+            label: 'This page',
+            group: 'On this page',
+            icon: FileTextIcon,
+            detail: page || document.title,
+            keywords: ['screen', 'page'],
+            ...added({ kind: 'page', label: page || document.title || 'This page' }),
+        });
+        for (const c of cardsOnScreen()) {
+            const label = c.title || kindName(c.kind);
+            const ref = { kind: 'card', label, id: c.id };
+            sourceItems.set(`card:${c.id}`, () => ({
+                ...ref,
+                card_kind: kindName(c.kind),
+                text: textOf(targetEl(`card:${c.id}`)),
+            }));
+            onPage.push({
+                value: `card:${c.id}`,
+                label,
+                group: 'On this page',
+                detail: kindName(c.kind),
+                target: `card:${c.id}`,
+                ...added(ref),
+            });
+        }
+        for (const x of sectionsOnScreen().slice(0, 60)) {
+            const ref = { kind: x.kind, label: x.label, id: x.id };
+            sourceItems.set(`section:${x.id}`, () => ({
+                ...ref,
+                text: textOf(targetEl(`section:${x.id}`)),
+            }));
+            onPage.push({
+                value: `section:${x.id}`,
+                label: x.label,
+                group: 'On this page',
+                detail: x.kind,
+                target: `section:${x.id}`,
+                ...added(ref),
+            });
+        }
+        onPage.push({
+            value: 'point',
+            label: 'Point at something…',
+            group: 'On this page',
+            icon: CrosshairIcon,
+            description: 'Click a card or a part of the page; Esc cancels',
+        });
+    }
     if (picked)
-        sourceItems.set('selection', picked);
+        sourceItems.set('selection', () => picked);
     const sourceOptions = picking === '#'
         ? [
             ...(picked
@@ -417,13 +494,14 @@ export function LumenComposer({ name, busy, queued, disabled, commands = [], tie
                         label: picked.label,
                         group: 'Selected text',
                         ...(selection?.where ? { detail: selection.where } : {}),
-                        ...(refs.some((r) => sameRef(r, picked)) ? { disabled: 'Added' } : {}),
+                        ...added(picked),
                     },
                 ]
                 : []),
+            ...onPage,
             ...sources.flatMap((s) => s.items(asked).map((i) => {
                 const value = `${s.id}:${i.id}`;
-                sourceItems.set(value, i.ref);
+                sourceItems.set(value, () => i.ref);
                 return {
                     value,
                     label: i.label,
@@ -432,17 +510,31 @@ export function LumenComposer({ name, busy, queued, disabled, commands = [], tie
                     ...(s.icon ? { icon: s.icon } : {}),
                     ...(i.keywords ? { keywords: i.keywords } : {}),
                     ...(i.target ? { target: i.target } : {}),
-                    ...(refs.some((r) => sameRef(r, i.ref)) ? { disabled: 'Added' } : {}),
+                    ...added(i.ref),
                 };
             })),
         ]
         : [];
+    // Point at…: on a phone the sheet covers the page, so it steps aside while the person picks and
+    // comes back with the pick as a chip and the words typed so far.
+    const point = async () => {
+        const phone = window.matchMedia('(max-width: 767px)').matches;
+        const typed = text.slice(0, caret - 1 - asked.length) + text.slice(caret).replace(/^ /, '');
+        if (phone)
+            assistantOpen.write(false);
+        const p = await pointAt();
+        if (phone)
+            composeAssistant({
+                text: typed,
+                refs: [...refs, ...(p ? [pointedRef(p)] : [])],
+                ...(tier ? { tier } : {}),
+            });
+        else if (p)
+            setRefs((prev) => [...prev, pointedRef(p)]);
+        requestAnimationFrame(() => box.current?.focus());
+    };
     const tierLabel = tiers.find((t) => t.id === tier)?.label;
-    const hints = [
-        commands.length && '/',
-        tiers.length > 1 && '@',
-        (sources.length || selection) && '#',
-    ].filter(Boolean);
+    const hints = [commands.length && '/', tiers.length > 1 && '@', '#'].filter(Boolean);
     return (_jsxs("div", { className: "shrink-0 border-t p-3", children: [queued && (_jsxs("p", { className: "mb-2 truncate text-muted-foreground text-xs", children: ["Queued: ", _jsx("span", { className: "text-foreground", children: queued })] })), picking === 'command' && (_jsx(LumenSelectorList, { handle: list, label: "Commands", className: "mb-2", fuzzy: true, query: m?.[1] ?? '', options: commands.map((c) => ({
                     value: c.name,
                     label: `/${c.name}`,
@@ -456,10 +548,14 @@ export function LumenComposer({ name, busy, queued, disabled, commands = [], tie
                     setTier(o.value);
                     dropWord();
                 }, onClose: () => setClosed(`${text}|${caret}`) })), picking === '#' && (_jsx(LumenSelectorList, { handle: list, label: "Point at", className: "mb-2", query: asked, options: sourceOptions, empty: "Nothing matches", onPick: (o) => {
-                    const r = sourceItems.get(o.value);
+                    dropWord();
+                    if (o.value === 'point') {
+                        void point();
+                        return;
+                    }
+                    const r = sourceItems.get(o.value)?.();
                     if (r)
                         setRefs((p) => [...p, r]);
-                    dropWord();
                 }, onClose: () => setClosed(`${text}|${caret}`) })), (tierLabel || refs.length > 0) && (_jsxs("div", { className: "mb-2 flex flex-wrap gap-1", children: [tierLabel && _jsx(ComposerChip, { sign: "@", label: tierLabel, onRemove: () => setTier(null) }), refs.map((r, i) => (_jsx(ComposerChip, { sign: "#", label: r.label, onRemove: () => setRefs((p) => p.filter((_, j) => j !== i)) }, `${r.kind}:${r.label}:${i}`)))] })), _jsxs("div", { className: "relative", children: [_jsx(Textarea, { ref: box, "aria-label": `Message ${name}`, placeholder: `Ask ${name}…${hints.length ? ` (${hints.join(' ')})` : ''}`, className: "max-h-48 min-h-11 resize-none pr-11", value: text, disabled: disabled, onChange: (e) => {
                             setText(e.target.value);
                             setCaret(e.target.selectionStart);
@@ -472,7 +568,21 @@ export function LumenComposer({ name, busy, queued, disabled, commands = [], tie
                             }
                         } }), _jsx("div", { className: "absolute right-1.5 bottom-1.5", children: busy && !text.trim() ? (_jsx(IconButton, { icon: SquareIcon, label: "Stop", variant: "outline", size: "icon-xs", onClick: onStop })) : (_jsx(IconButton, { icon: ArrowUpIcon, label: busy ? 'Queue' : 'Send', variant: "default", size: "icon-xs", disabled: !text.trim() || disabled, onClick: send })) })] })] }));
 }
-const sameRef = (a, b) => a.kind === b.kind && JSON.stringify(a) === JSON.stringify(b);
+// The same thing pointed at twice: its kind and what finds it, whatever its words read then.
+const refKey = (r) => r.kind === 'page'
+    ? 'page'
+    : JSON.stringify([r.kind, r.id ?? r.label, r.kind === 'selection' ? r.text : null]);
+const sameRef = (a, b) => refKey(a) === refKey(b);
+/** A card or section the person pointed at, as a chip with its words. */
+const pointedRef = (p) => p.kind === 'card'
+    ? {
+        kind: 'card',
+        label: p.card.title || kindName(p.card.kind),
+        id: p.card.id,
+        card_kind: kindName(p.card.kind),
+        text: textOf(p.el),
+    }
+    : { kind: p.section.kind, label: p.section.label, id: p.section.id, text: textOf(p.el) };
 /** The chat's cost and tokens (a popup splits them per part), and how full the context is. */
 function UsageLine({ usage }) {
     if (!usage || !usage.calls)

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { LumenViewCard, type LumenViewCardProps } from './lumen-view-card.js';
 export { LumenSelector, LumenSelectorList, type LumenSelectorListHandle, type LumenSelectorProps, type LumenOption, type LumenOptionGroup, SelectorRowContent, } from './lumen-selector.js';
 export { ColorChip, ColorDot, colorIcon } from './color-dot.js';
 export { EditCell, EditInputCell } from './view-edit-cell.js';
-export { type CardOnScreen, cardsOnScreen, kindName, onScreen, pointAtCard, spotlight, } from './spotlight.js';
+export { type CardOnScreen, cardsOnScreen, kindName, onScreen, pointAt, pointAtCard, type PointedAt, type SectionOnScreen, sectionsOnScreen, spotlight, targetEl, textOf, } from './spotlight.js';
 export { LinkDot, LinkPicker, type LinkColor, linkVar } from './lumen-links.js';
 export { CardSegments, CardSwitch } from './card-switch.js';
 export { PageInput, PageInputs } from './page-inputs.js';
@@ -52,6 +52,7 @@ export { ConnectionBlock, ErrorLine, IntegrationRow, KeyTestLine, type KeyTestRe
 export { LumenExpandList, LumenExpandRow } from './expand-list.js';
 export { LumenPager } from './pager.js';
 export { createDeskQueryClient } from './query-client.js';
+export { type ClientPoint, type ClientPointKind, type LumenTelemetryOptions, apiRoute, reportClient, reportClientError, reportFailedFetch, stackFingerprint, useLumenTelemetry, } from './telemetry.js';
 export { refreshHeaders, withRefreshToken } from './refresh.js';
 export { type LumenLoad, LumenError, LumenLazy, LumenLoadFooter, LumenLoadTime, LumenProgress, LumenRefresh, LumenSkeleton, LumenStates, marketTrades, useLumenLoad, useLumenSource, useLiveLoad, } from './lumen-source.js';
 export { LumenBoundary } from './lumen-boundary.js';

package/dist/index.js

@@ -11,7 +11,7 @@ export { LumenViewCard } from './lumen-view-card.js';
 export { LumenSelector, LumenSelectorList, SelectorRowContent, } from './lumen-selector.js';
 export { ColorChip, ColorDot, colorIcon } from './color-dot.js';
 export { EditCell, EditInputCell } from './view-edit-cell.js';
-export { cardsOnScreen, kindName, onScreen, pointAtCard, spotlight, } from './spotlight.js';
+export { cardsOnScreen, kindName, onScreen, pointAt, pointAtCard, sectionsOnScreen, spotlight, targetEl, textOf, } from './spotlight.js';
 export { LinkDot, LinkPicker, linkVar } from './lumen-links.js';
 export { CardSegments, CardSwitch } from './card-switch.js';
 export { PageInput, PageInputs } from './page-inputs.js';
@@ -59,6 +59,7 @@ export { ConnectionBlock, ErrorLine, IntegrationRow, KeyTestLine, TestBadge, err
 export { LumenExpandList, LumenExpandRow } from './expand-list.js';
 export { LumenPager } from './pager.js';
 export { createDeskQueryClient } from './query-client.js';
+export { apiRoute, reportClient, reportClientError, reportFailedFetch, stackFingerprint, useLumenTelemetry, } from './telemetry.js';
 export { refreshHeaders, withRefreshToken } from './refresh.js';
 export { LumenError, LumenLazy, LumenLoadFooter, LumenLoadTime, LumenProgress, LumenRefresh, LumenSkeleton, LumenStates, marketTrades, useLumenLoad, useLumenSource, useLiveLoad, } from './lumen-source.js';
 export { LumenBoundary } from './lumen-boundary.js';

package/dist/route-error.js

@@ -16,6 +16,7 @@ import { useRouter } from '@tanstack/react-router';
 import { ChevronRight, RefreshCw, RotateCcw, TriangleAlert } from 'lucide-react';
 import { useEffect, useState } from 'react';
 import { toast } from 'sonner';
+import { reportClientError } from './telemetry.js';
 import { Button } from './ui/button.js';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from './ui/collapsible.js';
 import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from './ui/empty.js';
@@ -166,6 +167,7 @@ export function reportError(error, outcome, where) {
     if (Date.now() - (sent.get(key) ?? 0) < GAP_MS)
         return;
     sent.set(key, Date.now());
+    reportClientError(err);
     const body = JSON.stringify({
         message: err.message.slice(0, 500),
         stack: (err.stack ?? '').slice(0, 2000),

package/dist/spotlight.d.ts

@@ -4,14 +4,29 @@ export interface CardOnScreen {
     /** `view` for a table card, else the widget's kind (chart, tiles, ...). */
     kind: string;
 }
+export interface SectionOnScreen {
+    /** `data-assistant-id`, else its name. */
+    id: string;
+    /** `data-assistant-section`: what the person calls it. */
+    label: string;
+    /** `data-assistant-kind`: what it is (role, story), `section` by default. */
+    kind: string;
+}
+export declare const sectionOf: (el: HTMLElement) => SectionOnScreen;
+/** The marked sections on the page now, top to bottom (the assistant's own are left out). */
+export declare const sectionsOnScreen: () => SectionOnScreen[];
+/** An element's text as the model reads it: its words, cut to `max` characters. */
+export declare const textOf: (el: Element | null, max?: number) => string;
+/** The element a `card:<id>` or `section:<id>` target stands for. */
+export declare const targetEl: (target: string) => HTMLElement | null;
 export declare const cardOf: (el: HTMLElement) => CardOnScreen;
 /** The cards on the page now, top to bottom. */
 export declare const cardsOnScreen: () => CardOnScreen[];
 /** Where a target is on screen now: a card on the page, a sidebar page, or neither. */
-export declare function onScreen(target: string | null | undefined): 'card' | 'nav' | null;
+export declare function onScreen(target: string | null | undefined): 'card' | 'section' | 'nav' | null;
 /**
- * Lights one target (`card:<id>` or an app path) and dims the page around it; null clears. The
- * target scrolls into view only after a short hover.
+ * Lights one target (`card:<id>`, `section:<id>` or an app path) and dims the page around it; null
+ * clears. The target scrolls into view only after a short hover.
  */
 export declare function spotlight(target: string | null | undefined, name?: string): void;
 /**
@@ -19,5 +34,20 @@ export declare function spotlight(target: string | null | undefined, name?: stri
  * name; a click picks it, Esc or a click off any card cancels.
  */
 export declare function pointAtCard(): Promise<CardOnScreen | null>;
+/** What `pointAt` picked: a card, or a section an app marked. */
+export type PointedAt = {
+    kind: 'card';
+    card: CardOnScreen;
+    el: HTMLElement;
+} | {
+    kind: 'section';
+    section: SectionOnScreen;
+    el: HTMLElement;
+};
+/**
+ * Point at a card or a marked section: the one under the cursor lights up with its name, the
+ * innermost when they nest; a click picks it, Esc or a click off any cancels.
+ */
+export declare const pointAt: () => Promise<PointedAt | null>;
 /** A card's style (`kind:style`) as a person says it: a table, a donut, a page's own card. */
 export declare function kindName(styleId: string): string;

package/dist/spotlight.js

@@ -5,10 +5,37 @@
 //                            sidebar page gets the sidebar's muted fill. No border, no glow.
 //   pointAtCard()            the cards dim, the one under the cursor lights up; a click picks it,
 //                            Esc cancels. Works on any LumenLayout card with no per-page setup.
+//   pointAt()                the same over cards and page sections: any element an app marks
+//                            `data-assistant-section="<name>"` (a résumé role, a story, a job),
+//                            with `data-assistant-kind` (what it is) and `data-assistant-id`.
+//                            A section's target is `section:<id>`; lit, it gets a muted fill.
 //
 // Both drive the DOM directly through data attributes the theme styles: one spotlight at a time.
 import { WIDGET_STYLES } from '@columenlabs/lumen-ui-types/views';
 const CARD = '[data-slot="lumen-card"][data-card]';
+const SECTION = '[data-assistant-section]';
+const sectionId = (el) => el.dataset.assistantId || el.dataset.assistantSection || '';
+const sectionEl = (id) => [...document.querySelectorAll(SECTION)].find((el) => sectionId(el) === id) ?? null;
+export const sectionOf = (el) => ({
+    id: sectionId(el),
+    label: el.dataset.assistantSection ?? '',
+    kind: el.dataset.assistantKind || 'section',
+});
+/** The marked sections on the page now, top to bottom (the assistant's own are left out). */
+export const sectionsOnScreen = () => [...document.querySelectorAll(SECTION)]
+    .filter((el) => !el.closest('[data-assistant]'))
+    .map(sectionOf);
+/** An element's text as the model reads it: its words, cut to `max` characters. */
+export const textOf = (el, max = 3000) => (el?.innerText ?? '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+    .slice(0, max);
+/** The element a `card:<id>` or `section:<id>` target stands for. */
+export const targetEl = (target) => target.startsWith('card:')
+    ? cardEl(target.slice(5))
+    : target.startsWith('section:')
+        ? sectionEl(target.slice(8))
+        : null;
 const cardEl = (id) => document.querySelector(`${CARD.slice(0, -1)}="${CSS.escape(id)}"]`);
 const navEl = (path) => [...document.querySelectorAll('[data-sidebar="sidebar"] a[href]')].find((a) => new URL(a.href).pathname.replace(/\/$/, '').endsWith(path.replace(/\/$/, ''))) ?? null;
 export const cardOf = (el) => ({
@@ -31,20 +58,20 @@ function clear() {
     tag?.remove();
     tag = null;
 }
-function light(el, name, nav) {
+function light(el, name, mode) {
     if (lit !== el) {
         if (lit)
             delete lit.dataset.spotlit;
         lit = el;
         el.dataset.spotlit = '';
     }
-    if (nav) {
+    if (mode === 'nav') {
         document.body.dataset.spotlight = 'nav';
         tag?.remove();
         tag = null;
         return;
     }
-    document.body.dataset.spotlight = 'card';
+    document.body.dataset.spotlight = mode;
     if (!name)
         return;
     tag ??= document.body.appendChild(document.createElement('div'));
@@ -60,42 +87,68 @@ export function onScreen(target) {
         return null;
     if (target.startsWith('card:'))
         return cardEl(target.slice(5)) ? 'card' : null;
+    if (target.startsWith('section:'))
+        return sectionEl(target.slice(8)) ? 'section' : null;
     return navEl(target) ? 'nav' : null;
 }
 /**
- * Lights one target (`card:<id>` or an app path) and dims the page around it; null clears. The
- * target scrolls into view only after a short hover.
+ * Lights one target (`card:<id>`, `section:<id>` or an app path) and dims the page around it; null
+ * clears. The target scrolls into view only after a short hover.
  */
 export function spotlight(target, name) {
     if (!target)
         return clear();
-    const card = target.startsWith('card:');
-    const el = card ? cardEl(target.slice(5)) : navEl(target);
+    const mode = target.startsWith('card:')
+        ? 'card'
+        : target.startsWith('section:')
+            ? 'section'
+            : 'nav';
+    const el = mode === 'nav' ? navEl(target) : targetEl(target);
     if (!el)
         return clear();
-    light(el, name, !card);
+    light(el, name, mode);
     clearTimeout(scrollTimer);
     scrollTimer = setTimeout(() => {
         const r = el.getBoundingClientRect();
         if (r.bottom < 0 || r.top > window.innerHeight)
             el.scrollIntoView({ block: 'center', behavior: 'smooth' });
-        if (card && name)
-            light(el, name, false);
+        if (mode !== 'nav' && name)
+            light(el, name, mode);
     }, 600);
 }
 /**
  * Point at the page: the cards dim and the one under the cursor (or finger) lights up with its
  * name; a click picks it, Esc or a click off any card cancels.
  */
-export function pointAtCard() {
+export async function pointAtCard() {
+    const picked = await pick(CARD);
+    return picked?.kind === 'card' ? picked.card : null;
+}
+/**
+ * Point at a card or a marked section: the one under the cursor lights up with its name, the
+ * innermost when they nest; a click picks it, Esc or a click off any cancels.
+ */
+export const pointAt = () => pick(`${SECTION}, ${CARD}`);
+function pick(selector) {
     clear();
     document.body.dataset.pointing = '';
     return new Promise((done) => {
-        const under = (e) => e.target?.closest?.(CARD) ?? null;
+        const under = (e) => {
+            const el = e.target?.closest?.(selector) ?? null;
+            return el?.closest('[data-assistant]') ? null : el;
+        };
+        const what = (el) => el.matches(CARD)
+            ? { kind: 'card', card: cardOf(el), el }
+            : { kind: 'section', section: sectionOf(el), el };
         const move = (e) => {
             const el = under(e);
-            if (el)
-                light(el, `${el.dataset.cardTitle ?? ''} · ${kindName(cardOf(el).kind)}`, false);
+            if (el) {
+                const p = what(el);
+                if (p.kind === 'card')
+                    light(el, `${p.card.title} · ${kindName(p.card.kind)}`, 'card');
+                else
+                    light(el, p.section.label, 'section');
+            }
             else if (lit) {
                 delete lit.dataset.spotlit;
                 lit = null;
@@ -115,7 +168,7 @@ export function pointAtCard() {
             e.preventDefault();
             e.stopPropagation();
             const el = under(e);
-            end(el ? cardOf(el) : null);
+            end(el ? what(el) : null);
         };
         const key = (e) => {
             if (e.key !== 'Escape')

package/dist/telemetry.d.ts

@@ -0,0 +1,40 @@
+export type ClientPointKind = 'view' | 'error' | 'fetch_fail' | 'vital';
+export interface ClientPoint {
+    kind: ClientPointKind;
+    /** The screen's route template (`/connections/$id`), never the address with its ids. */
+    route: string;
+    /** An error's class, an API route, or a vital's name (LCP, INP, CLS). */
+    name?: string;
+    /** A hash of the error's stack frames. */
+    fingerprint?: string;
+    /** The `X-Request-Id` of the failed answer, to find its server side. */
+    requestId?: string;
+    /** ms, or a vital's score. */
+    value?: number;
+    status?: number;
+    device?: 'phone' | 'desktop';
+}
+/** The stack's frames only (a message can carry anything), with each file's query dropped. */
+export declare function stackFingerprint(error: unknown): string;
+/** An API address as a route: no host or query, and id-like segments as `:id`. */
+export declare function apiRoute(url: string): string;
+/** Queues one point (nothing is kept until `useLumenTelemetry` has named the app); the batch goes out every 15 s, at 50 points, or when the tab is hidden. */
+export declare function reportClient(p: Omit<ClientPoint, 'device' | 'route'> & {
+    route?: string;
+}): void;
+/** A request that failed: its API route template, status (0 when it never answered) and id. */
+export declare function reportFailedFetch(apiRoute: string, status: number, requestId?: string | null): void;
+/** An error the page caught or didn't: its class and stack hash only. */
+export declare function reportClientError(error: unknown): void;
+export interface LumenTelemetryOptions {
+    /** The app's name in the points (`console`, `admin`). */
+    app: string;
+    /** The current screen's route template, from the app's router. */
+    route: string;
+    /** The build or deploy the page runs. */
+    version?: string;
+    /** Where batches go; `/api/t` by default. */
+    endpoint?: string;
+}
+/** Mount once at the app's root: every screen change is a view, and errors and vitals follow. */
+export declare function useLumenTelemetry(opts: LumenTelemetryOptions): void;

package/dist/telemetry.js

@@ -0,0 +1,135 @@
+/**
+ * The app's own telemetry from the browser: screens opened, uncaught errors, failed requests and
+ * Web Vitals, sent in batches to the app's Worker (by default `POST /api/t`), which checks each
+ * point and writes it with `meterClientBatch` from `@columenlabs/lumen-ops/client`.
+ *
+ * It is first party and keeps nothing in the browser: no cookie, no storage, no third party. A
+ * point holds a route template, an error's class and a hash of its stack, a status and a number.
+ * Never an error's message, a URL's query, page text or anything typed.
+ */
+import { useEffect } from 'react';
+import { onCLS, onINP, onLCP } from 'web-vitals';
+const MAX_BATCH = 50;
+const FLUSH_MS = 15_000;
+const CODE = /^[A-Za-z0-9_.:/$-]{1,64}$/;
+let endpoint = '/api/t';
+let app = '';
+let version = '';
+let route = '';
+const queue = [];
+let started = false;
+const fnv = (s) => {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++)
+        h = Math.imul(h ^ s.charCodeAt(i), 16777619) >>> 0;
+    return h.toString(16).padStart(8, '0');
+};
+/** The stack's frames only (a message can carry anything), with each file's query dropped. */
+export function stackFingerprint(error) {
+    const stack = error instanceof Error ? (error.stack ?? '') : '';
+    const frames = stack
+        .split('\n')
+        .filter((l) => /^\s*at\s|@/.test(l))
+        .slice(0, 8)
+        .map((l) => l.replace(/\?[^:)\s]*/g, '').trim());
+    return fnv(frames.join('\n'));
+}
+const device = () => typeof window !== 'undefined' && window.matchMedia?.('(max-width: 767px)').matches
+    ? 'phone'
+    : 'desktop';
+const code = (s) => (s && CODE.test(s) ? s : undefined);
+/** An API address as a route: no host or query, and id-like segments as `:id`. */
+export function apiRoute(url) {
+    let path = url;
+    try {
+        path = new URL(url, 'http://x').pathname;
+    }
+    catch { }
+    return path
+        .split('/')
+        .map((seg) => /^[a-z]{1,4}_[A-Za-z0-9]+$/.test(seg) ||
+        seg.length >= 20 ||
+        (seg.length >= 8 && /\d/.test(seg)) ||
+        /[^A-Za-z0-9_.-]/.test(seg)
+        ? ':id'
+        : seg)
+        .join('/')
+        .slice(0, 64);
+}
+function flush() {
+    if (!app || queue.length === 0)
+        return;
+    const points = queue.splice(0, MAX_BATCH);
+    const body = JSON.stringify({ app, version: code(version), points });
+    try {
+        const sent = navigator.sendBeacon?.(endpoint, new Blob([body], { type: 'application/json' }));
+        if (!sent)
+            fetch(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body,
+                keepalive: true,
+            }).catch(() => { });
+    }
+    catch {
+        // Telemetry must never break the page.
+    }
+    if (queue.length)
+        flush();
+}
+/** Queues one point (nothing is kept until `useLumenTelemetry` has named the app); the batch goes out every 15 s, at 50 points, or when the tab is hidden. */
+export function reportClient(p) {
+    if (!started)
+        return;
+    queue.push({
+        ...p,
+        route: p.route ?? route,
+        name: code(p.name),
+        requestId: code(p.requestId),
+        device: device(),
+    });
+    if (queue.length >= MAX_BATCH)
+        flush();
+}
+/** A request that failed: its API route template, status (0 when it never answered) and id. */
+export function reportFailedFetch(apiRoute, status, requestId) {
+    reportClient({ kind: 'fetch_fail', name: apiRoute, status, requestId: requestId ?? undefined });
+}
+/** An error the page caught or didn't: its class and stack hash only. */
+export function reportClientError(error) {
+    reportClient({
+        kind: 'error',
+        name: error instanceof Error ? error.name : 'Error',
+        fingerprint: stackFingerprint(error),
+    });
+}
+const vital = (m) => reportClient({ kind: 'vital', name: m.name, value: m.value });
+function start() {
+    if (started || typeof window === 'undefined')
+        return;
+    started = true;
+    window.addEventListener('error', (e) => reportClientError(e.error ?? new Error('script')));
+    window.addEventListener('unhandledrejection', (e) => reportClientError(e.reason));
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden')
+            flush();
+    });
+    window.addEventListener('pagehide', flush);
+    setInterval(flush, FLUSH_MS);
+    onLCP(vital);
+    onINP(vital);
+    onCLS(vital);
+}
+/** Mount once at the app's root: every screen change is a view, and errors and vitals follow. */
+export function useLumenTelemetry(opts) {
+    useEffect(() => {
+        app = opts.app;
+        version = opts.version ?? '';
+        endpoint = opts.endpoint ?? '/api/t';
+        start();
+    }, [opts.app, opts.version, opts.endpoint]);
+    useEffect(() => {
+        route = opts.route;
+        reportClient({ kind: 'view', route: opts.route });
+    }, [opts.route]);
+}

package/dist/theme.css

@@ -525,6 +525,12 @@ body[data-pointing],
 body[data-pointing] [data-slot="lumen-card"] * {
   cursor: crosshair;
 }
+body[data-spotlight="section"] [data-spotlit],
+body[data-pointing] [data-assistant-section][data-spotlit] {
+  background: color-mix(in oklab, var(--primary) 8%, transparent);
+  border-radius: calc(var(--radius) * 0.6);
+  transition: background 120ms ease-out;
+}
 body[data-spotlight="nav"] [data-spotlit] {
   background: var(--sidebar-accent);
   color: var(--sidebar-accent-foreground);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ui",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "description": "Lumen: shared React components (frame, views, widgets, charts, drawers).",
   "license": "MIT",
   "type": "module",
@@ -49,7 +49,7 @@
     "@codemirror/lang-javascript": "6.2.5",
     "@codemirror/lang-json": "6.0.2",
     "@codemirror/lang-sql": "6.10.0",
-    "@columenlabs/lumen-ui-types": "0.1.80",
+    "@columenlabs/lumen-ui-types": "0.1.82",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/sortable": "10.0.0",
     "@dnd-kit/utilities": "3.2.2",
@@ -83,6 +83,7 @@
     "sonner": "^2.0.8",
     "tailwind-merge": "^3.7.0",
     "topojson-client": "3.1.0",
+    "web-vitals": "6.2.3",
     "world-atlas": "2.0.2"
   },
   "peerDependencies": {