Add a way for devs to integrate with Cimo so uploading an image in their UI would trigger Cimo to optimize a media file

[bfintal]

Goal

Add a developer integration API so third-party plugins/themes can trigger Cimo optimization when uploading media from their own UI.

Optimization remains pre-upload only (browser-side): Cimo converts the file, then the integrator’s normal upload continues. Available in free and premium (premium converters apply automatically when Premium is loaded).

Out of scope: optimize-by-attachment-ID, bulk replace, server-side Imagick/GD compression.

---

What to implement

1. Public JS API — window.cimo.optimizeFiles

Expose a stable function integrators call with File / FileList objects before they upload:

const results = await window.cimo.optimizeFiles( files, { showProgress: true } )
// results: [ { file: File, metadata: Object|null }, ... ]
// then upload results.map( r => r.file )

Requirements:

• Reuse the same conversion + metadata path as Media Library interceptors (getFileConverter → optimize → saveMetadata).
• Prefer extracting a shared helper so interceptors and the public API do not diverge.
• Optional showProgress (default true) for Cimo’s progress modal; false for headless / host UI progress.
• Respect window.cimoSettings.disableOptimization (return originals).
• Unsupported types pass through unchanged.
• Free + premium; no separate premium entry point.

2. PHP filters for upload selectors

Allow developers to register CSS selectors so Cimo auto-intercepts file inputs / drops in their markup (same behavior as Media Library).

Filter	Purpose
cimo/select_files/allowed_locations	Wrappers for <input type="file"> (change events)
cimo/drop_zone/allowed_locations	Drop targets

• Define core default selectors in PHP.
• Apply the filters, localize results into cimoSettings (e.g. selectFilesAllowedLocations, dropZoneAllowedLocations).
• JS should read those lists when deciding whether to intercept (evaluate at event time, not only once at module load).
• Premium may keep extending via existing internal JS filters (forms / Optimize All Media); the public integrator API for selectors is PHP-only.

Example for integrators:

add_filter( 'cimo/select_files/allowed_locations', function ( $locations ) {
	$locations[] = '.my-plugin-uploader';
	return $locations;
} );

add_filter( 'cimo/drop_zone/allowed_locations', function ( $locations ) {
	$locations[] = '.my-plugin-dropzone';
	return $locations;
} );

3. Public enqueue helper — cimo_enqueue_assets()

• Admin / block editor already enqueue Cimo; frontend (and any custom screen missing assets) needs an explicit call.
• Add cimo_enqueue_assets() wrapping Cimo_Script_Loader::enqueue_cimo_assets() (idempotent).
• Document that integrators must enqueue on pages where they use the API or selector interception.

add_action( 'wp_enqueue_scripts', function () {
	if ( is_page( 'my-upload-form' ) ) {
		cimo_enqueue_assets();
	}
} );

4. Developer docs

Add a short integrator doc (e.g. DEVELOPER.md) covering:

• Enqueue
• window.cimo.optimizeFiles
• PHP location filters
• When to use which approach
• Free vs premium behavior notes (guest frontend: files still optimize; metadata save may skip if not logged in)

---

End state (acceptance)

Integrators can:

1. Call cimo_enqueue_assets() where needed.
2. Call window.cimo.optimizeFiles( files ) then upload the returned files.
3. Or add PHP selectors so a normal file input / drop in their UI is intercepted automatically.

Both free and premium; pre-upload only.

---

Implementation notes (codebase)

• Interceptors today: src/admin/js/media-manager/select-files.js, drop-zone.js
• Converters: src/shared/converters/
• Metadata: src/shared/metadata-saver.js + POST /cimo/v1/metadata
• Enqueue / localize: src/admin/class-script-loader.php
• Premium form selectors / optimizeAllMedia: pro__premium_only/src/compatibility/index.js (internal; keep working)

Related discussion: expose API + PHP filters + enqueue; do not rely on JS addFilter as the public selector API for third parties.