feat: update status handling and connection indicator in SurfSense plugin

- Changed initial status to "needs-setup" to prompt user configuration.
- Added a refreshStatus method to SyncEngine for immediate status updates after settings changes.
- Enhanced connection indicator logic in the settings tab to reflect the new status.
- Introduced "needs-setup" status visual for improved user feedback on configuration requirements.

surfsense_obsidian/src/main.ts

@@ -20,7 +20,7 @@ export default class SurfSensePlugin extends Plugin {
 	queue!: PersistentQueue;
 	engine!: SyncEngine;
 	private statusBar: StatusBar | null = null;
-	lastStatus: StatusState = { kind: "idle", queueDepth: 0 };
+	lastStatus: StatusState = { kind: "needs-setup", queueDepth: 0 };
 	serverCapabilities: string[] = [];
 	private settingTab: SurfSenseSettingTab | null = null;
 	private statusListeners = new Set<() => void>();
@@ -265,6 +265,9 @@ export default class SurfSensePlugin extends Plugin {
 
 	async saveSettings() {
 		await this.saveData(this.settings);
+		// Ensures the indicator reacts to settings edits (token paste, search-space pick)
+		// without waiting for the next sync trigger.
+		this.engine?.refreshStatus();
 	}
 
 	/**

surfsense_obsidian/src/settings.ts

@@ -20,6 +20,8 @@ export class SurfSenseSettingTab extends PluginSettingTab {
 	private readonly plugin: SurfSensePlugin;
 	private searchSpaces: SearchSpace[] = [];
 	private loadingSpaces = false;
+	private connectionIndicator: HTMLElement | null = null;
+	private readonly onStatusChange = (): void => this.updateConnectionIndicator();
 
 	constructor(app: App, plugin: SurfSensePlugin) {
 		super(app, plugin);
@@ -29,6 +31,7 @@ export class SurfSenseSettingTab extends PluginSettingTab {
 	display(): void {
 		const { containerEl } = this;
 		containerEl.empty();
+		this.plugin.onStatusChange(this.onStatusChange);
 
 		const settings = this.plugin.settings;
 
@@ -279,13 +282,26 @@ export class SurfSenseSettingTab extends PluginSettingTab {
 			);
 	}
 
+	hide(): void {
+		this.plugin.offStatusChange(this.onStatusChange);
+		this.connectionIndicator = null;
+	}
+
 	private renderConnectionHeading(containerEl: HTMLElement): void {
 		const heading = new Setting(containerEl).setName("Connection").setHeading();
 		heading.nameEl.addClass("surfsense-connection-heading");
-		const indicator = heading.nameEl.createSpan({
+		this.connectionIndicator = heading.nameEl.createSpan({
 			cls: "surfsense-connection-indicator",
 		});
+		this.updateConnectionIndicator();
+	}
+
+	private updateConnectionIndicator(): void {
+		const indicator = this.connectionIndicator;
+		if (!indicator) return;
 		const visual = STATUS_VISUALS[this.plugin.lastStatus.kind];
+		indicator.empty();
+		indicator.removeClass("surfsense-connection-indicator--err");
 		if (visual.isError) {
 			indicator.addClass("surfsense-connection-indicator--err");
 		}

surfsense_obsidian/src/status-visuals.ts

@@ -16,7 +16,8 @@ export const STATUS_VISUALS: Record<StatusKind, StatusVisual> = {
 	idle: { icon: "check-circle", label: "Synced", isError: false },
 	syncing: { icon: "refresh-ccw", label: "Syncing", isError: false },
 	queued: { icon: "clock", label: "Queued", isError: false },
+	"needs-setup": { icon: "cloud-off", label: "Setup required", isError: false },
 	offline: { icon: "wifi-off", label: "Offline", isError: false },
-	"auth-error": { icon: "user-x", label: "Reauthenticate", isError: true },
+	"auth-error": { icon: "alert-circle", label: "Reauthenticate", isError: true },
 	error: { icon: "alert-circle", label: "Error", isError: true },
 };

surfsense_obsidian/src/sync-engine.ts

@@ -46,6 +46,7 @@ export interface SyncEngineDeps {
 
 export interface SyncEngineSettings {
 	vaultId: string;
+	apiToken: string;
 	connectorId: number | null;
 	searchSpaceId: number | null;
 	includeFolders: string[];
@@ -103,7 +104,7 @@ export class SyncEngine {
 				this.handleStartupError(err);
 				return;
 			}
-			this.setStatus("idle", "Pick a search space in settings to start syncing.");
+			this.setStatus("idle");
 			return;
 		}
 
@@ -123,7 +124,7 @@ export class SyncEngine {
 	async ensureConnected(): Promise<boolean> {
 		const settings = this.deps.getSettings();
 		if (!settings.searchSpaceId) {
-			this.setStatus("idle", "Pick a search space in settings.");
+			this.setStatus("idle");
 			return false;
 		}
 		this.setStatus("syncing", "Connecting to SurfSense");
@@ -500,10 +501,34 @@ export class SyncEngine {
 
 	// ---- status helpers ---------------------------------------------------
 
+	/**
+	 * Recomputes status from settings + queue depth. Call from main.ts after
+	 * settings change so the indicator reacts to token paste / search-space
+	 * pick without waiting for the next sync trigger.
+	 */
+	refreshStatus(): void {
+		this.setStatus(this.queueStatusKind(), this.statusDetail());
+	}
+
 	private setStatus(kind: StatusKind, detail?: string): void {
+		// Errors carry meaningful signal; only "happy" kinds get downgraded
+		// to needs-setup when prerequisites are missing.
+		if (kind !== "auth-error" && kind !== "offline" && kind !== "error") {
+			const s = this.deps.getSettings();
+			if (!s.apiToken || !s.searchSpaceId || !s.connectorId) {
+				kind = "needs-setup";
+				detail = this.setupHint(s);
+			}
+		}
 		this.deps.setStatus({ kind, detail, queueDepth: this.deps.queue.size });
 	}
 
+	private setupHint(s: SyncEngineSettings): string {
+		if (!s.apiToken) return "Paste your API token in settings.";
+		if (!s.searchSpaceId) return "Pick a search space in settings.";
+		return "Connecting…";
+	}
+
 	private queueStatusKind(): StatusKind {
 		if (this.deps.queue.size > 0) return "queued";
 		return "idle";

surfsense_obsidian/src/types.ts

@@ -190,6 +190,7 @@ export type StatusKind =
 	| "idle"
 	| "syncing"
 	| "queued"
+	| "needs-setup"
 	| "offline"
 	| "auth-error"
 	| "error";