Files
kandev/docs/plans/threads-home-default/task-02-resolve-threads-home-navigation.md
T
2026-09-10 22:56:04 +01:00

14 KiB

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
id title status wave depends_on plan requirements acceptance_criteria system_design
02-resolve-threads-home-navigation Resolve Threads Home navigation done 2
01-persist-threads-startup-choice
plan.md
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-001
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-002
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-003
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-001.3
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-001.4
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-001.5
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-001.6
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-001.12
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-002.2
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-002.3
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-002.4
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-003.4
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-003.5
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-003.6
AC-UI-TASK-LISTING-DISPLAY-PREFERENCES-003.7
../../specs/ui/system-design/task-listing-display-preferences.md

Task 02: Resolve Threads Home Navigation

Summary

Make generic Home and bare startup honor the portable Threads choice in the resolved workspace. Keep explicit navigation and remembered listing behavior independent, including when settings bootstrap is delayed.

In scope

  • Use /tdd; add the design's entry-resolution and Home href matrices first.
  • Share the Home resolver between workspaceHomeHref, homeDestinationHref, and their actual sidebar/topbar/mobile/settings/picker/command consumers. Carry startupPage in NavContext and keep old callers' default behavior.
  • Override the palette's legacy overview href for the Threads choice only.
  • Resolve one startup redirect after authoritative settings/workspace bootstrap. Expose completion from useKanbanRouteBootstrap, including failed-fetch and empty-workspace completion. Keep cancellation tied to route identity. Preserve the local view hook's real loaded value rather than setting it to true during a rendering-mode update.
  • Preserve isExplicitHomeDestination, local view storage/fallbacks, explicit linkToTaskOverview, and path-preserving listingHistoryHref.

Out of scope

  • Settings radio/copy, saved Threads filter/session defaults, task Back destination changes, mobile topbar geometry, swipe timing, and new stores.

Acceptance

  • Every generic Home consumer honors Threads in the selected non-Office workspace; Office remains Office, and existing choices preserve current behavior, including the palette's legacy target.
  • Bare Home chooses Threads despite a competing local view or unavailable storage, with no earlier wrong-route redirect during settings/workspace hydration. Empty/error/no-workspace paths settle without loops.
  • Explicit task/session/workflow/overview/listing links and history remain usable; view toggles never change the portable default, last-task resume stays workspace-local/startup-only, and phone Pipeline fallback is not saved.

Verification

Task 01 has already installed dependencies. Run each line from the repo root:

(cd apps && pnpm --filter @kandev/web test lib/startup-page.test.ts lib/task-listing/view-preference.test.ts lib/task-listing/view-navigation.test.ts hooks/use-task-listing-view.test.tsx app/page-client.test.tsx)
(cd apps && pnpm --filter @kandev/web test lib/navigation/workspace-home.test.ts lib/navigation/resolve-destinations.test.ts hooks/use-app-destinations.test.tsx hooks/use-home-affordance.test.ts components/app-sidebar/app-sidebar-workspace-navigation.test.ts src/kanban-route.test.ts src/kanban-route-startup.test.tsx)
(cd apps/web && pnpm run typecheck)
git diff --check

workspace-home.test.ts and kanban-route-startup.test.tsx are new files. The latter covers deferred settings, stale workspace fetches, Office priority, and empty/error readiness using real route wiring with mocked transport. Browser entry-point proof is owned by Task 03; pure href tests alone do not complete the feature.

Files likely touched

  • apps/web/lib/startup-page.ts and startup-page.test.ts
  • apps/web/app/page-client.tsx and page-client.test.tsx
  • apps/web/src/kanban-route.tsx, existing kanban-route.test.ts, and new kanban-route-startup.test.tsx
  • apps/web/lib/navigation/workspace-home.ts and new workspace-home.test.ts
  • apps/web/lib/navigation/core-destinations.ts, types.ts, and resolve-destinations.test.ts
  • apps/web/hooks/use-app-destinations.ts, use-app-destinations.test.tsx, and use-home-affordance.test.ts
  • apps/web/hooks/use-task-listing-view.ts and use-task-listing-view.test.tsx
  • apps/web/lib/task-listing/view-preference.test.ts and view-navigation.test.ts
  • apps/web/components/app-sidebar/app-sidebar-header.tsx, app-sidebar-primary-nav.tsx, app-sidebar-footer.tsx, app-sidebar-workspace-picker.tsx, and app-sidebar-workspace-navigation.test.ts
  • apps/web/components/navigation/app-nav-sections.tsx (shared phone Home consumer)

view-preference.ts, view-navigation.ts, and use-home-affordance.ts already own the correct lower-level contracts; change their production logic only if needed for the shared resolver, not to move startup policy into view memory.

Dependencies

Task 01.

Risks

  • Root startup cannot distinguish generic Home from explicit overview by pathname alone; use entry intent rather than an unconditional redirect.
  • Gating on a workflow/snapshot deadlocks empty workspaces. Gating only on the local view hook's old loaded: true write races settings hydration.
  • A workspace picker must pass its selected workspace, not a stale active one.
  • The phone menu Home row owns listing Home; task Task overview is a separate explicit link and must not be swept into this change.

Parallelism

sequential

Inputs

  • Design sections Entry resolution, Home consumers, Remembered listing and list details, and Failure and recovery.
  • Existing view preference/navigation tests and page-client startup tests.
  • Existing useHomeAffordance and sidebar navigation tests.
  • apps/web/AGENTS.md, /mobile-parity, ADR 0023, and Office-mode ADR.

Results

Shared Home policy now covers the manifest, palette, sidebar, settings exit, workspace picker, and phone Home. Bare startup waits for authoritative route bootstrap; explicit destinations and Office retain priority. The device view hook preserves settings readiness.

RED: 11 destination/page/hook assertions and four bootstrap assertions failed for the expected missing behavior. GREEN: the listed suites plus existing SPA workspace and sidebar/header neighbors passed (16 files, 148 tests). Typecheck, focused ESLint, and git diff --check passed. The SPA workspace test now waits for bootstrap before asserting the selected workspace. Browser proof follows in Task 03.

PR review remediation

UI remains the owner of Home presentation; Office availability retains its existing feature-gate ownership. AC-003.6 and the Home-consumer design were clarified before repairing the phone brand's disabled-Office destination. Reuse the existing brand as direct navigation into the native task listing. Layout, touch targets, safe areas, scroll ownership, and the native menu/deck exemplars remain unchanged; no parent topbar or swipe work is included.

RED: the two disabled-Office header cases and phone href assertion resolved to /office instead of the expected task listing. The stale workspace-picker mock also reproduced 23 crashes before repair. GREEN: gate the phone's Office record with the existing feature flag, preserving its workspace ID fallback; restore complete fixture inputs and cover Threads selection and Office priority. Direct no-workspace and explicit-overview cases document existing resolver behavior, with a short production invariant comment.

Verification from apps/web:

pnpm exec vitest run components/kanban/kanban-header-mobile.test.tsx components/app-sidebar/app-sidebar-workspace-picker.test.tsx lib/startup-page.test.ts e2e/helpers/api-client.test.ts lib/navigation/workspace-home.test.ts hooks/use-home-affordance.test.ts src/kanban-route-startup.test.tsx app/page-client.test.tsx
pnpm run typecheck
pnpm exec eslint --max-warnings 0 components/kanban/kanban-header-mobile.tsx components/kanban/kanban-header-mobile.test.tsx components/app-sidebar/app-sidebar-workspace-picker.test.tsx lib/startup-page.ts lib/startup-page.test.ts e2e/helpers/api-client.ts e2e/helpers/api-client.test.ts e2e/tests/office/mobile-office-navigation.spec.ts

All 88 focused tests passed. After completing the typed header fixture and splitting its describe blocks to meet the lint limit, all 13 header tests passed again. Typecheck and focused ESLint passed. Task 03 records the rebuilt browser proof. Specification lint and its 30 validator tests passed.

CI navigation-fixture remediation

The full frontend CI suite exposed three additional stale store fixtures in the primary sidebar, phone navigation sheet, and integrations menu tests. All 32 failures reproduced locally because the shared Home context now reads userSettings.startupPage. Restore the complete settings slice from the existing default state and reset mutable settings between cases. Extend the existing desktop and phone Home assertions to cover the Threads choice.

This is test-only compatibility repair. Requirements, system design, public copy, production routing, and native surface geometry remain unchanged.

Verification from the repo root:

(cd apps/web && pnpm exec vitest run components/app-sidebar/app-sidebar-primary-nav.test.tsx components/navigation/app-nav-sheet.test.tsx components/integrations/integrations-menu.test.ts)
(cd apps/web && pnpm exec eslint --max-warnings 0 components/app-sidebar/app-sidebar-primary-nav.test.tsx components/navigation/app-nav-sheet.test.tsx components/integrations/integrations-menu.test.ts)
(cd apps/web && pnpm run typecheck)
(cd apps && NODE_ENV=production pnpm --filter @kandev/web test)

The pre-merge focused run passed all 34 tests, focused ESLint, and typecheck. Main integration then required the UI index to retain both this design and the new control-sizing design. The merged routing/settings suite passed 122 tests in 11 files, followed by full web lint, typecheck, i18n checks, tagged/race Go startup and boot-mapping tests, and the rebuilt browser checks in Task 03. Harness validation passed 19 tests and all 196 files; specification validation passed 36 tests and all specs. The PR-only diff is whitespace-clean; staged whitespace warnings were verified as unchanged incoming main content.

The first merged full-suite attempt could not open a tsx IPC socket inside the agent sandbox (EPERM) and was stopped without a verdict. Full-suite execution requires local IPC permission in this environment. Final broad-suite and current-head CI/review results belong to the PR delivery evidence; the scoped remediation checks above are complete.

CI live-filter readiness remediation

E2E shard 7 exposed four step-visibility failures after selecting All Workflows. The hydrated boot path returns without recording completion; clearing the live workflow filter then makes the snapshot predicate false and unmounts the board behind Loading Home. The exact first scenario also fails locally with no retries.

Keep completion settled for the same route on both hydration paths. Add focused tests for All Workflows, an uncached workflow, and a subsequent explicit route change that must still wait for its own bootstrap. Re-run the failed filter spec and the affected desktop/phone startup neighbors against a rebuilt bundle. This repairs AC-003.5 without changing default precedence, public copy, native layout, or the parent's topbar/swipe work. Before the later main merge, the two new unit assertions failed and then passed with 37 route/bootstrap tests; the rebuilt filter/startup E2E run passed 12 tests with no retries. Shard 5 later confirmed four more failures in workflow-filter.spec.ts with the same Loading Home evidence; include that complete spec in post-merge verification.

Landed parent and fixture integration

The parent polish landed on main and removed the phone brand link. Keep its header and header tests unchanged; Home now belongs to the shared menu's AppNavSections, which already uses this task's saved startup choice and feature-aware Office context. Update both phone startup/Office scenarios to tap that actual Home row, retaining workspace, destination, and reload checks. The earlier brand-specific test evidence above is historical; menu-based verification supersedes it. Public how-to documentation retains both the parent's compact-menu guidance and this task's three startup choices.

The mobile parked-background-work CI flake used a suite-level profile ID that per-test cleanup deleted when the seed already existed. Initial fresh-worker runs passed three times; seeding before provider restart reproduced the exact missing-session failure. Create a fresh mock profile after testPage cleanup. The existing scenario and its preceding file-viewer case passed twice (four tests, no retries). This is fixture-only repair; parked-work requirements and production behavior remain unchanged.

Post-merge verification from apps/web passed 109 tests across 13 files:

pnpm exec vitest run src/kanban-route-startup.test.tsx src/kanban-route.test.ts lib/routing/kanban-route-hydration.test.ts app/page-client.test.tsx components/kanban/kanban-header-mobile.test.tsx components/navigation/app-nav-sheet.test.tsx hooks/use-app-destinations.test.tsx lib/navigation/core-destinations.test.ts lib/navigation/workspace-home.test.ts
pnpm exec vitest run hooks/use-in-office.test.ts components/kanban/mobile-menu-sheet.test.tsx components/kanban/mobile-menu-utility-actions.test.tsx components/workspace-scope-provider.test.tsx
pnpm run lint
pnpm run typecheck
pnpm run i18n:check

All commands passed. The 12 startup tests passed again after explicitly asserting the new route's resolved workspace. Focused ESLint over the changed E2E tests also passed. Task 03 records the 73 rebuilt desktop/phone browser checks. All specification, harness, and public-docs validators passed; PR-only whitespace checks passed. Current-head remote CI/review remains delivery work after push.