Developer Integration API

[Arukuen]

fixes #65

Adds developer integration support for Cimo pre-upload optimization.

• Exposes window.cimo.optimizeFiles(files, { showProgress }) so plugins/themes can optimize File / FileList objects before running their own upload flow.
• Adds PHP selector filters so third-party upload UIs can opt into Cimo’s automatic file-input/drop-zone interception.
• Adds cimo_enqueue_assets() so custom frontend or non-standard screens can explicitly load Cimo assets.
• Adds DEVELOPER.md with integration examples and behavior notes.
  Behavior

How To Test

1. Test Frontend Enqueue

In a custom PHP plugin, enqueue Cimo assets on a frontend page:

add_action( 'wp_enqueue_scripts', function () {
	if ( function_exists( 'cimo_enqueue_assets' ) ) {
		cimo_enqueue_assets();
	}
} );

Visit the frontend page and run this in the browser console:

console.log(window.cimoSettings);
console.log(window.cimo);
console.log(window.cimo?.optimizeFiles);

Expected:

• window.cimoSettings is available.
• window.cimo is available.
• window.cimo.optimizeFiles is a function.

2. Test PHP Selector Filters

In the custom PHP plugin, add selector locations:

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;
} );

Visit the frontend page and run:

console.log(window.cimoSettings.selectFilesAllowedLocations);
console.log(window.cimoSettings.dropZoneAllowedLocations);

Expected:

• window.cimoSettings.selectFilesAllowedLocations includes .my-plugin-uploader.
• window.cimoSettings.dropZoneAllowedLocations includes .my-plugin-dropzone.

3. Test Automatic File Input Interception

Add this Custom HTML to the frontend page:

<div class="my-plugin-uploader">
	<input type="file" accept="image/*" />
</div>

Select an image from the input.

Expected:

• Cimo intercepts the file input because .my-plugin-uploader was added through the PHP filter.
• The image should be converted to webp.

4. Test window.cimo.optimizeFiles

Run this in the frontend browser console:

(async () => {
	const input = document.createElement('input');
	input.type = 'file';
	input.accept = 'image/*';

	input.onchange = async () => {
		const results = await window.cimo.optimizeFiles(input.files, {
			showProgress: true,
		});

		console.log('Optimized results:', results);

		console.table(results.map(({ file, metadata }) => ({
			name: file.name,
			type: file.type,
			size: file.size,
			hasMetadata: !!metadata,
		})));
	};

	input.click();
})();

Expected:

• Cimo opens the progress modal when applicable (large image).
• results is an array of { file, metadata }.
• Upload code should use results.map(result => result.file).

Summary by CodeRabbit

• New Features

  • Added a public browser API for optimizing files before upload.
  • Automatically optimizes files from configured file-selection fields and drag-and-drop areas.
  • Added configurable allowed locations to control which upload areas are handled.
  • Added support for optimizing multiple files and receiving optimization results for each file.
  • Centralized optimization progress, error handling, and metadata processing.

• Documentation

  • Added WordPress integration guidance covering asset loading, browser API usage, selector configuration, supported workflows, and current limitations.

[coderabbitai]

Warning

Review limit reached

Next included review available in 20 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 9d1e8788-5145-4bec-bb03-f78cc91a6935

📥 Commits

Reviewing files that changed from the base of the PR and between 0cdc246 and 4c744b2.

📒 Files selected for processing (7)

• DEVELOPER.md
• cimo.php
• e2e/fixtures/mu-plugins/cimo-e2e-dev-api.php
• e2e/readme.md
• e2e/tests/developer-api.spec.ts
• playwright.config.js
• readme.txt

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 62d5c20d-b6ea-4636-801b-f03f77b5b31f

📥 Commits

Reviewing files that changed from the base of the PR and between cff1995 and 0cdc246.

📒 Files selected for processing (1)

• cimo.php

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Cimo adds a guarded asset-enqueue helper, a window.cimo.optimizeFiles() API, PHP-configurable selector interception, and shared optimization handling for direct and intercepted uploads. Integration guidance is documented in DEVELOPER.md.

Changes

Developer integration

Layer / File(s)	Summary
PHP integration and selector localization cimo.php, src/admin/class-script-loader.php	Adds cimo_enqueue_assets() and localizes filtered, sanitized file-input and drop-zone selector lists.
Shared optimization pipeline and public API src/admin/js/optimize-files.js, src/admin/js/public-api.js, src/admin/js/index.js	Adds shared file optimization with conversion, metadata persistence, progress handling, cancellation, and bypass behavior, then exposes it as window.cimo.optimizeFiles.
Selector matching and interceptor integration src/admin/js/media-manager/allowed-locations.js, src/admin/js/media-manager/select-files.js, src/admin/js/media-manager/drop-zone.js	Centralizes selector normalization and matching, and routes file selection and drop-zone processing through the shared optimization helper.
Integration documentation DEVELOPER.md	Documents enqueueing, the public optimization API, selector filters, free and premium behavior, and pre-upload limitations.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Integrator
  participant window.cimo.optimizeFiles
  participant optimizeFileConverters
  participant UploadControl
  Integrator->>window.cimo.optimizeFiles: provide files before upload
  window.cimo.optimizeFiles->>optimizeFileConverters: resolve converters and optimize
  optimizeFileConverters-->>window.cimo.optimizeFiles: return optimized files and metadata
  window.cimo.optimizeFiles-->>Integrator: return results
  Integrator->>UploadControl: upload result files

Loading

Suggested reviewers: bfintal

Merge Risk: ⚪ Minimal · up to 0cdc2

The integration API, asset loading, selector interception, optimization fallback, progress handling, and metadata sequencing are consistent with the documented behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a developer integration API for Cimo.
Linked Issues check	✅ Passed	Issue #65 is a coding issue, and the reviewed changes implement its stated requirements. window.cimo.optimizeFiles accepts normalized file inputs and returns { file, metadata } results. It uses `g…
Out of Scope Changes check	✅ Passed	The reviewed changes stay within Issue #65. The interceptor refactoring, selector helpers, shared optimization helper, enqueue wrapper, and DEVELOPER.md directly support the requested integration AP…
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 4 files.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/dev-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🤖 Pull request artifacts

file	commit
pr67-cimo-67-merge.zip	4c744b2

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@DEVELOPER.md`:
- Around line 12-16: Update the documentation around the cimo_enqueue_assets
example to explicitly require registering selector filters before enqueueing
Cimo assets. Ensure the documented order places all selector filter registration
ahead of the wp_enqueue_scripts hook that calls cimo_enqueue_assets(), so
localized selectors use the custom values.
- Around line 24-28: Update the optimizeFiles example in DEVELOPER.md to wrap
the await and subsequent filesToUpload mapping in an async function, preserving
the existing behavior and making the snippet valid in a classic script.

In `@src/admin/js/public-api.js`:
- Around line 5-7: Update the comment above the public optimizeFiles assignment
to document that the API returns an array of objects shaped as {file, metadata},
with file as a File and metadata possibly null, rather than raw File objects.
Keep the window.cimo.optimizeFiles assignment unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b5658e52-1162-41c3-9c0c-12918c9f32c5

📥 Commits

Reviewing files that changed from the base of the PR and between 6041597 and 89e4b77.

📒 Files selected for processing (9)

• DEVELOPER.md
• cimo.php
• src/admin/class-script-loader.php
• src/admin/js/index.js
• src/admin/js/media-manager/allowed-locations.js
• src/admin/js/media-manager/drop-zone.js
• src/admin/js/media-manager/select-files.js
• src/admin/js/optimize-files.js
• src/admin/js/public-api.js