lemma-sdk 0.2.31 → 0.2.33

package/dist/react/useAssistantController.js

@@ -541,7 +541,6 @@ function isConversationRunning(status) {
 }
 export function useAssistantController({ client, podId, assistantName, assistantId, organizationId, enabled = true, }) {
     const [localError, setLocalError] = useState(null);
-    const [messages, setMessages] = useState([]);
     const [conversations, setConversations] = useState([]);
     const [activeConversationId, setActiveConversationId] = useState(null);
     const [availableModels, setAvailableModels] = useState([]);
@@ -555,10 +554,14 @@ export function useAssistantController({ client, podId, assistantName, assistant
     const [olderMessagesCursor, setOlderMessagesCursor] = useState(null);
     const activeConversationIdRef = useRef(null);
     const conversationsRef = useRef([]);
+    const isStreamingRef = useRef(false);
+    const sessionIsStreamingRef = useRef(false);
     const suppressAutoSelectRef = useRef(false);
     const lastAutoLoadedConversationIdRef = useRef(null);
     const loadingConversationIdRef = useRef(null);
     const skipInitialLoadConversationIdsRef = useRef(new Set());
+    const loadConversationMessagesRef = useRef(null);
+    const resumeIfRunningRef = useRef(null);
     const scope = useMemo(() => ({
         podId: podId ?? null,
         assistantName: assistantName ?? assistantId ?? null,
@@ -715,12 +718,24 @@ export function useAssistantController({ client, podId, assistantName, assistant
             setIsLoadingOlderMessages(false);
         }
     }, [isLoadingMessages, isLoadingOlderMessages, mergeMessages, olderMessagesCursor, sessionLoadMessages]);
+    useEffect(() => {
+        loadConversationMessagesRef.current = loadConversationMessages;
+    }, [loadConversationMessages]);
+    useEffect(() => {
+        resumeIfRunningRef.current = sessionResumeIfRunning;
+    }, [sessionResumeIfRunning]);
     useEffect(() => {
         activeConversationIdRef.current = activeConversationId;
     }, [activeConversationId]);
     useEffect(() => {
         conversationsRef.current = conversations;
     }, [conversations]);
+    useEffect(() => {
+        isStreamingRef.current = isStreaming;
+    }, [isStreaming]);
+    useEffect(() => {
+        sessionIsStreamingRef.current = sessionIsStreaming;
+    }, [sessionIsStreaming]);
     useEffect(() => {
         if (!enabled) {
             setAvailableModels([]);
@@ -738,22 +753,17 @@ export function useAssistantController({ client, podId, assistantName, assistant
             cancelled = true;
         };
     }, [enabled, loadAvailableModels]);
-    useEffect(() => {
-        const conversationId = activeConversationIdRef.current;
-        if (!conversationId) {
-            setMessages([]);
-            return;
-        }
+    const messages = useMemo(() => {
+        if (!activeConversationId)
+            return [];
         const normalized = sortMessagesByCreatedAt(runtimeMessages)
-            .filter((message) => message.conversation_id === conversationId);
-        if (normalized.length === 0) {
-            setMessages([]);
-            return;
-        }
+            .filter((message) => message.conversation_id === activeConversationId);
+        if (normalized.length === 0)
+            return [];
         const nextMessages = mapConversationMessages(normalized);
         const pendingText = sessionStreamingText.trim();
         if (pendingText.length > 0) {
-            const streamingId = `streaming-${conversationId}`;
+            const streamingId = `streaming-${activeConversationId}`;
             nextMessages.push({
                 id: streamingId,
                 role: "assistant",
@@ -762,8 +772,8 @@ export function useAssistantController({ client, podId, assistantName, assistant
                 parts: [{ id: `${streamingId}-text`, type: "text", text: pendingText }],
             });
         }
-        setMessages(nextMessages);
-    }, [runtimeMessages, sessionStreamingText]);
+        return nextMessages;
+    }, [activeConversationId, runtimeMessages, sessionStreamingText]);
     useEffect(() => {
         if (!activeConversationId)
             return;
@@ -794,7 +804,6 @@ export function useAssistantController({ client, podId, assistantName, assistant
             setAvailableModels([]);
             setConversationModelState(null);
             setConversations([]);
-            setMessages([]);
             setLocalError(null);
             setOlderMessagesCursor(null);
             setIsLoadingConversations(false);
@@ -810,7 +819,6 @@ export function useAssistantController({ client, podId, assistantName, assistant
         setActiveConversationId(null);
         setConversationModelState(null);
         setConversations([]);
-        setMessages([]);
         setLocalError(null);
         clearRuntimeMessages();
         setOlderMessagesCursor(null);
@@ -823,7 +831,6 @@ export function useAssistantController({ client, podId, assistantName, assistant
             clearRuntimeMessages();
             lastAutoLoadedConversationIdRef.current = null;
             loadingConversationIdRef.current = null;
-            setMessages([]);
             setOlderMessagesCursor(null);
             return;
         }
@@ -842,12 +849,12 @@ export function useAssistantController({ client, podId, assistantName, assistant
         loadingConversationIdRef.current = activeConversationId;
         const loadConversation = async () => {
             setOlderMessagesCursor(null);
-            await loadConversationMessages(activeConversationId);
+            await loadConversationMessagesRef.current?.(activeConversationId);
             if (cancelled)
                 return;
             lastAutoLoadedConversationIdRef.current = activeConversationId;
             try {
-                await sessionResumeIfRunning(activeConversationId);
+                await resumeIfRunningRef.current?.(activeConversationId);
             }
             catch (error) {
                 if (cancelled)
@@ -863,9 +870,9 @@ export function useAssistantController({ client, podId, assistantName, assistant
         return () => {
             cancelled = true;
         };
-    }, [activeConversationId, clearRuntimeMessages, enabled, loadConversationMessages, sessionResumeIfRunning]);
+    }, [activeConversationId, clearRuntimeMessages, enabled]);
     const stop = useCallback(() => {
-        const hadActiveStream = sessionIsStreaming || isStreaming;
+        const hadActiveStream = sessionIsStreamingRef.current || isStreamingRef.current;
         sessionCancel();
         setIsStreaming(false);
         const conversationId = activeConversationIdRef.current;
@@ -881,13 +888,34 @@ export function useAssistantController({ client, podId, assistantName, assistant
             touchConversation(conversationId, { status: previousStatus });
             setLocalError((prev) => prev || (error instanceof Error ? error.message : "Failed to stop conversation"));
         });
-    }, [isStreaming, sessionCancel, sessionIsStreaming, sessionStop, touchConversation]);
+    }, [sessionCancel, sessionStop, touchConversation]);
     const selectConversation = useCallback((conversationId) => {
-        if (sessionIsStreaming || isStreaming) {
+        if (sessionIsStreamingRef.current || isStreamingRef.current) {
             sessionCancel();
             setIsStreaming(false);
         }
-        const wasSameConversation = conversationId && conversationId === activeConversationIdRef.current;
+        const currentConversationId = activeConversationIdRef.current;
+        if (conversationId && conversationId === currentConversationId) {
+            if (loadingConversationIdRef.current === conversationId
+                || lastAutoLoadedConversationIdRef.current === conversationId) {
+                return;
+            }
+            loadingConversationIdRef.current = conversationId;
+            setLocalError(null);
+            setOlderMessagesCursor(null);
+            void loadConversationMessagesRef.current?.(conversationId)
+                .then(() => resumeIfRunningRef.current?.(conversationId))
+                .catch((error) => {
+                setLocalError((prev) => prev || (error instanceof Error ? error.message : "Failed to resume conversation"));
+            })
+                .finally(() => {
+                if (loadingConversationIdRef.current === conversationId) {
+                    loadingConversationIdRef.current = null;
+                }
+                lastAutoLoadedConversationIdRef.current = conversationId;
+            });
+            return;
+        }
         suppressAutoSelectRef.current = conversationId === null;
         setLocalError(null);
         activeConversationIdRef.current = conversationId;
@@ -895,15 +923,8 @@ export function useAssistantController({ client, podId, assistantName, assistant
         loadingConversationIdRef.current = null;
         setOlderMessagesCursor(null);
         clearRuntimeMessages();
-        setMessages([]);
-        if (wasSameConversation) {
-            void loadConversationMessages(conversationId);
-            void sessionResumeIfRunning(conversationId).catch((error) => {
-                setLocalError((prev) => prev || (error instanceof Error ? error.message : "Failed to resume conversation"));
-            });
-        }
         setActiveConversationId(conversationId);
-    }, [clearRuntimeMessages, isStreaming, loadConversationMessages, sessionCancel, sessionIsStreaming, sessionResumeIfRunning]);
+    }, [clearRuntimeMessages, sessionCancel]);
     const resetConversationState = useCallback((keepPendingFiles = false) => {
         stop();
         clearRuntimeMessages();
@@ -913,7 +934,6 @@ export function useAssistantController({ client, podId, assistantName, assistant
         loadingConversationIdRef.current = null;
         skipInitialLoadConversationIdsRef.current.clear();
         setActiveConversationId(null);
-        setMessages([]);
         setLocalError(null);
         setOlderMessagesCursor(null);
         if (!keepPendingFiles) {
@@ -945,7 +965,6 @@ export function useAssistantController({ client, podId, assistantName, assistant
         setActiveConversationId(createdConversation.id);
         setConversationModelState((createdConversation.model ?? conversationModel ?? null));
         clearRuntimeMessages();
-        setMessages([]);
         setOlderMessagesCursor(null);
         return createdConversation.id;
     }, [clearRuntimeMessages, conversationModel, scope, sessionCreateConversation]);
@@ -1099,7 +1118,7 @@ export function useAssistantController({ client, podId, assistantName, assistant
         const activeConversation = conversations.find((conversation) => conversation.id === activeConversationId);
         return isConversationRunning(activeConversation?.status);
     }, [activeConversationId, conversations]);
-    return {
+    return useMemo(() => ({
         messages,
         conversations,
         activeConversationId,
@@ -1125,5 +1144,31 @@ export function useAssistantController({ client, podId, assistantName, assistant
         loadOlderMessages,
         clearMessages,
         stop,
-    };
+    }), [
+        activeConversationId,
+        availableModels,
+        clearMessages,
+        clearPendingFiles,
+        completedActions,
+        conversationModel,
+        conversations,
+        error,
+        isActiveConversationRunning,
+        isLoading,
+        isLoadingConversations,
+        isLoadingMessages,
+        isLoadingOlderMessages,
+        isUploadingFiles,
+        loadOlderMessages,
+        messages,
+        olderMessagesCursor,
+        pendingActions,
+        pendingFiles,
+        removePendingFile,
+        selectConversation,
+        sendMessage,
+        setConversationModel,
+        stop,
+        uploadFiles,
+    ]);
 }

package/dist/react/useAssistantRuntime.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -115,6 +115,7 @@ export function useAssistantRuntime({ conversationId = null, sessionConversation
         setRuntimeMessages([]);
     }, []);
     useEffect(() => {
+        lastSessionMessageIdRef.current = null;
         setRuntimeMessages((previous) => {
             if (!conversationId) {
                 return [];
@@ -122,12 +123,15 @@ export function useAssistantRuntime({ conversationId = null, sessionConversation
             return previous.filter((message) => message.conversation_id === conversationId);
         });
     }, [conversationId]);
+    const lastSessionMessageIdRef = useRef(null);
     useEffect(() => {
         if (sessionMessages.length === 0)
             return;
-        // Session message state can lag one render behind active conversation
-        // updates. Prefer the session's own conversation id as fallback so we
-        // never relabel stale messages into the newly selected thread.
+        const lastSessionMessage = sessionMessages[sessionMessages.length - 1];
+        const lastSessionId = lastSessionMessage?.id ?? null;
+        if (lastSessionId && lastSessionId === lastSessionMessageIdRef.current)
+            return;
+        lastSessionMessageIdRef.current = lastSessionId;
         const fallbackConversationId = sessionConversationId ?? conversationId;
         const normalized = sessionMessages
             .map((message) => toRuntimeMessage(message, fallbackConversationId))

package/dist/react/useAssistantSession.js

@@ -61,6 +61,8 @@ export function useAssistantSession(options) {
     const statusRef = useRef(undefined);
     const streamingTextRef = useRef("");
     const autoResumedKeyRef = useRef(null);
+    const autoLoadInFlightKeyRef = useRef(null);
+    const lastAutoLoadedKeyRef = useRef(null);
     const onEventRef = useRef(onEvent);
     const onStatusRef = useRef(onStatus);
     const onMessageRef = useRef(onMessage);
@@ -73,6 +75,8 @@ export function useAssistantSession(options) {
                 return currentConversationId;
             }
             autoResumedKeyRef.current = null;
+            autoLoadInFlightKeyRef.current = null;
+            lastAutoLoadedKeyRef.current = null;
             streamingTextRef.current = "";
             setStreamingText("");
             setConversation(null);
@@ -113,7 +117,12 @@ export function useAssistantSession(options) {
             onStatusRef.current?.(normalized);
         }
     }, []);
+    const pendingStreamingFlushRef = useRef(null);
     const clearStreamingText = useCallback(() => {
+        if (pendingStreamingFlushRef.current) {
+            clearTimeout(pendingStreamingFlushRef.current);
+            pendingStreamingFlushRef.current = null;
+        }
         streamingTextRef.current = "";
         setStreamingText("");
     }, []);
@@ -121,7 +130,19 @@ export function useAssistantSession(options) {
         if (!token)
             return;
         streamingTextRef.current += token;
-        setStreamingText(streamingTextRef.current);
+        if (!pendingStreamingFlushRef.current) {
+            pendingStreamingFlushRef.current = setTimeout(() => {
+                pendingStreamingFlushRef.current = null;
+                setStreamingText(streamingTextRef.current);
+            }, 0);
+        }
+    }, []);
+    useEffect(() => {
+        return () => {
+            if (pendingStreamingFlushRef.current) {
+                clearTimeout(pendingStreamingFlushRef.current);
+            }
+        };
     }, []);
     const cancel = useCallback(() => {
         abortRef.current?.abort();
@@ -485,10 +506,18 @@ export function useAssistantSession(options) {
     }, [status]);
     useEffect(() => {
         if (!autoLoad || !conversationId) {
+            autoLoadInFlightKeyRef.current = null;
+            lastAutoLoadedKeyRef.current = null;
+            return;
+        }
+        const bootstrapKey = `${conversationId}:${autoResume ? "resume" : "load"}`;
+        if (autoLoadInFlightKeyRef.current === bootstrapKey
+            || lastAutoLoadedKeyRef.current === bootstrapKey) {
             return;
         }
         const controller = new AbortController();
         let cancelled = false;
+        autoLoadInFlightKeyRef.current = bootstrapKey;
         const bootstrapConversation = async () => {
             const latestConversation = await refreshConversation(conversationId);
             if (cancelled)
@@ -503,7 +532,20 @@ export function useAssistantSession(options) {
                 return;
             await resumeIfRunning(conversationId);
         };
-        void bootstrapConversation();
+        void bootstrapConversation()
+            .catch((bootstrapError) => {
+            if (cancelled)
+                return;
+            const normalized = normalizeError(bootstrapError, "Failed to load assistant conversation.");
+            setError(normalized);
+            onErrorRef.current?.(bootstrapError);
+        })
+            .finally(() => {
+            if (autoLoadInFlightKeyRef.current === bootstrapKey) {
+                autoLoadInFlightKeyRef.current = null;
+            }
+            lastAutoLoadedKeyRef.current = bootstrapKey;
+        });
         return () => {
             cancelled = true;
             controller.abort();

package/dist/react/useConversationMessages.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extractConversationMessageText, getLatestAssistantMessage, isConversationRunningStatus, normalizeConversationStatus, sortConversationMessagesByCreatedAt, } from "./assistant-output.js";
 import { useAssistantSession, } from "./useAssistantSession.js";
 function resolveConversationId(preferred, fallback) {
@@ -16,6 +16,8 @@ export function useConversationMessages({ client, podId, assistantName, assistan
     const [nextPageToken, setNextPageToken] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
     const [isLoadingOlder, setIsLoadingOlder] = useState(false);
+    const autoLoadInFlightKeyRef = useRef(null);
+    const lastAutoLoadedKeyRef = useRef(null);
     const { conversation: sessionConversation, conversationId: sessionConversationId, messages: sessionMessages, status, streamingText, isStreaming, error, refreshConversation, loadMessages, sendMessage, resume, resumeIfRunning, stop, cancel, clearMessages: clearSessionMessages, createConversation, } = useAssistantSession({
         client,
         podId,
@@ -74,6 +76,8 @@ export function useConversationMessages({ client, podId, assistantName, assistan
     }, [enabled, isLoading, isLoadingOlder, limit, loadMessages, nextPageToken, sessionConversationId]);
     useEffect(() => {
         if (!enabled || !conversationId) {
+            autoLoadInFlightKeyRef.current = null;
+            lastAutoLoadedKeyRef.current = null;
             setNextPageToken(null);
             setIsLoading(false);
             setIsLoadingOlder(false);
@@ -84,6 +88,12 @@ export function useConversationMessages({ client, podId, assistantName, assistan
         setNextPageToken(null);
         if (!autoLoad)
             return;
+        const bootstrapKey = `${conversationId}:${limit}:${autoResume ? "resume" : "load"}`;
+        if (autoLoadInFlightKeyRef.current === bootstrapKey
+            || lastAutoLoadedKeyRef.current === bootstrapKey) {
+            return;
+        }
+        autoLoadInFlightKeyRef.current = bootstrapKey;
         let cancelled = false;
         const bootstrap = async () => {
             await refresh({ conversationId, limit });
@@ -91,7 +101,14 @@ export function useConversationMessages({ client, podId, assistantName, assistan
                 return;
             await resumeIfRunning(conversationId);
         };
-        void bootstrap();
+        void bootstrap()
+            .catch(() => undefined)
+            .finally(() => {
+            if (autoLoadInFlightKeyRef.current === bootstrapKey) {
+                autoLoadInFlightKeyRef.current = null;
+            }
+            lastAutoLoadedKeyRef.current = bootstrapKey;
+        });
         return () => {
             cancelled = true;
         };

package/dist/react/useCreateRecord.d.ts

@@ -1,11 +1,41 @@
 import type { LemmaClient } from "../client.js";
-import type { RecordResponse } from "../types.js";
+import type { FunctionRun, RecordResponse } from "../types.js";
+/**
+ * React hook for creating a single record. Manages loading/error state and
+ * exposes a `create` function you can call from event handlers.
+ *
+ * Supports two modes:
+ * - `"direct"` (default): calls `records.create` directly.
+ * - `"function"`: calls `functions.runs.create`, routing the create through
+ *   a pod function that may enforce business logic.
+ *
+ * @example Direct create
+ * ```tsx
+ * const { create, isSubmitting } = useCreateRecord({ client, tableName: "comments" });
+ * await create({ body: "Hello", issue_id: "123" });
+ * ```
+ *
+ * @example Function-backed create
+ * ```tsx
+ * const { create, isSubmitting } = useCreateRecord({
+ *   client,
+ *   tableName: "issues",
+ *   createVia: "function",
+ *   createFunctionName: "create-issue",
+ * });
+ * await create({ title: "Bug", team_id: "team_1" });
+ * ```
+ */
 export interface UseCreateRecordOptions {
     client: LemmaClient;
     podId?: string;
     tableName: string;
     enabled?: boolean;
-    onSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    /** How the record is created. `"direct"` calls `records.create`. `"function"` calls `functions.runs.create`. */
+    createVia?: "direct" | "function";
+    /** Function name to run when `createVia` is `"function"`. Falls back to `tableName` if omitted. */
+    createFunctionName?: string;
+    onSuccess?: (record: Record<string, unknown>, response: RecordResponse | FunctionRun) => void;
     onError?: (error: unknown) => void;
 }
 export interface UseCreateRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
@@ -15,4 +45,4 @@ export interface UseCreateRecordResult<TRecord extends Record<string, unknown> =
     create: (data: Record<string, unknown>) => Promise<TRecord | null>;
     reset: () => void;
 }
-export declare function useCreateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, enabled, onSuccess, onError, }: UseCreateRecordOptions): UseCreateRecordResult<TRecord>;
+export declare function useCreateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, enabled, createVia, createFunctionName, onSuccess, onError, }: UseCreateRecordOptions): UseCreateRecordResult<TRecord>;

package/dist/react/useCreateRecord.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { normalizeError, resolvePodClient } from "./utils.js";
-export function useCreateRecord({ client, podId, tableName, enabled = true, onSuccess, onError, }) {
+export function useCreateRecord({ client, podId, tableName, enabled = true, createVia = "direct", createFunctionName, onSuccess, onError, }) {
     const [createdRecord, setCreatedRecord] = useState(null);
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [error, setError] = useState(null);
@@ -18,6 +18,16 @@ export function useCreateRecord({ client, podId, tableName, enabled = true, onSu
         setError(null);
         try {
             const scopedClient = resolvePodClient(client, podId);
+            if (createVia === "function") {
+                const functionName = createFunctionName ?? trimmedTableName;
+                const run = await scopedClient.functions.runs.create(functionName, { input: data });
+                const nextRecord = (run.output_data ?? { id: run.id, ...data });
+                setCreatedRecord(nextRecord);
+                if (nextRecord) {
+                    onSuccessRef.current?.(nextRecord, run);
+                }
+                return nextRecord;
+            }
             const response = await scopedClient.records.create(trimmedTableName, data);
             const nextRecord = (response.data ?? null);
             setCreatedRecord(nextRecord);
@@ -35,7 +45,7 @@ export function useCreateRecord({ client, podId, tableName, enabled = true, onSu
         finally {
             setIsSubmitting(false);
         }
-    }, [client, isEnabled, podId, trimmedTableName]);
+    }, [client, createFunctionName, createVia, isEnabled, podId, trimmedTableName]);
     const reset = useCallback(() => {
         setCreatedRecord(null);
         setError(null);

package/dist/react/useFile.d.ts

@@ -0,0 +1,18 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface UseFileOptions {
+    client: LemmaClient;
+    podId?: string;
+    path?: string | null;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseFileResult {
+    file: FileResponse | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        path?: string | null;
+    }) => Promise<FileResponse | null>;
+}
+export declare function useFile({ client, podId, path, enabled, autoLoad, }: UseFileOptions): UseFileResult;

package/dist/react/useFile.js

@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useFile({ client, podId, path = null, enabled = true, autoLoad = true, }) {
+    const [file, setFile] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedPath = typeof path === "string" ? path.trim() : "";
+    const isEnabled = enabled && trimmedPath.length > 0;
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        const nextPath = typeof overrides.path === "string" ? overrides.path.trim() : trimmedPath;
+        if (!enabled || nextPath.length === 0) {
+            setFile(null);
+            setError(null);
+            setIsLoading(false);
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextFile = await scopedClient.files.get(nextPath);
+            if (signal?.aborted)
+                return null;
+            setFile(nextFile);
+            return nextFile;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return null;
+            setError(normalizeError(refreshError, "Failed to load file."));
+            setFile(null);
+            return null;
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, podId, trimmedPath]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setFile(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        void refresh({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        file,
+        isLoading,
+        error,
+        refresh,
+    }), [error, file, isLoading, refresh]);
+}

package/dist/react/useFilePreview.d.ts

@@ -0,0 +1,23 @@
+import type { LemmaClient } from "../client.js";
+export type FilePreviewMode = "rendered" | "artifact";
+export interface UseFilePreviewOptions {
+    client: LemmaClient;
+    podId?: string;
+    path?: string | null;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    mode?: FilePreviewMode;
+    artifact?: string;
+}
+export interface UseFilePreviewResult {
+    content: string | null;
+    blob: Blob | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        path?: string | null;
+        mode?: FilePreviewMode;
+        artifact?: string;
+    }) => Promise<string | null>;
+}
+export declare function useFilePreview({ client, podId, path, enabled, autoLoad, mode, artifact, }: UseFilePreviewOptions): UseFilePreviewResult;