feat(media-folder-pro): add virtual folder system for WordPress media library

Custom WordPress plugin that replaces the default flat media library with
a structured folder view. Features: hierarchical folders via custom taxonomy,
sidebar folder tree, drag & drop, modal integration with Elementor/builders,
bulk assign, upload auto-assign, toast notifications.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.paul/phases/03-media-modal/03-01-SUMMARY.md

@@ -0,0 +1,121 @@
+---
+phase: 03-media-modal
+plan: 01
+subsystem: media
+tags: [wordpress, media-modal, backbone-extend, upload-hook, wp-uploader]
+
+requires:
+  - phase: 02-media-library-grid
+    provides: MFP_Media_Query filter, mfp_assign_media endpoint
+provides:
+  - Folder dropdown in wp.media modal
+  - Modal filtering via backbone props
+  - Auto-assign uploads to active folder
+  - mfp_upload_to_folder lightweight endpoint
+affects: [04-polish-ux]
+
+tech-stack:
+  added: []
+  patterns: [wp.media.view.AttachmentsBrowser.extend, wp.Uploader.queue hook, modal close hook, foldersCache pattern]
+
+key-files:
+  created:
+    - wp-content/plugins/media-folder-pro/assets/js/modal-integration.js
+  modified:
+    - wp-content/plugins/media-folder-pro/includes/class-ajax-handler.php
+    - wp-content/plugins/media-folder-pro/assets/js/folder-tree.js
+    - wp-content/plugins/media-folder-pro/assets/css/admin.css
+    - wp-content/plugins/media-folder-pro/media-folder-pro.php
+
+key-decisions:
+  - "Extend AttachmentsBrowser.prototype.createToolbar — call original then add dropdown"
+  - "Flat <select> dropdown instead of full tree in modal — lightweight, less DOM"
+  - "Hierarchical indent via em-space prefix in option labels"
+  - "Cache folders per modal open, invalidate on close"
+  - "Dual upload hook: wp.Uploader.queue + Attachment.sync override for reliability"
+  - "enqueue_modal_assets on all admin pages except upload.php (handled separately)"
+
+patterns-established:
+  - "mfp-folder-changed CustomEvent for cross-module sync"
+  - "Modal close → foldersCache invalidation + counter refresh"
+  - "Inline script registration (wp_register_script false) for mfpData on non-media pages"
+
+duration: ~10min
+started: 2026-03-28
+completed: 2026-03-28
+---
+
+# Phase 3 Plan 01: Media Upload Modal Integration Summary
+
+**Folder dropdown filter in wp.media modal with auto-assign on upload, using AttachmentsBrowser.extend and wp.Uploader hooks.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~10min |
+| Tasks | 2 completed |
+| Files created | 1 |
+| Files modified | 4 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Dropdown folderow widoczny w modalu | Pass | AttachmentsBrowser toolbar extended with select |
+| AC-2: Filtrowanie mediow w modalu | Pass | library.props.set via same MFP_Media_Query filter |
+| AC-3: Przypisanie folderu przy uploadzie | Pass | wp.Uploader.queue + Attachment.sync hooks |
+
+## Accomplishments
+
+- Extended `wp.media.view.AttachmentsBrowser.createToolbar` to inject folder dropdown
+- Hierarchical folder list with em-space indent and counts in dropdown options
+- Upload auto-assign via dual hooks (wp.Uploader.queue change:status + Attachment.sync)
+- `mfp_upload_to_folder` lightweight single-file endpoint
+- Modal close triggers `mfp-folder-changed` event → folder-tree.js refreshes counters
+- `enqueue_modal_assets()` loads on all admin pages where media-views is present
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `assets/js/modal-integration.js` | Created | Modal dropdown, filtering, upload auto-assign, close sync |
+| `includes/class-ajax-handler.php` | Modified | Added mfp_upload_to_folder endpoint |
+| `assets/js/folder-tree.js` | Modified | Added mfp-folder-changed listener |
+| `assets/css/admin.css` | Modified | Modal dropdown styles |
+| `media-folder-pro.php` | Modified | enqueue_modal_assets + modal JS enqueue on upload.php |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Extend prototype vs filter hook | More reliable, works across all modal instances | Robust integration |
+| Flat select vs tree in modal | Modal space is limited, select is native WP pattern | Consistent UX |
+| Dual upload hooks | Different WP versions trigger differently | Reliable across WP 6.0+ |
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## Next Phase Readiness
+
+**Ready:**
+- Full modal integration operational
+- All 7 AJAX endpoints in place
+- Core feature set complete for MVP
+- Phase 4 can focus purely on UX polish
+
+**Concerns:**
+- List view (table mode) still unhandled
+- No keyboard navigation in modal dropdown
+
+**Blockers:**
+- None
+
+---
+*Phase: 03-media-modal, Plan: 01*
+*Completed: 2026-03-28*