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/02-media-library-grid/02-01-SUMMARY.md

@@ -0,0 +1,119 @@
+---
+phase: 02-media-library-grid
+plan: 01
+subsystem: media
+tags: [wordpress, media-grid, drag-drop, taxonomy-filter, backbone-js]
+
+requires:
+  - phase: 01-media-folders-plugin
+    provides: media_folder taxonomy, AJAX CRUD, folder tree UI
+provides:
+  - Media grid filtering by folder via WP backbone props
+  - mfp_assign_media AJAX endpoint
+  - HTML5 drag & drop media to folders
+affects: [03-media-modal, 04-polish-ux]
+
+tech-stack:
+  added: []
+  patterns: [ajax_query_attachments_args filter, wp.media.props integration, HTML5 drag&drop, MutationObserver for dynamic content]
+
+key-files:
+  created:
+    - wp-content/plugins/media-folder-pro/includes/class-media-query.php
+    - wp-content/plugins/media-folder-pro/assets/js/media-filter.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:
+  - "Filter via ajax_query_attachments_args — no core WP modifications"
+  - "wp.media library.props.set() triggers grid reload natively"
+  - "HTML5 Drag & Drop API — no jQuery UI dependency"
+  - "MutationObserver to catch dynamically loaded attachments (infinite scroll)"
+  - "Drop on 'All Media' unassigns from folder (folder_id=0)"
+
+patterns-established:
+  - "window.mfpRefreshTree() exposed for cross-module communication"
+  - "media-filter.js depends on media-views + media-folder-pro-tree"
+  - "Delegated drag events on #mfp-folder-root for drop targets"
+
+duration: ~10min
+started: 2026-03-28
+completed: 2026-03-28
+---
+
+# Phase 2 Plan 01: Media Library Grid Integration Summary
+
+**Media grid filtering by folder click + drag & drop media assignment with live counter updates, integrated via WP backbone props and HTML5 Drag & Drop API.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~10min |
+| Tasks | 2 completed |
+| Files created | 2 |
+| Files modified | 4 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Filtrowanie mediow po kliknieciu folderu | Pass | ajax_query_attachments_args + library.props.set |
+| AC-2: Przypisywanie mediow przez AJAX | Pass | mfp_assign_media with folder_counts response |
+| AC-3: Drag & drop mediow na foldery | Pass | HTML5 D&D + MutationObserver + counter refresh |
+
+## Accomplishments
+
+- Server-side filter via `ajax_query_attachments_args` hook — supports folder filtering and "uncategorized" (id=-1)
+- `mfp_assign_media` endpoint assigns media to exactly 1 folder (or removes) and returns updated folder counts
+- HTML5 drag & drop from media grid thumbnails to folder tree with visual feedback
+- Drop on "All Media" removes folder assignment
+- MutationObserver catches dynamically loaded attachments for draggable setup
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `includes/class-media-query.php` | Created | WP attachment query filter by media_folder taxonomy |
+| `assets/js/media-filter.js` | Created | Grid filter via wp.media props + drag & drop logic |
+| `includes/class-ajax-handler.php` | Modified | Added mfp_assign_media endpoint |
+| `assets/js/folder-tree.js` | Modified | Exposed window.mfpRefreshTree() |
+| `assets/css/admin.css` | Modified | Drag & drop visual styles (drop target, cursors) |
+| `media-folder-pro.php` | Modified | MFP_Media_Query init, media-filter.js enqueue, i18n strings |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Use ajax_query_attachments_args | Native WP filter, no core mods | Clean integration |
+| library.props.set for grid reload | Backbone native, triggers AJAX automatically | No manual DOM manipulation |
+| MutationObserver for infinite scroll | Attachments load dynamically, need draggable on each | Robust for any load pattern |
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## Next Phase Readiness
+
+**Ready:**
+- Full folder filtering + assignment pipeline operational
+- media-filter.js pattern reusable for modal integration (Phase 3)
+- mfp_assign_media endpoint ready for bulk use (Phase 4)
+
+**Concerns:**
+- Media modal uses different wp.media frame — will need separate integration path
+- List view (table) not yet handled (deferred to Phase 4)
+
+**Blockers:**
+- None
+
+---
+*Phase: 02-media-library-grid, Plan: 01*
+*Completed: 2026-03-28*