Sip & Ship 💧

"Sip your water, Ship your code!"
An adorable, zero-distraction hydration companion for developers that keeps you healthy while staying 100% focused on your code.

📖 Table of Contents

• 💡 Overview & Philosophy
• 📸 Visual Showcase & Screenshots
• ✨ Key Features
• 🎬 Dynamic 3-GIF Visual Workflow
• 📐 Technical Architecture & Flowcharts
• 🚀 User Guide & How to Use
• ⌨️ Command Palette Reference
• ⚙️ Configuration & Settings
• 🎨 Media Assets & Credits
• 📁 Project Structure
• 🛠️ Development & Building

💡 Overview & Philosophy

Developers frequently experience deep coding flow states, often going hours without drinking water. Most reminder tools either open jarring popups that steal keyboard focus or require complex setups.

Sip & Ship was engineered around three strict principles:

1. Zero Flow Interruption: No editor tabs open or switch. Your cursor stays on your active code line, allowing you to keep typing uninterrupted.
2. Delightful Visuals: Dynamic animations with a cute companion that responds to your hydration milestones.
3. Auditory & Status Awareness: A subtle, crisp bubble chime paired with an active status bar indicator so you always know your hydration progress at a glance.

📸 Visual Showcase & Screenshots

1. Idle Countdown Mode	2. Time to Sip! (Reminder Popup)	3. Drinking (Celebration Mode)
Status Bar countdown & idle hover card (drinkbro.gif)	Active reminder & notification popup (splash.gif)	Celebration & glass count update (drinking.gif)

✨ Key Features

• ⏱️ Configurable Hydration Intervals: Set reminders every 15, 20, 30, 45, or 60 minutes (or enter any custom minute duration).
• 🫧 Instant Zero-Latency Bubble Sound: Plays a gentle, satisfying bubble chime (mixkit-liquid-bubble-3000.wav) the millisecond a reminder triggers.
• 📝 In-Editor Line Companion: A cute animated character peeks right beside the code line you are typing on for 3 seconds, then gracefully disappears.
• 💬 Actionable Notification Popups: Features direct [ Drinking ] and [ Snooze 10m ] action buttons.
• 📊 Status Bar & Rich Hover Card: Real-time tracker (⏱️ 30m | 3 🥛) with an interactive Markdown hover card showcasing animations and stats.
• 🔥 Daily Streak Tracker: Automatically calculates consecutive days of logging water intake with midnight auto-resets.
• 🌟 Open-Ended Sips Tracking: No artificial glass limits—track your actual daily and lifetime water intake.

🎬 Dynamic 3-GIF Visual Workflow

The companion dynamically shifts between three dedicated visual states:

1. Idle State (drinkbro.gif):
   • Companion rests peacefully while counting down: ⏱️ 28m | 3 🥛.
2. Active Reminder State (splash.gif):
   • The bubble sound plays 🫧.
   • Status bar updates to: 🌊 TIME TO SIP! | 3 🥛.
   • In-editor line margin shows splash.gif with 🌊 Sip your water & keep shipping! 💧.
   • Notification toast pops up: [ Drinking ] and [ Snooze 10m ].
3. Celebration State (drinking.gif):
   • Clicking Drinking records +1 glass, logs your streak, and displays celebratory status: ✨ Drinking! (+1) | 4 🥛.
   • Resets the countdown timer fresh from that moment.

📐 Technical Architecture & Flowcharts

1. Workflow & State Flowchart

flowchart TD
    A["⏱️ Timer Countdown (e.g., 30m)"] --> B{"Reminder Due?"}
    B -- "Yes" --> C["🔔 Trigger Reminder"]
    
    C --> C1["🫧 Play Bubble Sound"]
    C --> C2["📝 Show In-Editor Line Animation (3s)"]
    C --> C3["💬 Pop Up Notification: [Drinking] / [Snooze 10m]"]
    C --> C4["🌊 Update Status Bar: TIME TO SIP!"]
    
    C3 --> D{"User Action"}
    
    D -- "Clicks 'Drinking'" --> E["🎉 Celebrate & Log Sip"]
    E --> E1["✨ Show drinking.gif Animation (6s)"]
    E --> E2["📈 Today's Count & Lifetime Total +1"]
    E --> E3["🔥 Update Daily Streak Count"]
    E --> E4["🔄 Restart 30m Countdown Timer"]
    E4 --> A

    D -- "Clicks 'Snooze 10m'" --> F["⏰ Snooze for 10 Minutes"]
    F --> A

    D -- "No Click / Ignored" --> G["👀 Keep Status Bar as 'TIME TO SIP!'"]
    G --> H["Background timer keeps counting for next interval"]
    H --> A

2. Component Architecture

graph TD
    ExtEntry["extension.ts Entrypoint"] --> RemManager["ReminderManager"]
    ExtEntry --> StorageMgr["StorageManager"]
    ExtEntry --> StatBar["Status Bar Item"]

    RemManager --> SndPlayer["SoundPlayer (Native Audio)"]
    RemManager --> DecManager["EditorDecorationManager (Line Animation)"]
    RemManager --> StorageMgr
    RemManager --> StatBar

    DecManager --> ActiveEditor["Active Code Editor Line"]
    SndPlayer --> OS_Audio["OS Audio Hardware"]
    StorageMgr --> VSCode_GlobalState["VS Code Memento Storage"]

3. State Overview Table

🚀 User Guide & How to Use

1. Daily Workflow

1. Working & Coding:
   • As you code, glance at the bottom-right status bar to see your next reminder: ⏱️ 25m | 2 🥛.
2. When it's Time to Drink:
   • A bubble sound chime will play 🫧.
   • The status bar will pulse to 🌊 TIME TO SIP! | 2 🥛.
   • A 3-second animated buddy appears beside the line of code you are typing on.
   • A notification appears in the bottom right with [ Drinking ].
3. Logging Your Water:
   • Click Drinking directly in the notification, or click the status bar item to log your glass.
   • Watch the character celebrate with drinking.gif as your count increments (3 🥛)!

2. Status Bar Features

• Hovering: Hover your mouse over ⏱️ 30m | 3 🥛 to open the rich companion card showing:
  • Animated GIF of current state
  • Time remaining until next reminder
  • Today's glasses logged
  • Current daily streak
  • Total lifetime glasses
• Clicking: Clicking the status bar opens the Quick Action Menu:
  • Drinking (Log 1 Glass & Reset Timer)
  • Take a Sip Now (Immediate reminder trigger)
  • Pause / Resume Reminders
  • Change Reminder Interval
  • View Hydration Stats
  • Reset Today's Count

⌨️ Command Palette Reference

Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS) to access all commands:

⚙️ Configuration & Settings

Configure Sip & Ship via VS Code Settings (Ctrl+, / Cmd+,) by searching for Sip & Ship, or add these keys to your settings.json:

{
  // Interval between hydration reminder notifications (in minutes)
  "sipAndShip.intervalMinutes": 30,

  // Play a subtle bubble chime when reminder appears
  "sipAndShip.soundEnabled": true
}

🎨 Media Assets & Credits

All media assets used in this extension are credited to their respective creators:

📁 Project Structure

WaterBuddy/
├── .vscode/
│   ├── launch.json                   # F5 Extension debugging config
│   └── tasks.json                    # TypeScript build tasks
├── media/
│   ├── logo.png                      # Official extension branding avatar
│   ├── drinkBro.png                  # Screenshot: Idle countdown mode
│   ├── timeToSip.png                 # Screenshot: Active reminder popup
│   ├── drinking.png                  # Screenshot: Celebration state
│   ├── drinkbro.gif                  # Idle countdown animation
│   ├── splash.gif                    # Active reminder animation
│   ├── drinking.gif                  # Celebration sip animation
│   └── mixkit-liquid-bubble-3000.wav # Gentle bubble sound effect
├── src/
│   ├── editorDecorationManager.ts    # In-editor line margin animation engine
│   ├── extension.ts                  # Extension activation, status bar, and command bindings
│   ├── reminderManager.ts            # Timer scheduler, state manager, and notifications
│   ├── soundPlayer.ts                # Cross-platform non-blocking native audio player
│   └── storageManager.ts             # Persistent Memento storage, streaks, and date tracking
├── package.json                      # Extension manifest and contributions
├── tsconfig.json                     # TypeScript compiler configuration
└── README.md                         # Project documentation

🛠️ Development & Building

Prerequisites

• Node.js (v18.0.0 or higher)
• npm (v9.0.0 or higher)
• VS Code or Antigravity IDE

Setup & Compilation

# 1. Clone or navigate to the project directory
cd WaterBuddy

# 2. Install dependencies
npm install

# 3. Compile TypeScript
npm run compile

# 4. (Optional) Run compilation in watch mode during development
npm run watch

Running & Debugging

1. Open the project in VS Code or Antigravity.
2. Press F5 to launch the Extension Development Host.
3. In the new window, open any workspace and enjoy hydrating while you code!