ImagineGodMode

Discord

A multi-platform application for Grok media management built with React, TypeScript, and Tailwind CSS.

Chrome Extension: Full-featured extension for Chrome/Edge browsers with all features
iOS App: Native iOS wrapper using WKWebView with extension functionality

Contributors

B2K
Buku

Features

Analytics: Comprehensive Google Analytics 4 integration for anonymous usage tracking (always enabled, see docs/PRIVACY.md)
- Modal lifecycle tracking (open/close for all modals)
- Prompt interaction tracking (navigation, clipboard copy, to/from page actions)
- Bulk operation analytics (select all, deselect all, confirmations with counts)
- Video player control tracking (play/pause, fullscreen via button or keyboard)
- Keyboard shortcut usage tracking (F, Space, Ctrl+Enter combinations)
Prompt Management: Save, organize, and manage prompts with packs
- Duplicate Button: One-click prompt duplication in Prompt view (replaces Remove button)
  - Creates exact copy of current prompt including text and star rating
  - Automatically navigates to the newly created prompt
  - Always available (no restrictions)
- Long Press Navigation: Hold prev/next prompt buttons for fast navigation with accelerating speed
  - Starts slow (200ms intervals), speeds up to 50ms over 2 seconds
  - Touch and mouse support for all devices
  - Automatically stops at list boundaries (no looping)
- Non-Looping Navigation: Prev/next buttons stop at first/last prompt instead of wrapping around
- Streamlined UI: Reorganized button layout with consolidated Make button and toggle switches
  - Single "Make" button that respects all mode toggles (Random, Auto, Next)
  - Three toggle switches for mode control:
    - Random: Pick random prompt from current pack
    - Auto: Automatically loop through posts with 2-4 second random delays
    - Next: Navigate to next post after making (replaces separate "Make + Next" button)
  - Compact Make Togglers (optional): Space-saving mode with icon-only toggle buttons
    - Displays Random, Auto, and Next as small icon buttons next to Make button
    - Hides full toggle row for maximum space efficiency
    - Toggle in Settings → Packs + Prompts → "Compact Make Togglers"
  - Grid-based layout with perfectly aligned columns across rows
  - Reorganized action buttons into 2 rows (Add/Duplicate/Copy and Post Nav/To/From)
Per-Post State: Each post remembers its own selected pack, prompt, and prefix independently (optional, controlled via Settings)
Prompt Prefix: Per-post prefix text that automatically prepends to prompts when making videos (stored separately for each post)
Star Ratings: Rate your prompts with 1-5 stars (Material Design Icons)
Pack System: Create custom packs to organize prompts with confirmation dialog for deletion and text truncation
Packs Management Modal: Comprehensive pack and prompt management interface
- Split-Panel Design: Left panel for packs (33%), right panel for prompts (67%)
- Drag & Drop Reordering: Reorder packs and prompts within the same pack with visual feedback
- Pack Operations: Create, rename, delete packs with inline editing
  - Inline rename with save/cancel buttons
  - Automatic pack creation when all packs deleted (creates "Default")
  - Smart pack switching after deletion to first available pack
- Prompt Operations: Full CRUD operations for prompts
  - Edit prompt text in textarea with save/cancel buttons
  - Add new prompts directly to current pack
  - Duplicate prompts with single click
  - Delete prompts without "last prompt" restriction
- Quick Prompt Search: Filter prompts within current pack
  - Toggle search with magnifying glass icon next to add button
  - Real-time case-insensitive text filtering
  - Shows filtered count (e.g., "5/20 prompts" when searching)
  - Auto-focus on search input when opened
  - Disables drag-and-drop during search for clarity
  - Empty state message when no matches found
- Enhanced Pack Header: Improved typography and visual hierarchy
  - Larger pack name (text-base) for better readability
  - Dimmed grey prompt count (text-xs) to reduce visual clutter
  - Selection count in green when in selection mode
- Individual Deletion: Delete single prompts or packs with confirmation modals
- Selection Mode for Prompts: Toggle selection mode to select multiple prompts with checkboxes
  - Click anywhere on prompt to select/deselect
  - Select All / Deselect All controls
  - Batch delete multiple prompts at once
  - Batch move selected prompts to another pack via dropdown
  - Selected count displayed in header
- Selection Mode for Packs: Toggle selection mode to select multiple packs with checkboxes
  - Click anywhere on pack to select/deselect
  - Select All / Deselect All controls
  - Batch delete multiple packs with confirmation dialog
  - Selected count displayed in header
- Smart Prompt Counting: Displays actual non-empty prompt count in pack badges
- Empty State Handling: Shows all prompts including empty ones for easy management
- Drop Notifications: Toast-style notifications at top with slide-in/fade-out animations
- Visual Feedback: Drag-over highlighting with theme-aware colors, green highlight for selected items
- Pack Transfer: Drag prompts between packs to reorganize content
- AI Pack Generation: Copy Grok system prompt for generating themed prompt packs
Global Search: Type-ahead search across all packs with instant results
- Search button with magnifying glass icon
- Real-time search results with prompt preview
- Display pack name, prompt number, and star ratings
- Click to navigate directly to any prompt
Import/Export: Flexible pack management with multi-format support
- Multi-Select Export: Choose specific packs to export with checkbox interface
- Select All/Deselect All: Quick selection controls for batch operations
- Smart Export Format: Single pack → v1.0 format, Multiple packs → v2.0 format
- Minified JSON: Compact file sizes with base64 encoding in .pak files
- Backward Compatible Import: Supports both v1.0 (single) and v2.0 (multi-pack) formats
- Visual Validation: Real-time JSON validation with format detection and pack counts
- Theme-Aware UI: Export button with accent color hover states
- Merge or Replace Modes: Import new packs or overwrite existing ones
Unified Job Queue System: Centralized queue for all batch operations
- Single queue manages upscale, download, unlike, relike, and purge operations as jobs
- Sequential job processing with real-time progress tracking for each job
- Persists across post navigation and browser restarts
- Floating job queue indicator button with expandable panel showing live progress
- Auto-starts processing when new jobs are added
- Pause/Resume controls for queue processing
- Clear completed jobs or clear all jobs functionality
- Visual progress bars, status icons, and statistics (pending/processing/completed/failed counts)
- Jobs show detailed progress (processed items / total items, percentage)
- Supports concurrent batch operations without conflicts
Auto Download: Optional setting to automatically download all media after upscaling completes
List Limit: Configurable limit for fetching liked posts (100, 200, 500, or 1000)
- Default: 100 posts (recommended to avoid potential bans)
- Warning displayed when using limits different from 100
- Automatically refetches data when limit changes across all views
Max Bulk Processing Limit: Configurable limit for bulk operations (5, 10, 20, 50, or Unlimited)
- Default: Unlimited
- Applies to all bulk processing operations (upscale, download, unlike, relike)
- Processing stops cleanly after reaching the configured limit
- Informational message displayed when limit is set
- Console logs show when limit is applied for transparency
Video Upscaling: Parallel upscale requests with staggered start times for optimal performance
- Upscale jobs process 15 videos at a time per batch
- Auto-downloads completed batch before starting next (if Auto Download enabled)
Bulk Operations: Batch process multiple posts with visual selection interface
- Upscale All Liked: Select from liked posts to upscale videos in bulk
  - Accessible from panel controls or Ops view
  - Dedicated hook (useUpscaleAll) for modal and operation management
  - Creates process-for-upscale job to analyze posts and extract videos
  - Automatically creates upscale job after processing completes
- Download All Liked: Bulk download all media from multiple liked posts
  - Confirmation modal with visual post selection (all posts pre-selected)
  - Collects all media URLs including main media and child posts (videos)
  - Creates download job in unified queue with all collected media files
  - Shows file count and post count in status message
  - Supports shift-click multi-select and Select All/Deselect All controls
- Manage Likes: Unified modal with tabbed interface for like management
  - Liked Posts Tab: Unlike multiple posts at once with confirmation
    - Creates unlike jobs in the unified queue for batch processing
    - No progress bar in modal - track progress via job queue indicator
    - Automatic redirect to /favorites after job completion
  - Archive Tab: View and re-like previously unliked posts from local storage
    - Creates relike jobs in the unified queue for batch processing
    - Export/Import archive functionality with JSON validation
    - Shows unliked date badge on each archived post
    - Per-user archive with automatic migration
  - Tabbed navigation with badge counts for each tab
  - Independent selection states per tab (selections persist when switching)
  - All selections clear when modal reopens
- Delete Multiple Posts: Permanently delete multiple posts with confirmation dialog (currently hidden)
- Large modal interface (90vw × 85vh) with 5-column grid layout
- Heart/broken heart indicators for intuitive like/unlike selection
- Click anywhere on item to toggle selection (no navigation)
- Shift-click for batch selection/deselection (standard multi-select behavior)
- Reusable shared components for consistent UX across all bulk operation modals
- All bulk operations now use the unified job queue system for better reliability
- Real-time progress tracking via floating job queue indicator
- Local storage of unliked posts with minimal metadata (ID, prompt, thumbnail, timestamp)
Post Navigation: Quick navigation between posts in your favorites list
- Previous/Next buttons in Prompt view for seamless browsing
- Automatically loads liked posts on mount for instant navigation
- Buttons disabled when no previous/next post available
- Uses posts from favorites or fetched posts from bulk operations
Make + Next: Workflow automation for batch processing posts
- Applies current prompt, clicks Make button, and automatically navigates to next post
- Unified split-button design (60% Make+Next, 20% Random, 20% Auto toggle)
- Disabled when no next post available
- Uses fetched posts from "Upscale All Liked" or "Show Unliked"
- 1-second delay between Make and navigation for proper execution
- Optional "Remember Make Toggles" setting keeps Random, Auto, and Next selections when moving between posts
- Random Prompt Mode: Toggle to randomly select prompts from current pack on each iteration
  - Shuffle icon button for easy identification
  - When enabled, randomly picks a different prompt from the pack after each Make + Next
  - Works independently or combined with Auto mode
  - Visual active state (highlighted when enabled)
  - Perfect for testing prompt variations across multiple posts
- Auto Mode: Integrated toggle for automatically repeating Make + Next workflow
  - Seamless button split design with shared border (no gap between buttons)
  - Visual active state (slate background, dark icon)
  - Random 2-4 second delay between iterations
  - Automatically stops when reaching the end of the post list
  - Toggle off anytime to stop automation
  - Combines with Random mode for fully automated prompt variation testing
Video Progress Tracking: Real-time progress bar and button glow during video generation
HD Status Indicator: Green check icon appears when all videos are HD quality
Video Controls: Play/pause button with synchronized state tracking
Fullscreen Video Player: Intelligent fullscreen button that detects visible video (HD or SD)
Internationalization (i18n): Multi-language support with live language switching
- English, Spanish, Russian, and German translations
- Persistent language preference
- All UI elements translated including tooltips, buttons, and modals
Theme Customization: Choose from 9 themes (Dark, Light, Dracula, Winamp, LimeWire, Steam, Discord, Champagne, New Year's Eve) with full UI color adaptation
Configurable Themes: Themes loaded from JSON file for easy customization
UI Scaling: Adjust panel size from Tiny (70%) to Large (115%)
Visual Settings: Settings labels enhanced with Material Design Icons for better UX
Simple Shortcut Setting: Optional setting to use Ctrl/Cmd + Enter instead of Ctrl/Cmd + Shift + Enter for applying prompts
Hide Unsave Button: Optional setting to hide the "Unsave" button from the Grok page interface (off by default)
Enable The Pit: Optional setting to show/hide The Pit tab for accessing experimental video generation features (off by default)
Sound Effects Control: Optional setting to enable/disable UI sound effects (on by default) - controls cyberpunk-style audio feedback for purge modal interactions
Confirm Copy From: Optional setting to show confirmation dialog when copying from page would replace existing prompt text (on by default)
Collapsible Sections: Optional setting to enable collapsible UI sections with expand/collapse controls (on by default)
- When enabled: sections start collapsed with clickable headers and chevron indicators
- When disabled: all sections remain expanded with no collapse controls
- Smooth 300ms animations for expanding/collapsing with fade and height transitions
- Applies to Settings view panels (Packs + Prompts, Behavior, Appearance, Danger Zone) and Ops view (Bulk Actions)
Keyboard Shortcuts:
- Ctrl/Cmd + Shift + Enter: Apply current prompt with prefix and click "Make a Video" (default)
- Ctrl/Cmd + Enter: Apply current prompt with prefix and click "Make a Video" (when Simple Shortcut enabled)
- Left Arrow: Navigate to previous video
- Right Arrow: Navigate to next video
- F: Toggle fullscreen (works globally, even without extension panel open)
- Space: Play/pause video (works globally, even without extension panel open)
Arrow Key Navigation: Navigate videos with Left/Right arrow keys
Automatic Data Refetch: Automatically refetches post data when navigating between posts
Persistent Storage: All data saved with chrome.storage.local (prompts) and localStorage (settings, currentView)
Extension Context Validation: Graceful handling of extension reloads with proper error suppression
Persistent View State: Remembers last opened tab (Prompt/Ops/Settings/Help) across sessions
Modern UI: Bottom-placed tabs with icon-only queue tab, pill-shaped buttons, Material Design Icons, dynamic theming, glassmorphism design with frosted glass effects
- Custom Tooltip System: Lightweight custom tooltips with smart positioning
  - Always positioned at the top of elements
  - Automatically adjusts horizontally to stay within viewport
  - Arrow remains centered on trigger element even when tooltip shifts
  - Black background with white text for high contrast
  - Uses portal rendering for proper z-index layering
Enhanced Panel Controls: Collapsed panel shows quick-access buttons for common actions
- Previous/Next post navigation (dynamic based on available posts)
- Make video button (only when on a post with a prompt)
- Make + Next button (combines make and navigate actions)
- Auto mode toggle (for automated Make + Next workflow)
- Upscale All button (opens bulk upscale modal)
- Remember Pack Per Post toggle (visual indicator for per-post state persistence)
- Floating job queue indicator positioned above other controls (shows active job count)
- All buttons intelligently show/hide based on context (post availability, queue state, panel expansion)
Glassmorphism Design: Semi-transparent UI elements with backdrop blur creating modern frosted glass aesthetic
- Main panel and buttons: 67% opacity + 12px blur
- All modals: 67% opacity + 16px blur
- Consistent glass effect across entire extension UI
- Cross-browser compatibility with WebkitBackdropFilter support
Glow Animation Effects: Interactive hover effects with light sweep animations
- Universal glow hook for reusable animations across components
- Multi-item glow support for tabs, dropdowns, and lists
- Configurable animation duration, intensity, and effects
- Theme-aware glow colors matching UI theme
- Scale animation disabled on buttons for cleaner interactions
The Pit (Video Generation): Automated video generation with batch processing (Under Construction)
- Select source post from liked posts with image preview
- Navigate through liked posts with prev/next controls
- Manual prompt mode or pack-based prompt selection
- Configurable number of generation attempts (1-10 tries)
- Stop on first success toggle for early termination
- Real-time progress tracking (succeeded/failed counts)
- Automatic moderation detection treats moderated videos as failures
- Sequential execution - waits for each video to complete before starting next
- Streaming progress monitoring - tracks generation progress to 100%
- Staggered API calls with 1-2 second delays to avoid rate limiting
- 403 error detection with immediate stop and user notification
- Dynamic request headers (unique UUID and Statsig IDs per request)
- Loads all liked posts automatically for easy post selection
Spin Feature: Batch process list items (from userscript version)

Technology Stack

React 18 - UI framework
TypeScript - Type safety with strict mode
Zustand - Lightweight state management (settings, media, posts, modals)
Tailwind CSS - Utility-first styling
Vite - Fast build tool
CRXJS - Vite plugin for Chrome extensions
Chrome Manifest V3 - Latest extension API
Google Analytics 4 - Anonymous usage analytics via Measurement Protocol

Architecture

Modal System

The extension features a modern, scalable modal architecture:

Centralized State: Zustand-based modal store for optimal performance
Reusable Components: GridSelectionModal base for all bulk operation modals
Composition Utilities: Shared footer buttons, warning banners, and validation displays
Focus Management: Custom hooks for accessibility (focus trapping, animations)
Type Safety: Comprehensive TypeScript definitions for all modal patterns
Code Reduction: DeleteModal refactored from 387 to 124 lines (67% reduction)

Key Components

GridSelectionModal: Base component for Delete, Unlike, Upscale, and Archive modals
PacksManagementModal: Full-featured pack and prompt management with drag & drop
useShiftSelection: Custom hook providing shift-click multi-selection behavior
ModalFooterButtons: Three reusable footer patterns (Confirm, Action, BulkAction)
WarningBanner: Themed warning/info banners for modal alerts
ValidationDisplay: Form validation with success/error states

Installation

Chrome Extension (Development Mode)

Install dependencies:
```
npm install
```
Build the extension:
```
npm run build
```
Load in Chrome:
- Open Chrome and navigate to chrome://extensions/
- Enable "Developer mode" (toggle in top right)
- Click "Load unpacked"
- Select the dist folder from this project
Development with auto-reload:
```
npm run dev
```
This will watch for changes and rebuild automatically.

iOS App

For iOS app setup instructions, see ios/README.md.

Quick start:

# Build extension assets for iOS
./scripts/build-ios.sh

# Open in Xcode
open ios/imagineGodMode/imagineGodMode.xcodeproj

Features:

Full extension functionality in native iOS app
WKWebView-based wrapper loading grok.com
Chrome Storage bridge with dual-backend support:
- Primary: Swift UserDefaults for persistent storage
- Fallback: WKWebView localStorage when UserDefaults unavailable
- Automatic backend detection and graceful degradation
- Storage inspector utility (window.__inspectStorage()) for debugging
Photo library download support
Back/forward navigation and refresh controls
Optimized logging with reduced console output for better performance
Streamlined script injection with minimal logging overhead

Usage

Navigate to Grok Imagine: https://grok.com/imagine or any post: https://grok.com/imagine/post/*
The extension UI will appear in the bottom-right corner with smooth expand/collapse animations
Click the expand button to open the panel
Switch between "Prompt", "Ops", "Settings", "Help", and "Queue" tabs (bottom navigation with smooth transitions)
Prompt View: Manage and organize your prompts
- Each post remembers its own pack selection and prompt position
- Prefix input: Add prefix text that automatically prepends to prompts (with comma) when pressing Make
- Prefix, pack, and prompt index are stored per-post and persist across sessions
- Search prompts: Click magnifying glass icon to search across all packs
- Rate prompts with stars
- Navigate with arrow buttons or keyboard
- Copy and play prompts
- Make + Next: Automatically apply prompt, make video, and navigate to next post (requires fetched posts)
Ops View: Automatically fetches post data when opened
- Primary action: Upscale videos (parallel processing with staggered starts)
- Secondary action: Download media - creates download jobs in queue for batch processing
- Real-time status updates and progress tracking via job queue indicator
- Green check icon appears when all videos are HD quality
- Upscale All Liked: Bulk upscale videos from multiple liked posts
  - Opens large modal (90vw × 85vh) with 5-column image grid
  - All posts selected by default, click to toggle selection
  - Centered checkbox indicator for clear visual feedback
  - Click anywhere on item to toggle (no navigation on click)
  - Shift-click for batch selection/deselection
  - Creates process-for-upscale job followed by upscale job in queue
- Unlike Multiple Posts: Manage liked posts with bulk unlike
  - Opens large modal with 5-column grid of liked posts
  - Centered heart/broken heart indicators for intuitive selection
  - Click anywhere on item to toggle (no navigation on click)
  - Shift-click for batch selection/deselection
  - Creates unlike job in queue for batch processing
  - Automatic redirect to /favorites after job completion
  - Automatically saves unliked posts to archive
- Delete Multiple Posts: Permanently delete posts with safety confirmation
  - Opens large modal with 5-column grid layout
  - Centered delete icon indicator when selected
  - Click anywhere on item to toggle selection
  - Shift-click for batch selection/deselection
  - Warning banner: "Deleting posts is permanent and cannot be undone!"
  - Two-step confirmation: select posts → confirm deletion dialog
- Unliked Archive: Browse and restore previously unliked posts
  - Opens archive modal showing all unliked posts with timestamps
  - Re-like multiple posts at once to restore them to favorites
  - Creates relike job in queue for batch processing
  - Automatically removes from archive after successful re-like
  - Local storage with minimal data (no network required to browse)
Settings View: Customize your experience
- Choose theme: Dark, Light, Dracula, Winamp, LimeWire, Steam, Discord, Champagne, or New Year's Eve
- Themes are configurable via public/themes.json
- Adjust UI size: Tiny to Large
- Select language: English, Spanish (Español), Russian (Русский), or German (Deutsch)
- Enable Auto Download to automatically download media after upscaling
- Enable Sound to control UI sound effects (on by default) - affects purge modal audio feedback
- Configure List Limit to control how many liked posts to fetch (100/200/500/1000)
  - Default is 100 (recommended)
  - Warning: Using limits different from 100 might lead to a ban
- Automatically refetches data when changed
- Toggle Remember Pack Per Post to control per-post state persistence (enabled by default)
- Toggle Remember Make Toggles to persist Random/Auto/Next selections across post navigation (disabled by default)
- Toggle Simple Shortcut to use Ctrl/Cmd+Enter instead of Ctrl/Cmd+Shift+Enter for applying prompts
- Toggle Hide Unsave to hide the "Unsave" button from the page (off by default)
- Toggle Enable The Pit to show/hide The Pit tab for experimental video generation (off by default)
- Toggle Confirm Copy From to show confirmation when replacing existing prompt text (on by default)
- Toggle Collapsible Sections to enable section expand/collapse controls (on by default) - affects Settings and Ops view panels
- All settings labels include visual icons for easy identification
- Tooltips: Hover over any setting row for detailed explanations
- Data Management:
  - Export packs: Select any pack to export to .pak file (base64 encoded for backup/sharing)
  - Import packs: Upload .pak/.json files or paste raw JSON with real-time validation
  - Import modes: Add (create new) or Replace (overwrite existing)
  - Copy Grok prompt: System prompt for generating custom packs via AI
- Purge All Data: Nuclear option to reset all data (5-click activation with arrow key challenge)
  - Creates 3 separate purge jobs in the unified queue (liked posts, archive, packs)
  - Interactive arrow key sequence for safety with timed countdown
  - Visual feedback during arrow key challenge with status indicators
  - Jobs are queued and processed sequentially via job queue system
  - Track purge progress via floating job queue indicator
  - Cyberpunk-themed UI with animations and sound effects
Help View: Comprehensive feature documentation
- Complete list of all extension features with descriptions
- Interactive tooltips on hover for detailed explanations
- Keyboard shortcuts reference with visual key indicators
- About section with version and credits
- Multi-language support for all help content
Job Queue: Unified job queue system for all batch operations
- Floating job queue indicator button positioned above panel controls
- Badge shows count of active jobs (pending + processing)
- Pulsing animation when jobs are processing
- Click to expand/collapse detailed queue panel
- Expandable panel shows:
  - Current job progress bar with percentage and item counts
  - Statistics (pending, processing, completed, failed job counts)
  - List of up to 10 jobs with type icons and status indicators
  - Queue controls: Pause/Resume processing, Clear completed, Clear all
- Supports all operation types: upscale, download, unlike, relike, purge
- Real-time progress updates with smooth animations
- Jobs persist across browser sessions
The Pit View: Automated video generation from images (Under Construction)

Post Selection: Navigate through liked posts with image preview
- Automatically loads all liked posts on view open
- Prev/Next buttons to browse through posts
- Shows current post index and total count
- Thumbnail preview with loading state
Prompt Configuration:
- Manual mode: Free-form text input for custom prompts
- Pack mode: Select from existing prompt packs and navigate prompts
- Pack dropdown with all available prompt packs
- Prompt navigation with prev/next controls
Generation Settings:
- Tries: Configure number of generation attempts (1-10)
- Stop on First Success: Toggle to stop after first successful generation
Churning (Batch Generation) - Currently disabled during development:
- Sequential execution ensures videos generate one at a time
- Streaming response reader waits for 100% completion before proceeding
- Real-time progress display showing current attempt number
- Live success/failure counters with color coding (green/red)
- Automatic moderation detection: Moderated videos counted as failures
- 403 error handling with immediate stop and error message display
- Dynamic request headers generated per request for API compliance
- 1-2 second delays between requests to prevent rate limiting

Video Controls: Use the play/pause button or press Space to control video playback
Fullscreen: Click the fullscreen button or press F to enter fullscreen mode

Project Structure

grkgoondl/
├── src/
│   ├── api/              # API layer for Grok endpoints
│   ├── background/       # Background service worker
│   ├── components/       # React components (organized by type)
│   │   ├── buttons/      # Button components (FullscreenButton, PauseButton)
│   │   ├── common/       # Shared components (Icon, NoPostMessage, UpscaleQueueIndicator)
│   │   ├── inputs/       # Input components (Button, RatingSystem, Tabs)
│   │   ├── modals/       # Modal components (Upscale, Unlike, UnlikedArchive, Import, etc.)
│   │   ├── views/        # Main view components (Prompt, Ops, Settings, Help, Queue)
│   │   ├── MainPanel.tsx # Main panel container with expand/collapse animations
│   │   └── PackManager.tsx # Pack management component
│   ├── constants/        # Constants and configuration
│   ├── content/          # Content script (injection point)
│   ├── contexts/         # React contexts (i18n)
│   ├── hooks/            # Custom React hooks (bulk operations, loaders, glow animations)
│   ├── locales/          # Translation files (en.json, es.json, ru.json)
│   ├── store/            # Zustand stores
│   ├── types/            # TypeScript type definitions
│   ├── utils/            # Utility functions and helpers
│   ├── App.tsx           # Main app component
│   └── index.css         # Global styles (Tailwind)
├── ios/                  # iOS app implementation
│   ├── README.md         # iOS-specific documentation
│   ├── XCODE_SETUP.md    # Xcode setup instructions
│   └── imagineGodMode/   # Xcode project
│       └── imagineGodMode/
│           ├── WebView.swift              # WKWebView container with optimized logging
│           ├── ChromeStorageBridge.swift  # Chrome API bridge with enhanced debugging
│           ├── DownloadManager.swift      # Photo library integration
│           ├── StorageManager.swift       # App lifecycle handling
│           ├── ContentView.swift          # Main view
│           ├── imagineGodModeApp.swift   # App entry point
│           └── extension/                 # Built extension assets
│               ├── chromeStoragePolyfill.js  # Dual-backend storage polyfill
│               ├── content-script.js         # Main content script
│               ├── content-script.css        # Extension styles
│               └── helpers.js                # Utility functions
├── public/               # Static assets (icons, themes.json)
├── scripts/              # Build scripts
│   └── build-ios.sh      # iOS build script
├── dist/                 # Build output (load this in Chrome)
├── docs/                 # Documentation files
│   ├── PRIVACY.md        # Privacy policy and analytics documentation
│   ├── PLAN.md           # Development roadmap and planning
│   ├── CLAUDE.md         # Claude AI integration notes
│   └── *.md              # Release notes and other documentation
├── archive/              # Archived Tampermonkey userscript
├── manifest.json         # Extension manifest
├── vite.config.ts        # Vite configuration
├── tailwind.config.js    # Tailwind configuration
└── package.json          # Dependencies

Key Components

Stores (Zustand)

usePromptStore: Manages prompts, packs, ratings, and import/export operations
useMediaStore: Handles media URLs, upscaling, and status
useUIStore: Controls UI state (expanded/collapsed, view mode)
useSettingsStore: Manages theme, size, auto-download, list-limit, remember-post-state, remember-make-toggles, simple-shortcut, hide-unsave, enable-the-pit, enable-sound, confirm-copy-from, and collapsible-sections preferences with localStorage persistence
useJobQueueStore: Unified job queue managing all batch operations (upscale, download, unlike, relike, purge)
- Single queue for all job types with sequential processing
- Real-time progress tracking per job (processed items, percentage)
- Job states: pending → processing → completed/failed
- Auto-starts processing when jobs are added
- Pause/Resume controls for queue processing
- Persists to localStorage (excludes processing jobs)
- Batch upscaling: 15 videos at a time with auto-download support
- Sequential downloads with configurable delays
- Unlike/Relike with archive integration and auto-refresh
- Purge operations for liked posts, archive, and packs
usePostsStore: Manages fetched posts list and navigation helpers for "Make + Next" workflow
useUserStore: Manages user ID from API with localStorage persistence and automatic initialization
usePitStore: Manages The Pit state (selected post, manual mode, prompt, pack selection, tries, stop-on-first-success)

Contexts

I18nContext: Internationalization context providing translation functions and locale management
- useTranslation() hook for accessing translations
- Parameter interpolation support (e.g., {{packName}})
- Fallback to English for missing translations
- Persistent language preference in localStorage

Hooks

useKeyboardShortcuts: Global keyboard shortcut handlers
useUrlWatcher: Monitors URL changes, resets state, and triggers data refetch callback
useArrowKeyNavigation: Arrow key navigation for video controls
useVideoProgress: Real-time video generation progress tracking with polling
useLikedPostsLoader: Hook for loading and managing liked posts with loading state and configurable list limit from settings
useShiftSelection: Reusable hook for shift-click multi-selection behavior across bulk operation modals
useUpscaleAll: Hook for managing upscale all modal and bulk upscale operations
- Modal state management (open/close)
- Loads liked posts for selection
- Creates process-for-upscale job followed by upscale job in unified queue
- Analytics tracking for modal events
useGlowAnimation: Universal glow animation hook for button hover effects with configurable settings
useMultiGlowAnimation: Multi-item glow animation hook for tabs, dropdowns, and lists with individual tracking

Components

Views (src/components/views/)

PromptView: Prompt management interface with "Make + Next" workflow button
OpsView: Media controls with job queue-based upscaling, downloads, bulk operations (Upscale All Liked, Unlike Multiple Posts, Delete Multiple Posts)
SettingsView: Theme, size, language, auto-download, list-limit, remember-post-state, remember-make-toggles, simple-shortcut, hide-unsave, enable-sound, confirm-copy-from, collapsible-sections preferences, data management with import/export, and purge all data functionality
HelpView: Help and documentation interface
QueueView: Legacy view - functionality replaced by JobQueueIndicator floating component
PitView: Automated video generation interface with post selection, prompt configuration, generation settings, real-time progress tracking, and moderation detection

Modals (src/components/modals/)

BaseModal: Reusable modal foundation with animations, high z-index, portal rendering, and flexible configuration
UpscaleAllModal: Large modal (90vw × 85vh) with 5-column grid for bulk upscaling videos from liked posts (creates job queue jobs)
UnlikeModal: Large modal with 5-column grid, heart/broken heart indicators, bulk unlike (creates job queue jobs, no progress bar)
DeleteModal: Confirmation modal for bulk deleting posts with nested confirmation dialog for extra safety
UnlikedArchiveModal: Archive browser for viewing and re-liking previously unliked posts (creates job queue jobs, no progress bar)
PurgeModal: Interactive modal with random arrow key sequence challenge, creates 3 purge jobs in queue (liked/archive/packs)
SearchModal: Type-ahead search modal for finding prompts across all packs
PackSelectModal: Modal for selecting which pack to export
ImportPackModal: Modal for importing packs via paste or file upload with validation
ConfirmDeleteModal: Confirmation dialog for pack deletion with warning message
ConfirmModal: Generic confirmation modal with variant support (danger/warning/info) for reusable confirmation dialogs

Shared Modal Components (src/components/modals/shared/)

SelectionControls: Reusable select/deselect all buttons for consistent bulk selection UX
PostGrid: Reusable grid component for displaying posts with selection state, hover effects, video count badges, and customizable overlays

All modals extend BaseModal for consistent animations, behavior, and appearance.

Note: ProgressBar component removed as progress tracking is now handled by the floating JobQueueIndicator.

Buttons (src/components/buttons/)

PauseButton: Play/pause control with synchronized video state tracking
FullscreenButton: Intelligent fullscreen toggle with video detection

Inputs (src/components/inputs/)

Button: Reusable button component with theme-aware styling, hover states, and glow animations
Dropdown: Custom dropdown component with portal-based rendering for proper z-index stacking and glow animations
- Theme-aware styling with hover effects and smooth transitions
- Context-aware z-index (uses higher value when inside modals)
- Portal rendering to dedicated container with fixed positioning
- Dynamic position calculation with scroll and resize handling
- Click-outside detection for seamless UX
- Glow animation effects on hover for trigger and options
RatingSystem: 5-star rating component with white icons and optional readonly mode
Tabs: Tab navigation component with theme support, bottom placement, icon-only mode, badges, and glow animations
Toggle: Reusable toggle switch component with theme-aware SUCCESS color for active state and glow animations on hover

Common (src/components/common/)

Icon: Material Design Icons wrapper
NoPostMessage: Reusable component displayed when no post ID is found in URL
CollapsibleSection: Reusable collapsible section component with smooth animations
- Integrates with settings store for global collapse behavior control
- Smooth 300ms expand/collapse animations with fade and height transitions
- Conditionally clickable headers based on collapseSections setting
- Chevron indicators (up/down) when collapse controls enabled
- Dynamic height calculation for proper animation of variable content
JobQueueIndicator: Floating queue status indicator with expandable panel
- Shows badge with active job count (pending + processing)
- Pulsing animation when jobs are processing
- Expandable panel with current job progress, statistics, job list, and controls
- Supports all job types with appropriate icons and labels

Root (src/components/)

MainPanel: Floating panel container with pause, fullscreen, collapse buttons, version badge, smooth expand/collapse animations, and tab transition effects
PackManager: Pack dropdown with search button, text truncation, and CRUD operations

Architecture

Content Script

Injects the React app into Grok pages at document_idle.

Background Service Worker

Handles:

File downloads via chrome.downloads.download()
Message passing between content script and background

Note: API calls (fetchPost, upscaleVideo) moved to content script for direct page context and cookie access. Background worker now only handles downloads which require chrome.downloads API.

Message Passing

Uses chrome.runtime.sendMessage() for communication:

DOWNLOAD_MEDIA - Download media files (background worker)

Direct API calls (content script with credentials):

fetchPost() - Fetch post data from Grok API
upscaleVideo() - Upscale video with authentication

Storage

Uses multiple storage mechanisms with context validation:

chrome.storage.local: Packs with prompts and ratings, prompt prefixes per-post, per-post state (selected pack and prompt index), unliked posts archive with minimal metadata per-user
localStorage: Theme, size, language, auto-download preferences, user ID, and currentView (last opened tab) for instant loading
Extension Context Validation: All storage operations check for valid extension context to gracefully handle extension reloads
Unliked Posts Archive:
- Per-user storage: Each Grok user ID has separate unliked posts
- Automatic user ID detection from fetchLikedPosts API on extension init
- Backward compatibility: Old format automatically migrated to current user
- Stores minimal data (ID, prompt, thumbnail URL, media URL, timestamp, child post count) for efficient browsing and re-liking
- Multi-account support: Switch between Grok accounts without data conflicts
Import/Export:
- Per-pack .pak export (base64 encoded) with timestamped filenames
- Import via .pak/.json file upload or raw JSON paste with real-time validation
- Automatic base64 decoding for .pak files, direct JSON parsing for .json files
- Add/Replace modes with pack name conflict handling
- Version tracking and comprehensive data validation
- Interactive Grok prompt for AI-generated pack creation

Development

Type Checking

npm run type-check

Building

npm run build

Development Server

npm run dev

Migration from Tampermonkey

This Chrome extension is a complete rewrite of the original Tampermonkey userscript with:

✅ Modern React architecture
✅ Full TypeScript type safety
✅ Chrome extension APIs (no Tampermonkey dependency)
✅ Improved state management with Zustand
✅ Tailwind CSS for styling
✅ Component-based architecture
✅ Better separation of concerns

Key Differences

Feature	Tampermonkey	Chrome Extension
Storage	`localStorage`	`chrome.storage.local`
Downloads	`GM_download()`	`chrome.downloads.download()`
State	Global object	Zustand stores
UI	Vanilla JS + DOM	React components
Styling	Inline styles	Tailwind CSS
Build	esbuild	Vite + CRXJS

Notes

Documentation: All documentation files have been organized into the docs/ folder for better project structure
Build Artifacts: ZIP files are now stored in zip/ directory instead of being scattered throughout the project
Archived Userscript: The original Tampermonkey version is in archive/userscript/
Spin automation feature not yet implemented in extension (was in userscript)
Custom icons included (gold "G" logo at 16px, 48px, 128px)
Extension requires permissions for storage, downloads, and activeTab
Works on https://grok.com/* and https://www.grok.com/*
Theme System: Nine built-in themes (Dark, Light, Dracula, Winamp, LimeWire, Steam, Discord, Champagne, New Year's Eve) with full color palette adaptation including theme-aware accent colors
Configurable Themes: Themes loaded from public/themes.json for easy customization without code changes
Theme-Aware Accents: Success indicators and toggle switches adapt to each theme's color scheme for consistent visual design
UI Scaling: CSS transform-based scaling maintains crisp rendering at all sizes
All buttons use pill shape with theme-aware styling and hover states
Material Design Icons for professional appearance
Tab-style navigation with bottom placement and theme-aware active states
Fullscreen mode with proper CSS styling for video display
Video progress polling every 500ms with auto-removal on completion
Console initialization tag with styled branding using theme colors
API architecture refactored: content script handles authenticated calls, background worker handles downloads
Message passing includes retry mechanism (3 attempts) to handle service worker wake-up delays
Download queue system processes files sequentially with configurable delays between downloads
Settings persist in localStorage for instant theme/size/language/auto-download/list-limit/remember-post-state/remember-make-toggles/simple-shortcut/hide-unsave/enable-the-pit/enable-sound/confirm-copy-from/collapsible-sections application on load
Hide Unsave Feature: Dynamic CSS injection to hide Unsave button when enabled
- Uses useEffect hook to inject/remove style element
- CSS selector targets button[aria-label="Unsave"]
- Cleanup on unmount and setting toggle
Internationalization: Complete i18n infrastructure with English, Spanish, Russian, and German translations
Tooltip System: Enhanced global tooltip system with consistent styling
- Smaller text size (text-xs) for better readability
- Max width of 20rem with automatic text wrapping
- Whole-row hover areas in Settings and Help views
- Detailed explanations for all features and settings
- Multi-language tooltip support across all four languages
- Live language switching without reload
- Translation context with parameter interpolation
- Fallback mechanism for missing keys
- All UI elements fully translated (buttons, labels, tooltips, modals)
Visual Enhancement: Settings labels enhanced with Material Design Icons (palette, resize, translate, download, database, swap)
Unified Job Queue System: Centralized queue for all batch operations
- Single queue handles upscale, download, unlike, relike, and purge jobs
- Sequential job processing with real-time progress tracking
- Auto-starts processing when jobs are added
- Persists to localStorage across sessions (excludes processing state)
- Floating indicator button with pulsing badge showing active job count
- Expandable panel with current job progress, statistics, job list, and controls
- Upscale jobs process videos in batches of 15 with staggered delays
- Auto-download support: creates download job after upscale completes
- Unlike/Relike jobs integrate with archive and auto-refresh browser
- Purge jobs handle data cleanup operations
- Pause/Resume controls and job clearing (completed or all)
Download Protection: Download button disabled until all videos are HD quality
Auto Download: Queue automatically downloads each completed batch of upscaled videos
Remember Pack Per Post: Optional toggle (enabled by default) to save/restore selected pack and prompt index per post
HD Status Visual: Green check icon displays in Ops view when all videos are HD quality
Video State Sync: Play/pause button automatically syncs with video element state via event listeners
Global Keyboard Shortcuts: F (fullscreen) and Space (play/pause) work globally across the page, with fallbacks to direct video element control
Extension Reload Handling: Storage operations validate extension context and fail gracefully during reloads
Smart URL Watching: URL changes trigger automatic data refetch via callback pattern in OpsView component
Pack Import/Export:
- Per-pack exports with descriptive filenames (imaginegodmode-pack-Name-Date.pak)
- Base64 encoded .pak files for secure storage and sharing
- PackSelectModal for choosing which pack to export
- ImportPackModal with paste/upload options supporting .pak and .json files
- Automatic base64 decoding for .pak files, raw JSON paste support
- Real-time validation showing pack name, prompt count, and error details
- Add mode prevents overwriting, Replace mode allows updates
- Grok AI integration: Copy system prompt to generate custom packs via conversation
Analytics: Google Analytics 4 (GA4) integration for anonymous usage tracking
- Mandatory analytics (no opt-out) - see docs/PRIVACY.md
- Anonymous client IDs using UUID v4
- Session tracking with 30-minute timeout
- Comprehensive event tracking:
  - Feature usage, prompt/pack actions, media operations, settings changes
  - Modal lifecycle events (open/close for all modals: upscale, unlike, archive, search, delete, import/export)
  - Prompt interactions (navigation, clipboard copy, to/from page, Make+Next)
  - Bulk operations (select/deselect all, confirmations with item counts, completion metrics)
  - Video controls (play/pause, fullscreen) with method tracking (button vs keyboard)
  - Keyboard shortcut usage (F, Space, Ctrl+Enter, Ctrl+Shift+Enter)
- No personal data, prompt content, or identifying information collected
- Uses GA4 Measurement Protocol (no script loading)
Modal System: Unified modal architecture with BaseModal component
- Smooth fade-in and slide-in animations (0.2s/0.3s)
- Portal rendering to document.body for proper stacking
- Modals persist when extension panel is collapsed (no state loss)
- Consistent behavior: overlay click, close button, keyboard shortcuts
- Flexible sizing: configurable width, height, padding, overlay opacity
- Optional footer for action buttons with theme-aware styling
- DRY principle reduces code duplication across 7+ modals (~250 lines saved)
Z-Index Management: Centralized layering system for predictable element stacking
- Hierarchical constants defined in constants.ts (10000-10600 range)
- Main panel (10000) → Video progress (10100) → Dropdown (10200) → Tooltip (10300) → Modal (10400) → Modal dropdown (10500) → Modal tooltip (10600)
- Context-aware dropdowns automatically use higher z-index when rendered inside modals
- Portal-based rendering with fixed positioning for reliable overlay behavior
- Prevents z-index conflicts and ensures proper layering across all UI elements
Loading Indicators: Animated spinner icons for all loading states
- Material Design Icons rotating spinner (mdiLoading) replaces static "..." text
- Tailwind's animate-spin for smooth rotation animation
- Consistent across all components: buttons, modals, progress bars, queue indicator
- Button component supports iconClassName prop for animation classes
- Dynamic icon switching in loading states for better visual feedback
Web Audio API Integration: Procedural sound generation for UI feedback
- Cyberpunk-style aggressive sound design for purge modal
- Frequency sweeps and square wave synthesis
- No external audio files required (all sounds generated in-browser)
- Success melody with C major progression and harmonic layers
- Error sounds with harsh downward frequency sweeps
- Sound effects can be toggled on/off via Settings (enabled by default)
- Settings preference checked before playing any sound
Glassmorphism UI: Modern frosted glass design throughout the extension
- Semi-transparent backgrounds with backdrop blur on all UI elements
- Main panel, buttons, and controls: 67% opacity (aa suffix) + 12px blur
- All modals: 67% opacity + 16px blur for deeper glass effect
- Cross-browser support with both backdropFilter and WebkitBackdropFilter
- Hover states maintain transparency for consistent glass aesthetic
- Flexbox gap-based spacing in modals for cleaner layout (gap-2 = 8px)
- Compact modal padding (p-3 = 12px) for modern, space-efficient design
Component Refactoring: Modular architecture for bulk operation modals
- Shared components eliminate code duplication across UnlikeModal, UnlikedArchiveModal, and UpscaleAllModal
- PostGrid component handles all grid rendering logic with customizable overlays and badges
- SelectionControls component standardizes select/deselect all buttons
- useShiftSelection hook encapsulates shift-click selection logic
- Unified job queue system eliminates need for individual progress tracking components
- Reduced code duplication and improved reliability through centralized job processing
Animation System: Smooth transitions and effects throughout the UI
- Panel expand/collapse with scale and fade animations
- Tab switching with slide transitions
- Glow effects on button and dropdown hovers
- Progress bar animations with smooth loading indicators
- Configurable animation hooks for reusability
The Pit Improvements: Enhanced video generation API reliability
- Sequential execution prevents parallel API calls
- Streaming response reader monitors progress to 100% completion
- UUID v4 generation for x-xai-request-id header (unique per request)
- Base64-like random string generation for x-statsig-id header (88 chars)
- 403 error detection stops churning immediately with user-friendly error display
- Removed debug console.log statements from PostsStore for cleaner logs
Queue System Refactor: Unified job queue architecture (December 2024)
- Replaced separate upscale and download queue stores with single useJobQueueStore
- All batch operations (upscale, download, unlike, relike, purge) now use unified job system
- Better error handling: likePost/unlikePost return error objects instead of throwing
- Removed useBulkUnlike and useBulkRelike hooks - logic moved to job queue processors
- Modals simplified: no more progress bars or processing states - use job queue indicator
- Fixed React strict mode warnings: wrapped setState calls in setTimeout to avoid synchronous updates in effects
- JobQueueIndicator floating component replaces QueueView tab and panel controls queue button
- Improved reliability with centralized job processing and better state management

Theme Customization

Themes are fully customizable via the public/themes.json configuration file.

Available Themes

Dark: Classic dark theme with neutral grays
Light: Clean light theme with white backgrounds
Dracula: Popular Dracula color scheme with purple/pink accents
Winamp: Retro Winamp-inspired theme with teal backgrounds and green LED text
LimeWire: Nostalgic P2P aesthetic with signature lime green on black
Steam: Valve's iconic dark blue slate with light blue accents
Discord: Authentic Discord dark theme with signature blurple accents
Champagne: Elegant theme with warm brown backgrounds and gold/cream tones
New Year's Eve: Festive theme with deep black backgrounds and bright gold sparkle effects

Creating Custom Themes

Edit public/themes.json
Add or modify theme entries with required color properties
Update src/store/useSettingsStore.ts to add theme name to Theme type
Update src/components/SettingsView.tsx dropdown options
Rebuild: npm run build

See public/THEMES_README.md for detailed theme customization guide.

Commands

Extension Commands

npm install             # Install dependencies
npm run build           # Build extension for production
npm run build:zip       # Build and create zip for Chrome Web Store
npm run zip             # Create zip from existing dist folder
npm run dev             # Development mode with hot reload
npm run type-check      # TypeScript type checking
npm run generate-icons  # Regenerate extension icons
npm run process-bg      # Process background images with theme-specific color tints

iOS Commands

npm run ios:build       # Build extension assets and copy to iOS app
npm run ios:open        # Open Xcode project
npm run ios:deploy      # Build + open Xcode (recommended workflow)
npm run ios:simulator   # Build and run in iPhone 15 simulator
npm run ios:clean       # Clean Xcode build artifacts

Or use the shell script directly:

./scripts/build-ios.sh  # Build extension assets and copy to iOS app

Future Enhancements

License

See LICENSE file.

Name		Name	Last commit message	Last commit date
Latest commit History 312 Commits
archive/userscript		archive/userscript
assets		assets
docs		docs
ios		ios
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
TAILWIND_DEMO.tsx		TAILWIND_DEMO.tsx
eslint.config.js		eslint.config.js
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

ImagineGodMode

Contributors

Features

Technology Stack

Architecture

Modal System

Key Components

Installation

Chrome Extension (Development Mode)

iOS App

Usage

Project Structure

Key Components

Stores (Zustand)

Contexts

Hooks

Components

Architecture

Content Script

Background Service Worker

Message Passing

Storage

Development

Type Checking

Building

Development Server

Migration from Tampermonkey

Key Differences

Notes

Theme Customization

Available Themes

Creating Custom Themes

Commands

Extension Commands

iOS Commands

Future Enhancements

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 25

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages