iina-plugin-bookmarks/
├── src/
│   ├── index.ts              # Plugin entry point
│   ├── bookmark-manager.ts   # Core bookmark management (unified orchestrator)
│   ├── bookmark-import-export.ts # Import/export functionality
│   ├── bookmark-persistence.ts   # Storage/persistence layer
│   ├── cloud-storage.ts      # Cloud storage provider
│   ├── cloud-sync-handler.ts # Cloud sync orchestration
│   ├── types.ts              # TypeScript type definitions
│   └── utils/                # Utility functions
│       ├── formatTime.ts     # Time formatting helpers
│       └── validation.ts     # Input validation and sanitization
├── ui/
│   ├── sidebar/              # IINA sidebar UI
│   │   ├── index.html
│   │   ├── index.tsx
│   │   └── app.tsx
│   ├── overlay/              # Media overlay UI
│   │   ├── index.html
│   │   ├── index.tsx
│   │   └── app.tsx
│   ├── window/               # Standalone window UI
│   │   ├── index.html
│   │   ├── index.tsx
│   │   └── app.tsx
│   ├── components/           # Shared React components
│   ├── hooks/                # Custom React hooks
│   ├── utils/                # UI utility functions
│   ├── types.ts              # UI-specific types
│   └── shared.scss           # Shared styles
├── tests/                    # Vitest test suites
├── docs/                     # Fumadocs documentation site
└── ...config files           # ESLint, TypeScript, Parcel, etc.

class BookmarkManager {
  private bookmarks: BookmarkData[];
  private persistence: BookmarkPersistence;
  private importExport: BookmarkImportExport;
  private cloudSync: CloudSyncHandler;

  constructor(dependencies: IINARuntimeDependencies)

  // Bookmark operations
  addBookmark(title?: string, timestamp?: number, filepath?: string): void
  deleteBookmark(id: string): void
  updateBookmark(id: string, updates: BookmarkUpdatableFields): void
  jumpToBookmark(id: string): void

  // Data management
  exportBookmarks(format: 'json' | 'csv'): string
  importBookmarks(data: BookmarkData[], options: ImportOptions): ImportResult

  // Cloud sync
  syncToCloud(provider: 'google-drive' | 'dropbox', credentials: CloudCredentials): Promise<void>

  // UI management
  private setupWebUI(): void
  private handleUIMessage(message: UIMessage, source: UISource): void
}

class BookmarkPersistence {
  load(): BookmarkData[]
  save(bookmarks: BookmarkData[]): void
  recoverFromBackup(): BookmarkData[]
}

class BookmarkImportExport {
  import(existing: BookmarkData[], raw: unknown[], options?: ImportOptions): ImportResult
  exportJSON(bookmarks: BookmarkData[]): string
  exportCSV(bookmarks: BookmarkData[]): string
}

class CloudSyncHandler {
  sync(provider: CloudStorageManager, bookmarks: BookmarkData[]): Promise<BookmarkData[]>
  upload(provider: CloudStorageManager, bookmarks: BookmarkData[]): Promise<void>
  download(provider: CloudStorageManager): Promise<BookmarkData[]>
}

interface IINARuntimeDependencies {
  core: IINACore;           // Media playback control
  event: IINAEventBus;      // Event system
  preferences: IINAPreferences; // Persistent storage
  menu: IINAMenu;           // Menu integration
  overlay: IINAUIAPI;       // Overlay UI
  sidebar: IINAUIAPI;       // Sidebar UI
  standaloneWindow: IINAUIAPI; // Window UI
  http: IINAHttp;           // Network requests
  console: IINAConsole;     // Logging
}

class BookmarkManager {
  constructor(dependencies: IINARuntimeDependencies) {
    this.deps = dependencies;
    // Inject dependencies into sub-components
    this.persistence = new BookmarkPersistence(dependencies.preferences, dependencies.console);
    this.importExport = new BookmarkImportExport(dependencies.console);
    // ...
  }
}

type UIMessage = {
  type: 'ADD_BOOKMARK' | 'DELETE_BOOKMARK' | 'JUMP_TO_BOOKMARK' | /* ... */;
  payload: Record<string, unknown>;
};

private handleUIMessage(message: UIMessage, source: UISource): void {
  switch (message.type) {
    case 'ADD_BOOKMARK':
      this.addBookmark(/* ... */);
      break;
    // ...
  }
}

graph TD
    A[UI: User clicks Add Bookmark] --> B[UI sends ADD_BOOKMARK message]
    B --> C[BookmarkManager receives message]
    C --> D[Get current file path from IINA core]
    D --> E[Get current timestamp from player]
    E --> F[Create BookmarkData with auto-detected metadata]
    F --> G[Add to bookmarks array]
    G --> H[BookmarkPersistence saves to storage]
    H --> I[Send updated bookmarks to all UIs]

graph TD
    A[User initiates cloud sync] --> B[CloudSyncHandler.sync called]
    B --> C[Download existing bookmarks from cloud]
    C --> D[Merge local + cloud bookmarks]
    D --> E{Conflicts?}
    E -->|Yes| F[Keep both versions with conflict markers]
    E -->|No| G[Upload merged bookmarks to cloud]
    F --> G
    G --> H[Update local storage]
    H --> I[Return merged bookmarks to UI]

graph TD
    A[User selects file to import] --> B[BookmarkImportExport.import called]
    B --> C[Validate bookmark array structure]
    C --> D{Duplicate handling mode?}
    D -->|skip| E[Skip duplicates by filepath+timestamp]
    D -->|replace| F[Replace matching bookmarks]
    D -->|merge| G[Keep both versions]
    E --> H[Return import result with stats]
    F --> H
    G --> H
    H --> I[BookmarkManager updates bookmarks]
    I --> J[Save to persistence]

interface BookmarkData {
  id: string;
  title: string;
  timestamp: number;
  filePath: string;
  description?: string;
  tags: string[];
  createdAt: Date;
  updatedAt: Date;
}

// Strip HTML tags to prevent injection
import { stripHtmlTags } from './utils/validation';

const sanitizedTitle = stripHtmlTags(userInput);

// Validate bookmark array structure
const validated = validateBookmarkArray(rawBookmarks, console);

function sanitizeCsvCell(value: string): string {
  if (/^[=+\-@\t\r]/.test(value)) {
    return "'" + value; // Prefix dangerous characters
  }
  return value;
}

class BookmarkPersistence {
  save(bookmarks: BookmarkData[]): void {
    // Save to backup key before overwriting
    preferences.set('bookmarks_backup', JSON.stringify(bookmarks));
    preferences.set('bookmarks', JSON.stringify(bookmarks));
  }

  recoverFromBackup(): BookmarkData[] {
    // Restore from backup if main storage is corrupted
    return JSON.parse(preferences.get('bookmarks_backup') || '[]');
  }
}

// ui/hooks/useDebounce.ts
const debouncedSearchTerm = useDebounce(searchTerm, 300);

class CloudSyncHandler {
  private syncInProgress = false;
  private readonly SYNC_TIMEOUT = 60000; // 60 seconds

  async sync(/* ... */): Promise<BookmarkData[]> {
    if (this.syncInProgress) {
      throw new Error('Sync already in progress');
    }
    // Implement timeout guard...
  }
}

// Only parse when needed
const bookmarks = JSON.parse(preferences.get('bookmarks') || '[]');

describe('BookmarkImportExport', () => {
  it('should skip duplicates when importing', () => {
    const existing = [{ id: '1', filepath: '/test.mp4', timestamp: 100, /* ... */ }];
    const toImport = [{ filepath: '/test.mp4', timestamp: 100, /* ... */ }];

    const result = importExport.import(existing, toImport, {
      duplicateHandling: 'skip'
    });

    expect(result.imported).toBe(0);
    expect(result.skipped).toBe(1);
  });
});

describe('Cloud Sync Integration', () => {
  it('should merge local and cloud bookmarks', async () => {
    const mockCloudStorage = createMockCloudStorageManager();
    const handler = new CloudSyncHandler(mockCloudStorage, mockConsole);

    const local = [/* local bookmarks */];
    const merged = await handler.sync(mockCloudStorage, local);

    expect(merged.length).toBeGreaterThan(local.length);
  });
});

describe('ErrorBoundary', () => {
  it('should catch errors and display fallback UI', () => {
    const ThrowError = () => { throw new Error('Test error'); };

    render(
      <ErrorBoundary>
        <ThrowError />
      </ErrorBoundary>
    );

    expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();
  });
});

import { stripHtmlTags } from './utils/validation';

// Strip HTML/script tags from all user-provided strings
const sanitized = {
  title: stripHtmlTags(userInput.title),
  description: userInput.description ? stripHtmlTags(userInput.description) : undefined,
  tags: userInput.tags.map(stripHtmlTags)
};

// Prefix dangerous characters with single quote
function sanitizeCsvCell(value: string): string {
  if (/^[=+\-@\t\r]/.test(value)) {
    return "'" + value;
  }
  return value;
}