kandev/docs/specs/ui/task-surface-refresh.md

status, created, owner

status	created	owner
approved	2026-07-27	Kandev

Task Surface Foreground Refresh and Mobile Create Action

Why

People returning to Kandev after the browser, window, or device has been idle can see a task List, Kanban board, or task-detail chat that no longer matches backend state. This affects desktop window switching as well as suspended mobile browsers. Phone users also need a familiar recovery gesture and the same thumb-reachable create action in List that Kanban already provides.

What

• Mobile List shows the same safe-area-aware floating Add task button as mobile Kanban.
• The List floating action opens the existing task-create flow in the active workspace and workflow; a successful creation becomes visible under the current List filters and pagination rules.
• Mobile List and mobile Kanban support pull-to-refresh from the top of their current vertical scroll surface.
• The pull gesture activates only for a primarily downward single-touch drag that starts while the active vertical scroll owner is at its top. Horizontal Kanban navigation, task drag-and-drop, and ordinary scrolling do not trigger refresh.
• The UI shows pull progress, a release threshold, and an in-progress state without replacing already-rendered tasks with an empty or loading screen.
• Releasing beyond the threshold performs one refresh at a time. Releasing before the threshold restores the surface without fetching.
• A List refresh reloads the current page using the current workspace, workflow, repository, query, archive, sort, and pagination settings.
• A Kanban refresh reloads the current workspace's visible workflow snapshots, including the active workflow state used by task preview and creation.
• When Kandev becomes the focused window, becomes visible after being hidden, resumes from the browser page cache, or returns online, the active task surface performs an authoritative foreground refresh even when the WebSocket connection still reports connected.
• Foreground events emitted together for one return to Kandev are coalesced so each active data source refreshes once rather than once per browser event.
• Kanban/Home foreground refresh reloads the current workspace's workflow snapshots.
• List foreground refresh reloads the current filtered and paginated List request.
• Task-detail foreground refresh reloads the open task, its session list, the active session's chat messages, and its queued-message state. Existing subscription and focus state remains attached to the same task and session.
• Automatic foreground refresh applies on desktop and mobile. Pull-to-refresh and the List floating create action are phone-only.
• Refreshed responses must not overwrite a newer workspace selection or a task mutation that lands while a refresh is in flight.

Failure modes

• A failed manual refresh keeps the last rendered tasks and presents the existing user-facing error feedback pattern; the pull indicator settles back to idle so the user can retry.
• A failed automatic foreground refresh keeps the last rendered tasks and does not interrupt the user with a modal.
• A refresh requested while another refresh for the same data source is in flight is coalesced rather than issuing overlapping requests.
• If the active workspace or workflow changes during a refresh, the stale response is discarded.

Scenarios

• GIVEN List is open on a phone, WHEN the user taps the floating Add task button and completes task creation, THEN the existing create flow uses the active workspace and workflow and the new task appears when it matches the current List query.
• GIVEN mobile List is scrolled to the top, WHEN the user pulls downward beyond the release threshold, THEN the current filtered page is reloaded and a refresh indicator remains visible until the request settles.
• GIVEN mobile Kanban's current column is scrolled to the top, WHEN the user pulls downward beyond the release threshold, THEN current workflow snapshots are reloaded without changing the focused workflow or column.
• GIVEN either task listing is not at its vertical scroll top, WHEN the user drags downward, THEN the surface scrolls normally and no refresh is started.
• GIVEN mobile Kanban, WHEN the user swipes primarily horizontally between columns, THEN pull-to-refresh does not activate.
• GIVEN a task changes while Kandev is hidden or suspended, WHEN the user returns to List, THEN the changed task is reflected without a full browser reload.
• GIVEN a task changes while Kandev is hidden or suspended, WHEN the user returns to Kanban, THEN the changed task is reflected without a full browser reload even if connection status never left connected.
• GIVEN Kanban/Home remains visible in an unfocused desktop browser window while tasks change, WHEN the user focuses Kandev again, THEN the board reflects those changes without a full browser reload.
• GIVEN an open task receives messages or session-state changes while the Kandev window is unfocused, hidden, suspended, or offline, WHEN the user returns to Kandev, THEN the task details, session list, active chat messages, and queued-message state converge to their authoritative backend values without changing the selected task or session.
• GIVEN one return to Kandev emits focus, visibilitychange, pageshow, and/or online close together, WHEN foreground recovery runs, THEN each active data source issues at most one concurrent refresh.
• GIVEN a manual or automatic refresh fails, WHEN the request settles, THEN previously rendered tasks remain usable and a later pull or foreground event can retry.

Out of scope

• Adding pull-to-refresh to task detail, Office, settings, or other Kandev pages.
• Changing the existing WebSocket event schema or backend task APIs.
• Periodically polling all Kandev data while the app remains continuously focused.
• Adding a floating create action on desktop List.
• Persisting pull distance, refresh timestamps, or refresh state.
• Changing List filters, sorting, grouping, pagination, or Kanban navigation.

Implementation plan

• Task surface refresh implementation plan