feat: Complete Deep URL Navigation with Cross-Platform Copy Functionality

[stevepresley]

Summary

Implementation of deep URL navigation for projects, tasks, and documents with comprehensive cross-platform copy functionality, mobile support, performance optimizations, and scrollbar fixes for all three areas. Also allows direct navigation to Table or Board views in the Tasks area of a project.

✅ Deep URL Navigation Features

• Project Direct Links: /projects/{projectId} - Auto-loads and highlights specific projects
• Task View Links: /projects/{projectId}/tasks?view=table/board - Navigate directly to Board or Table view for a Project's Task list
• Task Direct Links: /projects/{projectId}/tasks/{taskId}?view=table/board - Task highlighting with view persistence
• Document Direct Links: /projects/{projectId}/docs/{docId} - Document loading and display
• URL Parameters: View mode persistence via ?view=table/board for shareable, bookmarkable URLs
• Browser Support: Forward/back buttons, bookmarks, page refresh, copy/paste URLs

✅ Cross-Platform Copy Functionality

• Desktop: Shift-click copies full URL, regular click copies ID
• Mobile (iOS/Android): Separate "Copy URL" buttons with proper text labels
• Error Handling: Toast notifications for copy success/failure states
• iOS Compatibility: Clipboard API with graceful fallbacks for iOS restrictions

✅ Task Highlighting & Navigation

• Visual Feedback: Vibrant cyan highlighting for deep-linked tasks
• Auto-Scroll: Automatically centers selected content in viewport
• Status-Based Display: Tasks appear in correct status columns/tabs
• Cross-View Support: Works in both Table and Board views
• Fade Override: Highlighted tasks maintain full opacity

✅ Performance Optimizations

• Progressive Loading: Load target project first, others in background (Projects AND Documents)
• API Call Reduction: From 60+ API calls to 3 calls per navigation (96% reduction)
• Data Transfer: Reduced from 400KB to 15KB per deep URL navigation
• Load Time: Page loads reduced from 3-5 seconds to 500ms
• Document Content Caching: Prevents duplicate API calls for same document
• Dramatically improves performance on mobile devices and lower-bandwidth or high-latency connections

✅ Cross-Platform Scrollbar Fixes

• Issue: Scrollbars disappearing after scroll completion on Mac across multiple components
• Solution: Custom force-scrollbar CSS class with -webkit-appearance: none
• GitHub Issue: 🐛 [Bug]: Projects are not accessible via web UI if you have more than 5 #216
• Components Fixed:
  • Projects horizontal scroll (ProjectPage.tsx)
  • Documents horizontal scroll (DocsTab.tsx)
  • Task Table vertical scroll bars (CSS style conformity and Mac fix)
• Files: src/index.css, ProjectPage.tsx, DocsTab.tsx, Task table components
• Impact: Cross-platform scrollbar visibility and consistent styling (Windows, Mac, iOS)

✅ Mobile UX Fixes

• Project Cards: Added "Copy URL" text to mobile ExternalLink buttons
• Task Cards: Proper button grouping and "Copy URL" text labels
• Document Cards: Added "Doc ID" and "Copy URL" text, fixed visibility on mobile
• Critical Fix: Resolved projectId is not defined error in TaskBoardView

✅ Additional Bug Fixes

• iOS/Android Copy Issue: Fixed clipboard functionality with enhanced fallback mechanism (Fixes 🐛 [Bug]: Copy id feature not working #202)
• HTTP Polling Log Spam: 96% API call reduction and elimination of redundant page reloads significantly reducing log noise (Significantly improves Development logs flooded with polling requests, making debugging difficult #568)
• React Key Duplication: Fixed SimpleMarkdown component key conflicts in document navigation
• Socket.IO Reconnection: Restored real-time task updates after server reconnection
• Remote Access: Fixed hardcoded localhost preventing Windows remote access
• Document Titles: Fixed "Untitled Document" display in PRPViewer

✅ Cross-Platform Testing

• Desktop: Windows, Mac - all functionality verified
• Mobile: iOS Safari, iOS Chrome, Android emulator - copy buttons working
• Real-time Updates: Socket.IO reconnection working without page reload

📋 Technical Implementation

• Files Modified: 24 files across frontend components, services, and styles
• New Utilities: platformDetection.ts, copyHelpers.ts for cross-platform support
• URL Architecture: Parameter-based persistence for shareable, bookmarkable URLs
• React Router v6: Enhanced parameter handling in existing components
• CSS Enhancements: Custom scrollbar styles, task highlighting, responsive design

🔗 Example URLs

• Project: http://localhost:3737/projects/452536cf-1fd2-45dc-82cb-064c79f487f8
• Tasks (Table): http://localhost:3737/projects/452536cf-1fd2-45dc-82cb-064c79f487f8/tasks?view=table
• Tasks (Board): http://localhost:3737/projects/452536cf-1fd2-45dc-82cb-064c79f487f8/tasks?view=board
• Specific Task (Table): http://localhost:3737/projects/452536cf-1fd2-45dc-82cb-064c79f487f8/tasks/8a93d601-ec86-486a-9fef-b487a1b375fe?view=table
• Specific Task (Board): http://localhost:3737/projects/452536cf-1fd2-45dc-82cb-064c79f487f8/tasks/8a93d601-ec86-486a-9fef-b487a1b375fe?view=board
• Specific Document: http://localhost:3737/projects/452536cf-1fd2-45dc-82cb-064c79f487f8/docs/bc6df4e7-5fe5-480c-8769-5717c8f4960b

Test Plan

• Deep URL navigation for all content types (projects, tasks, documents)
• Cross-platform copy functionality (Windows, Mac, iOS, Android)
• Task highlighting and auto-scroll in both Table and Board views
• View mode persistence via URL parameters (?view=table/board)
• Status-based task display and filtering
• Progressive loading for both Projects and Documents
• Mobile UI copy button visibility and functionality
• Cross-platform scrollbar persistence (Projects, Documents, Task Table)
• Error handling and user feedback (toast notifications)
• Browser navigation (forward/back, bookmarks, page refresh)

Implementation Details

Frontend Routing

Uses React Router v6 with enhanced route definitions:

• Route path="/projects/:projectId/tasks/:taskId" for task deep linking
• Route path="/projects/:projectId/docs/:documentId" for document deep linking
• URL parameter extraction with useParams() and navigation with useNavigate()

URL State Management

• Route Parameters: Project, document, and task IDs
• Query Parameters: View mode (?view=table/board)
• Path-based Tabs: /docs and /tasks determine active tab
• Navigation Replacement: Uses replace: true for clean browser history

Error Handling

• Invalid Project IDs: Falls back to default project selection
• Missing Documents/Tasks: Continues to load project without pre-selection
• Disabled Features: Redirects appropriately when projects are disabled

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Implements deep URL linking for projects, documents, and tasks across the UI and docs; adds copy-to-clipboard and platform-aware link utilities; adjusts routing and selection synchronization; introduces lightweight project/doc listing and project stats APIs; updates health and Socket.IO connection handling; adds scrollbar CSS utilities; and provides dev scripts.

Changes

Cohort / File(s)	Summary
Routing & Page Wiring archon-ui-main/src/App.tsx, archon-ui-main/src/pages/ProjectPage.tsx	Expanded routes for projects/docs/tasks with deep-link params; URL-driven initialization, tab syncing, and selection; added redirect when projects disabled; refined health reconnect handling and effect lifecycle.
Tasks UI (Board/Table/Tabs/Cards) archon-ui-main/src/components/project-tasks/TasksTab.tsx, .../TaskBoardView.tsx, .../TaskTableView.tsx, .../DraggableTaskCard.tsx	Added selectedTaskId/projectId/currentView props; URL-synced view mode; auto-scroll to selected task; selection highlighting; copy ID/URL actions with toasts and mobile-friendly buttons; force-scrollbar usage.
Docs UI archon-ui-main/src/components/project-tasks/DocsTab.tsx, .../DocumentCard.tsx	Added selectedDocumentId/onDocumentSelect and projectId props; light-mode doc list via listDocuments; on-demand full-content fetch; deep-link selection; enhanced copy ID/URL with toasts and mobile button.
Copy & Platform Utilities archon-ui-main/src/utils/copyHelpers.ts, archon-ui-main/src/utils/platformDetection.ts	New helpers to construct deep links, robust clipboard copy with fallbacks, shift-click behavior; platform detection and mobile link-button gating.
Frontend Services archon-ui-main/src/services/projectService.ts, .../socketIOService.ts, .../serverHealthService.ts, archon-ui-main/src/config/api.ts	Added listDocuments and getProjectStats; listProjects gains include_content; Socket.IO dev/prod URL logic and longer timeout; health service reconnection flow with dynamic socket reconnect; API URL construction simplified and logged.
Styling archon-ui-main/src/index.css	New .force-scrollbar WebKit scrollbar styling with light/dark variants.
Markdown Rendering archon-ui-main/src/components/prp/components/SimpleMarkdown.tsx	Replaced static React keys with dynamic composite keys for rendered blocks.
Docs Site docs/docs/deep-url-linking.mdx, docs/sidebars.js, CLAUDE.md	New deep URL linking documentation; sidebar entry; added project Documents API docs.
Backend APIs python/src/server/api_routes/projects_api.py, python/src/server/api_routes/socketio_handlers.py, python/src/server/services/projects/document_service.py	New GET /projects/{project_id}/stats (duplicated declaration present); Socket.IO project broadcasts/subscriptions use lightweight list_projects(include_content=False); document service returns full doc with timestamps and builds metadata.
Dev/Docker Scripts scripts/*, .gitignore	Added rebuild/start/stop helper scripts; updated ignores for Claude, logs, .DS_Store.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant Router as React Router
  participant ProjectPage
  participant DocsTab
  participant TasksTab
  participant ProjectSvc as projectService
  participant CopyUtils as copyHelpers

  User->>Router: Navigate /projects/:projectId/(docs|tasks)/:itemId?
  Router->>ProjectPage: Render with params
  ProjectPage->>ProjectSvc: getProject(projectId) + getProjectStats(projectId)
  ProjectPage->>DocsTab: selectedDocumentId (if docs route)
  ProjectPage->>TasksTab: selectedTaskId,currentView (if tasks route)
  DocsTab->>ProjectSvc: listDocuments(projectId, includeContent=false)
  DocsTab-->>DocsTab: loadFullDocument(docId) on selection/deep-link
  TasksTab-->>TasksTab: sync view mode with URL (?view=table|board)
  User->>ProjectPage: Click copy (ID/URL)
  ProjectPage->>CopyUtils: handleCopyClick(event, 'project', projectId)
  CopyUtils-->>User: Clipboard result (toast)

  opt Select doc/task
    User->>DocsTab: Select document
    DocsTab->>ProjectPage: onDocumentSelect(docId)
    ProjectPage->>Router: Navigate /projects/:projectId/docs/:docId
  end

Loading

sequenceDiagram
  autonumber
  participant Health as serverHealthService
  participant TaskSock as taskSocketService (dynamic)
  participant App as App.tsx

  loop interval
    Health->>Health: checkHealth()
    alt healthy
      Health-->>Health: reset missedChecks
      Health->>Health: handleConnectionRestored()
      opt reconnect flow
        Health->>TaskSock: import + reconnect()
      end
      Health->>App: onReconnected()
    else unhealthy
      Health-->>Health: missedChecks++
      alt threshold reached
        Health->>App: onDisconnected()
      end
    end
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• Fix critical token consumption issue in list endpoints (#488) #502 — Similar lightweight listing changes adding include_content and adjusting list_projects/list_documents paths across server and client.
• Improve development environment with Docker Compose profiles #435 — Related adjustments to frontend API URL construction and dev/docker configuration affecting archon-ui-main/src/config/api.ts and scripts.
• Add titles to icon buttons  #445 — Touches DocumentCard.tsx UI; overlaps with this PR’s copy/URL and prop changes and may introduce conflicts or complement UX tweaks.

Poem

I nibble links in moonlit grass,
Hop through routes where params pass.
A tap—copy IDs that gleam,
Shift-click spins a URL dream.
Stats burrow light, sockets mend—
With gentle scroll, I find my friend.
Thump-thump: deep links never end. 🐇✨

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 277bfda and ec47c64.

📒 Files selected for processing (30)

• .gitignore (1 hunks)
• CLAUDE.md (1 hunks)
• archon-ui-main/src/App.tsx (2 hunks)
• archon-ui-main/src/components/project-tasks/DocsTab.tsx (8 hunks)
• archon-ui-main/src/components/project-tasks/DocumentCard.tsx (4 hunks)
• archon-ui-main/src/components/project-tasks/DraggableTaskCard.tsx (7 hunks)
• archon-ui-main/src/components/project-tasks/TaskBoardView.tsx (12 hunks)
• archon-ui-main/src/components/project-tasks/TaskTableView.tsx (9 hunks)
• archon-ui-main/src/components/project-tasks/TasksTab.tsx (5 hunks)
• archon-ui-main/src/components/prp/components/SimpleMarkdown.tsx (7 hunks)
• archon-ui-main/src/config/api.ts (1 hunks)
• archon-ui-main/src/index.css (1 hunks)
• archon-ui-main/src/pages/ProjectPage.tsx (24 hunks)
• archon-ui-main/src/services/projectService.ts (3 hunks)
• archon-ui-main/src/services/serverHealthService.ts (3 hunks)
• archon-ui-main/src/services/socketIOService.ts (2 hunks)
• archon-ui-main/src/utils/copyHelpers.ts (1 hunks)
• archon-ui-main/src/utils/platformDetection.ts (1 hunks)
• docs/docs/deep-url-linking.mdx (1 hunks)
• docs/sidebars.js (1 hunks)
• python/src/server/api_routes/projects_api.py (2 hunks)
• python/src/server/api_routes/socketio_handlers.py (2 hunks)
• python/src/server/services/projects/document_service.py (5 hunks)
• scripts/rebuild_UI.sh (1 hunks)
• scripts/start_dev_1_backend.sh (1 hunks)
• scripts/start_dev_2_ui.sh (1 hunks)
• scripts/start_dev_3_docs.sh (1 hunks)
• scripts/start_full.sh (1 hunks)
• scripts/stop_dev_backend.sh (1 hunks)
• scripts/stop_full.sh (1 hunks)

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[stevepresley]

Closing this PR temporarily - was created to upstream repo prematurely. I wanted to clean up the PR before I submitted but gh pr create defaulted to upstream. Will clean up branch and reopen it shortly.

[stevepresley]

Ended up adding additional commits, so please see new PR here: #573