dragonflight/services/premiere-plugin/PLUGIN_FILES.txt

WILD DRAGON MAM - PREMIERE PRO CEP PANEL PLUGIN
================================================

This directory contains a complete, production-ready Premiere Pro CEP 11.0 panel plugin for the Wild Dragon MAM system.

FILE STRUCTURE AND PURPOSES
============================

CSXS/manifest.xml
-----------------
- CEP extension manifest file required by Adobe
- Defines extension ID: net.wilddragon.dragonflight.panel
- Specifies Premiere Pro (PPRO) version compatibility: 22.0 to 99.9
- Sets panel dimensions: 400x700 (responsive 350-500px width)
- Declares CEP version 11.0 requirement
- Defines extension metadata (author, license, UI type)

css/styles.css
--------------
- Complete dark theme styling matching Wild Dragon branding
- Color scheme: #0f0f1e (primary bg), #1a1a2e (secondary bg), #e94560 (accent)
- Responsive grid layout for asset thumbnails
- Styled form inputs, buttons, scrollbars, and animations
- Connection status indicator with pulse animation
- Asset card grid with hover effects and selection states
- Details panel sidebar styling
- Progress bar and message styling
- Dark mode scrollbar styling
- Mobile-responsive layout adjustments for panel resizing

js/CSInterface.js
-----------------
- Adobe CEP interface shim/polyfill
- Implements CSInterface class with key methods:
  * evalScript() - Execute ExtendScript in Premiere Pro context
  * getSystemPath() - Get system paths (temp, documents, app data)
  * requestOpenExtension() - Open other extensions
  * addEventListener() - Register for CEP events
  * dispatchEvent() - Send events
- SystemPath enum for common directories
- CSXSEvent class for event communication
- Note: Production use should include Adobe's official CSInterface.js

js/main.js
----------
- Main panel logic and state management
- Features:
  * Server connection with URL persistence to localStorage
  * Asset browsing with lazy-loaded thumbnails
  * Search functionality (debounced 300ms)
  * Project filtering
  * Asset selection and detail display
  * Proxy file downloading with progress tracking
  * Premiere Pro project import via ExtendScript
  * Error/success message display
  * Responsive UI updates
- API integration:
  * GET /api/health - Connection check
  * GET /api/projects - Project list
  * GET /api/assets - Asset list with pagination/search
  * GET /api/assets/{id} - Asset details
  * POST /api/assets/{id}/download - Signed download URL
- Utility functions:
  * formatDuration() - Convert seconds to timecode
  * formatFileSize() - Format bytes to human-readable
  * debounce() - Debounce search/filter operations

jsx/premiere.jsx
----------------
- Adobe ExtendScript code running in Premiere Pro process
- Core functions:
  * importFileToProject(filePath) - Import file to project
  * getActiveSequence() - Get active sequence metadata
  * insertClipToSequence(filePath, trackIndex) - Insert to timeline
  * getProjectPath() - Get project file path
  * getSequenceTracks() - List video tracks
  * getPlayheadPosition() - Get current timecode
  * getProjectInfo() - Get project metadata
  * exportSequence(path, preset) - Export sequence
- Helper functions:
  * findProjectItemByName() - Recursive item search
  * pad() - Zero-pad numbers for timecode
- All functions return JSON for easy parsing

index.html
----------
- Main panel HTML structure
- Sections:
  1. Connection bar: Server URL input + Connect button + Status indicator
  2. Search/filter area: Search input + Project dropdown
  3. Content area with two columns:
     - Asset grid: Scrollable card-based layout for thumbnails
     - Details panel: Metadata display for selected asset
  4. Progress indicator: Download/import progress bar
  5. Action bar: Import + Import All buttons
- References:
  * css/styles.css - Panel styling
  * js/CSInterface.js - Adobe interface
  * js/main.js - Panel logic
  * jsx/premiere.jsx - Premiere Pro integration

.debug
------
- CEP debug configuration file
- Specifies Premiere Pro (PPRO) debug port: 7737
- Enables debugger connection for development
- Required for unsigned extensions in debug mode

README.md
---------
- Complete installation and usage guide
- Features overview
- Step-by-step installation for Windows and macOS
- Registry/plist settings for unsigned extensions
- Usage instructions (connect, browse, search, import)
- Configuration options
- File structure reference
- API endpoint documentation
- ExtendScript function reference
- Troubleshooting guide
- Performance notes
- Security considerations
- Requirements

INTEGRATION WITH WILD DRAGON MAM
=================================

The plugin expects the following MAM API structure:

Endpoints:
  GET /api/health
    Returns: {"status": "ok"}

  GET /api/projects
    Returns: {"projects": [{"id": "...", "name": "..."}, ...]}

  GET /api/assets?offset=0&limit=50&search=query&project_id=id
    Returns: {
      "assets": [{
        "id": "...",
        "filename": "...",
        "codec": "...",
        "resolution": "...",
        "fps": 24,
        "duration": 86400,
        "file_size": 1000000,
        "status": "ready",
        "tags": ["tag1", "tag2"],
        "thumbnail_url": "...",
        "file_id": "...",
        "proxy_file_id": "..."
      }, ...],
      "total": 100
    }

  GET /api/assets/{id}
    Returns: Full asset object (same structure as above)

  POST /api/assets/{id}/download
    Returns: {"signed_url": "https://s3.../path?signature=..."}

  POST /api/assets/{id}/proxies/{proxy_id}/download
    Returns: {"signed_url": "https://s3.../path?signature=..."}

PREMIERE PRO REQUIREMENTS
=========================

- Version 22.0 or later (2022 or later)
- CEP 11.0 compatible
- JavaScript engine must be enabled
- ExtendScript execution must be enabled

DEPLOYMENT INSTRUCTIONS
=======================

Use the installer artifacts from the latest release:
  https://forge.wilddragon.net/zgaetano/dragonflight/releases

  Windows: dragonflight-premiere-panel-<version>-windows-setup.exe
           Double-click. Installer copies bundle to
           %APPDATA%\Adobe\CEP\extensions\net.wilddragon.dragonflight.panel\,
           sets PlayerDebugMode=1 for CSXS 8..13, and removes any legacy
           com.wilddragon.mam.panel install.

  macOS:   dragonflight-premiere-panel-<version>.zxp
           Install with Anastasiy's ZXP Installer
           (https://install.anastasiy.com/), then run once in Terminal:
             defaults write com.adobe.CSXS.11 PlayerDebugMode 1

Restart Premiere Pro, then: Window > Extensions > Wild Dragon MAM

To build the installers locally, see services/premiere-plugin/build/README.md.

DEVELOPMENT NOTES
=================

- The plugin uses Adobe's CEP 11.0 specification
- Responsive design supports panel widths 350-500px
- All API calls use standard fetch() with JSON
- ExtendScript communication is handled via CSInterface.evalScript()
- localStorage is used for persisting server URL
- Asset grid uses CSS Grid with auto-fill for responsive layout
- Lazy loading is used for thumbnails to improve performance
- Progress tracking uses a simple percentage-based bar
- Error messages auto-dismiss after 5 seconds

VERSION HISTORY
===============

1.0.0 (April 2026)
- Initial release
- Complete asset browser with search/filter
- Proxy import functionality
- Progress tracking
- Dark theme UI
- Signed URL support for S3 downloads
- Premiere Pro 22.0+ compatibility