@kortix/ui 0.0.0-stage → 0.14.4

package/dist/session/status/reload-forensics.js

@@ -0,0 +1,200 @@
+'use client';
+import { addBreadcrumb, captureMessage } from '../../lib/telemetry.js';
+import { useEffect } from 'react';
+/**
+ * Why did this session page load again?
+ *
+ * A user reported sessions "randomly disconnecting" on long threads, and a
+ * screen recording (2026-08-23) showed the page reload ITSELF mid-turn — no
+ * click, cursor motionless — then re-render into the composer's waking state.
+ * Nothing in the app calls `location.reload()` on its own, so the reload came
+ * from outside our code, and after the fact there is no way to tell which
+ * outside: Chrome discarding a heavy tab under memory pressure, a chunk that
+ * 404'd after a deploy (App Router recovers with a hard navigation), or a
+ * renderer crash. Those need different fixes, and guessing between them is how
+ * this stays open.
+ *
+ * So record the one moment that can distinguish them — the load right after —
+ * and label it. Read-only, best-effort, and silent unless something actually
+ * looks involuntary.
+ */
+const CHUNK_ERROR_KEY = 'kortix.lastChunkError';
+const HEAP_SAMPLE_KEY = 'kortix.lastHeapSample';
+/**
+ * Heap size above which a bare reload stops looking ordinary.
+ *
+ * Chrome kills a renderer that runs out of memory and reloads the tab, and that
+ * load is indistinguishable from cmd+R in every field the platform exposes —
+ * `wasDiscarded` is false, the navigation type is 'reload', no chunk failed. So
+ * the previous life has to leave the evidence behind itself. A session tab
+ * sitting above this before it vanished is not a person pressing reload.
+ *
+ * Chrome's per-renderer budget on a 64-bit desktop is ~2-4GB; 1.5GB is high
+ * enough that an ordinary thread never reaches it and low enough to catch the
+ * approach to a kill.
+ */
+export const HEAP_PRESSURE_BYTES = 1_500_000_000;
+/** A failed lazy chunk is the one involuntary reload cause we can see COMING. */
+export function noteChunkLoadFailure(message) {
+    try {
+        sessionStorage.setItem(CHUNK_ERROR_KEY, JSON.stringify({ message, at: Date.now() }));
+    }
+    catch {
+        /* storage unavailable — the label is a nice-to-have, never a requirement */
+    }
+}
+/** Record what this tab is holding, so the NEXT load can say whether it died
+ *  under memory pressure. Best-effort: `performance.memory` is Chromium-only
+ *  and absent in a cross-origin-isolated context. */
+export function noteHeapSample(now = Date.now()) {
+    try {
+        const memory = performance.memory;
+        const used = memory?.usedJSHeapSize;
+        if (typeof used !== 'number')
+            return;
+        sessionStorage.setItem(HEAP_SAMPLE_KEY, JSON.stringify({ used, at: now }));
+    }
+    catch {
+        /* storage or the API is unavailable — the label is a nice-to-have */
+    }
+}
+export function readReloadForensics(now = Date.now()) {
+    let discarded = false;
+    let navigationType = null;
+    let recentChunkError = null;
+    let heapBeforeReload = null;
+    try {
+        discarded = document.wasDiscarded === true;
+    }
+    catch {
+        /* older engines */
+    }
+    try {
+        const [nav] = performance.getEntriesByType('navigation');
+        navigationType = nav?.type ?? null;
+    }
+    catch {
+        /* no navigation timing */
+    }
+    try {
+        const raw = sessionStorage.getItem(CHUNK_ERROR_KEY);
+        if (raw) {
+            const parsed = JSON.parse(raw);
+            // Only the previous life counts. An hour-old entry says nothing about
+            // THIS load, and a stale label is worse than none.
+            if (parsed?.at && now - parsed.at < 30_000 && parsed.message) {
+                recentChunkError = parsed.message;
+            }
+            sessionStorage.removeItem(CHUNK_ERROR_KEY);
+        }
+    }
+    catch {
+        /* storage unavailable */
+    }
+    try {
+        const raw = sessionStorage.getItem(HEAP_SAMPLE_KEY);
+        if (raw) {
+            const parsed = JSON.parse(raw);
+            if (parsed?.at && now - parsed.at < 120_000 && typeof parsed.used === 'number') {
+                heapBeforeReload = parsed.used;
+            }
+            sessionStorage.removeItem(HEAP_SAMPLE_KEY);
+        }
+    }
+    catch {
+        /* storage unavailable */
+    }
+    return { discarded, navigationType, recentChunkError, heapBeforeReload };
+}
+/** Name the involuntary load, or `null` when the load looks ordinary. */
+export function classifyReloadCause(f) {
+    // A chunk failure is the most specific signal — report it even if the tab was
+    // also discarded, because it is the one we can act on (a stale deployment).
+    if (f.recentChunkError !== null)
+        return 'chunk-error';
+    if (f.discarded)
+        return 'discarded';
+    // The renderer-OOM signature: a plain reload, no chunk error, nothing
+    // discarded — but the tab was holding more than a person's session should
+    // just before it vanished. Without this the one hypothesis with no other
+    // fingerprint stays invisible.
+    if (f.navigationType === 'reload' && (f.heapBeforeReload ?? 0) >= HEAP_PRESSURE_BYTES) {
+        return 'renderer-oom';
+    }
+    return null;
+}
+/** True when the load looks involuntary — worth reporting, unlike an ordinary
+ *  navigation or a reload the user pressed themselves (which we cannot tell
+ *  apart from an automatic one, so a bare 'reload' alone is NOT enough). Boolean
+ *  summary of `classifyReloadCause`. */
+export function isInvoluntaryLoad(f) {
+    return classifyReloadCause(f) !== null;
+}
+/**
+ * True when the cause deserves a standalone Sentry event.
+ *
+ * A `discarded` tab is routine background reclaim: Chrome unloads a backgrounded
+ * tab and reloads it when the user comes back. It is expected browser behavior,
+ * not an app defect — the page reloads from the URL and the session reconnects
+ * from its durable state. It must not page. The two causes we CAN act on keep
+ * reporting: a failed lazy chunk is a deploy that left a stale tab behind, and a
+ * renderer killed under heap pressure is the silent one with no other
+ * fingerprint.
+ */
+export function shouldReportReloadCause(cause) {
+    return cause === 'chunk-error' || cause === 'renderer-oom';
+}
+/**
+ * Label this page load, and watch for the chunk failure that would explain the
+ * NEXT one. Mount once per session page.
+ *
+ * Classifies the load once (`classifyReloadCause`); an ordinary navigation — or a
+ * reload someone pressed — has no cause and stays silent. Every involuntary load
+ * is logged locally. A Sentry event fires only for an actionable cause
+ * (`shouldReportReloadCause`): a chunk-404-after-deploy or a renderer killed
+ * under heap pressure. A browser tab discard, the overwhelming majority, leaves a
+ * breadcrumb instead so it still explains a later error without paging on its
+ * own.
+ */
+export function useReloadForensics(sessionId) {
+    useEffect(() => {
+        const onError = (event) => {
+            const message = event?.message ?? '';
+            if (/loading chunk|chunkloaderror|failed to fetch dynamically imported module/i.test(message)) {
+                noteChunkLoadFailure(message);
+            }
+        };
+        window.addEventListener('error', onError);
+        // Sample now and on an interval, so whatever ends this tab leaves a number
+        // behind. 30s is far below the 2-minute freshness window the reader applies.
+        noteHeapSample();
+        const heapTimer = window.setInterval(() => noteHeapSample(), 30_000);
+        const forensics = readReloadForensics();
+        const cause = classifyReloadCause(forensics);
+        if (cause !== null) {
+            console.warn('[session] involuntary page load', { sessionId, cause, ...forensics });
+        }
+        if (shouldReportReloadCause(cause)) {
+            captureMessage('session page reloaded involuntarily', {
+                level: 'warning',
+                extra: { sessionId, cause, ...forensics },
+            });
+        }
+        else if (cause === 'discarded') {
+            // Expected browser behavior, not an app fault: keep the cause as a
+            // breadcrumb so it still attaches to any later real error, but never page
+            // on the discard itself. No `message` field — a `message:` literal reads as
+            // UI copy to the i18n audit, and this is developer-facing telemetry; the
+            // category and `data.cause` carry the meaning.
+            addBreadcrumb({
+                category: 'session.reload',
+                level: 'info',
+                data: { sessionId, cause, ...forensics },
+            });
+        }
+        return () => {
+            window.clearInterval(heapTimer);
+            window.removeEventListener('error', onError);
+        };
+    }, [sessionId]);
+}

package/dist/session/status/sandbox-loading-boundary.d.ts

@@ -0,0 +1,3 @@
+export declare function SandboxLoadingBoundary({ children }: {
+    children: React.ReactNode;
+}): import("react").JSX.Element;

package/dist/session/status/sandbox-loading-boundary.js

@@ -0,0 +1,43 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Safety net for the session subtree: during sandbox provisioning the opencode
+ * runtime URL isn't pinned yet, and any stray `getClient()` call throws
+ * "Server URL not ready — sandbox is still loading". Without this, such a throw
+ * escalates to the Next route boundary (app/error.tsx) and the user sees a hard
+ * "Something went wrong" instead of a loading state.
+ *
+ * This boundary catches ONLY those transient runtime-not-ready errors and
+ * auto-retries silently until the runtime is ready. It intentionally renders no
+ * fallback: the project shell is already mounted during session navigation and
+ * must never be replaced by a full-page loading logo. Every other error is
+ * rethrown so it bubbles to the outer boundary exactly as before.
+ *
+ * The gate fix in `use-opencode-sessions/keys.ts` + the guard in `session-chat`
+ * should prevent these throws in the first place; this is belt-and-suspenders so
+ * a missed caller degrades to "loading", never to a crash.
+ */
+import { ErrorBoundary } from '../../primitives/error-boundary.js';
+import { isRuntimeStartingError } from '@kortix/sdk';
+import { useEffect } from 'react';
+function RuntimeLoadingFallback({ reset }) {
+    // The runtime URL lands within a second or two of provisioning. Soft-reset the
+    // boundary on a short interval so the subtree re-renders and picks it up the
+    // moment it's ready — no hard reload, no manual "Try again". This must stay
+    // visually empty: initial project access has its own legitimate loader, but a
+    // transient runtime race while switching sessions must not cover the loaded
+    // project with the ASCII logo.
+    useEffect(() => {
+        const t = setInterval(reset, 800);
+        return () => clearInterval(t);
+    }, [reset]);
+    return null;
+}
+// Rethrow non-runtime errors so they propagate to the nearest OUTER boundary
+// (a boundary doesn't catch throws from its own fallback render).
+function Rethrow({ error }) {
+    throw error;
+}
+export function SandboxLoadingBoundary({ children }) {
+    return (_jsx(ErrorBoundary, { fallback: ({ error, reset }) => isRuntimeStartingError(error) ? (_jsx(RuntimeLoadingFallback, { reset: reset })) : (_jsx(Rethrow, { error: error })), children: children }));
+}

package/dist/session/status/session-busy-indicator.d.ts

@@ -0,0 +1,19 @@
+export declare function SessionBusyIndicator({ statusText, elapsedLabel, retryLabel, ambient, sessionId, className, }: {
+    statusText?: string;
+    /**
+     * Live elapsed time for the current status, e.g. `"24s"`. Rendered beside the
+     * phrase in its OWN non-animated span: it ticks once a second, and folding it
+     * into `statusText` would change the `AnimatePresence` key every second and
+     * replay the roll-swap forever during long tool calls.
+     */
+    elapsedLabel?: string;
+    retryLabel?: string;
+    ambient?: boolean;
+    /**
+     * Keys the dot-matrix glyph: each session hashes to its own variant
+     * (`SessionDotMatrix`), stable for that session's whole life. Session-less
+     * surfaces (home demo, debug harness) omit it and keep the default glyph.
+     */
+    sessionId?: string;
+    className?: string;
+}): React.ReactElement;

package/dist/session/status/session-busy-indicator.js

@@ -0,0 +1,55 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AnimatePresence, m, useReducedMotion } from 'motion/react';
+import { useEffect, useState } from 'react';
+import { SessionDotMatrix } from '../../primitives/dot-matrix/session-dot-matrix.js';
+import { TextShimmer } from '../../primitives/text-shimmer.js';
+import { cn } from '../../lib/utils.js';
+const DEFAULT_STATUS = 'Thinking';
+const AMBIENT_MESSAGES = [
+    'Reading the context',
+    'Working through the problem',
+    'Tracing the logic',
+    'Checking the details',
+    'Weighing the options',
+    'Pulling it together',
+    'Verifying the approach',
+    'Mapping the next step',
+    'Drafting the response',
+    'Polishing the answer',
+];
+const AMBIENT_HOLD_MS = 4000;
+const ROLL_SWAP = {
+    initial: { transform: 'translateY(100%)', opacity: 0 },
+    animate: { transform: 'translateY(0%)', opacity: 1 },
+    exit: { transform: 'translateY(-100%)', opacity: 0 },
+    transition: { type: 'spring', duration: 0.4, bounce: 0 },
+};
+const FADE_SWAP = {
+    initial: { opacity: 0 },
+    animate: { opacity: 1 },
+    exit: { opacity: 0 },
+    transition: { duration: 0.2, ease: 'easeOut' },
+};
+export function SessionBusyIndicator({ statusText, elapsedLabel, retryLabel, ambient = false, sessionId, className, }) {
+    const reduceMotion = useReducedMotion() ?? false;
+    const retryText = retryLabel?.trim();
+    const isRetrying = Boolean(retryText);
+    const status = statusText?.trim();
+    const elapsed = elapsedLabel?.trim();
+    const [ambientIdx, setAmbientIdx] = useState(() => Math.floor(Math.random() * AMBIENT_MESSAGES.length));
+    const useAmbient = ambient && !isRetrying && !status;
+    useEffect(() => {
+        if (!useAmbient)
+            return;
+        const id = setInterval(() => {
+            setAmbientIdx((i) => (i + 1) % AMBIENT_MESSAGES.length);
+        }, AMBIENT_HOLD_MS);
+        return () => clearInterval(id);
+    }, [useAmbient]);
+    const label = retryText ||
+        status ||
+        (useAmbient ? AMBIENT_MESSAGES[ambientIdx % AMBIENT_MESSAGES.length] : DEFAULT_STATUS);
+    const swap = reduceMotion ? FADE_SWAP : ROLL_SWAP;
+    return (_jsxs(m.div, { role: "status", "aria-live": useAmbient ? 'off' : 'polite', "data-testid": "session-busy-indicator", className: cn('text-muted-foreground flex w-full min-w-0 items-center gap-1.5 py-0.5 text-xs', className), children: [_jsx(SessionDotMatrix, { sessionId: sessionId, size: 14, className: "shrink-0" }), _jsx("span", { className: "relative min-w-0 flex-1", "aria-hidden": true, children: isRetrying ? (_jsx("span", { className: "text-muted-foreground/70 block truncate text-sm leading-5 tabular-nums", children: label })) : (_jsxs("span", { className: "flex min-w-0 items-center gap-1.5", children: [_jsx("span", { className: "relative block min-w-0 flex-1 overflow-hidden leading-5", children: _jsx(AnimatePresence, { initial: false, mode: "popLayout", children: _jsx(m.span, { initial: swap.initial, animate: swap.animate, exit: swap.exit, transition: swap.transition, className: "block min-w-0 whitespace-nowrap", children: _jsx(TextShimmer, { className: "truncate text-center align-middle text-sm leading-5", children: label }) }, label) }) }), elapsed ? (_jsx("span", { className: "text-muted-foreground/70 shrink-0 text-sm leading-5 tabular-nums", children: elapsed })) : null] })) }), _jsx("span", { className: "sr-only", children: label })] }));
+}

package/dist/session/status/session-chat-busy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Is the session busy, for every surface a user can act on — the Stop button,
+ * the turn shimmer, the question/permission composer locks, and the send
+ * anchoring.
+ *
+ * `hasRetryingAssistant` is a separate term rather than a refinement of
+ * `isServerBusy` because during a provider backoff the runtime's own status
+ * frame is stale by construction: OpenCode emits `session.error` only AFTER its
+ * internal retry ladder is exhausted, so no later `busy` or `retry` frame
+ * follows to correct the slot. The transcript is the only observer that still
+ * proves the turn is open.
+ */
+export declare function resolveEffectiveBusy(input: {
+    isServerBusy: boolean;
+    isOptimisticCompacting: boolean;
+    hasRetryingAssistant: boolean;
+}): boolean;

package/dist/session/status/session-chat-busy.js

@@ -0,0 +1,15 @@
+/**
+ * Is the session busy, for every surface a user can act on — the Stop button,
+ * the turn shimmer, the question/permission composer locks, and the send
+ * anchoring.
+ *
+ * `hasRetryingAssistant` is a separate term rather than a refinement of
+ * `isServerBusy` because during a provider backoff the runtime's own status
+ * frame is stale by construction: OpenCode emits `session.error` only AFTER its
+ * internal retry ladder is exhausted, so no later `busy` or `retry` frame
+ * follows to correct the slot. The transcript is the only observer that still
+ * proves the turn is open.
+ */
+export function resolveEffectiveBusy(input) {
+    return input.isServerBusy || input.isOptimisticCompacting || input.hasRetryingAssistant;
+}

package/dist/session/status/session-error-banner.d.ts

@@ -0,0 +1,82 @@
+import { type GatewayErrorDetails } from '@kortix/sdk';
+import { type KortixSendError } from '@kortix/sdk/react';
+type TurnErrorGatewayDetails = Pick<GatewayErrorDetails, 'provider' | 'code' | 'suggestion' | 'requestId' | 'attemptFailures' | 'requestedModel' | 'resolvedModel'>;
+/**
+ * Which row a plain-text turn error renders, and whether it opens. The one
+ * decision `TurnErrorDisplay` makes for `errorText`, exported so the debug page
+ * can check it instead of re-deriving it. (A typed send failure can also reach
+ * a billing card through `error.kind`; that path is not described here.)
+ */
+export declare function describeTurnErrorRow({ text, gateway, raw, }: {
+    text: string;
+    gateway?: TurnErrorGatewayDetails;
+    raw?: string;
+}): {
+    kind: 'billing-card' | 'checkpoint';
+    expandable: boolean;
+};
+export declare function actionableSuggestion(suggestion: string | undefined, modelOptions: number | undefined): string | undefined;
+interface TurnErrorDisplayProps {
+    /**
+     * Plain-text error — for turn-level errors derived directly from
+     * `AssistantMessage.error.data.message` via `getTurnError()`, which never go
+     * through `classifySendError` (no typed `error` available for them). Ignored
+     * when `error` is also provided.
+     */
+    errorText?: string;
+    /**
+     * The gateway's structured fields for `errorText` (from
+     * `getTurnErrorDetails()`) — provider/suggestion/request_id computed
+     * server-side by `gatewayErrorBody()`. Ignored when `error` is also
+     * provided (its own `.gateway` wins).
+     */
+    errorDetails?: TurnErrorGatewayDetails | null;
+    /**
+     * The technical text behind `errorText` (from `getTurnErrorRawText()`),
+     * folded beneath the sentence. Omit it when it would only repeat the text.
+     */
+    errorRaw?: string;
+    /** Start with the detail open — the debug page and markup tests use it; the
+     *  transcript leaves the row closed. */
+    defaultDetailsOpen?: boolean;
+    /**
+     * Typed send failure from the SDK's `classifySendError` (send/command/reply
+     * catch paths). When present, billing-vs-runtime routing reads `.kind`
+     * (and `.billing.detail.code` for the credits-vs-usage-limit card) instead
+     * of regexing the message.
+     */
+    error?: KortixSendError | null;
+    /**
+     * Was this turn ACTUALLY aborted — i.e. is the error's identity `AbortError`?
+     *
+     * Passed by the transcript, which can read the structured error on the
+     * message. `getTurnError` flattens that to a display string and drops the
+     * name, so without this the only signal left is the word "abort" appearing
+     * somewhere in the prose — which mislabels genuine failures as user
+     * interruptions and hides what actually went wrong.
+     *
+     * Undefined means "caller could not tell"; the SDK's `isAbortError` last-resort
+     * text sniff (over `text`) is used then.
+     */
+    isAbort?: boolean;
+    /** Models the account can pick — lets the row drop a "choose another model"
+     *  hint the composer cannot honor (KRTX-2598). */
+    modelOptions?: number;
+    className?: string;
+}
+/**
+ * Renders a turn-level or send-failure error inline.
+ *
+ * Abort errors render nothing at all — a stop the user asked for is not a
+ * failure to report back to them, whatever its `AbortReason`.
+ */
+export declare function TurnErrorDisplay({ errorText, errorDetails, errorRaw, defaultDetailsOpen, error, isAbort, modelOptions, className, }: TurnErrorDisplayProps): import("react").JSX.Element | null;
+interface SessionRetryDisplayProps {
+    message: string;
+    attempt: number;
+    secondsLeft: number;
+    details?: GatewayErrorDetails;
+    className?: string;
+}
+export declare function SessionRetryDisplay({ message, attempt, secondsLeft, details, className, }: SessionRetryDisplayProps): import("react").JSX.Element | null;
+export {};