FEAT: Social Sharing & Deep-Linked Challenge Invitations

[Bana0615]

FEAT: Social Sharing & Deep-Linked Challenge Invitations

Type: Feature Request

Context / Problem Statement:
Currently, Grit is a siloed experience. Users have no native way to celebrate their "Grit" with their social circles or invite friends to follow their exact custom protocols. This lack of social proof and frictionless onboarding for new users limits the platform's community growth and viral potential.

User Story:
As a disciplined user, I want to share my completion stats and specific challenge configurations so that I can showcase my progress and invite others to join me in the same protocol with zero setup friction.

Proposed Solution:
Implement a two-pronged social strategy:

1. Results Sharing: A useShare utility hook that leverages the Web Share API for native mobile sharing and a Clipboard Fallback for desktop users.
2. Challenge Cloning: A URL serialization utility to encode ChallengeRules (Workouts, Diet, Water, etc.) into a Base64-encoded string or URL parameters, allowing the /app/setup page to act as a dynamic landing page that auto-fills based on the link.

Acceptance Criteria (AC):

• Implement a Share My Wins button in the CompletionModal footer.
• Share payload must include dynamic metrics: Duration, Workouts, Gallons, and Pages.
• Implement Copy-to-Clipboard fallback with a formatted text summary if the Web Share API is unavailable.
• Create a Share This Protocol button within the Protocol Rulebook/Settings.
• Clicking a shared invitation link must successfully populate the Setup Wizard with all rules preset.
• Ensure the "Vice" (Custom Habit) field is correctly serialized and deserialized in the deep link.
• Shared links must be short enough to be handled by standard social media platforms.

Technical Implementation Details:

• Utilities: Create src/utils/serialization.ts to handle serializeRules() and deserializeRules().
• Hooks: Create src/hooks/useShare.ts to wrap the navigator.share API and navigator.clipboard fallback.
• Routing: Update the SetupPage (/app/setup) to use useSearchParams to detect an incoming rules or invite parameter.

Definition of Done (DoD):

• Manual verification of the Web Share API on iOS (Safari) and Android (Chrome).
• Unit tests for Serialization Utility to ensure accurate encoding/decoding.
• UI verification: Ensure the sharing buttons match the existing Grit design system.