highjourney

Imported from harsh2204/highjourney (AGENTS.md). Install upstream with npx skills add harsh2204/highjourney. Copyright stays with the author.

AGENTS.md - Highjourney Extension Knowledge Base

Project Overview

Highjourney is a browser extension (Chrome/Edge) designed to organize and track Midjourney scene generation workflows for music video production. It provides a complete CRUD (Create, Read, Update, Delete) system for managing JSON-based timeline projects with scenes and animation entries.

Core Purpose

• Import JSON project files containing scene definitions
• Track generation status for each scene and timeline entry
• Manage timelines with full CRUD operations
• Export updated projects back to JSON
• Provide visual progress tracking across all scenes

Architecture

Technology Stack

• Runtime: Bun (v1.3.3+)
• Language: TypeScript
• UI Framework: React 18.3
• Build Tool: Bun's native bundler
• Extension Format: Chrome Manifest V3
• Storage: chrome.storage.local API

Project Structure

highjourney/
├── src/
│   ├── background/
│   │   └── service-worker.ts    # Background service worker (badge updates)
│   ├── popup/
│   │   ├── popup.html           # Popup HTML entry point
│   │   ├── popup.tsx             # Main popup UI (React)
│   │   └── popup.css             # Popup styles
│   ├── options/
│   │   ├── options.html          # Options page HTML
│   │   ├── options.tsx           # Options page (project import/management)
│   │   └── options.css            # Options styles
│   ├── content/
│   │   └── discord.ts            # Content script (placeholder, not used)
│   ├── shared/
│   │   ├── types.ts              # TypeScript type definitions
│   │   ├── storage.ts            # Chrome storage utilities
│   │   ├── parser.ts             # JSON parsing and validation
│   │   ├── timeline-crud.ts      # CRUD operations for timelines
│   │   └── utils.ts              # Helper functions (progress, clipboard, etc.)
│   └── components/
│       ├── ProjectSelector.tsx   # Project dropdown selector
│       ├── SceneCard.tsx         # Scene card with progress bar
│       ├── StatusBadge.tsx       # Status indicator badge
│       └── TimelineEditor.tsx    # Full timeline CRUD editor
├── public/
│   └── icons/                    # Extension icons (16x16, 48x48, 128x128)
├── dist/                         # Built extension (generated)
├── manifest.json                 # Extension manifest
├── build.config.ts               # Bun build configuration
├── package.json                  # Dependencies and scripts
└── tsconfig.json                 # TypeScript configuration

Data Models

Core Types

Project

interface Project {
  project_name: string;
  total_duration: string;  // e.g., "3:38"
  global_settings: {
    model: string;         // e.g., "--niji 7"
    aspect_ratio: string;  // e.g., "--ar 16:9"
  };
  scenes: Scene[];
}

Scene

interface Scene {
  scene_number: number;
  title: string;
  duration: string;        // e.g., "12s"
  base_image_prompt: string;  // Full Midjourney prompt
  timeline: TimelineEntry[];
}

TimelineEntry

interface TimelineEntry {
  type: 'animation_base' | 'extension_1' | 'extension_2';
  start: string;           // e.g., "0s", "5s"
  end: string;             // e.g., "5s", "9s"
  direction: string;       // Animation description
  motion: 'low' | 'high';  // Motion intensity
}

Storage Structure

interface StoredProject {
  metadata: ProjectMetadata;
  originalScenes: Scene[];  // Full scene data for editing
  scenes: {
    [sceneNumber: number]: SceneStatus;  // Status tracking
  };
}

interface SceneStatus {
  baseImage: ImageStatus;
  extension1: ImageStatus;
  extension2: ImageStatus;
}

interface ImageStatus {
  status: 'pending' | 'in_progress' | 'completed' | 'failed';
  url?: string;           // Generated image URL (optional)
  timestamp?: number;     // Completion timestamp
}

Key Features

1. Project Import & Management

• Location: src/options/options.tsx
• Import JSON project files via file input
• Validate JSON structure using parser.ts
• Store projects in chrome.storage.local
• Support multiple projects with project selector
• Delete projects

2. Status Tracking

• Location: src/shared/storage.ts
• Track status for each timeline entry (baseImage, extension1, extension2)
• Four states: pending, in_progress, completed, failed
• Store optional image URLs and timestamps
• Calculate progress percentages

3. Timeline CRUD Operations

• Location: src/shared/timeline-crud.ts
• Create: Add new scenes and timeline entries
• Read: Retrieve project data and status
• Update: Edit scenes, entries, and project metadata
• Delete: Remove scenes and entries (auto-renumbers scenes)
• Export: Generate JSON from stored project data

4. Popup Interface

• Location: src/popup/popup.tsx
• Project selector dropdown
• Progress overview (X/Y entries, percentage)
• Scene list with expandable cards
• Progress bars in collapsed state (200px fixed width, right-aligned)
• Base prompt display when expanded
• Copy prompts to clipboard
• Mark entries as in progress/complete

5. Timeline Editor

• Location: src/components/TimelineEditor.tsx
• Full CRUD interface for timelines
• Edit project metadata (name, duration, model, aspect ratio)
• Create/edit/delete scenes
• Create/edit/delete timeline entries
• Export project to JSON file download
• Inline editing with save/cancel

6. Background Service Worker

• Location: src/background/service-worker.ts
• Updates extension badge with progress percentage
• Monitors storage changes
• Calculates overall project progress

Build System

Build Configuration

• File: build.config.ts
• Uses Bun's native build() function
• Builds each entry point separately:
  • Background service worker → dist/background/
  • Popup → dist/popup/
  • Options page → dist/options/
• Copies HTML files and static assets
• Generates source maps for debugging

Build Commands

# Production build
bun run build

# Watch mode (auto-rebuild on changes)
bun run dev

# Type checking only
bun run typecheck

Manifest Paths

Important: Manifest paths are relative to the dist/ folder:

• popup/popup.html (not dist/popup/popup.html)
• background/service-worker.js
• options/options.html
• icons/icon*.png

Storage System

Storage Key

All data stored under: highjourney_data

Storage Structure

{
  projects: {
    [projectId: string]: StoredProject
  },
  currentProjectId?: string
}

Key Functions

• saveProject(project: Project): Promise<string> - Import and save project
• getProject(projectId: string): Promise<StoredProject> - Get project data
• updateSceneStatus(...) - Update entry status
• getAllProjects() - List all projects
• setCurrentProjectId(id) - Set active project

UI Components

SceneCard

• Location: src/components/SceneCard.tsx
• Displays scene with title, duration, and progress
• Collapsed state shows progress bar (200px, right-aligned)
• Expanded state shows:
  • Base image prompt (highlighted blue box)
  • Timeline entries with status badges
  • Copy prompt buttons
  • Mark complete/in progress buttons

TimelineEditor

• Location: src/components/TimelineEditor.tsx
• Full-screen editor interface
• Project metadata editor
• Scene list with inline editing
• Timeline entry management
• Export to JSON functionality

ProjectSelector

• Location: src/components/ProjectSelector.tsx
• Dropdown to select current project
• Auto-loads on mount
• Updates current project in storage

StatusBadge

• Location: src/components/StatusBadge.tsx
• Color-coded status indicators
• Colors: green (completed), blue (in progress), red (failed), gray (pending)

JSON Format

Expected Input Format

{
  "project_name": "Warm Mezcal Music Video",
  "total_duration": "3:38",
  "global_settings": {
    "model": "--niji 7",
    "aspect_ratio": "--ar 16:9"
  },
  "scenes": [
    {
      "scene_number": 1,
      "title": "The Valley",
      "duration": "12s",
      "base_image_prompt": "Wide shot of a rustic fantasy village... --ar 16:9 --niji 7",
      "timeline": [
        {
          "type": "animation_base",
          "start": "0s",
          "end": "5s",
          "direction": "Camera slowly pans right...",
          "motion": "low"
        },
        {
          "type": "extension_1",
          "start": "5s",
          "end": "9s",
          "direction": "Continue panning right...",
          "motion": "low"
        },
        {
          "type": "extension_2",
          "start": "9s",
          "end": "12s",
          "direction": "The sun peaks over...",
          "motion": "low"
        }
      ]
    }
  ]
}

Validation

• Location: src/shared/parser.ts
• Validates project structure
• Checks required fields
• Validates scene and timeline entry types
• Throws descriptive errors on invalid data

Development Workflow

Setup

1. Install Bun: curl -fsSL https://bun.sh/install | bash
2. Install dependencies: bun install
3. Build extension: bun run build
4. Load in Chrome:
   • Open chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked"
   • Select dist/ folder

Development

1. Run watch mode: bun run dev
2. Make changes to source files
3. Build auto-runs on file changes
4. Reload extension in Chrome (click refresh icon)
5. Test changes

Testing Checklist

• Import JSON project file
• View project in popup
• See progress bars in collapsed scenes
• Expand scenes to see base prompts
• Copy prompts to clipboard
• Mark entries as complete/in progress
• Open timeline editor
• Edit project metadata
• Create/edit/delete scenes
• Create/edit/delete timeline entries
• Export project to JSON

Important Implementation Details

Progress Calculation

• Each scene has 3 entries: baseImage, extension1, extension2
• Progress = (completed entries / total entries) * 100
• Calculated per-scene and project-wide

Scene Numbering

• Scenes are auto-renumbered when deleted
• Scene numbers start at 1
• Timeline entries map to status by index: [0] = baseImage, [1] = extension1, [2] = extension2

Prompt Generation

• Base prompt comes from scene.base_image_prompt
• Timeline entry prompts combine base + direction
• Function: generatePrompt(scene, entry) in parser.ts

Storage Persistence

• All data persists in chrome.storage.local
• Survives browser restarts
• Can be cleared via Chrome DevTools → Application → Storage

Known Limitations

1. No Discord Integration: Content script exists but is not used. Discord integration was removed from manifest.
2. No Image Upload: Image URLs must be manually entered (no automatic extraction)
3. Single Browser: Data doesn't sync across browsers/devices
4. No Collaboration: No multi-user support
5. Manual Workflow: Requires manual Midjourney interaction (no API automation)

Future Enhancements (Not Implemented)

• Direct Discord bot integration
• Automatic image URL extraction from Discord messages
• Batch prompt generation
• Image comparison/viewer
• Export to video editing software formats
• Cloud sync across devices
• Collaboration features
• Keyboard shortcuts
• Search/filter scenes

Troubleshooting

Extension Won't Load

• Check manifest.json paths are relative to dist/
• Verify all files exist in dist/
• Check browser console for errors

Build Errors

• Ensure Bun is installed: bun --version
• Clear dist/ and rebuild: rm -rf dist && bun run build
• Check TypeScript errors: bun run typecheck

Storage Issues

• Open DevTools → Application → Storage → Local Storage
• Check highjourney_data key exists
• Clear storage to reset extension state

UI Not Updating

• Reload extension in chrome://extensions/
• Check browser console for React errors
• Verify storage operations are completing

Key Files Reference

Code Patterns

Storage Pattern

// Get storage
const data = await getStorage();

// Modify data
data.projects[projectId] = newProject;

// Save storage
await setStorage(data);

Status Update Pattern

await updateSceneStatus(
  projectId,
  sceneNumber,
  'baseImage',  // or 'extension1', 'extension2'
  'completed',  // or 'in_progress', 'pending', 'failed'
  imageUrl  // optional
);

Progress Calculation Pattern

const progress = calculateProgress(project.scenes);
// Returns: { completed: 15, total: 57, percentage: 26 }

Notes for Future Agents

1. Always rebuild after changes: Run bun run build before testing
2. Check manifest paths: They must be relative to dist/, not include dist/ prefix
3. Storage is async: All storage operations return Promises
4. React components: Use hooks (useState, useEffect) for state management
5. Type safety: All types are in src/shared/types.ts - use them consistently
6. Progress bars: Fixed 200px width, right-aligned with collapse indicator
7. Base prompts: Always visible when scene is expanded, in blue highlighted box
8. Scene numbering: Starts at 1, auto-renumbers on delete

Quick Reference Commands

# Install dependencies
bun install

# Build extension
bun run build

# Watch mode
bun run dev

# Type check
bun run typecheck

# Clean build
rm -rf dist && bun run build

Last Updated: January 2025 Version: 1.0.0 Maintainer: See project README