deepspace 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -6966,6 +6966,7 @@ interface IntegrationResponse<T = unknown> {
 interface RequestOptions {
     headers?: Record<string, string>;
     timeoutMs?: number;
+    signal?: AbortSignal;
 }
 declare const integration: {
     post<T = unknown>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<IntegrationResponse<T>>;
@@ -7053,6 +7054,155 @@ type AiStreamAction = {
 /** Decode one v5 UIMessage stream chunk into an action, or `null` to ignore. */
 declare function decodeAiStreamChunk(chunk: AiStreamChunk): AiStreamAction | null;
 
+type LoadState = 'loading' | 'ready' | 'empty' | 'error' | 'signedOut';
+interface LoadStateAuthInput {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    requireSignedIn?: boolean;
+    requireUser?: boolean;
+    userLoading?: boolean;
+}
+interface LoadStateStatusInput {
+    status: 'loading' | 'ready' | 'error' | 'idle' | 'refreshing';
+    error?: unknown;
+}
+interface DeriveLoadStateInput {
+    auth?: LoadStateAuthInput;
+    queries?: LoadStateStatusInput[];
+    resources?: LoadStateStatusInput[];
+    empty?: boolean;
+}
+interface AsyncResourceDefaults {
+    retry: number;
+    retryDelayMs: number;
+    slowAfterMs: number;
+}
+declare const ASYNC_RESOURCE_DEFAULTS: AsyncResourceDefaults;
+declare function isAsyncResourceSlow(input: {
+    startedAt: number;
+    now: number;
+    slowAfterMs: number;
+}): boolean;
+interface PagedResourceCooldownInput {
+    failureCount: number;
+    retryDelayMs: number;
+    maxRetryDelayMs: number;
+}
+declare function getPagedResourceCooldownMs(input: PagedResourceCooldownInput): number;
+declare function canAutoLoadPagedResource(input: {
+    hasMore: boolean;
+    isLoading: boolean;
+    now: number;
+    cooldownUntil: number;
+}): boolean;
+declare function clampPagedResourceItems<T>(input: {
+    items: T[];
+    maxItemsPerPage: number;
+}): {
+    items: T[];
+    droppedItemCount: number;
+};
+declare function deriveLoadState(input: DeriveLoadStateInput): LoadState;
+
+interface UseAuthStatusOptions {
+    requireSignedIn?: boolean;
+}
+interface UseAuthProfileReadyOptions extends UseAuthStatusOptions {
+    requireUser?: boolean;
+}
+/** @deprecated Use `UseAuthProfileReadyOptions` instead. */
+type UseAuthReadyOptions = UseAuthProfileReadyOptions;
+declare function useAuthStatus(options?: UseAuthStatusOptions): {
+    status: LoadState;
+    isReady: boolean;
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    userId: string | null;
+    sessionId: string | null;
+};
+declare function useAuthProfileReady(options?: UseAuthProfileReadyOptions): {
+    user: User | null;
+    userLoading: boolean;
+    refetchUser: () => Promise<void>;
+    status: LoadState;
+    isReady: boolean;
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    userId: string | null;
+    sessionId: string | null;
+};
+/** @deprecated Use `useAuthStatus` for auth-only UI or `useAuthProfileReady` for profile-backed UI. */
+declare const useAuthReady: typeof useAuthProfileReady;
+type AsyncResourceStatus = 'idle' | 'loading' | 'ready' | 'error';
+type PagedResourceStatus = AsyncResourceStatus;
+interface AsyncResourceState<T> {
+    status: AsyncResourceStatus;
+    data: T | null;
+    error: string | null;
+    isRefreshing: boolean;
+    isSlow: boolean;
+    retryCount: number;
+}
+interface UseAsyncResourceOptions<T> {
+    enabled?: boolean;
+    initialData?: T | null;
+    keepPreviousData?: boolean;
+    retry?: number;
+    retryDelayMs?: number;
+    slowAfterMs?: number;
+}
+interface PagedResourceFetchArgs {
+    page: number;
+    pageSize: number;
+    signal: AbortSignal;
+}
+interface PagedResourcePage<T> {
+    items: T[];
+    hasMore?: boolean;
+}
+interface PagedResourceState<T> {
+    status: PagedResourceStatus;
+    items: T[];
+    error: string | null;
+    warning: string | null;
+    hasMore: boolean;
+    isLoadingInitial: boolean;
+    isLoadingMore: boolean;
+    isRefreshing: boolean;
+}
+interface UsePagedResourceOptions<T> {
+    enabled?: boolean;
+    initialItems?: T[];
+    pageSize?: number;
+    maxItemsPerPage?: number;
+    keepPreviousData?: boolean;
+    autoRetryOnError?: boolean;
+    retryDelayMs?: number;
+    maxRetryDelayMs?: number;
+}
+declare function useAsyncResource<T>(fetcher: (signal: AbortSignal) => Promise<T>, deps: readonly unknown[], options?: UseAsyncResourceOptions<T>): {
+    reload: () => void;
+    status: AsyncResourceStatus;
+    data: T | null;
+    error: string | null;
+    isRefreshing: boolean;
+    isSlow: boolean;
+    retryCount: number;
+};
+declare function usePagedResource<T>(fetchPage: (args: PagedResourceFetchArgs) => Promise<PagedResourcePage<T>>, deps: readonly unknown[], options?: UsePagedResourceOptions<T>): {
+    loadMore: () => void;
+    retry: () => void;
+    refresh: () => void;
+    status: PagedResourceStatus;
+    items: T[];
+    error: string | null;
+    warning: string | null;
+    hasMore: boolean;
+    isLoadingInitial: boolean;
+    isLoadingMore: boolean;
+    isRefreshing: boolean;
+};
+
 /**
  * Subscription primitives shared between client (useSubscription hook) and
  * server (requireSubscription helper). Pulled into a shared module so the
@@ -7447,6 +7597,43 @@ interface ToastProviderProps {
 }
 declare function ToastProvider({ children, position, maxToasts, }: ToastProviderProps): React__default.ReactElement;
 
+/**
+ * Error decoding + a friendly error screen.
+ *
+ * Production React replaces error text with a numeric code and a docs link
+ * (e.g. `Minified React error #310`), so a developer whose app crashes in a
+ * deployed build sees only the number. `decodeReactError` turns that number
+ * back into a plain-English explanation; `ErrorScreen` renders it. The most
+ * common offenders are the hook-order errors (#300 / #310), which almost
+ * always mean a hook was placed after an early `return`.
+ */
+interface DecodedReactError {
+    code: number;
+    title: string;
+    explanation: string;
+    hint: string;
+    docsUrl: string;
+}
+/**
+ * Decode a (possibly minified) React error into a friendly explanation, or
+ * `null` if it isn't a recognizable React error — in which case the caller
+ * should just show the raw message.
+ */
+declare function decodeReactError(error: unknown): DecodedReactError | null;
+interface ErrorScreenProps {
+    /** The thrown value, as caught by an error boundary (often non-Error). */
+    error: unknown;
+    /** Recovery action. Defaults to a full page reload. */
+    onReset?: () => void;
+}
+/**
+ * A self-contained crash screen. Renders standalone — it replaces the app
+ * shell when used as a root error boundary, so it must not depend on app
+ * providers (toasts, auth, theme context). It reuses only context-free
+ * primitives and reads its colors from the active theme's CSS variables.
+ */
+declare function ErrorScreen({ error, onReset }: ErrorScreenProps): react_jsx_runtime.JSX.Element;
+
 interface EmptyStateProps extends React__default.HTMLAttributes<HTMLDivElement> {
     icon?: ReactNode;
     title: string;
@@ -7595,4 +7782,4 @@ interface SearchInputProps extends Omit<React$1.ComponentProps<'input'>, 'type'>
 }
 declare const SearchInput: React$1.ForwardRefExoticComponent<Omit<SearchInputProps, "ref"> & React$1.RefAttributes<HTMLInputElement>>;
 
-export { type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, Alert, AlertDescription, AlertTitle, AuthGate, type AuthGateProps, AuthOverlay, Avatar, AvatarFallback, AvatarImage, Awareness, type AwarenessState, type AwarenessStates, Badge, type BadgeProps, type BaseMessage, Button, type ButtonProps, type CanvasShapeClient, Card, CardContent, CardDescription, CardFooter, CardGrid, CardHeader, CardTitle, type Channel, type ChannelInvitation, type ChannelMember, type ChargeOnceOpts, type ChargeOnceResult, Checkbox, type ClientMessage, type CollectionSchema, ConfirmModal, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronTaskState, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, ENV, EmptyDocuments, EmptyError, EmptyItems, EmptyProjects, EmptySearch, EmptyState, EmptyTeam, type Environment, type FetchUserProfile, type FileAttachment, type GamePlayer, GridCard, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, Input, type IntegrationResponse, type JobStatusView, type JobView, Label, type LinkPreviewData, LoadingOverlay, LoadingSpinner, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MemberRecord, type Message, type MessageHandlers, type MessageRecord, Modal, type MsgType, type PlanInfo, PlatformContext, type PlatformContextValue, PlatformProvider, type PlatformWSOptions, type PlatformWSResult, type PresencePeerClient, PricingTable, type PricingTablePlan, type PricingTablePrice, type ProductChargeOpts, Progress, type ProtocolMessage, type Purchase, type Query, type R2FileInfo, type R2Scope, type R2UploadResult, ROLES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_CONFIG, ROLE_DEFAULT, type Reaction, type ReactionRecord, type ReadCursorRecord, type ReadReceipt, type RecordData, RecordProvider, type RecordProviderProps, RecordScope, type RequestOptions, type Role, type RoomUser, type ScopeEntry, ScopeRegistryProvider, SearchInput, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type ServerMessage, SignedIn, SignedOut, Skeleton, SkeletonAvatar, SkeletonCard, SkeletonList, SkeletonTable, SkeletonText, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, Switch, type SyncResult, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, ToastProvider, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, type UseGameRoomResult, type UseJobsResult, type UsePresenceRoomResult, type UseR2FilesReturn, type UseYjsFieldResult, type UseYjsRoomResult, type UseYjsTextResult, type User, type UserCredits, type UserInfo, type UserKarma, type UserProfile, type ViewportClient, applyDeepSpaceTheme, applyUIThemeTokens, authClient, badgeVariants, buttonVariants, clearAuthToken, clearDeepSpaceTheme, clientBuild, cn, createDecoder, createEncoder, decodeAiStreamChunk, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getEnvironmentConfig, getMessageType, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, integration, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, resetEnvironmentCache, serverBuild, shouldGroupMessages, signIn, signOut, toConnectionStatus, toUint8Array, useAuth, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, useGameRoom, useInbox, useIsDarkTheme, useJobs, useMessages, useMutations, usePlatform, usePlatformWS, usePosts, usePresence, usePresenceRoom, useQuery, useR2Files, useReactions, useReadReceipts, useRecordContext, useSession, useSubscription, useToast, useUser, useUserLookup, useUsers, useYjsField, useYjsRoom, useYjsText, writeVarUint, writeVarUint8Array };
+export { ASYNC_RESOURCE_DEFAULTS, type AdHocChargeOpts, type AiStreamAction, type AiStreamChunk, Alert, AlertDescription, AlertTitle, type AsyncResourceDefaults, type AsyncResourceState, type AsyncResourceStatus, AuthGate, type AuthGateProps, AuthOverlay, Avatar, AvatarFallback, AvatarImage, Awareness, type AwarenessState, type AwarenessStates, Badge, type BadgeProps, type BaseMessage, Button, type ButtonProps, type CanvasShapeClient, Card, CardContent, CardDescription, CardFooter, CardGrid, CardHeader, CardTitle, type Channel, type ChannelInvitation, type ChannelMember, type ChargeOnceOpts, type ChargeOnceResult, Checkbox, type ClientMessage, type CollectionSchema, ConfirmModal, type ConnectionAttachment, type ConnectionStatus, type ContentSegment, type ConversationObject, type CronHistoryEntry, type CronTaskState, DEEPSPACE_THEME_PROPERTIES, DEFAULT_USER_COLORS, type DecodedReactError, DeepSpaceAuthProvider, type DeepSpaceThemeConfig, DeepSpaceThemeProvider, type DeepSpaceThemeProviderProps, type DeriveLoadStateInput, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, ENV, EmptyDocuments, EmptyError, EmptyItems, EmptyProjects, EmptySearch, EmptyState, EmptyTeam, type Environment, ErrorScreen, type ErrorScreenProps, type FetchUserProfile, type FileAttachment, type GamePlayer, GridCard, type GroupedReaction, GuestBanner, type HandlerContext, type InboxEntry, Input, type IntegrationResponse, type JobStatusView, type JobView, Label, type LinkPreviewData, type LoadState, type LoadStateAuthInput, type LoadStateStatusInput, LoadingOverlay, LoadingSpinner, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MemberRecord, type Message, type MessageHandlers, type MessageRecord, Modal, type MsgType, type PagedResourceFetchArgs, type PagedResourcePage, type PagedResourceState, type PagedResourceStatus, type PlanInfo, PlatformContext, type PlatformContextValue, PlatformProvider, type PlatformWSOptions, type PlatformWSResult, type PresencePeerClient, PricingTable, type PricingTablePlan, type PricingTablePrice, type ProductChargeOpts, Progress, type ProtocolMessage, type Purchase, type Query, type R2FileInfo, type R2Scope, type R2UploadResult, ROLES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_CONFIG, ROLE_DEFAULT, type Reaction, type ReactionRecord, type ReadCursorRecord, type ReadReceipt, type RecordData, RecordProvider, type RecordProviderProps, RecordScope, type RequestOptions, type Role, type RoomUser, type ScopeEntry, ScopeRegistryProvider, SearchInput, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type ServerMessage, SignedIn, SignedOut, Skeleton, SkeletonAvatar, SkeletonCard, SkeletonList, SkeletonTable, SkeletonText, type SubscribeOpts, type SubscribeResult, type SubscriptionState, type SubscriptionStatus, Switch, type SyncResult, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, ToastProvider, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UseAsyncResourceOptions, type UseAuthProfileReadyOptions, type UseAuthReadyOptions, type UseAuthStatusOptions, type UseCanvasResult, type UseCheckoutOpts, type UseCronMonitorResult, type UseGameRoomResult, type UseJobsResult, type UsePagedResourceOptions, type UsePresenceRoomResult, type UseR2FilesReturn, type UseYjsFieldResult, type UseYjsRoomResult, type UseYjsTextResult, type User, type UserCredits, type UserInfo, type UserKarma, type UserProfile, type ViewportClient, applyDeepSpaceTheme, applyUIThemeTokens, authClient, badgeVariants, buttonVariants, canAutoLoadPagedResource, clampPagedResourceItems, clearAuthToken, clearDeepSpaceTheme, clientBuild, cn, createDecoder, createEncoder, decodeAiStreamChunk, decodeReactError, deriveLoadState, detectEnvironment, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, formatFileSize, formatFullTimestamp, formatMessageTime, getApiUrl, getAuthToken, getAuthUrl, getConversationDisplayName, getConversationParticipantIds, getEnvironmentConfig, getMessageType, getPagedResourceCooldownMs, getPlatformWorkerUrl, getThreadCounts, getUserColor, groupReactionsForMessage, handleAwarenessMessage, handleSyncMessage, hasContent, integration, isAsyncResourceSlow, isDMConversation, isDarkColor, isImageFile, isLocalDev, isProduction, parseMessageMetadata, parseSseLine, readThemeFromDOM, readVarUint, readVarUint8Array, resetEnvironmentCache, serverBuild, shouldGroupMessages, signIn, signOut, toConnectionStatus, toUint8Array, useAsyncResource, useAuth, useAuthProfileReady, useAuthReady, useAuthStatus, useAuthUser, useCanvas, useChannelMembers, useChannels, useCheckout, useCommunities, useConversation, useConversations, useCronMonitor, useDisplayName, useGameRoom, useInbox, useIsDarkTheme, useJobs, useMessages, useMutations, usePagedResource, usePlatform, usePlatformWS, usePosts, usePresence, usePresenceRoom, useQuery, useR2Files, useReactions, useReadReceipts, useRecordContext, useSession, useSubscription, useToast, useUser, useUserLookup, useUsers, useYjsField, useYjsRoom, useYjsText, writeVarUint, writeVarUint8Array };