# CRR Image Overlay Web App — Implementation Plan ## 1. Project Goal Build a small, fast, privacy-friendly web application that allows users to upload a base image and place one or more overlay images on top of it. The primary use case is adding the **CRR logo** to posters, photos, and promotional images, but the application must be generic enough to support: - logos; - sponsor images; - QR codes; - badges; - decorative graphics; - arbitrary custom images uploaded by the user. The editor must allow users to position and resize overlays visually and also adjust their exact coordinates numerically. The application must run entirely in the browser. No image data should be uploaded to a server. ## 2. Technology Stack Use: - **Vue 3** - **Vite** - **Fabric.js** - **TypeScript preferred** - **Docker** - **nginx** for serving the production build The application is a static frontend. Do **not** add: - a backend; - a database; - authentication; - user accounts; - server-side image processing; - cloud image storage. ## 3. Core User Workflow 1. Open the application. 2. Upload a base/background image. 3. Display that image in the editor. 4. Add an overlay image: - select a predefined image from the hosted overlay library; or - upload a custom image. 5. Select the overlay. 6. Move it by dragging. 7. Resize it using Fabric.js controls. 8. Fine-tune X, Y, and width. 9. Optionally move it instantly to one of the four corners. 10. Add more overlays if needed. 11. Export/download the final image as PNG or JPEG. The exported image must keep the **original pixel dimensions of the uploaded background image**. ## 4. Background Image Allow the user to upload a base image. Supported formats: - PNG - JPEG - WebP Provide: - a file picker; - drag-and-drop if practical. After loading the image, display its original dimensions: ```text Image: 1280 × 1280 px ``` The uploaded image becomes the non-editable background of the Fabric.js editor. The background image must not normally be selectable, draggable, or resizable. The exported image must preserve the original background resolution. ## 5. Overlay Images An overlay is any image placed above the background. Examples: - CRR logo; - event logo; - sponsor logo; - QR code; - badge; - custom image. Each overlay must be represented as an independent Fabric.js object. The architecture must support **multiple overlays at the same time**. Do not design the application around a single hardcoded `logo` object. Use generic names such as: - `overlay`; - `overlayImage`; - `selectedOverlay`; - `overlays`. ## 6. Hosted Overlay Library The application must include a library of predefined overlay images. The CRR logo must be included by default. Suggested structure: ```text public/ └── overlays/ ├── overlays.json ├── crr-logo.png ├── event-logo.png └── ... ``` The overlay choices must **not** be hardcoded in Vue components. Use: ```text public/overlays/overlays.json ``` Example: ```json [ { "id": "crr-logo", "name": "CRR Logo", "file": "crr-logo.png" }, { "id": "event-logo", "name": "Event Logo", "file": "event-logo.png" } ] ``` The application should load this file at runtime and populate the overlay selector. Adding a new predefined overlay should require only: 1. adding the image to `public/overlays/`; 2. adding an entry to `overlays.json`. No Vue source code should need to change. ## 7. Custom Overlay Upload Users must also be able to add an arbitrary image from their own device. Provide a control such as: ```text [ Upload custom image ] ``` Supported formats: - PNG - JPEG - WebP PNG transparency must be preserved. Custom overlay images must stay entirely local to the browser. After being loaded, a custom overlay must behave exactly like a predefined overlay: - selectable; - draggable; - resizable; - repositionable numerically; - removable; - exportable. ## 8. Fabric.js Editor Use Fabric.js for the main editing experience. At minimum support: - selecting an overlay; - dragging; - resizing; - maintaining aspect ratio while resizing; - Fabric.js selection handles; - deleting/removing the selected overlay; - multiple overlay objects. Rotation is not required for the MVP. If Fabric.js enables rotation by default, disable the rotation control for now. ## 9. Canonical Coordinate System This is one of the most important implementation requirements. The **original background image dimensions must be the canonical coordinate system**. Example: ```text Original image: 4032 × 3024 Displayed editor: 900 × 675 ``` Coordinates shown to the user must still refer to the original image coordinate system. The application must maintain a clear distinction between: - logical/original image coordinates; - display scale used to fit the editor into the browser. All of the following must be correct relative to original image pixels: - X; - Y; - overlay width; - overlay height; - drag movement; - resize operations; - corner positioning; - bounds checking; - final export. Prefer keeping Fabric's logical canvas coordinate space aligned with the original image dimensions and scaling its visual presentation for the UI. ## 10. Responsive Canvas Display Large images must not force the browser to display a 4032 px-wide editor. The editor should scale responsively to the available container width while preserving the background aspect ratio. On resize: - recalculate display scaling; - keep object logical positions unchanged; - keep the output resolution unchanged. The page must not require horizontal scrolling at normal mobile or desktop sizes. ## 11. Selected Overlay Controls When an overlay is selected, display an editor panel. Example: ```text Selected element CRR Logo Position X [ 849 ] Y [ 20 ] Size Width [ 360 ] Quick position [ ↖ ] [ ↗ ] [ ↙ ] [ ↘ ] [ Remove element ] ``` If no overlay is selected, hide or disable object-specific controls. ## 12. Exact X/Y Controls Display numeric fields for the selected overlay: ```text X [ 849 ] px Y [ 20 ] px ``` Requirements: - coordinates are in original image pixels; - dragging an overlay updates the inputs immediately; - changing an input updates the Fabric.js object immediately; - values should be rounded to integer pixels; - invalid values must be clamped; - never display `NaN`, `undefined`, or invalid values. ## 13. Overlay Size Controls Provide at least a width field: ```text Width [ 360 ] px ``` Requirements: - changing width preserves aspect ratio; - resizing with Fabric.js handles updates the width field; - changing the width field updates the object; - do not allow accidental distortion. The UI may also display calculated dimensions. ## 14. Quick Positioning Provide buttons for: - top-left; - top-right; - bottom-left; - bottom-right. Example: ```text [ ↖ ] [ ↗ ] [ ↙ ] [ ↘ ] ``` Use a sensible margin relative to the background image. Suggested starting point: ```ts margin = imageWidth * 0.025; ``` Top-right example: ```ts x = imageWidth - overlayWidth - margin; y = margin; ``` Use the overlay's actual transformed dimensions. ## 15. Overlay Bounds Prefer constraining the full overlay to: ```text x >= 0 y >= 0 x + overlayWidth <= imageWidth y + overlayHeight <= imageHeight ``` Bounds checks must work when: - dragging; - resizing; - editing X/Y manually; - using quick-position buttons. If a value is invalid, clamp it to the nearest valid value. ## 16. Initial Overlay Placement When an overlay is added: - place it automatically near the top-right corner; - use a small proportional margin; - size it relative to the base image. Suggested starting width: ```ts overlayWidth = imageWidth * 0.22; ``` The default must be resolution-independent. ## 17. Multiple Overlay Support Users must be able to add more than one overlay. Example: ```text Background ├── CRR Logo ├── Sponsor Logo └── QR Code ``` Each object must be independently: - selectable; - draggable; - resizable; - removable. A layers panel is not required for the MVP. ## 18. Removing Elements Provide: ```text [ Remove element ] ``` for the selected overlay. Keyboard Delete/Backspace may also be supported on desktop if it does not interfere with inputs. ## 19. Export Provide: ```text [ Download PNG ] [ Download JPEG ] ``` The final output must: - preserve the exact original background dimensions; - include all visible overlays; - preserve overlay coordinates accurately; - preserve aspect ratios; - exclude Fabric.js controls and selection boxes; - work independently of browser display scale. PNG must export at full quality. JPEG may use approximately: ```text quality = 0.95 ``` ## 20. Overlay Picker Behavior The hosted image library should use a dropdown/select for the MVP. Example: ```text Overlay [ CRR Logo ▼ ] [ Add ] ``` Selecting an item should not replace an existing overlay. The explicit **Add** action should create a new object. Custom upload should also create a new overlay. ## 21. Privacy All user images must remain in the browser. Do not: - POST images to a server; - store images in nginx; - send images to APIs; - persist image content remotely. Display a short notice: > Images are processed locally in your browser and are not uploaded to the server. ## 22. Public Repository and Security The source code will be **publicly available**. Assume everything committed to Git can be viewed by anyone. Never commit: - passwords; - tokens; - API keys; - private keys; - deployment credentials; - private certificates; - sensitive infrastructure configuration. The application currently requires no secrets and should ideally remain that way. ## 23. Environment Variables Environment-specific configuration should use environment variables where appropriate. Local environment values may live in: ```text .env ``` The repository must include: ```text .env.example .gitignore .dockerignore ``` Suggested `.gitignore`: ```gitignore .env .env.* !.env.example ``` Example `.env.example`: ```env APP_PORT=8080 # Public frontend configuration only. VITE_APP_NAME=CRR Image Editor VITE_OVERLAYS_CONFIG=/overlays/overlays.json ``` Never include real secrets in `.env.example`. ## 24. Important Vite Security Rule `VITE_*` variables are compiled into the frontend and are visible to users. Therefore they are **not secrets**. Safe: ```env VITE_APP_NAME=CRR Image Editor VITE_OVERLAYS_CONFIG=/overlays/overlays.json ``` Forbidden: ```env VITE_API_SECRET=... VITE_CLOUDFLARE_TOKEN=... VITE_ADMIN_PASSWORD=... ``` Any future feature that genuinely needs a secret must use a server-side component. Do not attempt to hide credentials in: - minified JavaScript; - Vue source; - Docker images; - frontend environment variables. ## 25. Docker Security Do not copy `.env` into the production image. Provide `.dockerignore`, for example: ```text .git .env .env.* !.env.example node_modules dist ``` Deployment-specific values should be configurable externally where useful. Example: ```yaml services: image-editor: build: . restart: unless-stopped ports: - "${APP_PORT:-8080}:80" ``` Do not bake private credentials into: - `Dockerfile`; - `docker-compose.yml`; - nginx configuration; - frontend source; - CI files. If CI/CD later requires credentials, use the secret-management mechanism provided by the CI platform. ## 26. Suggested Project Structure ```text crr-image-editor/ ├── .dockerignore ├── .env.example ├── .gitignore ├── Dockerfile ├── docker-compose.yml ├── nginx.conf ├── package.json ├── vite.config.ts ├── tsconfig.json ├── README.md ├── PLAN.md │ ├── public/ │ └── overlays/ │ ├── overlays.json │ ├── crr-logo.png │ └── ... │ └── src/ ├── App.vue ├── main.ts ├── components/ │ ├── ImageEditor.vue │ ├── BackgroundUpload.vue │ ├── OverlayPicker.vue │ ├── OverlayControls.vue │ └── ExportControls.vue ├── composables/ │ └── useFabricEditor.ts ├── types/ │ └── editor.ts └── styles/ └── main.css ``` Keep Fabric.js-specific operations centralized. ## 27. Suggested Component Responsibilities ### `App.vue` - overall layout; - major application state; - privacy notice; - high-level empty/loading/error states. ### `BackgroundUpload.vue` - background file selection; - drag-and-drop; - file validation. ### `OverlayPicker.vue` - load `overlays.json`; - list predefined overlays; - add selected predefined overlay; - upload custom overlays. ### `ImageEditor.vue` - host Fabric.js canvas; - responsive display sizing; - selected-object state; - Fabric lifecycle. ### `OverlayControls.vue` - selected element information; - X; - Y; - width; - corner positioning; - removal. ### `ExportControls.vue` - PNG export; - JPEG export; - download filename. ### `useFabricEditor.ts` Centralize: - Fabric canvas creation/destruction; - background loading; - overlay loading; - object selection; - transforms; - coordinate handling; - bounds enforcement; - event handling; - export. ## 28. Error Handling Handle cleanly: - unsupported image type; - invalid/corrupt image; - overlay config load failure; - overlay image load failure; - browser image decode failure; - export before loading a background. Show human-readable messages. A failure loading one predefined overlay should not make the whole application unusable. ## 29. Object URL Cleanup If `URL.createObjectURL()` is used: - revoke old background URLs; - revoke custom overlay URLs when appropriate; - avoid leaking object URLs during long sessions. ## 30. Fabric.js Lifecycle Vue component unmounting must clean up the Fabric.js canvas and listeners. Avoid: - duplicate event handlers; - unnecessary canvas recreation; - stale selected-object references. Use a single controlled Fabric canvas instance per editor. ## 31. Bounds Implementation Details Bounds enforcement must use transformed object dimensions. Do not assume: ```ts object.width === displayedWidth ``` Use Fabric.js APIs for scaled/transformed dimensions and bounding rectangles as appropriate. After programmatic movement or resize, update Fabric coordinates before bounds checks/rendering when required. ## 32. File Validation For uploads: - check MIME type; - attempt actual image decoding; - reject invalid files with a useful message. Do not trust only the file extension. Reasonable file-size protection may be added to avoid browser crashes, but do not impose unnecessarily small limits. ## 33. Accessibility Requirements: - file inputs have labels; - numeric controls have labels; - buttons have descriptive text or accessible labels; - keyboard users can operate controls; - visible focus states; - adequate contrast; - drag is not the only way to position an overlay. The X/Y/width fields provide the non-drag alternative. ## 34. Browser Support Target current versions of: - Chrome; - Edge; - Firefox; - Safari; - mobile Safari; - mobile Chrome. Avoid experimental browser APIs for core functionality. ## 35. Docker Deployment Use a multi-stage build. Example: ```dockerfile FROM node:22-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM nginx:alpine COPY --from=build /app/dist /usr/share/nginx/html EXPOSE 80 ``` Basic Compose example: ```yaml services: image-editor: build: . restart: unless-stopped ports: - "${APP_PORT:-8080}:80" ``` The app must work behind a standard reverse proxy. ## 36. Implementation Phases ### Phase 1 — Project Bootstrap - Create Vue 3 + Vite project. - Add Fabric.js. - Prefer TypeScript. - Create basic responsive layout. - Add Dockerfile. - Add docker-compose.yml. - Add nginx configuration. - Add `.gitignore`. - Add `.dockerignore`. - Add `.env.example`. ### Phase 2 — Background Editor - Implement background image upload. - Decode image locally. - Read original dimensions. - Initialize Fabric.js canvas. - Set image as non-selectable background. - Implement responsive visual scaling. - Verify canonical coordinates remain original-image coordinates. ### Phase 3 — Predefined Overlay Library - Add `public/overlays/`. - Add `overlays.json`. - Add CRR logo. - Load config from frontend. - Implement dropdown. - Implement Add button. - Load selected image into Fabric. - Apply default size and top-right placement. ### Phase 4 — Custom Overlays - Implement custom overlay upload. - Preserve PNG transparency. - Add custom images as Fabric objects. - Manage object URLs correctly. ### Phase 5 — Editing Controls - Implement Fabric selection. - Drag overlays. - Resize overlays. - Preserve aspect ratio. - Disable rotation for MVP. - Implement X control. - Implement Y control. - Implement width control. - Keep controls synchronized with Fabric events. - Add remove action. ### Phase 6 — Bounds and Quick Positioning - Implement bounds enforcement. - Add four corner buttons. - Calculate proportional margin. - Clamp manual coordinates. - Handle resizing near edges. - Verify no overlay is clipped accidentally. ### Phase 7 — Multiple Overlays - Verify multiple predefined/custom overlays coexist. - Ensure controls operate only on active object. - Verify removal affects only selected object. - Verify export maintains stacking order. ### Phase 8 — Export - Implement PNG export. - Implement JPEG export. - Preserve original dimensions. - Verify display scale does not affect output. - Ensure selection/control UI is not exported. - Trigger browser download. ### Phase 9 — Mobile and UX Polish - Test responsive desktop layout. - Test mobile layout. - Test touch drag/resize. - Improve empty states. - Add image dimension information. - Add privacy notice. - Add useful error messages. ### Phase 10 — Public Repository Review Before publishing: - verify `.env` is ignored; - verify no `.env` exists in Git history; - search repository for credentials; - verify `.env.example` uses example values only; - verify no secret uses `VITE_*`; - inspect Docker image contents; - verify `.env` is not copied into Docker; - inspect README examples for private values; - verify production build contains no sensitive configuration. ## 37. Testing Checklist ### Background - Upload PNG. - Upload JPEG. - Upload WebP. - Upload portrait image. - Upload landscape image. - Upload square image. - Upload high-resolution image. - Replace current background. ### Hosted overlays - Load `overlays.json`. - Add CRR logo. - Add second hosted overlay. - Handle missing overlay image gracefully. ### Custom overlays - Upload transparent PNG. - Upload JPEG. - Upload WebP. - Add multiple custom overlays. ### Editing - Drag. - Resize. - Change X manually. - Change Y manually. - Change width manually. - Select different objects. - Remove selected object. ### Bounds - Drag beyond every edge. - Resize against every edge. - Enter negative X/Y. - Enter excessively large X/Y. ### Quick positioning - Top-left. - Top-right. - Bottom-left. - Bottom-right. - Test portrait, landscape, and square backgrounds. ### Scaling Verify coordinate accuracy with: ```text 1280 × 1280 1920 × 1080 1080 × 1920 4032 × 3024 ``` Resize the browser and ensure coordinates remain stable. ### Export - PNG dimensions match source. - JPEG dimensions match source. - Overlay coordinates match preview. - Multiple overlays appear correctly. - Transparent logos render correctly. - Fabric controls are absent. - Export after browser resize still works. ### Mobile - Upload via mobile picker. - Select overlay. - Drag via touch. - Resize via touch. - Edit numeric values. - Export/download. ## 38. MVP Acceptance Criteria - [ ] Vue 3 + Vite application is implemented. - [ ] Fabric.js is used for the editor. - [ ] User can upload PNG, JPEG, and WebP backgrounds. - [ ] Background original dimensions are detected. - [ ] Background is displayed responsively. - [ ] Original image coordinates are the canonical editor coordinate system. - [ ] User can select an overlay from `overlays.json`. - [ ] CRR logo is included as a predefined overlay. - [ ] User can upload a custom overlay image. - [ ] PNG transparency is preserved. - [ ] More than one overlay can exist simultaneously. - [ ] Overlays can be selected. - [ ] Overlays can be dragged. - [ ] Overlays can be resized. - [ ] Aspect ratio is preserved. - [ ] X coordinate can be edited numerically. - [ ] Y coordinate can be edited numerically. - [ ] Width can be edited numerically. - [ ] Numeric controls update during visual manipulation. - [ ] Four corner-position buttons work. - [ ] Overlay bounds are enforced. - [ ] Selected overlay can be removed. - [ ] PNG export works. - [ ] JPEG export works. - [ ] Export preserves original background dimensions. - [ ] Exported coordinates match editor coordinates. - [ ] Fabric selection controls do not appear in export. - [ ] Desktop UI works. - [ ] Mobile UI works. - [ ] User images never leave the browser. - [ ] No backend is required. - [ ] Docker production build works. - [ ] Application works behind a reverse proxy. - [ ] `.env` is excluded from Git. - [ ] `.env.example` exists. - [ ] `.dockerignore` prevents `.env` from entering Docker builds. - [ ] No secrets are present in source code. - [ ] No secrets are exposed via `VITE_*`. - [ ] Repository is safe to publish publicly. ## 39. Non-Goals for MVP Do not spend time on these unless required for the core implementation: - authentication; - user accounts; - server-side persistence; - cloud storage; - project history; - templates; - layers sidebar; - text editor; - rotation UI; - filters; - cropping; - image effects; - undo/redo history; - collaborative editing; - admin interface; - remote APIs. ## 40. Future Enhancements Potential future features: - text overlays; - QR-code generator; - rotation; - opacity; - duplicate element; - layers panel; - z-index controls; - snapping/alignment guides; - center/top/bottom/left/right quick positioning; - templates for common CRR artwork sizes; - save/load project JSON; - undo/redo; - keyboard arrow movement; - Shift + arrow for larger movements; - social-media presets; - predefined export sizes. These are outside the initial MVP. ## 41. Guiding Principle Keep the application simple. The target experience is: ```text Upload image ↓ Add CRR logo / another image ↓ Drag and resize ↓ Fine-tune coordinates if necessary ↓ Download ``` A normal user should be able to create the final image in a few seconds without understanding Fabric.js, image coordinates, scaling, or export resolution. The implementation must hide the technical complexity while keeping the output pixel-accurate.