@columenlabs/lumen-ui 0.0.0-stage → 0.2.1

package/dist/assistant-panel.js

@@ -0,0 +1,244 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenAssistant's frame (was the assistant panel's): what any app's AI assistant sits
+// in, with nothing of the assistant itself. Docked right of the page on desktop (drag its left edge
+// for ASSISTANT_WIDTH, never past half the window), a full-height sheet on phone; the header's ✦
+// button with an unread dot; ⌘J; and the chat history menu grouped by when each chat was last used.
+// Open or closed and the width are each browser tab's own (sessionStorage). The
+// product fills the body (the product's assistant: its chat, composer, cards and spend).
+import { HistoryIcon, SparklesIcon } from 'lucide-react';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { useIsMobile } from './hooks/use-mobile.js';
+import { cn } from './lib/utils.js';
+import { LumenBoundary } from './lumen-boundary.js';
+import { LumenSelector } from './lumen-selector.js';
+import { ASSISTANT_WIDTH, usePrefs } from './prefs.js';
+import { Button } from './ui/button.js';
+import { Kbd } from './ui/kbd.js';
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from './ui/sheet.js';
+import { Tooltip, TooltipContent, TooltipTrigger } from './ui/tooltip.js';
+/** A value kept for this browser tab (sessionStorage), read with `use` and set with `write`. */
+export function tabState(key, fallback, parse) {
+    const listeners = new Set();
+    const read = () => {
+        try {
+            const raw = sessionStorage.getItem(key);
+            return raw == null ? fallback : (parse(raw) ?? fallback);
+        }
+        catch {
+            return fallback;
+        }
+    };
+    let state = typeof sessionStorage === 'undefined' ? fallback : read();
+    const write = (next) => {
+        state = next;
+        try {
+            sessionStorage.setItem(key, String(next));
+        }
+        catch { }
+        for (const l of listeners)
+            l();
+    };
+    const use = () => useSyncExternalStore((l) => {
+        listeners.add(l);
+        return () => listeners.delete(l);
+    }, () => state, () => fallback);
+    return { write, use, get: () => state };
+}
+/** Whether the assistant is open in this tab. */
+export const assistantOpen = tabState('assistant_open', false, (raw) => raw === '1');
+/** Dragged width in px, within ASSISTANT_WIDTH; 0 is the shell's default. */
+const assistantWidth = tabState('assistant_width', 0, (raw) => {
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= ASSISTANT_WIDTH.min
+        ? Math.min(Math.round(n), ASSISTANT_WIDTH.max)
+        : 0;
+});
+/** ⌘J (Ctrl+J) calls `toggle` anywhere in the app. */
+export function useAssistantHotkey(toggle) {
+    const ref = useRef(toggle);
+    ref.current = toggle;
+    useEffect(() => {
+        const onKey = (e) => {
+            if (e.key.toLowerCase() === 'j' && (e.metaKey || e.ctrlKey)) {
+                e.preventDefault();
+                ref.current();
+            }
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, []);
+}
+/** The page header's ✦ button: shown while the assistant is closed, with a dot when a reply came. */
+export function LumenAssistantButton({ name, open, unread, onOpen, className, }) {
+    if (open)
+        return null;
+    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsxs(Button, { variant: "outline", size: "icon-sm", className: cn('relative shrink-0', className), "aria-label": name, onClick: onOpen, children: [_jsx(SparklesIcon, { className: "text-edge" }), unread && (_jsx("span", { "aria-hidden": true, "data-slot": "assistant-unread", className: "absolute -top-0.5 -right-0.5 size-2 rounded-full bg-primary" }))] }) }), _jsxs(TooltipContent, { children: [name, " ", _jsx(Kbd, { children: "\u2318J" })] })] }));
+}
+/**
+ * Docked right of the page on desktop (nothing while closed); a full-height sheet on phone, with
+ * `closedBar` under the page while it is closed. `children` draws the body; it is told which.
+ */
+export function LumenAssistantPanel({ name, open, onOpenChange, closedBar, children, }) {
+    const phone = useIsMobile();
+    if (phone)
+        return (_jsxs(_Fragment, { children: [!open && closedBar, _jsx(Sheet, { open: open, onOpenChange: onOpenChange, children: _jsxs(SheetContent, { side: "right", showCloseButton: false, className: "gap-0 p-0 data-[side=right]:w-full data-[side=right]:sm:max-w-none", children: [_jsx(SheetTitle, { className: "sr-only", children: name }), _jsxs(SheetDescription, { className: "sr-only", children: ["Chat with ", name, " about your data."] }), _jsx(LumenBoundary, { where: "assistant", what: "panel", children: children(true) })] }) })] }));
+    if (!open)
+        return null;
+    return _jsx(Docked, { name: name, children: children(false) });
+}
+function Docked({ name, children }) {
+    const saved = assistantWidth.use();
+    const [drag, setDrag] = useState(null);
+    const width = drag ?? saved;
+    const ref = useRef(null);
+    // Side sheets open left of the assistant, never over it: they read its width
+    // from `--assistant-docked` (ui/sheet.tsx), which is 0 while it is closed or on phone.
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const root = document.documentElement;
+        const set = () => root.style.setProperty('--assistant-docked', `${el.offsetWidth}px`);
+        set();
+        const watch = new ResizeObserver(set);
+        watch.observe(el);
+        return () => {
+            watch.disconnect();
+            root.style.removeProperty('--assistant-docked');
+        };
+    }, []);
+    return (_jsxs("aside", { ref: ref, "aria-label": name, "data-assistant-docked": "", 
+        // Its width is the dragged one (or the shell's default), within ASSISTANT_WIDTH and half the window.
+        style: width ? { width } : undefined, className: "pointer-events-auto sticky top-0 h-svh w-(--shell-assistant-width) max-w-[50vw] min-w-80 shrink-0 border-l bg-background", children: [_jsx(ResizeEdge, { name: name, width: width || 416, onWidth: (w) => {
+                    setDrag(null);
+                    assistantWidth.write(w);
+                }, onDrag: setDrag }), _jsx(LumenBoundary, { where: "assistant", what: "panel", children: children })] }));
+}
+/**
+ * The panel's left edge: drag it, or focus it and use the arrow keys, to set the width; a double
+ * click goes back to the default. While dragging only `onDrag` hears it.
+ */
+function ResizeEdge({ name, width, onDrag, onWidth, }) {
+    const clamp = (w) => Math.round(Math.max(ASSISTANT_WIDTH.min, Math.min(w, ASSISTANT_WIDTH.max, Math.floor(window.innerWidth / 2))));
+    // The panel's width on screen (the default one is CSS's).
+    const now = (el) => Math.round(el.parentElement?.getBoundingClientRect().width ?? width);
+    const [dragging, setDragging] = useState(false);
+    useEffect(() => {
+        if (!dragging)
+            return;
+        document.body.style.cursor = 'col-resize';
+        document.body.style.userSelect = 'none';
+        return () => {
+            document.body.style.cursor = '';
+            document.body.style.userSelect = '';
+        };
+    }, [dragging]);
+    return (_jsx("div", { role: "separator", "aria-orientation": "vertical", "aria-label": `Resize ${name}`, "aria-valuemin": ASSISTANT_WIDTH.min, "aria-valuemax": ASSISTANT_WIDTH.max, "aria-valuenow": width, tabIndex: 0, "data-slot": "assistant-resize", "data-dragging": dragging ? '' : undefined, className: "absolute inset-y-0 -left-1 z-20 w-2 cursor-col-resize outline-none after:absolute after:inset-y-0 after:left-1/2 after:w-0.5 after:-translate-x-1/2 after:transition-colors hover:after:bg-ring focus-visible:after:bg-ring data-dragging:after:bg-ring", onPointerDown: (e) => {
+            if (e.button !== 0)
+                return;
+            e.preventDefault();
+            const el = e.currentTarget;
+            el.setPointerCapture(e.pointerId);
+            const x0 = e.clientX;
+            const w0 = now(el);
+            let last = w0;
+            setDragging(true);
+            const move = (m) => {
+                last = clamp(w0 + x0 - m.clientX);
+                onDrag(last);
+            };
+            const up = () => {
+                el.removeEventListener('pointermove', move);
+                el.removeEventListener('pointerup', up);
+                el.removeEventListener('pointercancel', up);
+                setDragging(false);
+                onWidth(last);
+            };
+            el.addEventListener('pointermove', move);
+            el.addEventListener('pointerup', up);
+            el.addEventListener('pointercancel', up);
+        }, onDoubleClick: () => onWidth(0), onKeyDown: (e) => {
+            const step = e.shiftKey ? 64 : 16;
+            if (e.key === 'ArrowLeft')
+                onWidth(clamp(now(e.currentTarget) + step));
+            else if (e.key === 'ArrowRight')
+                onWidth(clamp(now(e.currentTarget) - step));
+            else
+                return;
+            e.preventDefault();
+        } }));
+}
+/** The history groups, newest first. */
+const GROUPS = ['Today', 'Yesterday', 'This week', 'Last week', 'Last month'];
+/** Under this age a chat's time reads relative ("12m ago"), past it the clock, day or date. */
+const RELATIVE_MS = 6 * 3600_000;
+const DAY_MS = 86_400_000;
+/** `2026-10-14` in the person's time zone. */
+const dayOf = (at, timeZone) => new Intl.DateTimeFormat('en-CA', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+}).format(at);
+/** Which group a chat last used at `at` falls in, by calendar days in `timeZone`; weeks start Monday. */
+function groupOf(at, now, timeZone) {
+    const days = Math.round((Date.parse(dayOf(now, timeZone)) - Date.parse(dayOf(at, timeZone))) / DAY_MS);
+    const weekday = new Date(dayOf(now, timeZone)).getUTCDay(); // 0 Sunday
+    const sinceMonday = (weekday + 6) % 7;
+    if (days <= 0)
+        return 'Today';
+    if (days === 1)
+        return 'Yesterday';
+    if (days <= sinceMonday)
+        return 'This week';
+    if (days <= sinceMonday + 7)
+        return 'Last week';
+    return 'Last month';
+}
+/** `now`, `12m ago`, `3h ago`, then `06:15` (today, yesterday), `Thu` (the weeks) or `28 Sep`. */
+function whenOf(at, now, group, timeZone) {
+    const ago = now.getTime() - at.getTime();
+    if (ago < 60_000)
+        return 'now';
+    if (ago < 3600_000)
+        return `${Math.floor(ago / 60_000)}m ago`;
+    if (ago < RELATIVE_MS)
+        return `${Math.floor(ago / 3600_000)}h ago`;
+    if (group === 'Today' || group === 'Yesterday')
+        return new Intl.DateTimeFormat('en-GB', {
+            timeZone,
+            hour: '2-digit',
+            minute: '2-digit',
+        }).format(at);
+    if (group === 'This week' || group === 'Last week')
+        return new Intl.DateTimeFormat('en-US', { timeZone, weekday: 'short' }).format(at);
+    return new Intl.DateTimeFormat('en-GB', { timeZone, day: 'numeric', month: 'short' }).format(at);
+}
+/**
+ * Chats, a dropdown from the panel header: chats grouped by when they were
+ * last used, searched by title. A row is read ahead when highlighted, so picking it opens at once.
+ */
+export function LumenAssistantChats({ chats, value, note, disabled, onOpen, onRefresh, onHighlight, }) {
+    const { timeZone } = usePrefs();
+    const now = new Date();
+    const byId = new Map((chats ?? []).map((c) => [c.id, c]));
+    const groups = GROUPS.map((group) => ({
+        label: group,
+        options: (chats ?? []).flatMap((c) => {
+            const at = new Date(c.updated_at);
+            const g = groupOf(at, now, timeZone);
+            return g === group
+                ? [{ value: c.id, label: c.title, detail: whenOf(at, now, g, timeZone) }]
+                : [];
+        }),
+    })).filter((g) => g.options.length > 0);
+    return (_jsx(LumenSelector, { trigger: "icon", icon: HistoryIcon, label: "Chats", search: true, align: "end", groups: groups, empty: chats === null ? 'Loading…' : 'No chats yet', header: note && _jsx("p", { className: "px-2 pt-1 text-xs text-muted-foreground", children: note }), value: value, disabled: disabled, onOpenChange: (o) => o && onRefresh?.(), onHighlight: (id) => {
+            const c = byId.get(id);
+            if (c)
+                onHighlight?.(c);
+        }, onChange: (id) => {
+            const c = byId.get(id);
+            if (c)
+                onOpen(c);
+        } }));
+}

package/dist/assistant-screen.d.ts

@@ -0,0 +1,124 @@
+import type { IndicatorSpec } from '@columenlabs/lumen-ui-types/chart-formula';
+import { type ReactNode } from 'react';
+import { type CardOnScreen } from './spotlight.js';
+/** What one part of the screen does for the assistant; every handler is optional. */
+export interface AssistantMoveHandlers {
+    /** Opens a row's drawer by its title; returns why not when no row matches. */
+    open?: (title: string) => string | null;
+    /** Opens a symbol's chart, or several to compare, with the indicators the assistant asked for. */
+    chart?: (symbols: string | string[], indicators?: IndicatorSpec[]) => void;
+    /** Opens Settings at a section. */
+    settings?: (section: string) => void;
+    /** The Settings sections, for the page map. */
+    sections?: {
+        id: string;
+        title: string;
+    }[];
+    /** Rows that `open` can find, by title (the first few), for the page note. */
+    rows?: () => string[];
+    /**
+     * What the part shows now, in a line, told to the assistant after a call that ends on it (a view: rows
+     * shown, columns empty everywhere, each source's state), so it reports what is there, not what
+     * it asked for.
+     */
+    read?: () => string;
+    /** True while the person is editing here: moves wait for their tap. */
+    editing?: () => boolean;
+    snapshot?: () => unknown;
+    restore?: (snap: unknown) => void;
+}
+/** One move, as the server checked it. */
+export type AssistantMove = {
+    go: string;
+} | {
+    settings: string;
+    row?: string;
+} | {
+    chart: string | string[];
+    indicators?: IndicatorSpec[];
+} | {
+    open: string;
+} | {
+    point: string;
+};
+export type ScreenStatus = 'done' | 'failed' | 'waiting' | 'undone';
+export interface ScreenOutcome {
+    status: ScreenStatus;
+    text?: string;
+}
+/**
+ * What a sidebar page stands for (a symbol, a saved view, a basket): a nav section says it for its
+ * items (`pageType`), the @ picker groups by it and LumenFinder looks up its group in `pageTypes`.
+ */
+export type AssistantPageType = string;
+/** One page the nav names: its sidebar section and what it stands for. */
+export interface AssistantPage {
+    path: string;
+    title: string;
+    section?: string;
+    type?: AssistantPageType;
+    /** The item it sits under (a screener's symbol). */
+    parent?: string;
+}
+/**
+ * The workspace on screen, by id:
+ * The assistant addresses workspaces and tabs by these ids, so a rename never loses them.
+ */
+export interface WorkspaceOnScreen {
+    id: string;
+    name: string;
+    tabs: {
+        id: string;
+        name: string;
+        source: string;
+    }[];
+    /** The tab open now. */
+    open: string | null;
+}
+/** What the browser can do now, sent with each message while Screen is on. */
+export interface ScreenMap {
+    routes: string[];
+    pages: AssistantPage[];
+    settings: {
+        id: string;
+        title: string;
+    }[];
+    cards: CardOnScreen[];
+    workspace?: WorkspaceOnScreen;
+}
+interface ScreenApi {
+    register: (slot: string, h: AssistantMoveHandlers | null) => void;
+    pages: (key: string, items: AssistantPage[] | null) => void;
+    /** The workspace page says which workspace and tabs are on screen while it shows. */
+    workspace: (w: WorkspaceOnScreen | null) => void;
+    /** Runs a call's moves (one call at a time, in order); `force` runs them even mid-edit. */
+    run: (id: string, moves: AssistantMove[], force?: boolean) => Promise<ScreenOutcome>;
+    undo: (id: string) => Promise<ScreenOutcome>;
+    canUndo: (id: string) => boolean;
+    map: () => ScreenMap;
+    /** What the page note says the assistant can open and point at. */
+    can: () => {
+        cards: string[];
+        rows: string[];
+    } | null;
+}
+export declare const useAssistantScreen: () => ScreenApi | null;
+/** The workspace page tells the assistant which workspace and tab are on screen, by id. */
+export declare function useAssistantWorkspace(w: WorkspaceOnScreen | null): void;
+/** A part of the screen takes moves while it is mounted. */
+export declare function useAssistantMoves(slot: string, handlers: AssistantMoveHandlers): void;
+/**
+ * The nav's pages, for the page map the assistant reads and the @ picker: each keeps its sidebar section
+ * and what it stands for, so two "SPY" pages read as Trades ▸ SPY and Screeners ▸ SPY.
+ */
+export declare function useAssistantPages(items: {
+    title: string;
+    to: string;
+    type?: AssistantPageType;
+    parent?: string;
+}[], section?: string, type?: AssistantPageType): void;
+/** Holds what each part of the screen takes, and runs the assistant's moves over them. */
+export declare function AssistantScreenProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/assistant-screen.js

@@ -0,0 +1,252 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRouter } from '@tanstack/react-router';
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, } from 'react';
+import { cardsOnScreen } from './spotlight.js';
+/** How long one screen move may take before it fails. */
+const MOVE_MS = 10_000;
+const ScreenCtx = createContext(null);
+export const useAssistantScreen = () => useContext(ScreenCtx);
+/** The workspace page tells the assistant which workspace and tab are on screen, by id. */
+export function useAssistantWorkspace(w) {
+    const set = useContext(ScreenCtx)?.workspace;
+    const key = w ? JSON.stringify(w) : '';
+    useEffect(() => {
+        if (!set || !key)
+            return;
+        set(JSON.parse(key));
+        return () => set(null);
+    }, [set, key]);
+}
+/** A part of the screen takes moves while it is mounted. */
+export function useAssistantMoves(slot, handlers) {
+    const s = useContext(ScreenCtx);
+    // The latest handlers, read when a move runs: no re-register on every render.
+    const ref = useRef(handlers);
+    ref.current = handlers;
+    const register = s?.register;
+    const sections = JSON.stringify(handlers.sections ?? null);
+    useEffect(() => {
+        if (!register)
+            return;
+        const live = ref.current;
+        const proxy = {
+            open: live.open &&
+                ((t) => (ref.current.open ? ref.current.open(t) : 'This page has no rows to open')),
+            chart: live.chart && ((x, i) => ref.current.chart?.(x, i)),
+            settings: live.settings && ((x) => ref.current.settings?.(x)),
+            sections: JSON.parse(sections) ?? undefined,
+            rows: live.rows && (() => ref.current.rows?.() ?? []),
+            read: live.read && (() => ref.current.read?.() ?? ''),
+            editing: () => ref.current.editing?.() ?? false,
+            snapshot: live.snapshot && (() => ref.current.snapshot?.()),
+            restore: live.restore && ((x) => ref.current.restore?.(x)),
+        };
+        register(slot, proxy);
+        return () => register(slot, null);
+    }, [register, slot, sections]);
+}
+/**
+ * The nav's pages, for the page map the assistant reads and the @ picker: each keeps its sidebar section
+ * and what it stands for, so two "SPY" pages read as Trades ▸ SPY and Screeners ▸ SPY.
+ */
+export function useAssistantPages(items, section, type) {
+    const s = useContext(ScreenCtx);
+    const key = useId();
+    const pages = JSON.stringify(items.map((i) => ({
+        path: i.to,
+        title: i.title,
+        section,
+        type: i.type ?? type,
+        parent: i.parent,
+    })));
+    const set = s?.pages;
+    useEffect(() => {
+        if (!set)
+            return;
+        set(key, JSON.parse(pages));
+        return () => set(key, null);
+    }, [set, key, pages]);
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/** Polls until `cond` holds, up to `ms`. */
+async function waitFor(cond, ms = 3000) {
+    for (let t = 0; t <= ms; t += 100) {
+        const v = cond();
+        if (v)
+            return v;
+        await sleep(100);
+    }
+    return null;
+}
+/** Scrolls to an element and pulses it for 2 s. */
+function pulse(el) {
+    el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'smooth' });
+    el.dataset.assistantPoint = '';
+    setTimeout(() => delete el.dataset.assistantPoint, 2000);
+}
+const here = () => `${window.location.pathname}${window.location.search}${window.location.hash}`;
+const cardOf = (id) => document.querySelector(`[data-slot="lumen-card"][data-card="${CSS.escape(id)}"]`);
+/** Holds what each part of the screen takes, and runs the assistant's moves over them. */
+export function AssistantScreenProvider({ children }) {
+    const router = useRouter();
+    const slots = useRef(new Map());
+    const navPages = useRef(new Map());
+    const shownWorkspace = useRef(null);
+    const snaps = useRef(new Map());
+    // One call at a time, in the order they came.
+    const chain = useRef(Promise.resolve());
+    const register = useCallback((slot, h) => {
+        if (h)
+            slots.current.set(slot, h);
+        else
+            slots.current.delete(slot);
+    }, []);
+    const pages = useCallback((key, items) => {
+        if (items)
+            navPages.current.set(key, items);
+        else
+            navPages.current.delete(key);
+    }, []);
+    const editing = useCallback(() => [...slots.current.values()].some((h) => h.editing?.()) ||
+        !!document.querySelector('[role="alertdialog"]'), []);
+    const settled = useCallback(() => waitFor(() => router.state.status === 'idle' && !router.state.isLoading, 3000), [router]);
+    const snapshot = useCallback(() => ({
+        href: here(),
+        slots: [...slots.current].flatMap(([slot, h]) => h.snapshot ? [[slot, h.snapshot()]] : []),
+    }), []);
+    /** One move; returns why it failed, or null. */
+    const one = useCallback(async (m) => {
+        if ('go' in m) {
+            const [path] = m.go.split(/[?#]/);
+            // A search (Try screener's inputs) goes as an href, which the router parses like a link.
+            await router.navigate((/[?#]/.test(m.go) ? { href: m.go } : { to: m.go }));
+            await settled();
+            const last = router.state.matches[router.state.matches.length - 1];
+            if (!last || last.routeId === '__root__' || last.status === 'notFound')
+                return `no page ${path} on this desk`;
+            // The new page registers its views; give it a moment to mount.
+            await sleep(150);
+            return null;
+        }
+        if ('settings' in m) {
+            const h = slots.current.get('settings');
+            if (!h?.settings)
+                return 'Settings is not on this desk';
+            h.settings(m.settings);
+            if (!m.row)
+                return null;
+            const want = m.row.toLowerCase();
+            const row = await waitFor(() => [
+                ...document.querySelectorAll('[data-slot="settings"] [data-slot="setting-row"]'),
+            ].find((el) => el.querySelector('label')?.textContent?.trim().toLowerCase().includes(want)));
+            if (!row)
+                return `no row "${m.row}" in that section`;
+            pulse(row);
+            return null;
+        }
+        if ('chart' in m) {
+            const h = slots.current.get('chart');
+            if (!h?.chart)
+                return 'this desk has no chart';
+            h.chart(m.chart, m.indicators);
+            return null;
+        }
+        if ('open' in m) {
+            const h = await waitFor(() => [...slots.current.values()].find((x) => x.open));
+            if (!h?.open)
+                return 'no view with rows on this page';
+            return h.open(m.open);
+        }
+        const id = m.point.replace(/^card:/, '');
+        const el = await waitFor(() => cardOf(id));
+        if (!el)
+            return `no card "${id}" on this page`;
+        pulse(el);
+        return null;
+    }, [router, settled]);
+    const run = useCallback((id, moves, force = false) => {
+        const go = async () => {
+            if (!force && editing())
+                return { status: 'waiting' };
+            snaps.current.set(id, snapshot());
+            for (const m of moves) {
+                // A move that never settles (a navigation that hangs) fails on its own, so it can't
+                // hold every later move and Undo behind it.
+                let timer;
+                const late = new Promise((done) => {
+                    timer = setTimeout(() => done(`the move took over ${MOVE_MS / 1000} s`), MOVE_MS);
+                });
+                const wrong = await Promise.race([one(m).catch((e) => e.message), late]);
+                clearTimeout(timer);
+                if (wrong)
+                    return { status: 'failed', text: wrong.slice(0, 200) };
+            }
+            // What the page shows after the moves: the view that took them reads itself once its rows
+            // are in (up to 3 s), so the assistant hears rows and sources, not only "done".
+            const view = await waitFor(() => [...slots.current.values()].find((h) => h.read));
+            const text = view?.read ? await waitFor(() => view.read?.() || null, 3000) : null;
+            return text ? { status: 'done', text: text.slice(0, 1200) } : { status: 'done' };
+        };
+        const next = chain.current.then(go, go);
+        chain.current = next.catch(() => undefined);
+        return next;
+    }, [editing, snapshot, one]);
+    const undo = useCallback((id) => {
+        const go = async () => {
+            const snap = snaps.current.get(id);
+            if (!snap)
+                return { status: 'failed', text: 'nothing to undo' };
+            snaps.current.delete(id);
+            if (here() !== snap.href) {
+                router.history.push(snap.href);
+                await settled();
+                await sleep(150);
+            }
+            for (const [slot, value] of snap.slots) {
+                const h = await waitFor(() => slots.current.get(slot), 1000);
+                h?.restore?.(value);
+            }
+            return { status: 'undone' };
+        };
+        const next = chain.current.then(go, go);
+        chain.current = next.catch(() => undefined);
+        return next;
+    }, [router, settled]);
+    const api = useMemo(() => ({
+        register,
+        pages,
+        workspace: (w) => {
+            shownWorkspace.current = w;
+        },
+        run,
+        undo,
+        canUndo: (id) => snaps.current.has(id),
+        map: () => {
+            const routes = [
+                ...new Set(Object.values(router.routesById)
+                    .map((r) => (r.fullPath ?? '').replace(/(.)\/$/, '$1'))
+                    .filter((p) => p.startsWith('/'))),
+            ];
+            const seen = new Set();
+            const named = [...navPages.current.values()].flat().filter((p) => {
+                if (seen.has(p.path))
+                    return false;
+                seen.add(p.path);
+                return true;
+            });
+            return {
+                routes,
+                pages: named.slice(0, 300),
+                settings: slots.current.get('settings')?.sections ?? [],
+                cards: cardsOnScreen().slice(0, 60),
+                ...(shownWorkspace.current ? { workspace: shownWorkspace.current } : {}),
+            };
+        },
+        can: () => {
+            const cards = cardsOnScreen().map((c) => `${c.id} (${c.title})`);
+            const rows = [...slots.current.values()].flatMap((h) => h.rows?.() ?? []).slice(0, 30);
+            return { cards, rows };
+        },
+    }), [register, pages, run, undo, router]);
+    return _jsx(ScreenCtx.Provider, { value: api, children: children });
+}

package/dist/card-switch.d.ts

@@ -0,0 +1,16 @@
+export declare function CardSwitch({ label, checked, onCheckedChange, }: {
+    label: string;
+    checked: boolean;
+    onCheckedChange: (on: boolean) => void;
+}): import("react").JSX.Element;
+/** A one-of-a-few choice for a card's header (`tools`), such as the live basket Orders card's
+ * Live | Shadow: a segmented control that never goes empty. */
+export declare function CardSegments<T extends string>({ label, value, options, onValueChange, }: {
+    label: string;
+    value: T;
+    options: {
+        value: T;
+        label: string;
+    }[];
+    onValueChange: (v: T) => void;
+}): import("react").JSX.Element;

package/dist/card-switch.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A labelled on/off switch for a card's header (`tools`) or toolbar: one
+// control for a mode a card turns on, like Tune's Advanced, instead of a pair of buttons in its body.
+import { useId } from 'react';
+import { Label } from './ui/label.js';
+import { Switch } from './ui/switch.js';
+import { ToggleGroup, ToggleGroupItem } from './ui/toggle-group.js';
+export function CardSwitch({ label, checked, onCheckedChange, }) {
+    const id = useId();
+    return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Switch, { id: id, checked: checked, onCheckedChange: onCheckedChange, size: "sm" }), _jsx(Label, { htmlFor: id, className: "text-xs", children: label })] }));
+}
+/** A one-of-a-few choice for a card's header (`tools`), such as the live basket Orders card's
+ * Live | Shadow: a segmented control that never goes empty. */
+export function CardSegments({ label, value, options, onValueChange, }) {
+    return (_jsx(ToggleGroup, { type: "single", size: "sm", variant: "outline", spacing: 0, value: value, onValueChange: (v) => v && onValueChange(v), "aria-label": label, children: options.map((o) => (_jsx(ToggleGroupItem, { value: o.value, className: "px-2.5 text-xs", children: o.label }, o.value))) }));
+}

package/dist/color-dot.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentType, ReactNode } from 'react';
+export declare function ColorDot({ color, className }: {
+    color: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** The dot as an icon component, for an `LumenOption.icon`; one per colour, so it keeps its identity. */
+export declare function colorIcon(color: string): ComponentType<{
+    className?: string;
+}>;
+/** A value as a chip in its colour (a label): a tint behind, the colour as text. */
+export declare function ColorChip({ color, children }: {
+    color?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;