(readArtifactAppsViewMode);
+ const debouncedSearchQuery = useDebounce(searchQuery.trim(), 300);
+ const {
+ data,
+ isError,
+ isLoading,
+ isFetching,
+ hasNextPage,
+ fetchNextPage,
+ isFetchingNextPage,
+ refetch,
+ } = useListArtifactAppsQuery(scope, debouncedSearchQuery);
+ const pinnedArtifactIds =
+ pinnedArtifactState.scope === activityStorageScope
+ ? pinnedArtifactState.value
+ : EMPTY_PINNED_ARTIFACT_IDS;
+ const viewedArtifactTimes =
+ viewedArtifactState.scope === activityStorageScope
+ ? viewedArtifactState.value
+ : EMPTY_VIEWED_ARTIFACT_TIMES;
+ const loadedApps = useMemo(() => data?.pages.flatMap((page) => page.apps) ?? [], [data]);
+ const apps = useMemo(() => {
+ return [...loadedApps].sort((first, second) => {
+ const firstPinned = pinnedArtifactIds.has(first.artifactAppId);
+ const secondPinned = pinnedArtifactIds.has(second.artifactAppId);
+ return Number(secondPinned) - Number(firstPinned);
+ });
+ }, [loadedApps, pinnedArtifactIds]);
+
+ useEffect(() => {
+ setPinnedArtifactState({
+ scope: activityStorageScope,
+ value: readPinnedArtifactApps(activityStorageScope),
+ });
+ setViewedArtifactState({
+ scope: activityStorageScope,
+ value: readViewedArtifactApps(activityStorageScope),
+ });
+ }, [activityStorageScope]);
+
+ const togglePinnedArtifact = (artifactAppId: string) => {
+ const next = new Set(pinnedArtifactIds);
+ const pinned = next.has(artifactAppId);
+ if (pinned) {
+ next.delete(artifactAppId);
+ } else {
+ next.add(artifactAppId);
+ }
+ writePinnedArtifactApps(activityStorageScope, next);
+ setPinnedArtifactState({ scope: activityStorageScope, value: next });
+ showToast({
+ status: pinned ? 'info' : 'success',
+ message: localize(pinned ? 'com_ui_unpinned' : 'com_ui_pinned'),
+ });
+ };
+
+ const removeDeletedArtifactActivity = (artifactAppId: string) => {
+ const nextPinnedIds = new Set(pinnedArtifactIds);
+ nextPinnedIds.delete(artifactAppId);
+ writePinnedArtifactApps(activityStorageScope, nextPinnedIds);
+ setPinnedArtifactState({ scope: activityStorageScope, value: nextPinnedIds });
+
+ const nextViewedTimes = new Map(viewedArtifactTimes);
+ nextViewedTimes.delete(artifactAppId);
+ writeViewedArtifactApps(activityStorageScope, nextViewedTimes);
+ setViewedArtifactState({ scope: activityStorageScope, value: nextViewedTimes });
+ };
+
+ const changeViewMode = (nextViewMode: ArtifactAppsViewMode) => {
+ writeArtifactAppsViewMode(nextViewMode);
+ setViewMode(nextViewMode);
+ };
+
+ const openArtifact = (app: (typeof apps)[number]) => {
+ const nextViewedTimes = new Map(viewedArtifactTimes);
+ nextViewedTimes.set(app.artifactAppId, new Date().toISOString());
+ writeViewedArtifactApps(activityStorageScope, nextViewedTimes);
+ setViewedArtifactState({ scope: activityStorageScope, value: nextViewedTimes });
+
+ const source = app.sourceMetadata;
+ if (app.createdBy === user?.id && source?.conversationId) {
+ const artifactKey = source.sourceKey ?? source.originalArtifactId ?? source.messageId;
+ const params = new URLSearchParams();
+ if (artifactKey) {
+ params.set('artifact', artifactKey);
+ }
+ if (source.sourceKey && source.originalArtifactId) {
+ params.set('artifactId', source.originalArtifactId);
+ }
+ if (source.sourceKey && source.messageId) {
+ params.set('artifactMessageId', source.messageId);
+ }
+ const query = params.size > 0 ? `?${params.toString()}` : '';
+ setArtifactNavigationRequest(
+ artifactKey
+ ? {
+ conversationId: source.conversationId,
+ sourceKey: artifactKey,
+ originalArtifactId: source.originalArtifactId,
+ messageId: source.messageId,
+ }
+ : null,
+ );
+ navigate(`/c/${source.conversationId}${query}`);
+ return;
+ }
+ navigate(`/apps/${app.artifactAppId}`);
+ };
+
+ const renderContent = () => {
+ if (isLoading) {
+ return (
+
+ {localize('com_ui_artifact_app_loading')}
+
+ );
+ }
+
+ if (isError && data == null) {
+ return (
+
+
{localize('com_ui_artifact_apps_load_error')}
+
+
+
+
{localize(titleKey)}
+
{localize(hintKey)}
+
+ {apps.map((app) => {
+ const isPinned = pinnedArtifactIds.has(app.artifactAppId);
+ const visibilityLabel = localize(
+ app.createdBy === user?.id
+ ? 'com_ui_artifact_scope_personal'
+ : 'com_ui_artifact_shared_with_you',
+ );
+ const activityText = [
+ localize('com_ui_artifact_app_version_number', {
+ 0: String(app.latestVersionNumber),
+ }),
+ formatArtifactActivityDate(app.updatedAt, 'edited', localize, i18n.language),
+ formatArtifactActivityDate(
+ viewedArtifactTimes.get(app.artifactAppId),
+ 'viewed',
+ localize,
+ i18n.language,
+ ),
+ ]
+ .filter(Boolean)
+ .join(' · ');
+
+ if (viewMode === 'grid') {
+ return (
+ -
+
+
+
+
+ );
+ }
+
+ return (
+ -
+
+
+
+
+ );
+ })}
+
+ {isError && (
+
+
+ {localize('com_ui_artifact_apps_refresh_error')}
+
+
+
+
+
+ )}
+
+ );
+ };
+
+ return (
+
+
+ {!isSmallScreen && (
+
+
+
+ {localize('com_ui_artifact_apps')}
+
+
+ {localize('com_ui_artifact_apps_description')}
+
+
+
+ )}
+
+
+
+
+
+
+
+ {!isSmallScreen &&
}
+
+
+
+ {SCOPES.map((candidate) => (
+
+ ))}
+
+
+
+
+
+
+ {renderContent()}
+
+
+
+
onChange(event.target.value)}
+ placeholder={localize('com_ui_artifact_apps_search_placeholder')}
+ className="h-12 rounded-xl border-border-medium bg-transparent pl-12 pr-12 text-lg text-text-primary shadow-md transition-[border-color,box-shadow] duration-200 placeholder:text-text-secondary focus:border-border-heavy focus:shadow-lg focus:ring-0"
+ aria-label={localize('com_ui_artifact_apps_search_aria')}
+ autoComplete="off"
+ spellCheck="false"
+ />
+
+
+
+ {value && (
+
+ )}
+
chart
;',
+ messageId: 'message-1',
+ lastUpdateTime: 1,
+ ...overrides,
+ };
+}
+
+describe('ArtifactCatalogRegistrar', () => {
+ let artifacts: Record;
+ let context: {
+ conversationId: string;
+ isSubmitting: boolean;
+ latestMessageId: string | null;
+ latestMessageError: boolean;
+ };
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ mockStartupConfig = undefined;
+ mockFetchQuery.mockRejectedValue({ response: { status: 404 } });
+ artifacts = { 'artifact-1': makeArtifact() };
+ context = {
+ conversationId: 'conversation-1',
+ isSubmitting: false,
+ latestMessageId: 'message-1',
+ latestMessageError: false,
+ };
+ mockUseRecoilValue.mockImplementation(() => artifacts);
+ mockUseArtifactsContext.mockImplementation(() => context);
+ });
+
+ it('does not register artifacts while reading idle conversation history', async () => {
+ const { rerender } = render();
+
+ artifacts = { 'artifact-old': makeArtifact({ id: 'artifact-old', content: 'old snapshot' }) };
+ context = {
+ conversationId: 'conversation-old',
+ isSubmitting: false,
+ latestMessageId: 'message-old',
+ latestMessageError: false,
+ };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).not.toHaveBeenCalled();
+ });
+
+ it('persists only artifacts changed by a completed generation', async () => {
+ const unchanged = makeArtifact({ id: 'artifact-old', identifier: 'unchanged' });
+ artifacts = { 'artifact-old': unchanged };
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = {
+ 'artifact-old': unchanged,
+ 'artifact-new': makeArtifact({
+ id: 'artifact-new',
+ identifier: 'new-chart',
+ messageId: 'message-2',
+ lastUpdateTime: 2,
+ }),
+ };
+ context = { ...context, latestMessageId: 'message-2' };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].source.sourceKey).toContain('new-chart');
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[3]).toBe(5_500);
+ });
+
+ it('does not register artifacts left over from an aborted or errored generation', async () => {
+ const unchanged = makeArtifact({ id: 'artifact-old', identifier: 'unchanged' });
+ artifacts = { 'artifact-old': unchanged };
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = {
+ 'artifact-old': unchanged,
+ 'artifact-new': makeArtifact({
+ id: 'artifact-new',
+ identifier: 'new-chart',
+ messageId: 'message-2',
+ lastUpdateTime: 2,
+ }),
+ };
+ context = { ...context, latestMessageId: 'message-2' };
+ rerender();
+ context = { ...context, isSubmitting: false, latestMessageError: true };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).not.toHaveBeenCalled();
+ });
+
+ it('continues observing previews that resolve after generation completion', async () => {
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+
+ artifacts = {
+ 'artifact-delayed': makeArtifact({
+ id: 'artifact-delayed',
+ identifier: 'delayed-presentation',
+ type: 'application/vnd.librechat.presentation-preview',
+ content: 'presentation',
+ lastUpdateTime: 2,
+ }),
+ };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].artifact.type).toBe('presentation');
+ });
+
+ it('does not impose a wall-clock deadline on a completed generation', async () => {
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+
+ artifacts = {
+ 'artifact-very-delayed': makeArtifact({
+ id: 'artifact-very-delayed',
+ identifier: 'very-delayed-presentation',
+ type: 'application/vnd.librechat.presentation-preview',
+ content: 'eventually ready',
+ lastUpdateTime: 2,
+ }),
+ };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps observing a completed generation while the next generation runs', async () => {
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true, latestMessageId: 'message-a' };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ context = { ...context, isSubmitting: true, latestMessageId: 'message-b' };
+ rerender();
+
+ artifacts = {
+ 'artifact-a': makeArtifact({
+ id: 'artifact-a',
+ identifier: 'generation-a',
+ messageId: 'message-a',
+ }),
+ };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].source.messageId).toBe('message-a');
+ });
+
+ it('tracks a first generation when a new conversation receives its persisted id', async () => {
+ artifacts = {};
+ context = {
+ conversationId: String(Constants.NEW_CONVO),
+ isSubmitting: true,
+ latestMessageId: 'message-new',
+ latestMessageError: false,
+ };
+ const { rerender } = render();
+
+ context = { ...context, conversationId: 'conversation-created' };
+ artifacts = {
+ 'artifact-new': makeArtifact({
+ id: 'artifact-new',
+ messageId: 'message-new',
+ }),
+ };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].source.conversationId).toBe(
+ 'conversation-created',
+ );
+ });
+
+ it('ignores delayed artifacts from a message outside a completed generation', async () => {
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ context = { ...context, isSubmitting: false, latestMessageId: 'message-new' };
+ rerender();
+ artifacts = {
+ 'artifact-stale': makeArtifact({
+ id: 'artifact-stale',
+ identifier: 'stale-presentation',
+ messageId: 'message-old',
+ }),
+ };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).not.toHaveBeenCalled();
+ });
+
+ it('uses the configured settle delay when persisting registration work', async () => {
+ mockStartupConfig = {
+ artifactApps: { clientSyncSettleDelayMs: 25, clientPreviewCaptureTimeoutMs: 750 },
+ };
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = { 'artifact-new': makeArtifact() };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[3]).toBe(775);
+ });
+
+ it('persists the observed server-side latestVersionNumber alongside the request as a durable baseline', async () => {
+ mockFetchQuery.mockResolvedValue({
+ app: { latestVersionNumber: 3 },
+ version: { artifactVersionId: 'version-1' },
+ });
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = { 'artifact-new': makeArtifact() };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].basedOnVersionNumber).toBe(3);
+ const request = mockEnqueueArtifactSync.mock.calls[0]?.[1];
+ expect(mockFetchQuery).toHaveBeenCalledWith(
+ [QueryKeys.artifactApp, 'source', request.source.conversationId, request.source.sourceKey],
+ expect.any(Function),
+ { retry: false },
+ );
+ });
+
+ it('persists a confirmed-absence baseline of 0 when the source has never been synced (404)', async () => {
+ mockFetchQuery.mockRejectedValue({ response: { status: 404 } });
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = { 'artifact-new': makeArtifact() };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].basedOnVersionNumber).toBe(0);
+ expect(logger.error).not.toHaveBeenCalled();
+ });
+
+ it('leaves the baseline unresolved, and logs, when lookup fails for a non-404 reason', async () => {
+ mockFetchQuery.mockRejectedValue(new Error('network down'));
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = { 'artifact-new': makeArtifact() };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].basedOnVersionNumber).toBeUndefined();
+ expect(logger.error).toHaveBeenCalledWith(
+ 'artifacts',
+ 'Failed to resolve artifact baseline before sync',
+ expect.any(Error),
+ );
+ });
+
+ it('queues a captured preview promptly and includes it in the sync request', async () => {
+ const preview = {
+ type: 'image' as const,
+ imageUrl:
+ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=',
+ alt: 'Revenue chart',
+ };
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = { 'artifact-new': makeArtifact({ preview }) };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(1);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[1].artifact.preview).toEqual(preview);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[3]).toBe(500);
+ });
+
+ it('supersedes the delayed fallback when a preview arrives after generation', async () => {
+ const preview = {
+ type: 'image' as const,
+ imageUrl:
+ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=',
+ };
+ artifacts = {};
+ const { rerender } = render();
+
+ context = { ...context, isSubmitting: true };
+ rerender();
+ artifacts = { 'artifact-new': makeArtifact() };
+ rerender();
+ context = { ...context, isSubmitting: false };
+ rerender();
+ await act(flushRegistration);
+
+ artifacts = { 'artifact-new': makeArtifact({ preview }) };
+ rerender();
+ await act(flushRegistration);
+
+ expect(mockEnqueueArtifactSync).toHaveBeenCalledTimes(2);
+ expect(mockEnqueueArtifactSync.mock.calls[0]?.[3]).toBe(5_500);
+ expect(mockEnqueueArtifactSync.mock.calls[1]?.[1].artifact.preview).toEqual(preview);
+ expect(mockEnqueueArtifactSync.mock.calls[1]?.[3]).toBe(500);
+ });
+});
diff --git a/client/src/components/ArtifactApps/ArtifactCatalogRegistrar.tsx b/client/src/components/ArtifactApps/ArtifactCatalogRegistrar.tsx
new file mode 100644
index 00000000000..7c91342e7b4
--- /dev/null
+++ b/client/src/components/ArtifactApps/ArtifactCatalogRegistrar.tsx
@@ -0,0 +1,187 @@
+import { useEffect, useRef } from 'react';
+import { useRecoilValue } from 'recoil';
+import { useQueryClient } from '@tanstack/react-query';
+import {
+ Constants,
+ QueryKeys,
+ dataService,
+ DEFAULT_ARTIFACT_APPS_CONFIG,
+ Permissions,
+ PermissionTypes,
+} from 'librechat-data-provider';
+import type { TSyncArtifactAppRequest, TArtifactAppWithVersion } from 'librechat-data-provider';
+import { enqueueArtifactSync } from '~/components/ArtifactApps/sync/queue';
+import { toLatestArtifactSyncRequests } from '~/utils/artifactCatalog';
+import { useGetStartupConfig } from '~/data-provider';
+import useHasAccess from '~/hooks/Roles/useHasAccess';
+import { useArtifactsContext } from '~/Providers';
+import { useAuthContext } from '~/hooks';
+import { logger } from '~/utils';
+import store from '~/store';
+
+function getSyncKey(request: TSyncArtifactAppRequest): string {
+ return `${request.source.conversationId}\u0000${request.source.sourceKey}`;
+}
+
+function getRequestSignature(request: TSyncArtifactAppRequest): string {
+ return JSON.stringify(request);
+}
+
+interface SourceLookupError {
+ response?: { status?: number };
+}
+
+/**
+ * Observes the baseline once, at the moment this content is captured, and persists it alongside
+ * the request. Worker.tsx sends that pairing unchanged on every attempt, including retries — a
+ * baseline re-derived later would describe the server's state at send time, not the state this
+ * (possibly older, still-queued) content was actually written against, which would let stale
+ * content pass the server's conflict check under a basis it never had.
+ */
+export default function ArtifactCatalogRegistrar() {
+ const artifacts = useRecoilValue(store.artifactsState);
+ const { conversationId, isSubmitting, latestMessageId, latestMessageError } =
+ useArtifactsContext();
+ const { user } = useAuthContext();
+ const queryClient = useQueryClient();
+ const { data: startupConfig } = useGetStartupConfig();
+ const syncSettleDelayMs =
+ startupConfig?.artifactApps?.clientSyncSettleDelayMs ??
+ DEFAULT_ARTIFACT_APPS_CONFIG.clientSyncSettleDelayMs;
+ const previewCaptureTimeoutMs =
+ startupConfig?.artifactApps?.clientPreviewCaptureTimeoutMs ??
+ DEFAULT_ARTIFACT_APPS_CONFIG.clientPreviewCaptureTimeoutMs;
+ const canCreate = useHasAccess({
+ permissionType: PermissionTypes.ARTIFACTS,
+ permission: Permissions.CREATE,
+ });
+ const previousIsSubmittingRef = useRef(false);
+ const conversationRef = useRef(null);
+ const activeGenerationConversationRef = useRef(null);
+ const activeGenerationMessageRef = useRef(null);
+ /**
+ * Completed message ids stay eligible for the lifetime of the active
+ * conversation. Deferred office previews expose no reliable client-side ETA,
+ * so a wall-clock expiry would silently lose slow but valid conversions.
+ * Conversation navigation clears the set and keeps history reads inert.
+ */
+ const completedGenerationMessagesRef = useRef(new Set());
+ const observedSignaturesRef = useRef(new Map());
+
+ useEffect(() => {
+ const validConversation =
+ conversationId != null && conversationId !== Constants.NEW_CONVO ? conversationId : null;
+ const requests =
+ validConversation && artifacts
+ ? toLatestArtifactSyncRequests(artifacts, validConversation)
+ : [];
+ const wasSubmitting = previousIsSubmittingRef.current;
+ previousIsSubmittingRef.current = isSubmitting;
+
+ if (conversationRef.current !== validConversation) {
+ conversationRef.current = validConversation;
+ activeGenerationConversationRef.current = null;
+ activeGenerationMessageRef.current = null;
+ completedGenerationMessagesRef.current.clear();
+ observedSignaturesRef.current.clear();
+ if (!isSubmitting) {
+ for (const request of requests) {
+ observedSignaturesRef.current.set(getSyncKey(request), getRequestSignature(request));
+ }
+ } else if (validConversation) {
+ activeGenerationConversationRef.current = validConversation;
+ activeGenerationMessageRef.current = latestMessageId;
+ }
+ }
+
+ if (isSubmitting && !wasSubmitting) {
+ activeGenerationConversationRef.current = validConversation;
+ activeGenerationMessageRef.current = latestMessageId;
+ } else if (isSubmitting && activeGenerationConversationRef.current === validConversation) {
+ activeGenerationMessageRef.current = latestMessageId ?? activeGenerationMessageRef.current;
+ }
+
+ if (
+ !isSubmitting &&
+ wasSubmitting &&
+ activeGenerationConversationRef.current === validConversation
+ ) {
+ const completedMessageId = latestMessageId ?? activeGenerationMessageRef.current;
+ if (completedMessageId && !latestMessageError) {
+ completedGenerationMessagesRef.current.add(completedMessageId);
+ }
+ activeGenerationConversationRef.current = null;
+ activeGenerationMessageRef.current = null;
+ }
+
+ if (!canCreate || !user?.id || !validConversation) {
+ return;
+ }
+
+ for (const request of requests) {
+ const messageId = request.source.messageId;
+ if (!messageId || !completedGenerationMessagesRef.current.has(messageId)) {
+ continue;
+ }
+ const syncKey = getSyncKey(request);
+ const signature = getRequestSignature(request);
+ if (observedSignaturesRef.current.get(syncKey) === signature) {
+ continue;
+ }
+ observedSignaturesRef.current.set(syncKey, signature);
+ const delayMs =
+ !request.artifact.preview && request.artifact.type !== 'code'
+ ? syncSettleDelayMs + previewCaptureTimeoutMs
+ : syncSettleDelayMs;
+ void (async () => {
+ // A 404 confirms no app exists yet for this source — a real, observed absence, distinct
+ // from a lookup that simply failed. Only the latter falls back to an unresolved baseline.
+ let basedOnVersionNumber: number | undefined;
+ try {
+ const resolved = await queryClient.fetchQuery(
+ [
+ QueryKeys.artifactApp,
+ 'source',
+ request.source.conversationId,
+ request.source.sourceKey,
+ ],
+ () =>
+ dataService.getArtifactAppBySource(
+ request.source.conversationId,
+ request.source.sourceKey,
+ ),
+ { retry: false },
+ );
+ basedOnVersionNumber = resolved.app.latestVersionNumber;
+ } catch (error) {
+ if ((error as SourceLookupError)?.response?.status === 404) {
+ basedOnVersionNumber = 0;
+ } else {
+ logger.error('artifacts', 'Failed to resolve artifact baseline before sync', error);
+ }
+ }
+ const requestToPersist =
+ basedOnVersionNumber != null ? { ...request, basedOnVersionNumber } : request;
+ await enqueueArtifactSync(user.id, requestToPersist, signature, delayMs);
+ })().catch((error) => {
+ if (observedSignaturesRef.current.get(syncKey) === signature) {
+ observedSignaturesRef.current.delete(syncKey);
+ }
+ logger.error('artifacts', 'Failed to persist artifact catalog registration', error);
+ });
+ }
+ }, [
+ artifacts,
+ canCreate,
+ conversationId,
+ isSubmitting,
+ latestMessageError,
+ latestMessageId,
+ previewCaptureTimeoutMs,
+ queryClient,
+ syncSettleDelayMs,
+ user?.id,
+ ]);
+
+ return null;
+}
diff --git a/client/src/components/ArtifactApps/Share.spec.tsx b/client/src/components/ArtifactApps/Share.spec.tsx
new file mode 100644
index 00000000000..b9717be9d12
--- /dev/null
+++ b/client/src/components/ArtifactApps/Share.spec.tsx
@@ -0,0 +1,171 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { PermissionBits, PermissionTypes, Permissions, SystemRoles } from 'librechat-data-provider';
+import type { TArtifactApp } from 'librechat-data-provider';
+import ArtifactAppShareDialog from './Share';
+
+const mockUseAuthContext = jest.fn();
+const mockUseHasAccess = jest.fn();
+
+jest.mock('~/hooks', () => ({
+ useAuthContext: () => mockUseAuthContext(),
+ useHasAccess: (args: { permissionType: string; permission: string }) => mockUseHasAccess(args),
+}));
+
+jest.mock('~/components/Sharing', () => ({
+ GenericGrantAccessDialog: ({
+ resourceDbId,
+ resourceId,
+ resourceName,
+ defaultOpen,
+ children,
+ }: {
+ resourceDbId?: string;
+ resourceId?: string;
+ resourceName?: string;
+ defaultOpen?: boolean;
+ children?: React.ReactNode;
+ }) => (
+
+ {resourceName}
+ {children}
+
+ ),
+}));
+
+const app = {
+ id: 'db-revenue-chart',
+ artifactAppId: 'revenue-chart',
+ createdBy: 'user-1',
+ title: 'Revenue chart',
+} as TArtifactApp;
+
+function mockAccess({
+ share = true,
+ viewUsers = false,
+ viewGroups = false,
+ viewRoles = false,
+ sharePublic = false,
+}: {
+ share?: boolean;
+ viewUsers?: boolean;
+ viewGroups?: boolean;
+ viewRoles?: boolean;
+ sharePublic?: boolean;
+} = {}) {
+ mockUseHasAccess.mockImplementation(
+ ({ permissionType, permission }: { permissionType: string; permission: string }) => {
+ if (permissionType === PermissionTypes.ARTIFACTS && permission === Permissions.SHARE) {
+ return share;
+ }
+ if (permissionType === PermissionTypes.ARTIFACTS && permission === Permissions.SHARE_PUBLIC) {
+ return sharePublic;
+ }
+ if (
+ permissionType === PermissionTypes.PEOPLE_PICKER &&
+ permission === Permissions.VIEW_USERS
+ ) {
+ return viewUsers;
+ }
+ if (
+ permissionType === PermissionTypes.PEOPLE_PICKER &&
+ permission === Permissions.VIEW_GROUPS
+ ) {
+ return viewGroups;
+ }
+ if (
+ permissionType === PermissionTypes.PEOPLE_PICKER &&
+ permission === Permissions.VIEW_ROLES
+ ) {
+ return viewRoles;
+ }
+ return false;
+ },
+ );
+}
+
+describe('ArtifactAppShareDialog', () => {
+ beforeEach(() => {
+ mockUseAuthContext.mockReturnValue({ user: { id: 'user-1', role: SystemRoles.USER } });
+ mockAccess({ share: true, viewUsers: true });
+ });
+
+ it('exposes the share dialog for the artifact owner without a per-resource permission fetch', () => {
+ render();
+
+ const dialog = screen.getByTestId('artifact-share-dialog');
+ expect(dialog).toHaveAttribute('data-resource-db-id', 'db-revenue-chart');
+ expect(dialog).toHaveAttribute('data-resource-id', 'revenue-chart');
+ expect(dialog).toHaveTextContent('Revenue chart');
+ });
+
+ it('exposes the share dialog for an admin who does not own the artifact', () => {
+ mockUseAuthContext.mockReturnValue({ user: { id: 'admin-1', role: SystemRoles.ADMIN } });
+
+ render();
+
+ expect(screen.getByTestId('artifact-share-dialog')).toBeInTheDocument();
+ });
+
+ it('exposes the share dialog when the catalog entry already includes SHARE', () => {
+ mockUseAuthContext.mockReturnValue({ user: { id: 'user-2', role: SystemRoles.USER } });
+
+ render();
+
+ expect(screen.getByTestId('artifact-share-dialog')).toBeInTheDocument();
+ });
+
+ it('hides the share dialog from a viewer whose catalog entry only includes VIEW', () => {
+ mockUseAuthContext.mockReturnValue({ user: { id: 'user-2', role: SystemRoles.USER } });
+
+ render();
+
+ expect(screen.queryByTestId('artifact-share-dialog')).not.toBeInTheDocument();
+ });
+
+ it('hides the share dialog when the ARTIFACTS SHARE permission is denied', () => {
+ mockAccess({ share: false, viewUsers: true });
+
+ render();
+
+ expect(screen.queryByTestId('artifact-share-dialog')).not.toBeInTheDocument();
+ });
+
+ it('hides the share dialog when no user, group, or public destination is permitted', () => {
+ mockAccess({ share: true, viewRoles: true });
+
+ render();
+
+ expect(screen.queryByTestId('artifact-share-dialog')).not.toBeInTheDocument();
+ });
+
+ it('exposes the share dialog when only people-picker users are permitted', () => {
+ mockAccess({ share: true, viewUsers: true });
+
+ render();
+
+ expect(screen.getByTestId('artifact-share-dialog')).toBeInTheDocument();
+ });
+
+ it('exposes the share dialog when only people-picker groups are permitted', () => {
+ mockAccess({ share: true, viewGroups: true });
+
+ render();
+
+ expect(screen.getByTestId('artifact-share-dialog')).toBeInTheDocument();
+ });
+
+ it('exposes the share dialog when only public sharing is permitted', () => {
+ mockAccess({ share: true, sharePublic: true });
+
+ render();
+
+ expect(screen.getByTestId('artifact-share-dialog')).toBeInTheDocument();
+ });
+});
diff --git a/client/src/components/ArtifactApps/Share.tsx b/client/src/components/ArtifactApps/Share.tsx
new file mode 100644
index 00000000000..c922fa027e5
--- /dev/null
+++ b/client/src/components/ArtifactApps/Share.tsx
@@ -0,0 +1,103 @@
+import {
+ SystemRoles,
+ Permissions,
+ ResourceType,
+ PermissionBits,
+ PermissionTypes,
+ hasPermissions,
+} from 'librechat-data-provider';
+import type { TArtifactApp } from 'librechat-data-provider';
+import type { ReactNode } from 'react';
+import { GenericGrantAccessDialog } from '~/components/Sharing';
+import { useAuthContext, useHasAccess } from '~/hooks';
+
+export function canShareArtifactApp({
+ app,
+ userId,
+ userRole,
+ hasAccessToShare,
+ canViewUsers,
+ canViewGroups,
+ canSharePublic,
+}: {
+ app: TArtifactApp;
+ userId?: string;
+ userRole?: string;
+ hasAccessToShare: boolean;
+ canViewUsers: boolean;
+ canViewGroups: boolean;
+ canSharePublic: boolean;
+}): boolean {
+ if (!hasAccessToShare || !app.id) {
+ return false;
+ }
+ if (!canViewUsers && !canViewGroups && !canSharePublic) {
+ return false;
+ }
+ if (app.createdBy === userId || userRole === SystemRoles.ADMIN) {
+ return true;
+ }
+ return hasPermissions(app.permissionBits ?? 0, PermissionBits.SHARE);
+}
+
+export function useCanShareArtifactApp(app: TArtifactApp): boolean {
+ const { user } = useAuthContext();
+ const hasAccessToShare = useHasAccess({
+ permissionType: PermissionTypes.ARTIFACTS,
+ permission: Permissions.SHARE,
+ });
+ const canViewUsers = useHasAccess({
+ permissionType: PermissionTypes.PEOPLE_PICKER,
+ permission: Permissions.VIEW_USERS,
+ });
+ const canViewGroups = useHasAccess({
+ permissionType: PermissionTypes.PEOPLE_PICKER,
+ permission: Permissions.VIEW_GROUPS,
+ });
+ const canSharePublic = useHasAccess({
+ permissionType: PermissionTypes.ARTIFACTS,
+ permission: Permissions.SHARE_PUBLIC,
+ });
+ return canShareArtifactApp({
+ app,
+ userId: user?.id,
+ userRole: user?.role,
+ hasAccessToShare,
+ canViewUsers,
+ canViewGroups,
+ canSharePublic,
+ });
+}
+
+export default function ArtifactAppShareDialog({
+ app,
+ children,
+ buttonClassName,
+ defaultOpen = false,
+ onOpenChange,
+}: {
+ app: TArtifactApp;
+ children?: ReactNode;
+ buttonClassName?: string;
+ defaultOpen?: boolean;
+ onOpenChange?: (open: boolean) => void;
+}) {
+ const canShare = useCanShareArtifactApp(app);
+ if (!canShare) {
+ return null;
+ }
+
+ return (
+
+ {children}
+
+ );
+}
diff --git a/client/src/components/ArtifactApps/StandaloneAppView.spec.tsx b/client/src/components/ArtifactApps/StandaloneAppView.spec.tsx
new file mode 100644
index 00000000000..ec37ba1fa73
--- /dev/null
+++ b/client/src/components/ArtifactApps/StandaloneAppView.spec.tsx
@@ -0,0 +1,270 @@
+import React from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type {
+ TArtifactApp,
+ TArtifactVersion,
+ TArtifactAppWithVersion,
+} from 'librechat-data-provider';
+import type { QueryObserverLoadingErrorResult } from '@tanstack/react-query';
+import {
+ useGetArtifactAppQuery,
+ useGetArtifactAppVersionQuery,
+ useListArtifactAppVersionsQuery,
+} from '~/data-provider';
+import StandaloneAppView from './StandaloneAppView';
+
+const mockNavigate = jest.fn();
+let mockVersionId: string | undefined;
+
+jest.mock('react-router-dom', () => ({
+ useParams: () => ({ artifactAppId: 'app-1', versionId: mockVersionId }),
+ useNavigate: () => mockNavigate,
+}));
+
+jest.mock('~/data-provider', () => ({
+ useGetArtifactAppQuery: jest.fn(),
+ useGetArtifactAppVersionQuery: jest.fn(),
+ useListArtifactAppVersionsQuery: jest.fn(),
+}));
+
+jest.mock('~/hooks/useLocalize', () => ({
+ __esModule: true,
+ default: () => (key: string) => key,
+}));
+
+jest.mock('~/hooks', () => ({
+ useAuthContext: () => ({ user: { id: 'user-1', role: 'USER' } }),
+ useHasAccess: () => true,
+}));
+
+jest.mock('~/components/Sharing', () => ({
+ GenericGrantAccessDialog: ({ resourceName }: { resourceName?: string }) => (
+
+ ),
+}));
+
+jest.mock('./AppRenderer', () => ({
+ __esModule: true,
+ default: ({ version }: { version: TArtifactVersion }) => (
+ {version.sourceSnapshot}
+ ),
+}));
+
+const app = {
+ id: 'db-app-1',
+ artifactAppId: 'app-1',
+ createdBy: 'user-1',
+ activeVersionId: 'version-2',
+ title: 'Revenue chart',
+ status: 'draft',
+} as TArtifactApp;
+
+const version = {
+ artifactAppId: 'app-1',
+ artifactVersionId: 'version-2',
+ versionNumber: 2,
+ sourceSnapshot: 'selected snapshot',
+} as TArtifactVersion;
+
+function makeQueryErrorResult(
+ error: unknown,
+ refetch = jest.fn(),
+): QueryObserverLoadingErrorResult {
+ return {
+ data: undefined,
+ dataUpdatedAt: 0,
+ error,
+ errorUpdateCount: 1,
+ errorUpdatedAt: 0,
+ failureCount: 1,
+ failureReason: error,
+ fetchStatus: 'idle',
+ isError: true,
+ isFetched: true,
+ isFetchedAfterMount: true,
+ isFetching: false,
+ isInitialLoading: false,
+ isLoading: false,
+ isLoadingError: true,
+ isPaused: false,
+ isPlaceholderData: false,
+ isPreviousData: false,
+ isRefetchError: false,
+ isRefetching: false,
+ isStale: true,
+ isSuccess: false,
+ refetch,
+ remove: jest.fn(),
+ status: 'error',
+ };
+}
+
+describe('StandaloneAppView', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ mockVersionId = undefined;
+ jest.mocked(useGetArtifactAppQuery).mockReturnValue({
+ data: { app, version },
+ isLoading: false,
+ isError: false,
+ } as ReturnType);
+ jest.mocked(useGetArtifactAppVersionQuery).mockReturnValue({
+ data: version,
+ isLoading: false,
+ isError: false,
+ } as ReturnType);
+ jest.mocked(useListArtifactAppVersionsQuery).mockReturnValue({
+ data: {
+ pages: [
+ {
+ versions: [
+ {
+ artifactAppId: 'app-1',
+ artifactVersionId: 'version-2',
+ versionNumber: 2,
+ },
+ ],
+ has_more: true,
+ after: 'next-page',
+ },
+ ],
+ pageParams: [undefined],
+ },
+ hasNextPage: true,
+ isFetchingNextPage: false,
+ fetchNextPage: jest.fn(),
+ } as unknown as ReturnType);
+ });
+
+ it('uses the active snapshot included in the backward-compatible detail response', () => {
+ render();
+
+ expect(useGetArtifactAppVersionQuery).toHaveBeenCalledWith('app-1', 'version-2', {
+ enabled: false,
+ });
+ expect(screen.getByTestId('artifact-renderer')).toHaveTextContent('selected snapshot');
+ expect(screen.getByRole('button', { name: 'Share Revenue chart' })).toBeInTheDocument();
+ });
+
+ it('loads additional metadata pages on demand', () => {
+ const fetchNextPage = jest.fn();
+ jest.mocked(useListArtifactAppVersionsQuery).mockReturnValue({
+ data: {
+ pages: [{ versions: [], has_more: true, after: 'next-page' }],
+ pageParams: [undefined],
+ },
+ hasNextPage: true,
+ isFetchingNextPage: false,
+ fetchNextPage,
+ } as unknown as ReturnType);
+
+ render();
+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_load_more' }));
+
+ expect(fetchNextPage).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries transient artifact detail failures instead of reporting not found', () => {
+ const refetch = jest.fn();
+ jest
+ .mocked(useGetArtifactAppQuery)
+ .mockReturnValue(
+ makeQueryErrorResult({ response: { status: 500 } }, refetch),
+ );
+
+ render();
+
+ expect(screen.getByRole('alert')).toHaveTextContent('com_ui_artifact_app_load_error');
+ expect(screen.queryByText('com_ui_artifact_app_not_found')).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));
+ expect(refetch).toHaveBeenCalledTimes(1);
+ });
+
+ it('reports a missing artifact without offering a retry', () => {
+ jest
+ .mocked(useGetArtifactAppQuery)
+ .mockReturnValue(
+ makeQueryErrorResult({ response: { status: 404 } }),
+ );
+
+ render();
+
+ expect(screen.getByRole('alert')).toHaveTextContent('com_ui_artifact_app_not_found');
+ expect(screen.queryByRole('button', { name: 'com_ui_retry' })).not.toBeInTheDocument();
+ });
+
+ it('retries transient version failures through the version query', () => {
+ const refetch = jest.fn();
+ mockVersionId = 'version-1';
+ jest
+ .mocked(useGetArtifactAppVersionQuery)
+ .mockReturnValue(
+ makeQueryErrorResult(new Error('network unavailable'), refetch),
+ );
+
+ render();
+
+ expect(screen.getByRole('alert')).toHaveTextContent('com_ui_artifact_app_version_load_error');
+ expect(screen.queryByText('com_ui_artifact_app_not_found')).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));
+ expect(refetch).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps rendering the active artifact when the initial version history request fails', () => {
+ const refetch = jest.fn();
+ jest.mocked(useListArtifactAppVersionsQuery).mockReturnValue({
+ data: undefined,
+ isError: true,
+ isFetching: false,
+ hasNextPage: false,
+ refetch,
+ } as unknown as ReturnType);
+
+ render();
+
+ expect(screen.getByTestId('artifact-renderer')).toHaveTextContent('selected snapshot');
+ expect(screen.getByRole('alert')).toHaveTextContent('com_ui_artifact_app_history_load_error');
+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));
+ expect(refetch).toHaveBeenCalledTimes(1);
+ });
+
+ it('preserves loaded history and offers retry when pagination fails', () => {
+ const refetch = jest.fn();
+ jest.mocked(useListArtifactAppVersionsQuery).mockReturnValue({
+ data: {
+ pages: [
+ {
+ versions: [
+ {
+ artifactAppId: 'app-1',
+ artifactVersionId: 'version-2',
+ versionNumber: 2,
+ },
+ {
+ artifactAppId: 'app-1',
+ artifactVersionId: 'version-1',
+ versionNumber: 1,
+ },
+ ],
+ has_more: true,
+ after: 'next-page',
+ },
+ ],
+ pageParams: [undefined],
+ },
+ isError: true,
+ isFetching: false,
+ hasNextPage: true,
+ refetch,
+ } as unknown as ReturnType);
+
+ render();
+
+ expect(screen.getByTestId('artifact-renderer')).toHaveTextContent('selected snapshot');
+ expect(screen.getAllByRole('option')).toHaveLength(2);
+ expect(screen.queryByRole('button', { name: 'com_ui_load_more' })).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));
+ expect(refetch).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/client/src/components/ArtifactApps/StandaloneAppView.tsx b/client/src/components/ArtifactApps/StandaloneAppView.tsx
new file mode 100644
index 00000000000..016124a9de8
--- /dev/null
+++ b/client/src/components/ArtifactApps/StandaloneAppView.tsx
@@ -0,0 +1,198 @@
+import { Button } from '@librechat/client';
+import { useParams, useNavigate } from 'react-router-dom';
+import type { TArtifactVersion } from 'librechat-data-provider';
+import {
+ useGetArtifactAppQuery,
+ useGetArtifactAppVersionQuery,
+ useListArtifactAppVersionsQuery,
+} from '~/data-provider';
+import useLocalize from '~/hooks/useLocalize';
+import ArtifactAppShareDialog from './Share';
+import AppRenderer from './AppRenderer';
+
+function errorStatus(error: unknown): number | undefined {
+ return (error as { response?: { status?: number } } | null)?.response?.status;
+}
+
+function StateMessage({
+ message,
+ onRetry,
+ isRetrying = false,
+}: {
+ message: string;
+ onRetry?: () => void;
+ isRetrying?: boolean;
+}) {
+ const localize = useLocalize();
+
+ return (
+
+
{message}
+ {onRetry && (
+
+ )}
+
+
+ {versionsQuery.isError && (
+
+ {localize('com_ui_artifact_app_history_load_error')}
+
+
+ )}
+
+ {version ? (
+
+ ) : (
+
+ )}
+
+
+ {preview ? (
+
+ ) : (
+
+
+ {localize('com_ui_artifact_app_preview_unavailable')}
+
+ )}
+
new
' } },
+ 'signature-2',
+ 0,
+ );
+
+ const [{ id }] = await listArtifactSyncQueue('user-1');
+ await completeArtifactSync(id, 'signature-1');
+
+ expect(await listArtifactSyncQueue('user-1')).toEqual([
+ expect.objectContaining({ signature: 'signature-2' }),
+ ]);
+ });
+
+ it('rejects the caller when the underlying write fails, but recovers the chain for later writes', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+
+ jest.spyOn(window.indexedDB, 'open').mockImplementationOnce(() => {
+ const fakeRequest = {} as IDBOpenDBRequest;
+ queueMicrotask(() => fakeRequest.onerror?.(new Event('error')));
+ return fakeRequest;
+ });
+
+ const updated = { ...request, artifact: { ...request.artifact, content: 'v2
' } };
+ await expect(enqueueArtifactSync('user-1', updated, 'signature-2', 0)).rejects.toThrow(
+ 'Unable to open artifact sync queue',
+ );
+
+ const updatedAgain = {
+ ...request,
+ artifact: { ...request.artifact, content: 'v3
' },
+ };
+ await enqueueArtifactSync('user-1', updatedAgain, 'signature-3', 0);
+ expect(await reloadQueue()).toEqual([expect.objectContaining({ signature: 'signature-3' })]);
+ });
+
+ it('propagates a completion to an already-hydrated tab via broadcast', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const secondTab = await loadSecondTab();
+ const [{ id }] = await listArtifactSyncQueue('user-1');
+ expect(secondTab.getCurrentArtifactSyncEntry(id)).toEqual(
+ expect.objectContaining({ signature: 'signature-1' }),
+ );
+
+ await completeArtifactSync(id, 'signature-1');
+ await waitUntil(() => secondTab.getCurrentArtifactSyncEntry(id) === undefined);
+
+ expect(secondTab.getCurrentArtifactSyncEntry(id)).toBeUndefined();
+ });
+
+ it('propagates a newer enqueue to an already-hydrated tab via broadcast', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const secondTab = await loadSecondTab();
+
+ const updated = { ...request, artifact: { ...request.artifact, content: 'new
' } };
+ await enqueueArtifactSync('user-1', updated, 'signature-2', 0);
+ const id = getArtifactSyncQueueId('user-1', updated);
+ await waitUntil(() => secondTab.getCurrentArtifactSyncEntry(id)?.signature === 'signature-2');
+
+ expect(secondTab.getCurrentArtifactSyncEntry(id)).toEqual(
+ expect.objectContaining({ signature: 'signature-2' }),
+ );
+ });
+
+ it('locks in a baseline resolved after enqueue for an entry that had none', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const id = getArtifactSyncQueueId('user-1', request);
+
+ await expect(recordArtifactSyncBaseline(id, 'signature-1', 7)).resolves.toBe(true);
+
+ expect(await listArtifactSyncQueue('user-1')).toEqual([
+ expect.objectContaining({
+ signature: 'signature-1',
+ request: expect.objectContaining({ basedOnVersionNumber: 7 }),
+ }),
+ ]);
+ });
+
+ it('does not overwrite a baseline the entry already resolved', async () => {
+ await enqueueArtifactSync('user-1', { ...request, basedOnVersionNumber: 1 }, 'signature-1', 0);
+ const id = getArtifactSyncQueueId('user-1', request);
+
+ await expect(recordArtifactSyncBaseline(id, 'signature-1', 7)).resolves.toBe(false);
+
+ expect(await listArtifactSyncQueue('user-1')).toEqual([
+ expect.objectContaining({
+ signature: 'signature-1',
+ request: expect.objectContaining({ basedOnVersionNumber: 1 }),
+ }),
+ ]);
+ });
+
+ it('does not record a baseline for an entry a newer edit has since replaced', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const updated = { ...request, artifact: { ...request.artifact, content: 'v2
' } };
+ await enqueueArtifactSync('user-1', updated, 'signature-2', 0);
+ const id = getArtifactSyncQueueId('user-1', request);
+
+ await expect(recordArtifactSyncBaseline(id, 'signature-1', 7)).resolves.toBe(false);
+
+ expect(await listArtifactSyncQueue('user-1')).toEqual([
+ expect.objectContaining({
+ signature: 'signature-2',
+ request: expect.not.objectContaining({ basedOnVersionNumber: expect.anything() }),
+ }),
+ ]);
+ });
+
+ it('records retry state without changing the queued request identity', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const [{ id }] = await listArtifactSyncQueue('user-1');
+ await rescheduleArtifactSync(id, 'signature-1', 1000);
+
+ expect(await listArtifactSyncQueue('user-1')).toEqual([
+ expect.objectContaining({ id, failures: 1, signature: 'signature-1' }),
+ ]);
+ });
+
+ it('does not persist an enqueue that completed while IndexedDB was opening', async () => {
+ await listArtifactSyncQueue('user-1');
+ const paused = pauseNextDatabaseOpen();
+ const enqueued = enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ await paused.ready;
+ const completed = completeArtifactSync(
+ getArtifactSyncQueueId('user-1', request),
+ 'signature-1',
+ );
+ await listArtifactSyncQueue('user-1');
+ expect(window.indexedDB.open).toHaveBeenCalledTimes(1);
+ paused.resume();
+ await Promise.all([enqueued, completed]);
+
+ expect(await reloadQueue()).toEqual([]);
+ });
+
+ it('does not overwrite a newer durable snapshot with a late enqueue', async () => {
+ await listArtifactSyncQueue('user-1');
+ const paused = pauseNextDatabaseOpen();
+ const enqueued = enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ await paused.ready;
+ const superseded = enqueueArtifactSync('user-1', request, 'signature-2', 0);
+ await listArtifactSyncQueue('user-1');
+ expect(window.indexedDB.open).toHaveBeenCalledTimes(1);
+ paused.resume();
+ await Promise.all([enqueued, superseded]);
+
+ expect(await reloadQueue()).toEqual([expect.objectContaining({ signature: 'signature-2' })]);
+ });
+
+ it('does not restore a completed snapshot from a late retry write', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const id = getArtifactSyncQueueId('user-1', request);
+ const paused = pauseNextDatabaseOpen();
+ const rescheduled = rescheduleArtifactSync(id, 'signature-1', 1000);
+ await paused.ready;
+ const completed = completeArtifactSync(id, 'signature-1');
+ await listArtifactSyncQueue('user-1');
+ expect(window.indexedDB.open).toHaveBeenCalledTimes(1);
+ paused.resume();
+ await Promise.all([rescheduled, completed]);
+
+ expect(await reloadQueue()).toEqual([]);
+ });
+
+ it('removes an older durable snapshot when a newer enqueue completes before its write', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const paused = pauseNextDatabaseOpen();
+ const enqueued = enqueueArtifactSync('user-1', request, 'signature-2', 0);
+ await paused.ready;
+ const completed = completeArtifactSync(
+ getArtifactSyncQueueId('user-1', request),
+ 'signature-2',
+ );
+ await listArtifactSyncQueue('user-1');
+ expect(window.indexedDB.open).toHaveBeenCalledTimes(1);
+ paused.resume();
+ await Promise.all([enqueued, completed]);
+
+ expect(await reloadQueue()).toEqual([]);
+ });
+
+ it('persists the newer snapshot and retry state when retry overtakes its enqueue write', async () => {
+ await enqueueArtifactSync('user-1', request, 'signature-1', 0);
+ const paused = pauseNextDatabaseOpen();
+ const enqueued = enqueueArtifactSync('user-1', request, 'signature-2', 0);
+ await paused.ready;
+ const rescheduled = rescheduleArtifactSync(
+ getArtifactSyncQueueId('user-1', request),
+ 'signature-2',
+ 1000,
+ );
+ await listArtifactSyncQueue('user-1');
+ expect(window.indexedDB.open).toHaveBeenCalledTimes(1);
+ paused.resume();
+ await Promise.all([enqueued, rescheduled]);
+
+ expect(await reloadQueue()).toEqual([
+ expect.objectContaining({ signature: 'signature-2', failures: 1 }),
+ ]);
+ });
+});
diff --git a/client/src/components/ArtifactApps/sync/queue.ts b/client/src/components/ArtifactApps/sync/queue.ts
new file mode 100644
index 00000000000..cc8d02eb03b
--- /dev/null
+++ b/client/src/components/ArtifactApps/sync/queue.ts
@@ -0,0 +1,351 @@
+import type { TSyncArtifactAppRequest } from 'librechat-data-provider';
+
+const DATABASE_NAME = 'librechat-artifact-sync';
+const DATABASE_VERSION = 1;
+const STORE_NAME = 'registrations';
+
+export interface ArtifactSyncQueueEntry {
+ id: string;
+ ownerId: string;
+ request: TSyncArtifactAppRequest;
+ signature: string;
+ failures: number;
+ nextAttemptAt: number;
+ updatedAt: number;
+}
+
+type QueueListener = () => void;
+
+const memoryQueue = new Map();
+const listeners = new Set();
+let hydrationPromise: Promise | null = null;
+let persistencePromise: Promise = Promise.resolve();
+
+/**
+ * Sub-millisecond `updatedAt` so two writes issued back-to-back (e.g. a rapid edit followed by
+ * another) never tie under Date.now()'s 1ms resolution, which would make the "keep the newer
+ * write" merge in hydration and broadcast handling silently favor whichever arrived first.
+ */
+function now(): number {
+ return typeof performance !== 'undefined'
+ ? performance.timeOrigin + performance.now()
+ : Date.now();
+}
+
+/**
+ * Order operations before opening IndexedDB; connection timing must not reorder snapshots.
+ * The internal chain always recovers so one failed write doesn't wedge every later write behind
+ * a permanently-rejected promise, but the caller gets the operation's own outcome, unmasked, so a
+ * real IndexedDB failure surfaces instead of being reported as successful persistence.
+ */
+function persistQueueChange(operation: () => Promise): Promise {
+ const attempt = persistencePromise.then(operation);
+ persistencePromise = attempt.then(
+ () => undefined,
+ () => undefined,
+ );
+ return attempt;
+}
+
+function notifyListeners(): void {
+ for (const listener of listeners) {
+ listener();
+ }
+}
+
+function hasIndexedDb(): boolean {
+ return typeof window !== 'undefined' && typeof window.indexedDB !== 'undefined';
+}
+
+function hasBroadcastChannel(): boolean {
+ return typeof window !== 'undefined' && typeof window.BroadcastChannel !== 'undefined';
+}
+
+type QueueBroadcastMessage =
+ | { type: 'upsert'; entry: ArtifactSyncQueueEntry }
+ | { type: 'delete'; id: string; signature: string };
+
+/** Propagates writes/deletes to other tabs so a stale in-memory snapshot never outsurvives its source. */
+const syncChannel: BroadcastChannel | null = hasBroadcastChannel()
+ ? new window.BroadcastChannel('librechat-artifact-sync')
+ : null;
+
+function broadcast(message: QueueBroadcastMessage): void {
+ syncChannel?.postMessage(message);
+}
+
+if (syncChannel) {
+ syncChannel.onmessage = (event: MessageEvent) => {
+ const message = event.data;
+ if (message.type === 'upsert') {
+ const current = memoryQueue.get(message.entry.id);
+ if (!current || current.updatedAt < message.entry.updatedAt) {
+ memoryQueue.set(message.entry.id, message.entry);
+ notifyListeners();
+ }
+ } else if (memoryQueue.get(message.id)?.signature === message.signature) {
+ memoryQueue.delete(message.id);
+ notifyListeners();
+ }
+ };
+}
+
+function openDatabase(): Promise {
+ if (!hasIndexedDb()) {
+ return Promise.resolve(null);
+ }
+ return new Promise((resolve, reject) => {
+ const request = window.indexedDB.open(DATABASE_NAME, DATABASE_VERSION);
+ request.onupgradeneeded = () => {
+ const database = request.result;
+ if (!database.objectStoreNames.contains(STORE_NAME)) {
+ database.createObjectStore(STORE_NAME, { keyPath: 'id' });
+ }
+ };
+ request.onsuccess = () => resolve(request.result);
+ request.onerror = () =>
+ reject(request.error ?? new Error('Unable to open artifact sync queue'));
+ });
+}
+
+function isQueueEntry(value: unknown): value is ArtifactSyncQueueEntry {
+ if (!value || typeof value !== 'object') {
+ return false;
+ }
+ const candidate = value as Partial;
+ return (
+ typeof candidate.id === 'string' &&
+ typeof candidate.ownerId === 'string' &&
+ typeof candidate.signature === 'string' &&
+ typeof candidate.failures === 'number' &&
+ typeof candidate.nextAttemptAt === 'number' &&
+ typeof candidate.updatedAt === 'number' &&
+ candidate.request != null
+ );
+}
+
+async function readStoredEntries(): Promise {
+ const database = await openDatabase();
+ if (!database) {
+ return [];
+ }
+ return new Promise((resolve, reject) => {
+ const transaction = database.transaction(STORE_NAME, 'readonly');
+ const request = transaction.objectStore(STORE_NAME).getAll();
+ request.onsuccess = () => resolve(request.result.filter(isQueueEntry));
+ request.onerror = () =>
+ reject(request.error ?? new Error('Unable to read artifact sync queue'));
+ transaction.oncomplete = () => database.close();
+ });
+}
+
+async function hydrateQueue(): Promise {
+ if (!hydrationPromise) {
+ hydrationPromise = readStoredEntries()
+ .catch(() => [])
+ .then((entries) => {
+ for (const entry of entries) {
+ const current = memoryQueue.get(entry.id);
+ if (!current || current.updatedAt < entry.updatedAt) {
+ memoryQueue.set(entry.id, entry);
+ }
+ }
+ });
+ }
+ await hydrationPromise;
+}
+
+async function writeStoredEntry(entry: ArtifactSyncQueueEntry, retry = false): Promise {
+ const database = await openDatabase();
+ if (!database) {
+ return true;
+ }
+ return new Promise((resolve, reject) => {
+ const transaction = database.transaction(STORE_NAME, 'readwrite');
+ const store = transaction.objectStore(STORE_NAME);
+ const readRequest = store.get(entry.id);
+ let written = false;
+ readRequest.onsuccess = () => {
+ const stored = readRequest.result;
+ if (!retry || !isQueueEntry(stored) || stored.signature === entry.signature) {
+ store.put(entry);
+ written = true;
+ }
+ };
+ transaction.oncomplete = () => {
+ database.close();
+ resolve(written);
+ };
+ transaction.onerror = () => reject(transaction.error ?? new Error('Unable to save sync item'));
+ });
+}
+
+async function deleteStoredEntry(id: string, signature: string): Promise {
+ const database = await openDatabase();
+ if (!database) {
+ return;
+ }
+ await new Promise((resolve, reject) => {
+ const transaction = database.transaction(STORE_NAME, 'readwrite');
+ const store = transaction.objectStore(STORE_NAME);
+ const readRequest = store.get(id);
+ readRequest.onsuccess = () => {
+ if (isQueueEntry(readRequest.result) && readRequest.result.signature === signature) {
+ store.delete(id);
+ }
+ };
+ transaction.oncomplete = () => {
+ database.close();
+ resolve();
+ };
+ transaction.onerror = () =>
+ reject(transaction.error ?? new Error('Unable to remove artifact sync item'));
+ });
+}
+
+export function getArtifactSyncQueueId(ownerId: string, request: TSyncArtifactAppRequest): string {
+ return `${ownerId}\u0000${request.source.conversationId}\u0000${request.source.sourceKey}`;
+}
+
+export async function enqueueArtifactSync(
+ ownerId: string,
+ request: TSyncArtifactAppRequest,
+ signature: string,
+ delayMs: number,
+): Promise {
+ await hydrateQueue();
+ const id = getArtifactSyncQueueId(ownerId, request);
+ const current = memoryQueue.get(id);
+ const entry: ArtifactSyncQueueEntry = {
+ id,
+ ownerId,
+ request,
+ signature,
+ failures: current?.signature === signature ? current.failures : 0,
+ nextAttemptAt: Date.now() + delayMs,
+ updatedAt: now(),
+ };
+ memoryQueue.set(id, entry);
+ const persisted = persistQueueChange(() => writeStoredEntry(entry));
+ notifyListeners();
+ broadcast({ type: 'upsert', entry });
+ await persisted;
+}
+
+export async function listArtifactSyncQueue(ownerId: string): Promise {
+ await hydrateQueue();
+ return Array.from(memoryQueue.values()).filter((entry) => entry.ownerId === ownerId);
+}
+
+/**
+ * Re-reads the in-memory snapshot for one entry. Other tabs keep this current via
+ * {@link broadcast}, so a caller can check it immediately before sending or activating a
+ * queued request to reject one superseded since it was read off {@link listArtifactSyncQueue}.
+ */
+export function getCurrentArtifactSyncEntry(id: string): ArtifactSyncQueueEntry | undefined {
+ return memoryQueue.get(id);
+}
+
+export async function completeArtifactSync(id: string, signature: string): Promise {
+ await hydrateQueue();
+ if (memoryQueue.get(id)?.signature !== signature) {
+ return;
+ }
+ memoryQueue.delete(id);
+ const persisted = persistQueueChange(() => deleteStoredEntry(id, signature));
+ notifyListeners();
+ broadcast({ type: 'delete', id, signature });
+ await persisted;
+}
+
+/**
+ * Locks in a baseline that failed to resolve when this entry was enqueued, once the worker
+ * manages to resolve it before a later send attempt. Applies only while the entry still has no
+ * baseline and is still the exact request it was resolved for (same signature) — an
+ * already-resolved baseline, or one superseded by a newer edit since the resolve started, is
+ * left alone.
+ */
+export async function recordArtifactSyncBaseline(
+ id: string,
+ signature: string,
+ basedOnVersionNumber: number,
+): Promise {
+ await hydrateQueue();
+ const current = memoryQueue.get(id);
+ if (!current || current.signature !== signature || current.request.basedOnVersionNumber != null) {
+ return false;
+ }
+ const updated: ArtifactSyncQueueEntry = {
+ ...current,
+ request: { ...current.request, basedOnVersionNumber },
+ updatedAt: now(),
+ };
+ memoryQueue.set(id, updated);
+ const persisted = await persistQueueChange(() => writeStoredEntry(updated, true));
+ if (!persisted) {
+ if (memoryQueue.get(id) === updated) {
+ memoryQueue.delete(id);
+ }
+ return false;
+ }
+ notifyListeners();
+ broadcast({ type: 'upsert', entry: updated });
+ const latest = memoryQueue.get(id);
+ return (
+ latest?.signature === signature && latest.request.basedOnVersionNumber === basedOnVersionNumber
+ );
+}
+
+export async function rescheduleArtifactSync(
+ id: string,
+ signature: string,
+ delayMs: number,
+): Promise {
+ await hydrateQueue();
+ const current = memoryQueue.get(id);
+ if (!current || current.signature !== signature) {
+ return;
+ }
+ const updated: ArtifactSyncQueueEntry = {
+ ...current,
+ failures: current.failures + 1,
+ nextAttemptAt: Date.now() + delayMs,
+ updatedAt: now(),
+ };
+ memoryQueue.set(id, updated);
+ const persisted = persistQueueChange(() => writeStoredEntry(updated, true));
+ notifyListeners();
+ broadcast({ type: 'upsert', entry: updated });
+ await persisted;
+}
+
+export function subscribeToArtifactSyncQueue(listener: QueueListener): () => void {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+}
+
+/** Test-only: releases this module instance's broadcast channel handle. */
+export function closeArtifactSyncChannelForTests(): void {
+ syncChannel?.close();
+}
+
+/** Test-only reset; production callers must retain queued registrations. */
+export async function clearArtifactSyncQueueForTests(): Promise {
+ await persistencePromise;
+ memoryQueue.clear();
+ hydrationPromise = null;
+ const database = await openDatabase();
+ if (!database) {
+ return;
+ }
+ await new Promise((resolve, reject) => {
+ const transaction = database.transaction(STORE_NAME, 'readwrite');
+ transaction.objectStore(STORE_NAME).clear();
+ transaction.oncomplete = () => {
+ database.close();
+ resolve();
+ };
+ transaction.onerror = () =>
+ reject(transaction.error ?? new Error('Unable to clear sync queue'));
+ });
+}
diff --git a/client/src/components/Artifacts/Artifact.tsx b/client/src/components/Artifacts/Artifact.tsx
index d2e98be5f1e..e7a9f6e6a23 100644
--- a/client/src/components/Artifacts/Artifact.tsx
+++ b/client/src/components/Artifacts/Artifact.tsx
@@ -1,13 +1,13 @@
import React, { useEffect, useCallback, useRef, useState } from 'react';
import throttle from 'lodash/throttle';
import { visit } from 'unist-util-visit';
-import { useSetRecoilState } from 'recoil';
import { useLocation } from 'react-router-dom';
+import { useRecoilValue, useSetRecoilState } from 'recoil';
import type { Pluggable } from 'unified';
import type { Artifact } from '~/common';
+import { artifactByIdSelector, artifactsState } from '~/store/artifacts';
import { useMessageContext, useArtifactContext } from '~/Providers';
import { logger, extractContent, isArtifactRoute } from '~/utils';
-import { artifactsState } from '~/store/artifacts';
import ArtifactButton from './ArtifactButton';
export const artifactPlugin: Pluggable = () => {
@@ -53,6 +53,7 @@ export function Artifact({
const setArtifacts = useSetRecoilState(artifactsState);
const [artifact, setArtifact] = useState(null);
+ const registeredArtifact = useRecoilValue(artifactByIdSelector(artifact?.id ?? ''));
const throttledUpdateRef = useRef(
throttle((updateFn: () => void) => {
@@ -124,5 +125,28 @@ export function Artifact({
updateArtifact();
}, [updateArtifact, resetCounter]);
+ /**
+ * Conversation hydration can reset the shared artifact map after message content has already
+ * rendered. Re-register the local parsed artifact when its map entry is missing or stale so a
+ * catalog deep link can resolve without requiring the message component to remount.
+ */
+ useEffect(() => {
+ if (!artifact || !isArtifactRoute(location.pathname)) {
+ return;
+ }
+ if (
+ registeredArtifact != null &&
+ registeredArtifact.content === artifact.content &&
+ registeredArtifact.type === artifact.type &&
+ registeredArtifact.title === artifact.title
+ ) {
+ return;
+ }
+ setArtifacts((prevArtifacts) => ({
+ ...(prevArtifacts ?? {}),
+ [artifact.id]: artifact,
+ }));
+ }, [artifact, location.pathname, registeredArtifact, setArtifacts]);
+
return ;
}
diff --git a/client/src/components/Artifacts/ArtifactButton.tsx b/client/src/components/Artifacts/ArtifactButton.tsx
index 58535031041..5e4c4d44127 100644
--- a/client/src/components/Artifacts/ArtifactButton.tsx
+++ b/client/src/components/Artifacts/ArtifactButton.tsx
@@ -3,6 +3,7 @@ import debounce from 'lodash/debounce';
import { useLocation } from 'react-router-dom';
import { useRecoilState, useSetRecoilState, useResetRecoilState } from 'recoil';
import type { Artifact } from '~/common';
+import useClearArtifactNavigationRequest from '~/hooks/Artifacts/useClearArtifactNavigationRequest';
import ArtifactRow from '~/components/Chat/Messages/Content/Parts/ArtifactRow';
import { artifactRowKind } from '~/utils/artifacts';
import { logger, isArtifactRoute } from '~/utils';
@@ -16,6 +17,7 @@ const ArtifactButton = ({ artifact }: { artifact: Artifact | null }) => {
const resetCurrentArtifactId = useResetRecoilState(store.currentArtifactId);
const isSelected = artifact?.id === currentArtifactId;
const [visibleArtifacts, setVisibleArtifacts] = useRecoilState(store.visibleArtifacts);
+ const clearArtifactNavigationRequest = useClearArtifactNavigationRequest();
const debouncedSetVisibleRef = useRef(
debounce((artifactToSet: Artifact) => {
@@ -52,6 +54,7 @@ const ArtifactButton = ({ artifact }: { artifact: Artifact | null }) => {
}
const handleOpen = () => {
+ clearArtifactNavigationRequest();
if (isSelected) {
resetCurrentArtifactId();
setVisible(false);
diff --git a/client/src/components/Artifacts/ArtifactPreview.test.tsx b/client/src/components/Artifacts/ArtifactPreview.test.tsx
new file mode 100644
index 00000000000..cfe22faf372
--- /dev/null
+++ b/client/src/components/Artifacts/ArtifactPreview.test.tsx
@@ -0,0 +1,96 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import type {
+ SandpackProviderProps,
+ SandpackPreviewRef,
+} from '@codesandbox/sandpack-react/unstyled';
+import { ARTIFACT_PREVIEW_BRIDGE_SCRIPT } from '~/utils/artifactPreviewCapture';
+import { ArtifactPreview } from './ArtifactPreview';
+
+const mockSandpackPreview = jest.fn(() => );
+const mockSandpackProvider = jest.fn((props: SandpackProviderProps) => (
+ {props.children}
+));
+
+jest.mock('@codesandbox/sandpack-react/unstyled', () => ({
+ SandpackPreview: () => mockSandpackPreview(),
+ SandpackProvider: (props: SandpackProviderProps) => mockSandpackProvider(props),
+}));
+
+describe('ArtifactPreview', () => {
+ beforeEach(() => {
+ mockSandpackPreview.mockClear();
+ mockSandpackProvider.mockClear();
+ });
+
+ it('renders static HTML artifacts through the isolated Sandpack preview, not a local iframe', () => {
+ const previewRef = {
+ current: undefined,
+ } as unknown as React.MutableRefObject;
+
+ const { container } = render(
+ Hello World!