@kortix/ui 0.0.0-stage → 0.14.4

package/dist/session/panel/use-session-panel-layout.js

@@ -0,0 +1,222 @@
+'use client';
+import { aspectChangedWidth, resolveSideSize, } from './session-panel-sizing.js';
+import { useKortixComputerStore } from '../../internal/stores/kortix-computer-store.js';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+/**
+ * The panel sizing and glide orchestration for `SessionLayout`'s desktop
+ * split, moved verbatim out of `session-layout.tsx` (KRTX-459). Owns the
+ * panel refs, the box observer that measures the split, the `sideSize`
+ * precedence, and the resize effect with its 320 ms glide.
+ */
+export function useSessionPanelLayout({ sessionId, isMobile, isExpanded, isEasy, panelSplit, panelAspect, shouldShowPanel, }) {
+    const mainPanelRef = useRef(null);
+    const sidePanelRef = useRef(null);
+    const panelGroupRef = useRef(null);
+    // The panel group's own box, in a REF and never in state. The fit is decided
+    // once per (document, ratio) pair; a window resize must not redecide it, or
+    // the layout would quietly walk away from a divider the user dragged by
+    // hand. State here would re-render — and therefore re-fit — on every resize
+    // tick, which is precisely the behavior we are refusing.
+    const panelBoxRef = useRef(null);
+    const { enablePanelTransition, disablePanelTransition } = usePanelTransitions(panelGroupRef);
+    usePanelBoxObserver({ isMobile, panelGroupRef, panelBoxRef });
+    const { sideSize, mainSize } = usePanelSideSize({
+        isExpanded,
+        isEasy,
+        panelSplit,
+        panelAspect,
+        panelBoxRef,
+    });
+    const isAnimating = usePanelGlide({
+        sessionId,
+        shouldShowPanel,
+        isExpanded,
+        isEasy,
+        panelSplit,
+        panelAspect,
+        sideSize,
+        mainSize,
+        mainPanelRef,
+        sidePanelRef,
+        disablePanelTransition,
+    });
+    usePanelGlideFrames({
+        isAnimating,
+        enablePanelTransition,
+        sideSize,
+        mainSize,
+        mainPanelRef,
+        sidePanelRef,
+    });
+    return { mainPanelRef, sidePanelRef, panelGroupRef, isAnimating };
+}
+function usePanelTransitions(panelGroupRef) {
+    const enablePanelTransition = useCallback(() => {
+        const el = panelGroupRef.current;
+        if (!el)
+            return;
+        const panels = el.querySelectorAll('[data-slot="resizable-panel"]');
+        panels.forEach((panel) => {
+            panel.style.transition = 'flex 300ms cubic-bezier(0.4, 0, 0.2, 1)';
+        });
+    }, []);
+    const disablePanelTransition = useCallback(() => {
+        const el = panelGroupRef.current;
+        if (!el)
+            return;
+        const panels = el.querySelectorAll('[data-slot="resizable-panel"]');
+        panels.forEach((panel) => {
+            panel.style.transition = 'none';
+        });
+    }, []);
+    return { enablePanelTransition, disablePanelTransition };
+}
+// Keep the box current so a measurement landing at any moment has a real
+// layout to be a fraction of. Desktop only — the mobile branch returns a
+// drawer and never mounts this element, and nothing there has a split to
+// observe for.
+function usePanelBoxObserver({ isMobile, panelGroupRef, panelBoxRef, }) {
+    useEffect(() => {
+        if (isMobile) {
+            // Drop the box with the observer. A desktop box left behind would let a
+            // measurement landing under the drawer compute a fit against a layout
+            // that is no longer on screen — and run the 320ms resize timer for it.
+            panelBoxRef.current = null;
+            return;
+        }
+        const el = panelGroupRef.current;
+        if (!el)
+            return;
+        const observer = new ResizeObserver((entries) => {
+            const box = entries[0]?.contentRect;
+            if (!box)
+                return;
+            panelBoxRef.current = { width: box.width, height: box.height };
+        });
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [isMobile]);
+}
+function usePanelSideSize({ isExpanded, isEasy, panelSplit, panelAspect, panelBoxRef, }) {
+    // Easy mode opens at the panel's MINIMUM width (35/65): the cards are a
+    // narrow column and the chat is where the user lives — a 50/50 split steals
+    // half the screen for whitespace. Advanced keeps 50/50 (its
+    // stepper/terminal/browser views earn the room). A layer that needs more
+    // room requests it through `panelSplit` — 70/30 for a presentation
+    // deliverable (the deck needs real width), 50/50 for the terminal. A
+    // document that reported its own shape beats all of that (`panelAspect`).
+    // The drag handle still lets either mode go wider/narrower by hand.
+    //
+    // Memoized on exactly the states that may re-decide the width, so the box
+    // read below is sampled at those moments and only those: this is what makes
+    // the fit survive a window resize instead of chasing it.
+    //
+    // `panelBoxRef.current` is read here ON PURPOSE, outside the dep array —
+    // this is a deliberate stale-ref read, not a missed dependency. Adding
+    // `panelBox` to the deps (or promoting the ref to state so it re-renders)
+    // would make every `ResizeObserver` tick re-decide `sideSize`, turning the
+    // one-shot fit into a live window-resize follower: it would fight a
+    // hand-dragged divider on every resize instead of leaving it alone, and a
+    // window resize would re-run the 300ms glide `aspectChangedWidth` below is
+    // built to fire only once per real change. Do not "fix" this lint.
+    const sideSize = useMemo(() => resolveSideSize({
+        isExpanded,
+        isEasy,
+        panelAspect,
+        panelSplit,
+        panelBox: panelBoxRef.current,
+    }), [isExpanded, isEasy, panelAspect, panelSplit]);
+    const mainSize = 100 - sideSize;
+    return { sideSize, mainSize };
+}
+function usePanelGlide(input) {
+    const { sessionId, shouldShowPanel, isExpanded, isEasy, panelSplit, panelAspect, sideSize, mainSize, mainPanelRef, sidePanelRef, disablePanelTransition, } = input;
+    const prevExpandedRef = useRef(isExpanded);
+    const prevSplitRef = useRef(panelSplit);
+    const prevAspectRef = useRef(panelAspect);
+    const prevSideSizeRef = useRef(sideSize);
+    const [isAnimating, setIsAnimating] = useState(false);
+    useEffect(() => {
+        const expandChanged = prevExpandedRef.current !== isExpanded;
+        const splitChanged = prevSplitRef.current !== panelSplit;
+        // A fit measurement joins the SAME change detection, so it rides the same
+        // 300ms glide — a ratio arriving during the entrance coalesces into it
+        // rather than fighting it. Judged on the width it produces against the
+        // panel's REAL width, which is why `getSize()` and not `prevSideSizeRef`:
+        // a divider the user dragged moved the panel without telling us, so the
+        // width we last commanded is not the width on screen. See
+        // `aspectChangedWidth` for both failures this guards.
+        const aspectChanged = aspectChangedWidth({
+            prevAspect: prevAspectRef.current,
+            nextAspect: panelAspect,
+            currentSize: sidePanelRef.current?.getSize() ?? prevSideSizeRef.current,
+            nextSize: sideSize,
+        });
+        prevExpandedRef.current = isExpanded;
+        prevSplitRef.current = panelSplit;
+        prevAspectRef.current = panelAspect;
+        prevSideSizeRef.current = sideSize;
+        const skipAnimation = consumeSkipNextExpandAnimation();
+        const changed = expandChanged || splitChanged || aspectChanged;
+        const shouldAnimate = changed && shouldShowPanel && !skipAnimation;
+        if (shouldAnimate) {
+            setIsAnimating(true);
+        }
+        else if (changed) {
+            // Instant path: clear any transition left on the panels so the resize
+            // below snaps rather than inheriting a prior glide.
+            disablePanelTransition();
+        }
+        applyPanelResize({ mainPanelRef, sidePanelRef, shouldShowPanel, sideSize, mainSize });
+        if (shouldAnimate) {
+            const timer = setTimeout(() => {
+                disablePanelTransition();
+                setIsAnimating(false);
+            }, 320);
+            return () => clearTimeout(timer);
+        }
+    }, [
+        shouldShowPanel,
+        isExpanded,
+        sessionId,
+        disablePanelTransition,
+        isEasy,
+        panelSplit,
+        panelAspect,
+        sideSize,
+        mainSize,
+    ]);
+    return isAnimating;
+}
+// A detail-close collapse rides in with this flag set: snap the width, don't
+// glide it (the detail plays its own slide-out — a width animation under it
+// is a second, competing motion). Consume it here so the next deliberate
+// fullscreen/minimize toggle (or wide-open) animates as usual.
+function consumeSkipNextExpandAnimation() {
+    const skipAnimation = useKortixComputerStore.getState().skipNextExpandAnimation;
+    if (skipAnimation)
+        useKortixComputerStore.setState({ skipNextExpandAnimation: false });
+    return skipAnimation;
+}
+function applyPanelResize({ mainPanelRef, sidePanelRef, shouldShowPanel, sideSize, mainSize, }) {
+    if (shouldShowPanel) {
+        sidePanelRef.current?.resize(sideSize);
+        mainPanelRef.current?.resize(mainSize);
+    }
+    else {
+        sidePanelRef.current?.resize(0);
+        mainPanelRef.current?.resize(100);
+    }
+}
+function usePanelGlideFrames({ isAnimating, enablePanelTransition, sideSize, mainSize, mainPanelRef, sidePanelRef, }) {
+    useEffect(() => {
+        if (!isAnimating)
+            return;
+        const raf = requestAnimationFrame(() => {
+            enablePanelTransition();
+            sidePanelRef.current?.resize(sideSize);
+            mainPanelRef.current?.resize(mainSize);
+        });
+        return () => cancelAnimationFrame(raf);
+    }, [isAnimating, enablePanelTransition, sideSize, mainSize]);
+}

package/dist/session/panel/use-session-panel-state.d.ts

@@ -0,0 +1,19 @@
+import { SessionPanelView } from '../../internal/stores/session-browser-store.js';
+export declare function useSessionPanelView({ sessionId, projectId, projectSessionId, transient, booting, }: {
+    sessionId: string;
+    projectId?: string;
+    projectSessionId?: string;
+    transient: boolean;
+    booting: boolean;
+}): {
+    isSessionBusy: boolean;
+    isEasy: boolean;
+    effectiveView: SessionPanelView;
+    auditPendingCount: number;
+    togglePanelMode: () => void;
+};
+export declare function useSessionPanelSessionSync({ sessionId, projectSessionId, transient, }: {
+    sessionId: string;
+    projectSessionId?: string;
+    transient: boolean;
+}): void;

package/dist/session/panel/use-session-panel-state.js

@@ -0,0 +1,116 @@
+'use client';
+import { isPendingAction, useSessionAudit } from './session-audit-shared.js';
+import { useKortixComputerStore } from '../../internal/stores/kortix-computer-store.js';
+import { normalizeSessionPanelLayoutView, useSessionBrowserStore, } from '../../internal/stores/session-browser-store.js';
+import { useTabStore } from '../../internal/stores/tab-store.js';
+import { useUserPreferencesStore } from '../../internal/stores/user-preferences-store.js';
+import { useSessionStateStore, useSessionWorking } from '@kortix/sdk/react';
+import { useEffect } from 'react';
+export function useSessionPanelView({ sessionId, projectId, projectSessionId, transient, booting, }) {
+    // The transcript is not read here: `SessionPanelProvider` reads the session
+    // log itself, so a streamed delta never re-renders the layout.
+    const storedPanelView = useSessionBrowserStore((s) => s.viewBySession[sessionId]);
+    const panelView = normalizeSessionPanelLayoutView(storedPanelView);
+    // Existing users' persisted preferences predate this key.
+    const panelMode = useUserPreferencesStore((s) => s.preferences.panelMode ?? 'easy');
+    const togglePanelMode = useUserPreferencesStore((s) => s.togglePanelMode);
+    const isEasy = panelMode === 'easy';
+    // The session's own working state — literally the same projection
+    // `session-chat.tsx` reads (as `isServerBusy`) to drive its own working
+    // indicator, over one shared `GET .../turn` cache entry and one shared send
+    // receipt. It used to be the raw SSE status slot instead, and a dropped
+    // end-of-turn frame left THIS panel reporting "running" while the composer
+    // beside it correctly read idle — so `useDeliverableReadiness` never saw the
+    // running→settled transition and the W1 "ready" chip never fired for that run.
+    //
+    // A transient sub-session has no Kortix session row for `/turn` to answer
+    // about, so it keeps the stream slot — repaired on every stream (re)connect
+    // by the status-snapshot reconciler in `use-opencode-events`.
+    const sessionStatus = useSessionStateStore((s) => s.sessionStatus[sessionId]);
+    const working = useSessionWorking(projectId ?? '', projectSessionId ?? '', {
+        enabled: !!projectId && !!projectSessionId,
+        runtimeSessionId: sessionId,
+    });
+    const isSessionBusy = projectId && projectSessionId
+        ? working.state === 'working'
+        : sessionStatus?.type === 'busy' || sessionStatus?.type === 'retry';
+    // Easy mode is only ever the card home — the other views are engineer
+    // surfaces reached through the (hidden) tab strip. Force the view and skip
+    // their bodies entirely; `session-browser-store`'s `viewBySession` stays
+    // untouched so Advanced mode picks up right where the user left it.
+    const effectiveView = isEasy ? 'actions' : panelView;
+    // Pending-approval count for the "Audit" tab badge. Shares the header nudge's
+    // query key so this is one deduped request; skipped while booting/transient.
+    const { data: auditData } = useSessionAudit(projectId, projectSessionId, {
+        enabled: !transient && !booting && !!projectId && !!projectSessionId,
+        silent: true,
+        // A badge, not a timeline: pending approvals are recent by construction.
+        limit: 100,
+    });
+    const auditPendingCount = (auditData?.actions ?? []).filter(isPendingAction).length;
+    return { isSessionBusy, isEasy, effectiveView, auditPendingCount, togglePanelMode };
+}
+export function useSessionPanelSessionSync({ sessionId, projectSessionId, transient, }) {
+    const isSidePanelOpen = useKortixComputerStore((s) => s.isSidePanelOpen);
+    const setIsSidePanelOpen = useKortixComputerStore((s) => s.setIsSidePanelOpen);
+    const setActiveSession = useKortixComputerStore((s) => s.setActiveSession);
+    const shouldOpenPanel = useKortixComputerStore((s) => s.shouldOpenPanel);
+    const clearShouldOpenPanel = useKortixComputerStore((s) => s.clearShouldOpenPanel);
+    const isActiveTab = useTabStore((s) => s.activeTabId === sessionId);
+    const isInTabSystem = useTabStore((s) => !!s.tabs[sessionId]);
+    // "This layout is the one on screen." A session inside the tab system is
+    // visible when it is the active tab; a session on the standalone
+    // /projects/:id/sessions/:id route has no tab and is always the visible one.
+    const isVisibleLayout = isInTabSystem ? isActiveTab : true;
+    // Tell the store which session owns the right side, and close it.
+    //
+    // This used to be gated on `isActiveTab` alone and skipped for transient
+    // sessions, so on the standalone route — and in the window before
+    // `tab-store.activeTabId` catches up with a navigation — it never fired.
+    // The store kept the PREVIOUS session's `isSidePanelOpen`, so opening a
+    // second session rendered its panel already open with nothing to put in it:
+    // the empty loading panel. Firing on visibility covers every entry path
+    // (fresh navigation, tab switch, back/forward, transient → real handoff),
+    // and `setActiveSession` closes both surfaces, so a session you have just
+    // arrived at never inherits the last one's right side.
+    //
+    // `continuity` names the Kortix project session behind this layout id and
+    // whether this mount is the transient boot shell. The store uses it for one
+    // thing: the boot→ready crossfade renames the layout from the Kortix session
+    // id (shell) to the OpenCode id (real chat) for the SAME session — that
+    // handoff must carry an open panel across instead of slamming it shut.
+    useEffect(() => {
+        if (!isVisibleLayout)
+            return;
+        setActiveSession(sessionId, {
+            projectSessionId: projectSessionId ?? null,
+            transient,
+        });
+    }, [isVisibleLayout, sessionId, setActiveSession, projectSessionId, transient]);
+    useEffect(() => {
+        if (shouldOpenPanel && !isSidePanelOpen) {
+            setIsSidePanelOpen(true);
+            clearShouldOpenPanel();
+        }
+        else if (shouldOpenPanel) {
+            clearShouldOpenPanel();
+        }
+    }, [shouldOpenPanel, isSidePanelOpen, setIsSidePanelOpen, clearShouldOpenPanel]);
+    const setActivePanelSession = useSessionBrowserStore((s) => s.setActiveSessionId);
+    useEffect(() => {
+        if (transient)
+            return;
+        if (!isVisibleLayout)
+            return;
+        setActivePanelSession(sessionId);
+        return () => {
+            if (useSessionBrowserStore.getState().activeSessionId === sessionId) {
+                setActivePanelSession(null);
+            }
+        };
+    }, [transient, isVisibleLayout, sessionId, setActivePanelSession]);
+    // ⌘I / Ctrl+I lives on `SessionActionPanelColumn` — it toggles the RIGHT SIDE
+    // as a whole (`toggleRightPanel`), so it closes this detail panel too. The
+    // detail panel is still content-driven: the key never opens it empty, only
+    // back onto content this session already has.
+}

package/dist/session/participants/session-participants.d.ts

@@ -0,0 +1,29 @@
+import type { SessionParticipant, SessionParticipants } from '@kortix/sdk';
+import { type ReactNode } from 'react';
+/** What an avatar needs: a participant, or a message's member author. */
+type AvatarPerson = Pick<SessionParticipant, 'name' | 'email'> & {
+    avatar_url?: string | null;
+};
+/** The display name, else the email local part. The viewer too: every row names a person. */
+export declare function participantLabel(person: AvatarPerson): string;
+/**
+ * A message in a shared session: its member author's avatar above the
+ * bubble, on the right edge, your own included. A message with no recorded
+ * author, or any message in a single-user session, renders alone. The author
+ * comes from `.../message-authors`.
+ */
+export declare function MessageSenderAbove({ sender, children, }: {
+    sender: AvatarPerson | null | undefined;
+    children: ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+/** Who can open the session beyond the listed rows: the route lists 20, `total` counts everyone. */
+export declare function hiddenParticipantCount(participants: SessionParticipants | undefined): number;
+/**
+ * The people who can open the session: overlapping avatars in the header.
+ * Hover lists them in the sub-agent card's layout. Read-only: nothing in it
+ * is clickable. Renders nothing unless two or more people can open it.
+ */
+export declare function SessionParticipantStack({ participants, }: {
+    participants: SessionParticipants | undefined;
+}): import("react").JSX.Element | null;
+export {};

package/dist/session/participants/session-participants.js

@@ -0,0 +1,58 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { AvatarGroup, AvatarGroupCount } from '../../primitives/avatar.js';
+import { FadedScrollArea } from '../../primitives/faded-scroll-area.js';
+import Hint from '../../primitives/hint.js';
+import { HoverCard, HoverCardContent, HoverCardTrigger } from '../../primitives/hover-card.js';
+import { UserAvatar } from '../../primitives/user-avatar.js';
+import { useTranslations } from '../../i18n/index.js';
+/** Faces shown in the header before the rest collapse into a count. */
+const STACK_LIMIT = 3;
+/** The display name, else the email local part. The viewer too: every row names a person. */
+export function participantLabel(person) {
+    return person.name?.trim() || person.email?.split('@')[0] || '';
+}
+function ParticipantAvatar({ person, size }) {
+    return (_jsx(UserAvatar, { size: size, name: person.name, email: person.email ?? '', avatarUrl: person.avatar_url ?? null }));
+}
+/**
+ * A message in a shared session: its member author's avatar above the
+ * bubble, on the right edge, your own included. A message with no recorded
+ * author, or any message in a single-user session, renders alone. The author
+ * comes from `.../message-authors`.
+ */
+export function MessageSenderAbove({ sender, children, }) {
+    const t = useTranslations('sessionParticipants');
+    if (!sender)
+        return children;
+    const name = participantLabel(sender);
+    return (_jsxs("div", { className: "flex max-w-full flex-col items-end gap-1.5", children: [_jsx("span", { className: "sr-only", children: t('sentBy', { name }) }), _jsx(Hint, { label: sender.email ?? name, side: "top", delayDuration: 300, children: _jsx("span", { "aria-hidden": true, className: "flex shrink-0", children: _jsx(ParticipantAvatar, { person: sender, size: "sm" }) }) }), _jsx("div", { className: "flex max-w-full min-w-0", children: children })] }));
+}
+/** Who can open the session beyond the listed rows: the route lists 20, `total` counts everyone. */
+export function hiddenParticipantCount(participants) {
+    if (!participants)
+        return 0;
+    return Math.max(0, participants.total - participants.participants.length);
+}
+/**
+ * The people who can open the session: overlapping avatars in the header.
+ * Hover lists them in the sub-agent card's layout. Read-only: nothing in it
+ * is clickable. Renders nothing unless two or more people can open it.
+ */
+export function SessionParticipantStack({ participants, }) {
+    const t = useTranslations('sessionParticipants');
+    const [open, setOpen] = useState(false);
+    if (!participants?.multi_user || participants.total < 2)
+        return null;
+    const shown = participants.participants.slice(0, STACK_LIMIT);
+    const more = participants.total - shown.length;
+    const names = shown
+        .map((person) => participantLabel(person))
+        .filter(Boolean)
+        .join(', ');
+    const label = more > 0 ? t('peopleMore', { names, count: more }) : t('people', { names });
+    return (_jsxs(HoverCard, { open: open, onOpenChange: setOpen, openDelay: 300, closeDelay: 100, children: [_jsx(HoverCardTrigger, { asChild: true, children: _jsx("span", { role: "img", "aria-label": label, className: "hover:bg-secondary flex h-7 cursor-pointer items-center rounded-md p-0.5", children: _jsxs(AvatarGroup, { className: "-space-x-1.5", children: [shown.map((person) => (_jsx(ParticipantAvatar, { person: person, size: "sm" }, person.user_id))), more > 0 && (
+                            // `min-w-6 w-auto`: the tile grows with the count (+97), never under 24px.
+                            _jsxs(AvatarGroupCount, { className: "h-6 w-auto min-w-6 px-1.5 text-xs tabular-nums", children: ["+", more] }))] }) }) }), _jsxs(HoverCardContent, { side: "bottom", align: "end", sideOffset: 6, animated: false, className: "w-72 overflow-hidden p-0", onEscapeKeyDown: () => setOpen(false), children: [_jsxs("div", { className: "text-muted-foreground flex items-center justify-between px-3.5 pt-2.5 pb-1 text-xs", children: [_jsx("span", { children: t('title') }), _jsx("span", { className: "tabular-nums", children: participants.total })] }), _jsx(FadedScrollArea, { fadeColor: "from-popover", fadeSize: "6", className: "max-h-64 overscroll-contain", children: _jsx("ul", { className: "p-1 pt-0", children: participants.participants.map((person) => (_jsx("li", { children: _jsxs("div", { className: "text-foreground flex min-h-9 items-center gap-2.5 px-2 py-1 text-sm", children: [_jsx(ParticipantAvatar, { person: person, size: "md" }), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx("span", { className: "truncate leading-tight", children: participantLabel(person) }), person.email ? (_jsx("span", { className: "text-muted-foreground truncate text-xs leading-tight", children: person.email })) : null] })] }) }, person.user_id))) }) }), hiddenParticipantCount(participants) > 0 ? (_jsx("p", { className: "text-muted-foreground border-border border-t px-3.5 py-2 text-xs tabular-nums", children: t('more', { count: hiddenParticipantCount(participants) }) })) : null] })] }));
+}

package/dist/session/print/load-entire-history.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pull the WHOLE conversation into the DOM before the browser prints it.
+ *
+ * The transcript is paged: `loadOlder()` prepends the previous page and
+ * `hasOlder` says whether another one exists (`use-session-sync.ts`). Printing
+ * without draining that first gives a PDF of the last page of a conversation
+ * and nothing before it — silently, because the output looks complete.
+ *
+ * The loop reads its state through a callback rather than taking values,
+ * because the caller's `hasOlder` is React state: it cannot change inside a
+ * synchronous loop, so the hook passes a reader that looks at a ref an effect
+ * keeps current. `settle` is the same reason — after each pull we hand control
+ * back so React can commit and the refs can move.
+ */
+export interface LoadEntireHistoryState {
+    /** Another page exists before the oldest message currently rendered. */
+    hasOlder: boolean;
+    /** A pull is already in flight. */
+    isLoadingOlder: boolean;
+}
+export interface LoadEntireHistoryOptions {
+    /** Current paging state — read fresh on every iteration. */
+    readState: () => LoadEntireHistoryState;
+    /** Ask for one more page. */
+    loadOlder: () => Promise<unknown> | unknown;
+    /** Yield to React between pulls so `readState` can observe the commit. */
+    settle: () => Promise<void>;
+    /**
+     * Stop after this many pages.
+     *
+     * A bound, not a target. `hasOlder` is reported by the sync controller, and a
+     * controller that answers `true` for a page it cannot actually deliver would
+     * otherwise spin here forever with the user staring at "Preparing…". 200
+     * pages is ~10,000 messages — past any conversation we have seen, and far
+     * enough out that hitting it means something is wrong rather than that
+     * someone has a long session.
+     */
+    maxPages?: number;
+    /**
+     * How many times to wait on an in-flight pull before giving up on that page.
+     *
+     * Waiting does not advance `pages`, so this is the bound that keeps a wedged
+     * `isLoadingOlder` from spinning for ever. At the hook's one-frame `settle`
+     * this is a fraction of a second of patience per page, which is all a
+     * healthy overlapping pull needs.
+     */
+    maxWaitsPerPage?: number;
+}
+export interface LoadEntireHistoryResult {
+    /** Pages pulled by this call. Zero means everything was already loaded. */
+    pages: number;
+    /** False when the bound or a stall stopped us before the true beginning. */
+    exhausted: boolean;
+}
+export declare const DEFAULT_MAX_HISTORY_PAGES = 200;
+/** See {@link LoadEntireHistoryOptions.maxWaitsPerPage}. */
+export declare const DEFAULT_MAX_WAITS_PER_PAGE = 600;
+/**
+ * Pull pages until `hasOlder` is false.
+ *
+ * Never throws: a failed pull ends the drain and reports `exhausted: false`.
+ * A print that is missing its oldest pages is worth having; an exception that
+ * cancels the print is not, and the caller has no better recovery than to go
+ * ahead with what is loaded.
+ */
+export declare function loadEntireHistory(options: LoadEntireHistoryOptions): Promise<LoadEntireHistoryResult>;

package/dist/session/print/load-entire-history.js

@@ -0,0 +1,61 @@
+/**
+ * Pull the WHOLE conversation into the DOM before the browser prints it.
+ *
+ * The transcript is paged: `loadOlder()` prepends the previous page and
+ * `hasOlder` says whether another one exists (`use-session-sync.ts`). Printing
+ * without draining that first gives a PDF of the last page of a conversation
+ * and nothing before it — silently, because the output looks complete.
+ *
+ * The loop reads its state through a callback rather than taking values,
+ * because the caller's `hasOlder` is React state: it cannot change inside a
+ * synchronous loop, so the hook passes a reader that looks at a ref an effect
+ * keeps current. `settle` is the same reason — after each pull we hand control
+ * back so React can commit and the refs can move.
+ */
+export const DEFAULT_MAX_HISTORY_PAGES = 200;
+/** See {@link LoadEntireHistoryOptions.maxWaitsPerPage}. */
+export const DEFAULT_MAX_WAITS_PER_PAGE = 600;
+/**
+ * Pull pages until `hasOlder` is false.
+ *
+ * Never throws: a failed pull ends the drain and reports `exhausted: false`.
+ * A print that is missing its oldest pages is worth having; an exception that
+ * cancels the print is not, and the caller has no better recovery than to go
+ * ahead with what is loaded.
+ */
+export async function loadEntireHistory(options) {
+    const maxPages = options.maxPages ?? DEFAULT_MAX_HISTORY_PAGES;
+    const maxWaits = options.maxWaitsPerPage ?? DEFAULT_MAX_WAITS_PER_PAGE;
+    let pages = 0;
+    let waits = 0;
+    while (pages < maxPages) {
+        const state = options.readState();
+        if (!state.hasOlder)
+            return { pages, exhausted: true };
+        // A pull started by the scroll sentinel is already doing this page. Wait
+        // for it rather than racing a second request for the same cursor.
+        //
+        // BOUNDED, because this branch does not advance `pages`: a controller that
+        // is wedged `isLoadingOlder` (a request that never settles — the sandbox
+        // going away mid-read does exactly this) would otherwise spin here for
+        // ever, and the only thing the user would see is "Preparing…" that never
+        // becomes a print dialog.
+        if (state.isLoadingOlder) {
+            if (waits >= maxWaits)
+                return { pages, exhausted: false };
+            waits += 1;
+            await options.settle();
+            continue;
+        }
+        waits = 0;
+        try {
+            await options.loadOlder();
+        }
+        catch {
+            return { pages, exhausted: false };
+        }
+        pages += 1;
+        await options.settle();
+    }
+    return { pages, exhausted: !options.readState().hasOlder };
+}

package/dist/session/print/print-chain.d.ts

@@ -0,0 +1,64 @@
+/**
+ * How the transcript escapes the app shell when the page is printed.
+ *
+ * The session shell is a stack of `h-full` flex boxes, every one of them
+ * `overflow-hidden` or `overflow-clip` (`session-layout.tsx`), with the
+ * transcript's own `overflow-y-auto` scroller at the bottom of it. A browser
+ * printing that tree prints ONE viewport: the first page is whatever happened
+ * to be scrolled into view, the rest of the conversation is clipped away, and
+ * the composer and sidebar come along for the ride. That is exactly what
+ * Cmd+P produced before this file existed.
+ *
+ * Un-clipping the chain by hand does not work either. There is no fixed list of
+ * ancestors to target — the shell composes differently for mobile, for the
+ * panel-open layout, and for the modal layout — so a selector written today is
+ * wrong the next time the shell is refactored.
+ *
+ * So the chain is discovered at print time instead of being declared. Walk from
+ * the transcript up to `<body>`, stamp every ancestor, and let one CSS rule
+ * (`print.css`) give them `display: contents` — which removes the box
+ * altogether: no height, no overflow, no clipping, children promoted into the
+ * page flow. A second rule hides every child of a stamped ancestor that is NOT
+ * itself on the chain, which is what takes the sidebar, the header, the action
+ * panel and the composer out of the printed page without naming any of them.
+ *
+ * Nothing here is print-only in principle — it is plain DOM marking — so it is
+ * pure and testable, and the hook owns when to apply and remove it.
+ */
+/** Stamped on every ancestor between the transcript and `<body>`. */
+export declare const PRINT_PASSTHROUGH_ATTR = "data-print-passthrough";
+/** Stamped on the transcript scroller itself — the one child that survives. */
+export declare const PRINT_ROOT_ATTR = "data-print-root";
+/**
+ * Opt a node that is NOT on the chain into the printed page anyway.
+ *
+ * The document header (`session-print-header.tsx`) is the only user today: it
+ * is a sibling of the transcript, so the sibling-hiding rule would otherwise
+ * remove the very block that names the conversation.
+ */
+export declare const PRINT_KEEP_ATTR = "data-print-keep";
+/**
+ * The slice of `HTMLElement` this module uses.
+ *
+ * Structural, not `HTMLElement`, for one reason: `apps/web` registers no
+ * jsdom/happy-dom for `bun test` (see `composer-editor.test.ts`), so a function
+ * that names `HTMLElement` is a function with no unit tests. A real element
+ * satisfies this shape, and a plain object in a test satisfies it too.
+ */
+export interface PrintChainNode {
+    readonly parentElement: PrintChainNode | null;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+}
+/**
+ * Mark `root` and every ancestor of it up to (but excluding) `stopAt`.
+ *
+ * Returns the elements it stamped, in the order it stamped them, so the caller
+ * can hand the same list back to {@link clearPrintChain}. Returning the list
+ * rather than re-querying is deliberate: a re-render between print and cleanup
+ * can replace nodes, and a query would then miss a stamp and leave the app
+ * rendering as `display: contents` on screen.
+ */
+export declare function markPrintChain<T extends PrintChainNode>(root: T | null | undefined, stopAt?: PrintChainNode | null): T[];
+/** Undo {@link markPrintChain}. Safe to call with a stale list. */
+export declare function clearPrintChain(marked: readonly PrintChainNode[]): void;