@hanzo/build 0.2.60 → 0.2.62

package/lib/run.js

@@ -25,12 +25,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { SizableText, useMedia, XStack, YStack } from '@hanzo/gui';
 import { ChevronDown, ChevronRight, Clock, Copy, ExternalLink, GitPullRequest, Globe, Pencil, Share } from '@hanzogui/lucide-icons-2';
-import { Button, Dialog, DialogContent, DialogTitle, DropdownMenu, Input } from '@hanzo/ui';
+import { Button, Dialog, DialogContent, DialogTitle, DropdownMenu, Grip, Input } from '@hanzo/ui';
 import { Steer } from '@hanzo/ui/agents';
 import { Failure } from '@hanzo/ui/chat';
 import { useLimits } from '@hanzo/ui/product/useLimits';
 import { useDictation, useVoice } from '@hanzo/voice';
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { approve, followUp, headline, retry, start } from './api/coding.js';
 import { limits as readLimits } from './api/models.js';
 import { list, message, pause, publish, rename, resume, stop, story, took } from './api/sessions.js';
@@ -38,7 +38,6 @@ import { answer, cards, outcome, pull, settled, steps } from './api/turn.js';
 import { verdict } from './api/verdict.js';
 import { useKept, useProjects, useRead, useRun } from './data.js';
 import { Desk, SEED } from './desk.js';
-import { Grip } from './grip.js';
 import { useHost, useTarget } from './host.js';
 import { useMind } from './mind.js';
 import { Out } from './out.js';
@@ -48,35 +47,11 @@ import { useSpoken } from './voice.js';
 import { speaker } from './reply.js';
 import { PanelToggle } from './panel.js';
 import { schedule } from './scheduled.js';
+import { SideProvider, useSplit } from './side.js';
 import { PAGE, useDeck, useKey, usePanel } from './tabs.js';
 import { compose, Files, pick } from './tools.js';
 import { Transcript } from './transcript.js';
 const LIVE = new Set(['running', 'paused', '']);
-/** The side panel's width, px: its default, the floor a drag holds, and what the transcript keeps beside it. */
-const DESK_WIDTH = 480;
-const DESK_FLOOR = 240;
-const TALK_FLOOR = 300;
-/** The most the side panel is drawn at before its row is measured, px. */
-const DESK_CEIL = 960;
-/**
- * How wide an element is drawn, px, read before the first paint and again as it
- * changes, so what depends on it is right on the first frame. 0 until it is drawn.
- */
-function useWidth() {
-    const [width, setWidth] = useState(0);
-    const [el, setEl] = useState(null);
-    useLayoutEffect(() => {
-        if (!el)
-            return;
-        setWidth(el.getBoundingClientRect().width);
-        if (typeof ResizeObserver === 'undefined')
-            return;
-        const watch = new ResizeObserver(([entry]) => setWidth(entry?.contentRect.width ?? 0));
-        watch.observe(el);
-        return () => watch.disconnect();
-    }, [el]);
-    return [width, (node) => setEl(node instanceof HTMLElement ? node : null)];
-}
 export function Run({ id }) {
     const host = useHost();
     const t = useTarget();
@@ -93,15 +68,8 @@ export function Run({ id }) {
     const [desk, setDesk] = usePanel('dev', true, wide);
     const side = useDeck('dev', SEED);
     useKey(() => setDesk(!desk));
-    // The side panel's width is the reader's, kept, and gives way so the
-    // transcript keeps its floor: bounded by the row it is drawn in once that is
-    // measured, and by its own `maxWidth` until then.
-    const [reach, setReach] = useKept('hanzo.build.desk.span', DESK_WIDTH);
-    const [room, size] = useWidth();
-    const most = room ? Math.max(DESK_FLOOR, room - TALK_FLOOR) : DESK_CEIL;
-    const across = Math.round(Math.min(most, Math.max(DESK_FLOOR, typeof reach === 'number' ? reach : DESK_WIDTH)));
-    // A drag repaints the pane's width directly and tells React once, on letting go.
-    const deskBox = useRef(null);
+    // The side panel's column: the person's width, the run hidden behind it, full screen (side.tsx).
+    const split = useSplit(desk && wide, 'run', () => setDesk(false));
     // Stop was pressed here: the run keeps its work after it answers, and says so with its status.
     const [stopping, setStopping] = useState(false);
     const [naming, setNaming] = useState(false);
@@ -373,7 +341,7 @@ export function Run({ id }) {
                         ? 'Follow up — continues in a new run'
                         : 'Reading this run…';
     const desk_ = (sheet) => (_jsx(Desk, { id: id, repo: record?.repo ?? '', branch: record?.branch ?? '', base: record?.base ?? '', environment: record?.environment ?? '', mode: mode, pr: pr, title: title, project: record?.project ?? '', sandbox: record?.sandbox ?? '', site: site, published: end.published, events: events, live: running, menu: [...manage, ...sharing], refused: signed ? refused || (detail.error ? detail.error.message : '') : 'Sign in to follow this run.', retry: signed ? 'Retry' : 'Sign in', onRetry: signed ? detail.reload : () => host.signIn?.(), side: side, sheet: sheet, onHide: () => setDesk(false) }));
-    return (_jsxs(XStack, { ref: size, "data-slot": "run-split", flex: 1, minH: 0, minW: 0, width: "100%", children: [_jsxs(YStack, { "data-slot": "run", ...pane, flex: 1, minH: 0, minW: 0, width: "100%", children: [_jsxs(XStack, { px: "$4", pt: "$3", pb: "$2", gap: "$2", items: "center", minH: 44, children: [_jsxs(YStack, { flex: 1, minW: 0, items: "flex-start", children: [_jsx(DropdownMenu, { trigger: _jsxs(XStack, { render: "button", "aria-label": "Manage this run", items: "center", gap: "$1.5", maxW: "100%", px: "$1.5", mx: "$-1.5", py: "$0.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: [_jsx(SizableText, { render: "h1", size: "$5", color: "$ink", numberOfLines: 1, minW: 0, children: title }), _jsx(ChevronDown, { size: 14 })] }), items: manage }), _jsx(SizableText, { size: "$1", color: "$soft", numberOfLines: 1, maxW: "100%", children: [state || (detail.loading ? 'reading' : ''), record?.repo, record?.branch, record?.published ? 'shared' : ''].filter(Boolean).join(' · ') })] }), pr.href ? (_jsx(Out, { href: pr.href, label: `Open pull request ${pr.label}`, children: _jsxs(XStack, { items: "center", gap: "$1.5", px: "$2.5", py: "$1.5", rounded: "$3", borderWidth: 1, borderColor: "$borderColor", hoverStyle: { bg: '$hover' }, children: [_jsx(GitPullRequest, { size: 14 }), _jsx(SizableText, { size: "$2", color: "$ink", children: pr.label }), _jsx(ExternalLink, { size: 12, opacity: 0.6 })] }) })) : null, sharing.length ? (_jsx(DropdownMenu, { trigger: _jsxs(XStack, { render: "button", "aria-label": "Share", items: "center", gap: "$1.5", px: "$2.5", py: "$1.5", rounded: "$3", borderWidth: 1, borderColor: "$borderColor", hoverStyle: { bg: '$hover' }, children: [_jsx(Share, { size: 14 }), _jsx(SizableText, { size: "$2", color: "$ink", children: "Share" })] }), items: sharing })) : null, _jsx(PanelToggle, { open: desk, onToggle: () => setDesk(!desk) })] }), _jsx(Transcript, { cards: shown, onOpen: look, onDiff: () => {
+    return (_jsxs(XStack, { "data-slot": "run-split", flex: 1, minH: 0, minW: 0, width: "100%", children: [_jsxs(YStack, { "data-slot": "run", ref: split.main, style: split.mainStyle, ...pane, flex: 1, minH: 0, minW: 0, width: "100%", children: [_jsxs(XStack, { px: "$4", pt: "$3", pb: "$2", gap: "$2", items: "center", minH: 44, children: [_jsxs(YStack, { flex: 1, minW: 0, items: "flex-start", children: [_jsx(DropdownMenu, { trigger: _jsxs(XStack, { render: "button", "aria-label": "Manage this run", items: "center", gap: "$1.5", maxW: "100%", px: "$1.5", mx: "$-1.5", py: "$0.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: [_jsx(SizableText, { render: "h1", size: "$5", color: "$ink", numberOfLines: 1, minW: 0, children: title }), _jsx(ChevronDown, { size: 14 })] }), items: manage }), _jsx(SizableText, { size: "$1", color: "$soft", numberOfLines: 1, maxW: "100%", children: [state || (detail.loading ? 'reading' : ''), record?.repo, record?.branch, record?.published ? 'shared' : ''].filter(Boolean).join(' · ') })] }), pr.href ? (_jsx(Out, { href: pr.href, label: `Open pull request ${pr.label}`, children: _jsxs(XStack, { items: "center", gap: "$1.5", px: "$2.5", py: "$1.5", rounded: "$3", borderWidth: 1, borderColor: "$borderColor", hoverStyle: { bg: '$hover' }, children: [_jsx(GitPullRequest, { size: 14 }), _jsx(SizableText, { size: "$2", color: "$ink", children: pr.label }), _jsx(ExternalLink, { size: 12, opacity: 0.6 })] }) })) : null, sharing.length ? (_jsx(DropdownMenu, { trigger: _jsxs(XStack, { render: "button", "aria-label": "Share", items: "center", gap: "$1.5", px: "$2.5", py: "$1.5", rounded: "$3", borderWidth: 1, borderColor: "$borderColor", hoverStyle: { bg: '$hover' }, children: [_jsx(Share, { size: 14 }), _jsx(SizableText, { size: "$2", color: "$ink", children: "Share" })] }), items: sharing })) : null, _jsx(PanelToggle, { open: desk, onToggle: () => setDesk(!desk) })] }), _jsx(Transcript, { cards: shown, onOpen: look, onDiff: () => {
                             side.open({ kind: 'diff', title: 'Diff' });
                             setDesk(true);
                         }, listen: signed ? listen : undefined, end: failed ? (_jsx(Failure, { onRetry: busy ? undefined : () => void act(() => carry(again, 'retry')), children: end.problem ? 'This run stopped before it finished.' : 'This run stopped with an error. Its work so far is on its branch.' })) : null, 
@@ -402,15 +370,17 @@ export function Run({ id }) {
                                                         : 'This run is still working.' }), _jsx(Steer, { onCommand: command, withhold: [
                                                     ...(paused ? ['pause'] : ['resume']),
                                                     ...(busy || waiting ? ['pause', 'resume', 'stop'] : []),
-                                                ] }), _jsx(Button, { size: "sm", disabled: notify, onPress: () => void ask(), children: notify ? 'You will be notified' : 'Notify me' })] })) : null] }), _jsx(Prompt, { framed: true, value: draft, onChange: setDraft, onSend: send, ready: Boolean(draft.trim()), disabled: !signed || busy || waiting || !(running || finished), placeholder: placeholder, label: steering ? 'Steer this run' : 'Follow up on this run', head: files.length ? _jsx(XStack, { gap: "$1.5", flexWrap: "wrap", children: _jsx(Files, { files: files, onFiles: setFiles }) }) : undefined, onAttach: () => pick(files, setFiles, setNote), 
+                                                ] }), _jsx(Button, { size: "sm", disabled: notify, onPress: () => void ask(), children: notify ? 'You will be notified' : 'Notify me' })] })) : null] }), _jsx(Prompt, { framed: true, value: draft, onChange: setDraft, onSend: send, ready: Boolean(draft.trim()), disabled: !signed || busy || waiting || !(running || finished), placeholder: placeholder, label: steering ? 'Steer this run' : 'Follow up on this run', head: files.length ? _jsx(XStack, { gap: "$1.5", flexWrap: "wrap", children: _jsx(Files, { files: files, onFiles: setFiles }) }) : undefined, plus: { upload: () => pick(files, setFiles, setNote) }, 
                                 // What a new run from here is made with; words that steer this run use neither.
-                                mind: signed && !steering ? mind : null, limits: limits, voice: voice, note: "Hanzo is AI and can make mistakes." })] })] }), desk && !wide ? desk_(true) : null, desk && wide ? (_jsxs(YStack, { "data-slot": "desk", ref: (el) => {
-                    deskBox.current = el instanceof HTMLElement ? el : null;
-                }, ...pane, 
+                                mind: signed && !steering ? mind : null, limits: limits, voice: voice, note: "Hanzo is AI and can make mistakes." })] })] }), desk && !wide ? desk_(true) : null, desk && wide ? (_jsxs(YStack, { "data-slot": "desk", ref: split.aside, ...pane, 
                 // A pane of its own beside the run's, the gutter between them.
-                ml: gap, position: "relative", shrink: 0, minH: 0, style: { width: across, maxWidth: `calc(100% - ${TALK_FLOOR}px)`, minWidth: DESK_FLOOR }, children: [_jsx(Grip, { side: "right", span: across, floor: DESK_FLOOR, ceil: most, reset: Math.min(most, DESK_WIDTH), onSpan: (n) => deskBox.current?.style.setProperty('width', `${n}px`), onKeep: setReach, onShut: () => setDesk(false), label: "Resize the side panel", 
+                ml: gap, position: "relative", shrink: 0, minH: 0, style: split.asideStyle, children: [split.grip ? (_jsx(Grip, { ...split.grip, label: "Resize the side panel", bar: "inline", 
+                        // The handle halfway down the edge, where a hand looks for it.
+                        justify: "center", 
                         // In the gutter between the two panes; `left` is measured inside the pane's 1px edge.
-                        l: `calc(-1 * ${gap} - ${pane.borderWidth}px)`, width: gap }), desk_(false)] })) : null, _jsx(Dialog, { open: naming, onOpenChange: setNaming, children: _jsxs(DialogContent, { maxW: 480, children: [_jsx(DialogTitle, { children: "Rename this run" }), _jsx(Input, { autoFocus: true, value: name, onChangeText: setName, "aria-label": "The run\u2019s name", maxLength: 512, onKeyDown: (e) => {
+                        l: `calc(-1 * ${gap} - ${pane.borderWidth}px)`, width: gap, 
+                        // A finger's band, centred on the gutter.
+                        $touchable: { l: `calc(-22px - ${gap} / 2 - ${pane.borderWidth}px)`, width: 44 } })) : null, _jsx(SideProvider, { value: split.side, children: desk_(false) })] })) : null, _jsx(Dialog, { open: naming, onOpenChange: setNaming, children: _jsxs(DialogContent, { maxW: 480, children: [_jsx(DialogTitle, { children: "Rename this run" }), _jsx(Input, { autoFocus: true, value: name, onChangeText: setName, "aria-label": "The run\u2019s name", maxLength: 512, onKeyDown: (e) => {
                                 if (e.key === 'Enter')
                                     save();
                             } }), _jsxs(XStack, { gap: "$2", justify: "flex-end", children: [_jsx(Button, { size: "sm", variant: "outline", onPress: () => setNaming(false), children: "Cancel" }), _jsx(Button, { size: "sm", disabled: busy || !name.trim(), onPress: save, children: "Save" })] })] }) })] }));

package/lib/side.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The side panel's column beside a conversation or a run, once for Chat and
+ * Dev: how wide it is, the middle column it can take the room from, and full
+ * screen. The host draws the two columns and spreads what `useSplit` hands it
+ * on them and on the kit's `Grip`; the `Panel` inside reads `useSide` for its
+ * full-screen button and its way back to the middle column.
+ *
+ *   width   the person's, kept in their preferences (`side.width`, /v1/pref),
+ *           so it follows them to every device and to both modes. Where no
+ *           PrefsProvider holds them (hanzo.team's rooms) it lasts the page.
+ *           Saved once a drag lets go, after a burst of keys has stopped.
+ *   main    the middle column keeps MAIN px. Pulled under half of that it is
+ *           hidden, never unmounted, so the transcript and the composer keep
+ *           their state, and the panel takes the room. Pulled back out, or the
+ *           strip's Show button, brings it back at the width kept.
+ *   full    the panel over the whole window. Escape or the button returns.
+ *
+ * A DRAG NEVER DRAWS REACT. Each frame writes the panel's width and the middle
+ * column's display on the two elements (`paint`), the same properties React
+ * writes from the settled state (`look`), so the two never disagree; React
+ * learns the width once, when the drag lets go. The room the two share is
+ * measured by a ResizeObserver, after layout, so a frame never reads layout
+ * it has just dirtied. A window narrowed under the panel is painted the same
+ * way: the panel gives way, and the person's width comes back with the room.
+ */
+import { type CSSProperties } from 'react';
+/** What the panel's strip reads of the column it stands in. */
+export interface Side {
+    /** What the middle column is called, in the button that brings it back: "chat", "run". */
+    main: string;
+    /** The middle column is hidden and the panel has the room. */
+    hidden: boolean;
+    show: () => void;
+    /** The panel is over the whole window. */
+    full: boolean;
+    fill: (on: boolean) => void;
+}
+/** Around the middle column's room and the panel: the panel's strip reads it. */
+export declare const SideProvider: import("react").Provider<Side | null>;
+/** The column the panel stands in, or null where it stands in none (a phone's sheet, a host's own column). */
+export declare const useSide: () => Side | null;
+export interface Split {
+    /** For `SideProvider`, around the middle column and the panel. */
+    side: Side;
+    /** The middle column's element and style. */
+    main: (el: unknown) => void;
+    mainStyle: CSSProperties;
+    /** The panel's column's element and style. */
+    aside: (el: unknown) => void;
+    asideStyle: CSSProperties;
+    /** The kit `Grip`'s props, but its label and its place; none while the panel is full screen. */
+    grip: {
+        side: 'right';
+        span: number;
+        floor: number;
+        ceil: number;
+        reset: number;
+        onSpan: (n: number) => void;
+        onKeep: (n: number) => void;
+        onShut: () => void;
+    } | null;
+}
+/**
+ * The column, for a host that draws it: `open` is whether the panel is drawn
+ * beside the middle column, `main` what that column is called, `onShut` puts
+ * the panel away (its edge pulled past its floor).
+ */
+export declare function useSplit(open: boolean, main: string, onShut: () => void): Split;

package/lib/side.js

@@ -0,0 +1,195 @@
+/**
+ * The side panel's column beside a conversation or a run, once for Chat and
+ * Dev: how wide it is, the middle column it can take the room from, and full
+ * screen. The host draws the two columns and spreads what `useSplit` hands it
+ * on them and on the kit's `Grip`; the `Panel` inside reads `useSide` for its
+ * full-screen button and its way back to the middle column.
+ *
+ *   width   the person's, kept in their preferences (`side.width`, /v1/pref),
+ *           so it follows them to every device and to both modes. Where no
+ *           PrefsProvider holds them (hanzo.team's rooms) it lasts the page.
+ *           Saved once a drag lets go, after a burst of keys has stopped.
+ *   main    the middle column keeps MAIN px. Pulled under half of that it is
+ *           hidden, never unmounted, so the transcript and the composer keep
+ *           their state, and the panel takes the room. Pulled back out, or the
+ *           strip's Show button, brings it back at the width kept.
+ *   full    the panel over the whole window. Escape or the button returns.
+ *
+ * A DRAG NEVER DRAWS REACT. Each frame writes the panel's width and the middle
+ * column's display on the two elements (`paint`), the same properties React
+ * writes from the settled state (`look`), so the two never disagree; React
+ * learns the width once, when the drag lets go. The room the two share is
+ * measured by a ResizeObserver, after layout, so a frame never reads layout
+ * it has just dirtied. A window narrowed under the panel is painted the same
+ * way: the panel gives way, and the person's width comes back with the room.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { usePrefs } from './prefs.js';
+/** The panel's least width, px, and the width it opens at before the person has chosen one. */
+const FLOOR = 240;
+const WIDTH = 480;
+/** The middle column's least width, px: under half of it, it is hidden and the panel takes the room. */
+const MAIN = 360;
+/** How long a burst of keys is waited out before its width is saved, ms. */
+const QUIET = 400;
+const Context = createContext(null);
+/** Around the middle column's room and the panel: the panel's strip reads it. */
+export const SideProvider = Context.Provider;
+/** The column the panel stands in, or null where it stands in none (a phone's sheet, a host's own column). */
+export const useSide = () => useContext(Context);
+/** The panel's own properties, at a width or with the room. Every key every time, so React and a drag write one set. */
+function look(width, hidden) {
+    return hidden
+        ? { width: 'auto', flexGrow: '1', flexShrink: '1', minWidth: '0px', maxWidth: 'none', marginLeft: '0px', gridColumnStart: 'pane' }
+        : { width: `${width}px`, flexGrow: '', flexShrink: '0', minWidth: `${FLOOR}px`, maxWidth: `calc(100vw - ${MAIN}px)`, marginLeft: '', gridColumnStart: '' };
+}
+/** Over the whole window, opaque, above the frame and under the kit's menus. */
+const FULL = {
+    position: 'fixed',
+    inset: '0px',
+    zIndex: '60',
+    width: 'auto',
+    maxWidth: 'none',
+    minWidth: '0px',
+    marginLeft: '0px',
+    borderRadius: '0px',
+    backgroundColor: 'var(--background)',
+    backdropFilter: 'none',
+};
+const write = (el, style) => {
+    for (const [k, v] of Object.entries(style))
+        el?.style.setProperty(k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`), v);
+};
+/**
+ * The column, for a host that draws it: `open` is whether the panel is drawn
+ * beside the middle column, `main` what that column is called, `onShut` puts
+ * the panel away (its edge pulled past its floor).
+ */
+export function useSplit(open, main, onShut) {
+    const prefs = usePrefs(false);
+    const kept = prefs?.prefs.side?.width;
+    const [width, setWidth] = useState(() => Math.max(FLOOR, kept ?? WIDTH));
+    const [hidden, setHidden] = useState(false);
+    const [full, setFull] = useState(false);
+    const [room, setRoom] = useState(0);
+    const [els, setEls] = useState({ main: null, aside: null });
+    // What a frame paints from, current without a render: the person's width,
+    // the room the two columns share, and the gutter between them.
+    const now = useRef({ width, room: 0, gap: 0, hidden });
+    now.current.width = width;
+    now.current.hidden = hidden;
+    const saving = useRef({ timer: undefined, width: 0 });
+    /**
+     * Draws the panel at `n`, or, for a person's pull (`pulled`), with the room;
+     * says which, and the width drawn. A window that narrows only squeezes it.
+     */
+    const paint = useCallback((n, pulled = true) => {
+        const { room, gap } = now.current;
+        if (!room)
+            return { hide: false, drawn: n };
+        const hide = pulled && room - gap - n < MAIN / 2;
+        const drawn = hide ? room : Math.max(FLOOR, Math.min(n, room - gap - MAIN));
+        write(els.aside, look(drawn, hide));
+        if (els.main)
+            els.main.style.display = hide ? 'none' : '';
+        return { hide, drawn };
+    }, [els]);
+    // The room, measured after layout: both columns' widths and the gutter, which
+    // a hidden middle column gives to the panel too. A change of window paints
+    // the person's width into it again.
+    useEffect(() => {
+        const { main, aside } = els;
+        if (!main || !aside || typeof ResizeObserver === 'undefined')
+            return;
+        const measure = () => {
+            // Full screen is the window's, not the room's.
+            if (aside.style.position === 'fixed')
+                return;
+            const shown = main.style.display !== 'none';
+            if (shown)
+                now.current.gap = parseFloat(getComputedStyle(aside).marginLeft) || 0;
+            const total = Math.round((shown ? main.getBoundingClientRect().width + now.current.gap : 0) + aside.getBoundingClientRect().width);
+            // A drag moves width between the two and leaves their sum; only a new window is news.
+            if (Math.abs(total - now.current.room) < 2)
+                return;
+            now.current.room = total;
+            setRoom(total);
+            if (shown)
+                paint(now.current.width, false);
+        };
+        const watch = new ResizeObserver(measure);
+        watch.observe(main);
+        watch.observe(aside);
+        return () => watch.disconnect();
+    }, [els, paint]);
+    // The person's width, once their preferences answer with one.
+    useEffect(() => {
+        if (kept && kept !== now.current.width)
+            setWidth(Math.max(FLOOR, kept));
+    }, [kept]);
+    // The preferences change with every save they answer; the save in waiting reads them current.
+    const held = useRef(prefs);
+    held.current = prefs;
+    const flush = useCallback(() => {
+        const s = saving.current;
+        if (s.timer === undefined)
+            return;
+        clearTimeout(s.timer);
+        s.timer = undefined;
+        // A refusal takes the width back (PrefsProvider), which is the answer.
+        held.current?.save({ side: { width: s.width } }).catch(() => { });
+    }, []);
+    const save = useCallback((n) => {
+        clearTimeout(saving.current.timer);
+        saving.current = { width: n, timer: held.current ? setTimeout(flush, QUIET) : undefined };
+    }, [flush]);
+    // A save still waiting goes now when the column goes.
+    useEffect(() => flush, [flush]);
+    const keep = useCallback((n) => {
+        const { hide, drawn } = paint(n);
+        setHidden(hide);
+        if (hide)
+            return;
+        setWidth(drawn);
+        save(drawn);
+    }, [paint, save]);
+    // Shut, the panel takes nothing with it: the middle column is back and the window is the frame's.
+    useEffect(() => {
+        if (open)
+            return;
+        setHidden(false);
+        setFull(false);
+    }, [open]);
+    // Escape leaves full screen, unless something open in it (a menu) took the key first.
+    useEffect(() => {
+        if (!full)
+            return;
+        const leave = (e) => {
+            if (e.key !== 'Escape' || e.defaultPrevented)
+                return;
+            setFull(false);
+        };
+        window.addEventListener('keydown', leave);
+        return () => window.removeEventListener('keydown', leave);
+    }, [full]);
+    const show = useCallback(() => {
+        setHidden(false);
+        const room = now.current.room;
+        if (room)
+            paint(Math.min(now.current.width, room - now.current.gap - MAIN));
+    }, [paint]);
+    const side = useMemo(() => ({ main, hidden: open && hidden, show, full: open && full, fill: setFull }), [main, open, hidden, full, show]);
+    const mainRef = useCallback((el) => setEls((was) => (was.main === el ? was : { ...was, main: el instanceof HTMLElement ? el : null })), []);
+    const asideRef = useCallback((el) => setEls((was) => (was.aside === el ? was : { ...was, aside: el instanceof HTMLElement ? el : null })), []);
+    const across = room ? Math.max(FLOOR, Math.min(width, room - now.current.gap - MAIN)) : width;
+    return {
+        side,
+        main: mainRef,
+        mainStyle: { display: side.hidden ? 'none' : '' },
+        aside: asideRef,
+        asideStyle: (side.full ? { ...look(across, side.hidden), ...FULL } : look(across, side.hidden)),
+        grip: side.full
+            ? null
+            : { side: 'right', span: side.hidden ? room : across, floor: FLOOR, ceil: Math.max(FLOOR, room), reset: WIDTH, onSpan: (n) => void paint(n), onKeep: keep, onShut },
+    };
+}

package/lib/suggest.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Up to three suggestions under the composer, each one person's own: what
+ * happened in their recent work, linked to where it happened, and the next step
+ * as a prompt the composer takes.
+ *
+ * Nothing here is written by hand. The rows are generated by Hanzo's own model
+ * (`MODEL`, POST /v1/chat/completions with the person's bearer, so the call is
+ * theirs like any other) from that person's activity alone: their recent
+ * conversations, their Dev runs, the org's issues and pull requests, their
+ * automations and their files. An account with no activity yet is given rows
+ * from what signup learned (its role, its use, what it said about its work),
+ * until there is activity to read. No input and no answer is no row: the model
+ * may answer none, and nothing pads it.
+ *
+ * Kept in the account (`suggest` in /v1/pref), so the rows follow the person:
+ *
+ *   {at, sig, rows, dismissed}   when they were made, the fingerprint of what
+ *                                they were made from, the rows, and the rows
+ *                                the person dismissed (by id)
+ *
+ * They are made again a day later, or once the activity's fingerprint has moved
+ * and the rows are at least `QUIET` old, so a busy hour asks the model once.
+ *
+ * This file is the pure half: inputs to a request, an answer to validated rows,
+ * the fingerprint and the policy. suggestions.tsx reads the sources and draws them.
+ */
+import type { Automation } from './api/auto.ts';
+import type { Conversation } from './api/conversations.ts';
+import type { Item } from './api/library.ts';
+import type { Session } from './api/sessions.ts';
+import type { Issue } from './merge.ts';
+export type Icon = 'github' | 'agent' | 'chat' | 'file' | 'task';
+export declare const ICONS: readonly Icon[];
+/** One row: where it came from, what happened, and what to do next. */
+export interface Suggestion {
+    /** Stable across generations: the source's address, or the title for a row with none. */
+    id: string;
+    icon: Icon;
+    /** What happened, a few words: "Hanzo app login fixes landed". */
+    title: string;
+    /** The source's own https address, copied from an input, or '' for none. */
+    href: string;
+    /** What the source says, a sentence or three: the hover card. */
+    summary: string;
+    /** The next step, a few words: "Verify the user flow". */
+    action: string;
+    /** What the composer is given when the row is chosen. */
+    prompt: string;
+}
+/** One piece of the person's activity, as the model is shown it. */
+export interface Input {
+    kind: 'conversation' | 'issue' | 'pull' | 'run' | 'automation' | 'file';
+    /** Its identity: an id, or its address. */
+    key: string;
+    title: string;
+    /** open or closed, a run's status, an automation's last result. */
+    state: string;
+    /** One line of detail: an issue's opening line, a run's repository, a schedule. */
+    text: string;
+    /** Its own https address, or ''. */
+    href: string;
+    /** RFC 3339, or ''. */
+    updated: string;
+}
+/** What signup and Settings learned about the person: the seed when there is no activity. */
+export interface Seed {
+    /** What Hanzo calls them. */
+    name?: string;
+    /** What best describes their work (Settings). */
+    work?: string;
+    /** The role chosen at signup (IAM `onboarding.role`). */
+    role?: string;
+    /** personal, team or enterprise (IAM `onboarding.use`). */
+    use?: string;
+    /** What every run is told about how they like to work. */
+    instructions?: string;
+}
+/** What the account keeps under `suggest`. */
+export interface Kept {
+    /** RFC 3339: when the rows were made. */
+    at: string;
+    /** The fingerprint of the inputs they were made from. */
+    sig: string;
+    rows: Suggestion[];
+    /** Ids of the rows the person dismissed, newest first. */
+    dismissed: string[];
+}
+/** Hanzo's model the rows are asked of: it decodes under a strict JSON schema at api.hanzo.ai. */
+export declare const MODEL = "zen5-flash";
+/** At most this many rows. */
+export declare const MOST = 3;
+/** Rows this old are made again whatever happened. */
+export declare const DAY: number;
+/** Rows younger than this are kept even when the activity has moved. */
+export declare const QUIET = 3600000;
+/** How many dismissals are remembered. */
+export declare const REMEMBER = 100;
+/** How many of each source the model reads. */
+export declare const TAKE: Record<Input['kind'], number>;
+/** One line, at most `n` characters. */
+export declare function line(v: unknown, n: number): string;
+/** An https address, or ''. A row links to nothing else. */
+export declare function https(v: unknown): string;
+/** cyrb53: a 53-bit string hash, as 14 hex digits. A fingerprint, never a secret. */
+export declare function hash(s: string): string;
+/** What the sources answered, read by suggestions.tsx. */
+export interface Activity {
+    conversations: Conversation[];
+    /** The org's issues and pull requests (GET /v1/task/board). */
+    issues: Issue[];
+    /** The org's Dev runs; only the person's own are read. */
+    runs: Session[];
+    automations: Automation[];
+    /** The person's own Library items. */
+    files: Item[];
+    /** The person as a run's `actor` names them: `<owner>/<sub>`. */
+    me: string;
+}
+/** The person's activity as inputs: their own runs only, each kind's newest `TAKE`. */
+export declare function inputs(a: Activity): Input[];
+/**
+ * The seed: what the account's preferences say (`callName`, `work`,
+ * `instructions` in /v1/pref) and what signup kept on the IAM user (`onboarding`
+ * in /v1/iam/preferences: the role picked, and personal, team or enterprise).
+ */
+export declare function seed(p: {
+    callName?: string;
+    work?: string;
+    instructions?: string;
+}, iam: unknown): Seed;
+/** Each kind's newest `TAKE`, newest first overall. */
+export declare function pick(all: Input[]): Input[];
+/**
+ * The fingerprint of what the rows are made from: each input's identity and
+ * state, and the seed. A new conversation, a closed issue or a finished run
+ * moves it; another turn in a conversation already read does not.
+ */
+export declare function sig(inputs: Input[], seed: Seed): string;
+/** Whether rows kept at `kept` are to be made again, now that the inputs read as `now`. */
+export declare function due(kept: Kept | null, fingerprint: string, now: number): boolean;
+/** Whether anything newer could change kept rows yet: false while they are younger than `QUIET`. */
+export declare function stale(kept: Kept | null, now: number): boolean;
+/** The icon a row about `i` carries: GitHub's mark only for GitHub's own address. */
+export declare function iconOf(i: Input): Icon;
+/** The answer's shape, decoded strictly by the model. */
+export declare const SCHEMA: {
+    readonly type: 'object';
+    readonly additionalProperties: false;
+    readonly required: readonly ['rows'];
+    readonly properties: {
+        readonly rows: {
+            readonly type: 'array';
+            readonly maxItems: 3;
+            readonly items: {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['icon', 'title', 'href', 'summary', 'action', 'prompt'];
+                readonly properties: {
+                    readonly icon: {
+                        readonly type: 'string';
+                        readonly enum: readonly Icon[];
+                    };
+                    readonly title: {
+                        readonly type: 'string';
+                    };
+                    readonly href: {
+                        readonly type: 'string';
+                    };
+                    readonly summary: {
+                        readonly type: 'string';
+                    };
+                    readonly action: {
+                        readonly type: 'string';
+                    };
+                    readonly prompt: {
+                        readonly type: 'string';
+                    };
+                };
+            };
+        };
+    };
+};
+/** The chat completion that asks for rows, or null when there is nothing to make them from. */
+export declare function request(inputs: Input[], seed: Seed, skip: string[], now: Date): Record<string, unknown> | null;
+/** The text of a chat completion's first choice, or ''. */
+export declare function content(raw: unknown): string;
+/** A row's id: its address, or for a row without one, its title. */
+export declare const idOf: (href: string, title: string) => string;
+/**
+ * The rows of a chat completion, validated: each with every field, an address
+ * that is one of the inputs' own (or none), its icon from that input, one row
+ * per source, at most `MOST`. Anything else is dropped, never repaired.
+ */
+export declare function answer(raw: unknown, inputs: Input[]): Suggestion[];
+/** The `suggest` key of the preference document, or undefined when it holds none. */
+export declare function kept(raw: unknown): Kept | undefined;
+/** The rows to draw: those not dismissed. */
+export declare const shown: (k: Kept | null | undefined) => Suggestion[];
+/** `k` with `id` dismissed: remembered first, the oldest forgotten past `REMEMBER`. */
+export declare function dismissed(k: Kept, id: string): Kept;
+/** The addresses and titles of dismissed rows the model is told to skip. */
+export declare function skip(k: Kept | null | undefined, inputs: Input[]): string[];