feat: add ShareRoomPicker component for selecting rooms to share Android content

- Implemented ShareRoomPicker component to allow users to pick a room for sharing content received from Android intents. - Integrated search functionality to filter rooms and directs. - Added virtualized list for efficient rendering of room options. - Created utility functions for handling Android share payloads, including fetching and clearing pending shares. Co-authored-by: Copilot <copilot@github.com>
2026-04-26 14:32:19 +10:00
parent 6df60c8348
commit c263b681d4
14 changed files with 1090 additions and 50 deletions
--- a/overlay/src/app/features/ShareRoomPicker.tsx
+++ b/overlay/src/app/features/ShareRoomPicker.tsx
@@ -0,0 +1,255 @@
+import { useAtomValue } from 'jotai';
+import React, { ChangeEventHandler, useCallback, useMemo, useRef, useState } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import FocusTrap from 'focus-trap-react';
+import {
+  Avatar,
+  Box,
+  Header,
+  Icon,
+  IconButton,
+  Icons,
+  Input,
+  MenuItem,
+  Modal,
+  Overlay,
+  OverlayBackdrop,
+  OverlayCenter,
+  Scroll,
+  Text,
+  config,
+} from 'folds';
+import { useMatrixClient } from '../hooks/useMatrixClient';
+import { useAllJoinedRoomsSet, useGetRoom } from '../hooks/useGetRoom';
+import { allRoomsAtom } from '../state/room-list/roomList';
+import { mDirectAtom } from '../state/mDirectList';
+import { useDirects, useRooms } from '../state/hooks/roomList';
+import { getDirectRoomAvatarUrl, getRoomAvatarUrl } from '../utils/room';
+import { RoomAvatar, RoomIcon } from '../components/room-avatar';
+import { nameInitials } from '../utils/common';
+import { useMediaAuthentication } from '../hooks/useMediaAuthentication';
+import { factoryRoomIdByActivity } from '../utils/sort';
+import {
+  SearchItemStrGetter,
+  useAsyncSearch,
+  UseAsyncSearchOptions,
+} from '../hooks/useAsyncSearch';
+import { VirtualTile } from '../components/virtualizer';
+import { AndroidSharePayload } from '../utils/androidShare';
+import { stopPropagation } from '../utils/keyboard';
+
+const SEARCH_OPTS: UseAsyncSearchOptions = {
+  limit: 200,
+  matchOptions: {
+    contain: true,
+  },
+};
+
+type ShareRoomPickerProps = {
+  /** The pending share payload to display a preview of. */
+  share: AndroidSharePayload;
+  /** Called when the user picks a room. */
+  onPick: (roomId: string) => void;
+  /** Called when the user dismisses without picking. */
+  onDismiss: () => void;
+};
+
+/**
+ * Full-screen modal that lets the user pick a room to send
+ * an incoming Android share intent into.
+ */
+export function ShareRoomPicker({ share, onPick, onDismiss }: ShareRoomPickerProps) {
+  const mx = useMatrixClient();
+  const useAuthentication = useMediaAuthentication();
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  const mDirects = useAtomValue(mDirectAtom);
+  const allRoomsSet = useAllJoinedRoomsSet();
+  const getRoom = useGetRoom(allRoomsSet);
+  const rooms = useRooms(mx, allRoomsAtom, mDirects);
+  const directs = useDirects(mx, allRoomsAtom, mDirects);
+
+  const allItems = useMemo(
+    () => [...rooms, ...directs].sort(factoryRoomIdByActivity(mx)),
+    [mx, rooms, directs]
+  );
+
+  const getRoomNameStr: SearchItemStrGetter<string> = useCallback(
+    (rId) => getRoom(rId)?.name ?? rId,
+    [getRoom]
+  );
+
+  const [searchResult, searchRoom, resetSearch] = useAsyncSearch(
+    allItems,
+    getRoomNameStr,
+    SEARCH_OPTS
+  );
+
+  const items = searchResult ? searchResult.items : allItems;
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => 48,
+    overscan: 8,
+  });
+  const vItems = virtualizer.getVirtualItems();
+
+  const handleSearchChange: ChangeEventHandler<HTMLInputElement> = (evt) => {
+    const value = evt.currentTarget.value.trim();
+    if (!value) {
+      resetSearch();
+      return;
+    }
+    searchRoom(value);
+  };
+
+  const handleRoomClick: React.MouseEventHandler<HTMLButtonElement> = (evt) => {
+    const roomId = evt.currentTarget.getAttribute('data-room-id');
+    if (roomId) {
+      onPick(roomId);
+    }
+  };
+
+  const previewText = share.text?.slice(0, 80) ?? share.subject?.slice(0, 80);
+  const fileCount = share.files.length;
+
+  return (
+    <Overlay open backdrop={<OverlayBackdrop />}>
+      <OverlayCenter>
+        <FocusTrap
+          focusTrapOptions={{
+            initialFocus: false,
+            clickOutsideDeactivates: true,
+            onDeactivate: onDismiss,
+            escapeDeactivates: stopPropagation,
+          }}
+        >
+          <Modal size="300">
+            <Box grow="Yes" direction="Column" style={{ maxHeight: '85vh' }}>
+              <Header
+                size="500"
+                style={{ padding: config.space.S200, paddingLeft: config.space.S400 }}
+              >
+                <Box grow="Yes" direction="Column" gap="100">
+                  <Text size="H4">Share to Room</Text>
+                  {(previewText || fileCount > 0) && (
+                    <Text size="T200" priority="300" style={{ opacity: 0.7 }}>
+                      {previewText
+                        ? `"${previewText}${(share.text?.length ?? 0) > 80 ? '…' : ''}"`
+                        : `${fileCount} file${fileCount !== 1 ? 's' : ''}`}
+                    </Text>
+                  )}
+                </Box>
+                <Box shrink="No">
+                  <IconButton size="300" radii="300" onClick={onDismiss}>
+                    <Icon src={Icons.Cross} />
+                  </IconButton>
+                </Box>
+              </Header>
+
+              <Box
+                style={{
+                  padding: `0 ${config.space.S300}`,
+                  paddingTop: config.space.S200,
+                  paddingBottom: config.space.S200,
+                }}
+              >
+                <Input
+                  onChange={handleSearchChange}
+                  before={<Icon size="200" src={Icons.Search} />}
+                  placeholder="Search rooms…"
+                  size="400"
+                  variant="Background"
+                  outlined
+                  autoFocus
+                />
+              </Box>
+
+              <Scroll ref={scrollRef} size="300" hideTrack style={{ flex: 1, minHeight: 0 }}>
+                <Box
+                  style={{ padding: config.space.S300, paddingTop: 0 }}
+                  direction="Column"
+                >
+                  {vItems.length === 0 && (
+                    <Box
+                      style={{ padding: `${config.space.S700} 0` }}
+                      alignItems="Center"
+                      justifyContent="Center"
+                      direction="Column"
+                      gap="100"
+                    >
+                      <Text size="H6" align="Center">
+                        {searchResult ? 'No Match Found' : 'No Rooms'}
+                      </Text>
+                      <Text size="T200" align="Center" priority="300">
+                        {searchResult
+                          ? `No rooms found for "${searchResult.query}".`
+                          : 'You have no rooms to share into.'}
+                      </Text>
+                    </Box>
+                  )}
+                  <Box
+                    style={{ position: 'relative', height: virtualizer.getTotalSize() }}
+                  >
+                    {vItems.map((vItem) => {
+                      const roomId = items[vItem.index];
+                      const room = getRoom(roomId);
+                      if (!room) return null;
+                      const isDm = mDirects.has(roomId);
+
+                      const avatarSrc = isDm
+                        ? getDirectRoomAvatarUrl(mx, room, 96, useAuthentication)
+                        : getRoomAvatarUrl(mx, room, 96, useAuthentication);
+
+                      return (
+                        <VirtualTile
+                          virtualItem={vItem}
+                          style={{ paddingBottom: config.space.S100 }}
+                          ref={virtualizer.measureElement}
+                          key={roomId}
+                        >
+                          <MenuItem
+                            data-room-id={roomId}
+                            onClick={handleRoomClick}
+                            variant="Surface"
+                            size="400"
+                            radii="400"
+                            before={
+                              <Avatar size="300" radii={isDm ? '400' : '300'}>
+                                {avatarSrc ? (
+                                  <RoomAvatar
+                                    roomId={roomId}
+                                    src={avatarSrc}
+                                    alt={room.name}
+                                    renderFallback={() => (
+                                      <Text as="span" size="H6">
+                                        {nameInitials(room.name)}
+                                      </Text>
+                                    )}
+                                  />
+                                ) : (
+                                  <RoomIcon room={room} size="200" filled />
+                                )}
+                              </Avatar>
+                            }
+                          >
+                            <Box grow="Yes" direction="Column">
+                              <Text size="B400" truncate>
+                                {room.name}
+                              </Text>
+                            </Box>
+                          </MenuItem>
+                        </VirtualTile>
+                      );
+                    })}
+                  </Box>
+                </Box>
+              </Scroll>
+            </Box>
+          </Modal>
+        </FocusTrap>
+      </OverlayCenter>
+    </Overlay>
+  );
+}
--- a/overlay/src/app/features/settings/notifications/SystemNotification.tsx
+++ b/overlay/src/app/features/settings/notifications/SystemNotification.tsx
@@ -1,4 +1,4 @@
-import React, { useCallback } from 'react';
+import React, { useCallback, useEffect, useState } from 'react';
 import { Box, Text, Switch, Button, color, Spinner } from 'folds';
 import { IPusherRequest } from 'matrix-js-sdk';
 import { SequenceCard } from '../../../components/sequence-card';
@@ -11,6 +11,12 @@ import { useEmailNotifications } from '../../../hooks/useEmailNotifications';
 import { AsyncStatus, useAsyncCallback } from '../../../hooks/useAsyncCallback';
 import { useMatrixClient } from '../../../hooks/useMatrixClient';
 import { isCapacitorNative, requestSystemNotificationPermission } from '../../../utils/tauri';
+import {
+  isBackgroundSyncSupported,
+  getBackgroundSyncStatus,
+  requestResetPushRegistration,
+  triggerBackgroundSyncPing,
+} from '../../../utils/backgroundSync';

 function EmailNotification() {
  const mx = useMatrixClient();
@@ -147,6 +153,7 @@ export function SystemNotification() {
          after={<Switch value={isNotificationSounds} onChange={setIsNotificationSounds} />}
        />
      </SequenceCard>
+      {isBackgroundSyncSupported() && <AndroidPushNotifications />}
      <SequenceCard
        className={SequenceCardStyle}
        variant="SurfaceVariant"
@@ -158,3 +165,126 @@ export function SystemNotification() {
    </Box>
  );
 }
+
+type PushStatus = {
+  registered: boolean;
+  distributor: string;
+  endpoint: string;
+};
+
+/** Android-only section showing UnifiedPush registration status and controls. */
+function AndroidPushNotifications() {
+  const [status, setStatus] = useState<PushStatus | undefined>(undefined);
+  const [loading, setLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    const s = await getBackgroundSyncStatus();
+    setStatus(
+      s
+        ? {
+            registered: s.registered,
+            distributor: s.distributor || '',
+            endpoint: s.endpoint || '',
+          }
+        : undefined
+    );
+    setLoading(false);
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const [resetState, reset] = useAsyncCallback(
+    useCallback(async () => {
+      await requestResetPushRegistration();
+      await refresh();
+    }, [refresh])
+  );
+
+  const [pingState, ping] = useAsyncCallback(
+    useCallback(async () => {
+      await triggerBackgroundSyncPing('manual-test');
+    }, [])
+  );
+
+  const isBusy =
+    loading ||
+    resetState.status === AsyncStatus.Loading ||
+    pingState.status === AsyncStatus.Loading;
+
+  return (
+    <Box direction="Column" gap="100">
+      <Text size="L400">Android Push (UnifiedPush)</Text>
+      <SequenceCard
+        className={SequenceCardStyle}
+        variant="SurfaceVariant"
+        direction="Column"
+        gap="400"
+      >
+        <SettingTile
+          title="Background Notifications"
+          description={
+            loading ? (
+              'Loading status…'
+            ) : status === undefined ? (
+              <Text as="span" style={{ color: color.Critical.Main }} size="T200">
+                Failed to read push status.
+              </Text>
+            ) : status.registered ? (
+              <>
+                <Text as="span" size="T200">
+                  {`Distributor: ${status.distributor || 'unknown'}`}
+                </Text>
+              </>
+            ) : (
+              <Text as="span" style={{ color: color.Warning?.Main ?? color.Critical.Main }} size="T200">
+                Not registered. Tap &quot;Reset&quot; to choose a distributor app.
+              </Text>
+            )
+          }
+          after={loading ? <Spinner variant="Secondary" /> : undefined}
+        />
+        <SettingTile
+          title="Change Distributor"
+          description="Re-open the UnifiedPush distributor selection dialog."
+          after={
+            <Button
+              size="300"
+              radii="300"
+              variant="Secondary"
+              disabled={isBusy}
+              onClick={() => void reset()}
+            >
+              {resetState.status === AsyncStatus.Loading ? (
+                <Spinner variant="Secondary" size="200" />
+              ) : (
+                <Text size="B300">Reset</Text>
+              )}
+            </Button>
+          }
+        />
+        <SettingTile
+          title="Test Notification"
+          description="Trigger a test push ping to verify the pipeline works."
+          after={
+            <Button
+              size="300"
+              radii="300"
+              variant="Secondary"
+              disabled={isBusy}
+              onClick={() => void ping()}
+            >
+              {pingState.status === AsyncStatus.Loading ? (
+                <Spinner variant="Secondary" size="200" />
+              ) : (
+                <Text size="B300">Send Test</Text>
+              )}
+            </Button>
+          }
+        />
+      </SequenceCard>
+    </Box>
+  );
+}
--- a/overlay/src/app/pages/client/ClientNonUIFeatures.tsx
+++ b/overlay/src/app/pages/client/ClientNonUIFeatures.tsx
@@ -1,5 +1,6 @@
 import { useAtomValue } from 'jotai';
-import React, { ReactNode, useCallback, useEffect, useRef } from 'react';
+import { useAtom, useSetAtom } from 'jotai';
+import React, { ReactNode, useCallback, useEffect, useRef, useState, Fragment } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { RoomEvent, RoomEventHandlerMap } from 'matrix-js-sdk';
 import { roomToUnreadAtom, unreadEqual, unreadInfoToUnread } from '../../state/room/roomToUnread';
@@ -28,6 +29,8 @@ import { roomToParentsAtom } from '../../state/room/roomToParents';
 import { useSelectedRoom } from '../../hooks/router/useSelectedRoom';
 import { useInboxNotificationsSelected } from '../../hooks/router/useInbox';
 import { useMediaAuthentication } from '../../hooks/useMediaAuthentication';
+import { plainToEditorInput, toPlainText } from '../../components/editor';
+import { ShareRoomPicker } from '../../features/ShareRoomPicker';
 import {
  isTauri,
  isElectron,
@@ -41,6 +44,20 @@ import {
  stopBackgroundSync,
  setAppForegroundState,
 } from '../../utils/backgroundSync';
+import {
+  TUploadItem,
+  roomIdToMsgDraftAtomFamily,
+  roomIdToUploadItemsAtomFamily,
+} from '../../state/room/roomInputDrafts';
+import { encryptFile } from '../../utils/matrix';
+import {
+  AndroidSharePayload,
+  clearPendingAndroidShare,
+  getPendingAndroidShare,
+  isAndroidShareSupported,
+  listenForAndroidShares,
+  materializeSharedFile,
+} from '../../utils/androidShare';

 /**
 * Applies the selected emoji style font to the document.
@@ -426,8 +443,13 @@ function MessageNotifications() {
 */
 function BackgroundSyncSetup() {
  const mx = useMatrixClient();
+  // Try to make a simple fetch to verify component is rendering
+  try {
+    fetch('/_matrix/client/v3/sync', { method: 'HEAD' }).catch(() => {});
+  } catch {}

  useEffect(() => {
+    console.log('BackgroundSyncSetup: Starting background sync for', mx.getUserId());
    startBackgroundSync(mx);

    const onVisibility = () => setAppForegroundState(!document.hidden);
@@ -493,6 +515,135 @@ function TaskbarFlashStopper() {
  return null;
 }

+function AndroidShareIntentHandler() {
+  const mx = useMatrixClient();
+  const [isMarkdown] = useSetting(settingsAtom, 'isMarkdown');
+  const [pendingShare, setPendingShare] = useState<AndroidSharePayload | null>(null);
+  const [pickedRoomId, setPickedRoomId] = useState<string | null>(null);
+  const [msgDraft, setMsgDraft] = useAtom(roomIdToMsgDraftAtomFamily(pickedRoomId ?? '__android_share__'));
+  const setUploadItems = useSetAtom(roomIdToUploadItemsAtomFamily(pickedRoomId ?? '__android_share__'));
+
+  const applyPendingShare = useCallback(
+    async (share: AndroidSharePayload, roomId: string) => {
+      const room = mx.getRoom(roomId);
+      if (!room) return false;
+
+      const nextParts = [share.subject?.trim(), share.text?.trim()].filter(
+        (value): value is string => !!value
+      );
+      if (nextParts.length > 0) {
+        const existingText = toPlainText(msgDraft, isMarkdown).trim();
+        const nextText = existingText ? `${existingText}\n${nextParts.join('\n')}` : nextParts.join('\n');
+        setMsgDraft(plainToEditorInput(nextText, isMarkdown));
+      }
+
+      if (share.files.length > 0) {
+        const uploadItems: TUploadItem[] = [];
+        for (const sharedFile of share.files) {
+          const originalFile = await materializeSharedFile(sharedFile, share.receivedAt);
+          if (room.hasEncryptionStateEvent()) {
+            const encrypted = await encryptFile(originalFile);
+            uploadItems.push({
+              file: encrypted.file,
+              originalFile,
+              metadata: { markedAsSpoiler: false },
+              encInfo: encrypted.encInfo,
+            });
+            continue;
+          }
+
+          uploadItems.push({
+            file: originalFile,
+            originalFile,
+            metadata: { markedAsSpoiler: false },
+            encInfo: undefined,
+          });
+        }
+
+        setUploadItems({
+          type: 'PUT',
+          item: uploadItems,
+        });
+      }
+
+      await clearPendingAndroidShare();
+      return true;
+    },
+    [isMarkdown, msgDraft, mx, setMsgDraft, setUploadItems]
+  );
+
+  const handlePickRoom = useCallback(
+    (roomId: string) => {
+      setPickedRoomId(roomId);
+      if (!pendingShare) return;
+
+      applyPendingShare(pendingShare, roomId)
+        .then((applied) => {
+          if (applied) {
+            setPendingShare(null);
+            setPickedRoomId(null);
+          }
+        })
+        .catch((err) => {
+          console.error('[AndroidShare] Failed to apply share after pick:', err);
+          setPendingShare(null);
+          setPickedRoomId(null);
+        });
+    },
+    [applyPendingShare, pendingShare]
+  );
+
+  const handleDismiss = useCallback(() => {
+    clearPendingAndroidShare().catch(() => {});
+    setPendingShare(null);
+    setPickedRoomId(null);
+  }, []);
+
+  useEffect(() => {
+    if (!isAndroidShareSupported()) return;
+
+    let mounted = true;
+    let listenerHandle: { remove: () => Promise<void> } | undefined;
+
+    getPendingAndroidShare()
+      .then((share) => {
+        if (mounted && share) {
+          setPendingShare(share);
+        }
+      })
+      .catch((err) => {
+        console.error('[AndroidShare] Failed to get pending share:', err);
+      });
+
+    listenForAndroidShares((share) => {
+      if (mounted) {
+        setPendingShare(share);
+      }
+    })
+      .then((handle) => {
+        listenerHandle = handle;
+      })
+      .catch((err) => {
+        console.error('[AndroidShare] Failed to listen for shares:', err);
+      });
+
+    return () => {
+      mounted = false;
+      void listenerHandle?.remove();
+    };
+  }, []);
+
+  if (!pendingShare) return null;
+
+  return (
+    <ShareRoomPicker
+      share={pendingShare}
+      onPick={handlePickRoom}
+      onDismiss={handleDismiss}
+    />
+  );
+}
+
 type ClientNonUIFeaturesProps = {
  children: ReactNode;
 };
@@ -508,6 +659,7 @@ export function ClientNonUIFeatures({ children }: ClientNonUIFeaturesProps) {
      <BackgroundSyncSetup />
      <PaarrotAPIInitializer />
      <TaskbarFlashStopper />
+      <AndroidShareIntentHandler />
      {children}
    </>
  );
--- a/overlay/src/app/utils/androidShare.ts
+++ b/overlay/src/app/utils/androidShare.ts
@@ -0,0 +1,73 @@
+import { Capacitor, registerPlugin, type PluginListenerHandle } from '@capacitor/core';
+
+/** Metadata for a file received from an Android share intent. */
+export type AndroidSharedFile = {
+  path: string;
+  name: string;
+  mimeType: string;
+  size: number;
+};
+
+/** Payload persisted by the native Android share handler. */
+export type AndroidSharePayload = {
+  text?: string;
+  subject?: string;
+  files: AndroidSharedFile[];
+  receivedAt: number;
+};
+
+interface AndroidShareHandlerPlugin {
+  /** Returns the last pending share payload, if one exists. */
+  getPendingShare(): Promise<{ share: AndroidSharePayload | null }>;
+  /** Clears the last pending share payload after it has been consumed. */
+  clearPendingShare(): Promise<void>;
+  addListener(
+    eventName: 'shareReceived',
+    listenerFunc: (payload: AndroidSharePayload) => void
+  ): Promise<PluginListenerHandle>;
+}
+
+const AndroidShareHandler = registerPlugin<AndroidShareHandlerPlugin>('AndroidShareHandler');
+
+/** Returns true when the Android share bridge is available. */
+export const isAndroidShareSupported = (): boolean =>
+  Capacitor.isNativePlatform() && Capacitor.getPlatform() === 'android';
+
+/** Fetches the current pending native share payload. */
+export const getPendingAndroidShare = async (): Promise<AndroidSharePayload | null> => {
+  if (!isAndroidShareSupported()) return null;
+  const result = await AndroidShareHandler.getPendingShare();
+  return result.share;
+};
+
+/** Clears the native pending share payload. */
+export const clearPendingAndroidShare = async (): Promise<void> => {
+  if (!isAndroidShareSupported()) return;
+  await AndroidShareHandler.clearPendingShare();
+};
+
+/** Subscribes to new incoming native share payloads. */
+export const listenForAndroidShares = async (
+  listener: (payload: AndroidSharePayload) => void
+): Promise<PluginListenerHandle | undefined> => {
+  if (!isAndroidShareSupported()) return undefined;
+  return AndroidShareHandler.addListener('shareReceived', listener);
+};
+
+/** Converts a cached native shared file into a browser File for upload. */
+export const materializeSharedFile = async (
+  sharedFile: AndroidSharedFile,
+  receivedAt: number
+): Promise<File> => {
+  const fileUrl = Capacitor.convertFileSrc(sharedFile.path);
+  const response = await fetch(fileUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to read shared file: ${sharedFile.name}`);
+  }
+
+  const blob = await response.blob();
+  return new File([blob], sharedFile.name, {
+    type: sharedFile.mimeType || blob.type,
+    lastModified: receivedAt,
+  });
+};
--- a/overlay/src/app/utils/backgroundSync.ts
+++ b/overlay/src/app/utils/backgroundSync.ts
@@ -7,7 +7,7 @@ type UnifiedPushStatus = {
  instance: string;
  registered: boolean;
  distributor: string;
-  distributors: string[];
+  distributors: string[] | string;
 };

 type UnifiedPushEndpointEvent = {
@@ -36,6 +36,8 @@ interface MatrixBackgroundSyncPlugin {
  }): Promise<void>;
  /** Trigger a one-shot fetch as if a push ping arrived. */
  triggerPing(options: { reason?: string }): Promise<void>;
+  /** Re-open distributor setup flow and retry registration. */
+  requestDistributorSetup(): Promise<{ success: boolean }>;
  /** Stop any in-flight fetch, clear credentials, and unregister UnifiedPush. */
  stop(): Promise<void>;
  /**
@@ -112,6 +114,24 @@ const clearStoredPusherState = (userId: string | null, deviceId: string | null):
  window.localStorage.removeItem(getStoredPusherKey(userId, deviceId));
 };

+const normalizeDistributors = (raw: UnifiedPushStatus['distributors']): string[] => {
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw !== 'string') return [];
+
+  const trimmed = raw.trim();
+  if (!trimmed || trimmed === '[]') return [];
+
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    return trimmed
+      .slice(1, -1)
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+
+  return [trimmed];
+};
+
 const resolveUnifiedPushGateway = async (endpoint: string): Promise<string> => {
  try {
    const discoveryUrl = new URL(endpoint);
@@ -143,31 +163,52 @@ class AndroidUnifiedPushManager {

  private listenersReady = false;

+  private distributorSetupAttempted = false;
+
+  private distributorPromptShown = false;
+
  /** Start native UnifiedPush registration and synchronize the Matrix pusher. */
  async start(mx: MatrixClient): Promise<void> {
-    if (!isBackgroundSyncSupported()) return;
+    console.log('[BackgroundSync] start() called, platform:', Capacitor.getPlatform(), 'isNative:', Capacitor.isNativePlatform());
+    
+    if (!isBackgroundSyncSupported()) {
+      console.log('[BackgroundSync] Background sync not supported on this platform');
+      return;
+    }

    const homeserverUrl = mx.getHomeserverUrl();
    const accessToken = mx.getAccessToken();
    const userId = mx.getUserId();
    const deviceId = mx.getDeviceId();

+    console.log('[BackgroundSync] Credentials check:', { userId, deviceId, hasToken: !!accessToken, hasUrl: !!homeserverUrl });
+
    if (!homeserverUrl || !accessToken || !userId) {
      console.warn('[BackgroundSync] Missing credentials, not starting');
      return;
    }

    this.client = mx;
+    this.distributorSetupAttempted = false;
+    this.distributorPromptShown = false;
    await this.ensureListeners();

-    await MatrixBackgroundSync.start({
-      homeserverUrl,
-      accessToken,
-      userId,
-      deviceId: deviceId ?? '',
-    });
+    try {
+      console.log('[BackgroundSync] Calling plugin.start()...');
+      await MatrixBackgroundSync.start({
+        homeserverUrl,
+        accessToken,
+        userId,
+        deviceId: deviceId ?? '',
+      });
+      console.log('[BackgroundSync] plugin.start() completed');
+    } catch (err) {
+      console.error('[BackgroundSync] plugin.start() failed:', err);
+      throw err;
+    }

    await this.syncExistingEndpoint();
+    await this.ensureDistributorPromptFromStatus();
    console.log('[BackgroundSync] UnifiedPush registration requested');
  }

@@ -227,6 +268,67 @@ class AndroidUnifiedPushManager {
  /** Log native registration failures so the missing distributor path is visible. */
  private handleRegistrationFailed(event: UnifiedPushRegistrationFailedEvent): void {
    console.warn('[BackgroundSync] UnifiedPush registration failed:', event.reason);
+
+    if (event.reason !== 'ACTION_REQUIRED' || this.distributorSetupAttempted) {
+      return;
+    }
+
+    this.distributorSetupAttempted = true;
+    void this.tryRequestDistributorSetup();
+  }
+
+  /** Re-opens distributor selection once after ACTION_REQUIRED and logs actionable status. */
+  private async tryRequestDistributorSetup(): Promise<void> {
+    try {
+      const setupResult = await MatrixBackgroundSync.requestDistributorSetup();
+      console.warn('[BackgroundSync] requestDistributorSetup result:', setupResult);
+      const status = await this.safeGetStatus();
+      console.warn('[BackgroundSync] UnifiedPush status after setup attempt:', status);
+      const distributors = normalizeDistributors(status?.distributors ?? []);
+      if (distributors.length === 0) {
+        console.error(
+          '[BackgroundSync] No UnifiedPush distributor installed. Install one (for example ntfy) to enable Android background notifications.'
+        );
+        this.showNoDistributorPrompt();
+      }
+    } catch (err) {
+      console.warn('[BackgroundSync] requestDistributorSetup failed:', err);
+    }
+  }
+
+  /** Fallback check so users still get prompted even when ACTION_REQUIRED event is missed. */
+  private async ensureDistributorPromptFromStatus(): Promise<void> {
+    const status = await this.safeGetStatus();
+    if (!status) return;
+
+    const distributors = normalizeDistributors(status.distributors);
+    if (!status.registered && distributors.length === 0) {
+      console.error(
+        '[BackgroundSync] No UnifiedPush distributor installed. Install one (for example ntfy) to enable Android background notifications.'
+      );
+      this.showNoDistributorPrompt();
+    }
+  }
+
+  /** Show a one-time actionable prompt when no distributor app is installed. */
+  private showNoDistributorPrompt(): void {
+    if (this.distributorPromptShown) return;
+    this.distributorPromptShown = true;
+
+    const message =
+      'Android background notifications need a UnifiedPush distributor app. Install one (for example ntfy), then reopen Paarrot.';
+    const docsUrl = 'https://unifiedpush.org/users/distributors/';
+
+    if (typeof window === 'undefined') return;
+
+    try {
+      const openDocs = window.confirm(`${message}\n\nOpen distributor list now?`);
+      if (openDocs) {
+        window.open(docsUrl, '_blank', 'noopener,noreferrer');
+      }
+    } catch {
+      window.alert(message);
+    }
  }

  /** Install plugin listeners once for the active Matrix client. */
@@ -235,7 +337,9 @@ class AndroidUnifiedPushManager {

    this.listenerHandles = [
      await MatrixBackgroundSync.addListener('unifiedPushNewEndpoint', (event) => {
-        void this.handleNewEndpoint(event);
+        void this.handleNewEndpoint(event).catch((err) => {
+          console.error('[BackgroundSync] handleNewEndpoint failed:', err);
+        });
      }),
      await MatrixBackgroundSync.addListener('unifiedPushUnregistered', (event) => {
        void this.handleUnregistered(event);
@@ -260,6 +364,7 @@ class AndroidUnifiedPushManager {
    if (!client) return;

    const status = await this.safeGetStatus();
+    console.log('[BackgroundSync] Native status before pusher sync:', status);
    if (status?.registered && status.endpoint) {
      await this.upsertPusher(client, status.endpoint);
    }
@@ -272,20 +377,40 @@ class AndroidUnifiedPushManager {
    const appId = buildPusherAppId(deviceId);
    const gatewayUrl = await resolveUnifiedPushGateway(endpoint);

-    await mx.setPusher({
-      kind: 'http',
-      app_id: appId,
-      pushkey: endpoint,
-      app_display_name: 'Paarrot',
-      device_display_name: deviceId ?? 'Android',
-      lang: 'en',
-      data: {
-        url: gatewayUrl,
-        format: 'event_id_only',
-      },
-      append: false,
-      device_id: deviceId ?? undefined,
-    } as unknown as IPusherRequest);
+    console.log('[BackgroundSync] Upserting Matrix pusher', {
+      appId,
+      endpoint,
+      gatewayUrl,
+      deviceId,
+      userId,
+    });
+
+    try {
+      await mx.setPusher({
+        kind: 'http',
+        app_id: appId,
+        pushkey: endpoint,
+        app_display_name: 'Paarrot',
+        device_display_name: deviceId ?? 'Android',
+        lang: 'en',
+        data: {
+          url: gatewayUrl,
+          format: 'event_id_only',
+        },
+        append: false,
+        device_id: deviceId ?? undefined,
+      } as unknown as IPusherRequest);
+
+      const pushers = (await mx.getPushers())?.pushers ?? [];
+      const thisPusher = pushers.find((p) => p.pushkey === endpoint && p.app_id === appId);
+      console.log('[BackgroundSync] Matrix pusher upserted successfully', {
+        totalPushers: pushers.length,
+        foundThisPusher: Boolean(thisPusher),
+      });
+    } catch (err) {
+      console.error('[BackgroundSync] Matrix pusher upsert failed:', err);
+      throw err;
+    }

    saveStoredPusherState(userId, deviceId, { endpoint, appId });
  }
@@ -359,3 +484,35 @@ export const setAppForegroundState = async (foreground: boolean): Promise<void>
    console.warn('[BackgroundSync] setAppForeground failed:', err);
  }
 };
+
+/**
+ * Re-opens the UnifiedPush distributor selection dialog.
+ * Allows users to re-select or change their push notification distributor without terminal access.
+ * Useful when the current endpoint becomes unavailable.
+ */
+export const requestResetPushRegistration = async (): Promise<{ success: boolean }> => {
+  if (!isBackgroundSyncSupported()) {
+    console.warn('[BackgroundSync] Background sync not supported on this platform');
+    return { success: false };
+  }
+
+  try {
+    const result = await MatrixBackgroundSync.requestDistributorSetup();
+    console.log('[BackgroundSync] requestDistributorSetup completed:', result);
+    return result ?? { success: false };
+  } catch (err) {
+    console.error('[BackgroundSync] requestDistributorSetup failed:', err);
+    return { success: false };
+  }
+};
+
+/** Returns the current native UnifiedPush status, or undefined if unavailable. */
+export const getBackgroundSyncStatus = async (): Promise<UnifiedPushStatus | undefined> => {
+  if (!isBackgroundSyncSupported()) return undefined;
+  try {
+    return await MatrixBackgroundSync.getStatus();
+  } catch (err) {
+    console.warn('[BackgroundSync] getStatus failed:', err);
+    return undefined;
+  }
+};