## Problem/Motivation #3615637 (GrapesJS Asset Manager) and #3615635 (Mosaico composition plugin) were developed in parallel and both landed an image upload surface. They work, they are independently tested, and CI is green — but the module now carries two upload endpoints with different permission models, different limits and duplicated usage tracking. | | Base module (#3615637) | campaign_mosaico (#3615635) | |---|---|---| | Route | `campaign.asset_upload` — `/campaign/asset/upload` | `campaign_mosaico.upload` — `/campaign-mosaico/upload` | | Permission | `upload campaign assets` (dedicated, restricted) | `create campaign messages+edit campaign messages` | | CSRF | `_csrf_token` query token baked into the URL server-side | `_csrf_request_header_token` — `X-CSRF-Token` header | | Directory | `public://campaign/images` | `public://campaign/mosaico` | | Limits | 5 MB cap, 4000x4000 dimension cap, extension allow-list | site upload limit, no dimension cap, same extension allow-list | | Response | `{"data": [...]}` / `{"error": "..."}` | blueimp `{"files": [...]}` envelope (GET and POST) | | Usage tracking | `AssetUsageTracker` service, scans **all revisions** | hooks in `campaign_mosaico.module`, scans the **current revision only** | Three consequences worth naming: - **The permission model is inconsistent.** #3615637 deliberately introduced a restricted `upload campaign assets` permission because an upload endpoint lets a user place files on the server. Installing `campaign_mosaico` re-opens that capability to anyone holding the ordinary message create/edit permissions, so the restriction no longer means what the base module says it means. - **Usage tracking diverges on revisions.** `AssetUsageTracker` keeps a file permanent while *any* revision references it; the Mosaico hooks only consider the current revision, so editing an image out of a message drops the usage even though an older revision still points at it. The file then becomes temporary and is eventually garbage-collected — reverting that revision yields a broken image. - **Two directories and two limit sets** mean site builders configuring quotas, backups or a CDN have to know about both. ## Proposed resolution Converge on the base module's asset surface and reduce `campaign_mosaico` to the Mosaico-specific parts: - Point the Mosaico editor at `campaign.asset_upload`, gated by `upload campaign assets`, storing into `public://campaign/images` with the base module's size and dimension caps. - Delete the Mosaico file-usage hooks and let `AssetUsageTracker` own tracking. The tracker is already plugin-agnostic — it serializes the whole composition configuration of every revision and scans it for the asset directory, so Mosaico's `metadata`/`content`/`html` configuration is covered without changes to the tracker beyond the directory it looks for. - Keep whatever thin protocol shim Mosaico's uploader genuinely needs (see below). ## What should stay in campaign_mosaico - **The image-processing endpoint** (`campaign_mosaico.image` — placeholder/resize/cover). This is Mosaico's `imgProcessorBackend` contract and has no GrapesJS counterpart. Its `src` confinement must follow the directory move. - **The blueimp response shape.** Mosaico's uploader expects the `{"files": [...]}` envelope with per-file `url`/`thumbnailUrl` and a GET gallery listing; the base endpoint answers `{"data": [...]}` and has no listing. Reconciling this is the main design question — either the base endpoint grows an optional protocol/format, or `campaign_mosaico` keeps a shim route that delegates to the shared upload service and re-shapes the response. The shim is the smaller change and keeps #3615637's contract untouched. ## Remaining tasks - [ ] Decide protocol reconciliation: shared endpoint with a format option, or a thin Mosaico shim delegating to it (shim recommended). - [ ] Extract the upload handling of `AssetUploadController` into a service both routes can call, if the shim route is chosen. - [ ] Move Mosaico uploads to `public://campaign/images`; update the image endpoint's confinement, the thumbnail URL builder and the tests. - [ ] Remove the `campaign_mosaico` file-usage hooks and their tests; assert the revision-aware behavior for a Mosaico-composed message in `AssetUsageTrackerTest`. - [ ] Update the Mosaico editor glue for the CSRF mechanism the chosen route uses. - [ ] **Upgrade path:** decide whether existing files under `public://campaign/mosaico` are migrated by an update hook or left in place with the endpoint accepting both directories read-only. Sites running the alpha may already hold uploads there. - [ ] Update `README.md` and `docs/architecture.md` to describe one asset surface. ## Notes This is cleanup of a parallel-development overlap, not a defect in either issue: both surfaces are tested and behave as designed. Nothing here blocks a release, but it is worth resolving before the permission model and directory layout harden into a public API. AI-Generated: Yes (Used Claude Code Opus 5 and/or Fable 5 to generate the text of this issue.)