# Project Specification: Ultimate Browser Screenshot & Editor
## 1. Project Overview
Create a high-performance, modular browser extension (Chrome Manifest V3) for capturing screenshots and editing them with professional-grade tools (comparable to light versions of Photoshop/Lightroom). The application must be built with a **Modular Architecture**, separating the Core, Raster Engine (WebGL), and Vector Engine.
## 2. Technical Architecture
The application must be modular to allow enabling/disabling components via plugins.
### Core Structure
- **Technology**: Vanilla JavaScript (ES6+) or TypeScript, HTML5, CSS3 (Variables, Flex/Grid).
- **Extension**: Manifest V3 (`activeTab`, `scripting`, `alarms`, `storage`, `offscreen`).
- **Module System**: A central `ModuleManager` that loads/unloads functionality dynamically.
- **Monetization/Locking Manager**: System to lock specific modules or tools based on user status (Free/Premium/Contributor).
### Modules
1. **Core Module**: Handles state, history (Undo/Redo), and layer management using a proprietary `LayerStack`.
2. **Raster Engine (WebGL 2.0)**:
- Responsible for high-performance image manipulation.
- **GPU Acceleration**: All photo filters (Exposure, HSL, Curves) must run as GLSL Shaders.
- Handles "Raster Layers".
3. **Vector Engine (SVG/Canvas)**:
- Handles "Vector Layers" (Shapes, Text, Bezier Curves).
- Objects remain editable (not baked into pixels immediately).
4. **UI Module**:
- Dynamic panels based on active modules.
- Theming capabilities.
## 3. Functional Requirements
### A. Capture Features (Extension)
- **Modes**:
- Visible Tab.
- Area Selection (Interactive drag & resize overlay).
- **Automation**:
- **Delayed Capture**: Timer (e.g., 3s, 5s, 10s).
- **Scheduled Capture**: Set date/time for automatic capture (via `chrome.alarms`).
### B. Editor - Professional Features
#### 1. Layer System
- **Types**: Raster Layer, Vector Layer, Adjustment Layer (non-destructive effects), Group Folder.
- **Support**: Visibility, Opacity, Blending Modes (Multiply, Screen, Overlay, etc.), Masks (Bitmap & Vector).
#### 2. Tools
- **Navigation**: Hand/Move tool, Zoom.
- **Raster Tools**:
- **Brush**: Size, Hardness, Flow, Spacing.
- **Eraser**: Hardness support (Soft edges), support for erasing on Masks.
- **Stamp/Heal**: Cloning areas (optional advanced feature).
- **Vector Tools**:
- **Shapes**: Rectangle, Circle/Ellipse, Triangle, Polygon, Star, Line, Arrow.
- **Pen Tool**: Full Bezier curve support (Paths).
- **Text**: Rich text editing, system fonts, hashtags support.
- **Utilities**:
- Crop (Free, 1:1, 16:9, 4:3, Golden Ratio).
- Gradient Tool (Linear, Radial).
- Bucket Fill.
### C. Photo Editing (LR-style)
Must utilize **WebGL** for real-time performance.
- **Global Adjustments**:
- Light: Exposure, Contrast, Highlights, Shadows, Whites, Blacks.
- Color: Temperature (WB), Tint, Saturation, Vibrance.
- **Tone Curve**: RGB and separate Red/Green/Blue channels.
- **HSL / Color Mixer**: Adjust Hue, Saturation, and Luminance for 8 separate color ranges (Red, Orange, Yellow, Green, Aqua, Blue, Purple, Magenta).
- **Detail**: Sharpening (Unsharp Mask), Noise Reduction, Vignette (with midpoint/roundness/feather control).
- **Local Adjustments (Masking)**:
- Brush Mask, Linear Gradient Mask, Radial Gradient Mask to apply effects locally.
### D. Export, Import & Assets
- **Import**:
- Standard: PNG, JPG, WEBP, SVG, GIF, BMP.
- **Advanced** (via libraries/WASM):
- **RAW** (CR2, NEF, ARW) using `libraw.wasm`.
- **PSD** (Photoshop) using `psd.js` (layers support preferred).
- **TIFF** using `utif.js`.
- **Modules/Extensions**:
- **Gallery Module**:
- Grid view of images in a directory (File System Access API).
- Navigation: Arrow keys, Mouse selection.
- **Batch Actions**: Apply Preset to selection, Sync Settings.
- **Export**:
- **Formats**: PNG, JPG, WEBP, AVIF, TIFF.
- **Compression**: Slider 0-100, estimated file size preview.
- **Batch Export**: Export selected hierarchy or list.
- **Vector/Hybrid**: SVG, PDF.
- **Share**: Web Share API integration.
## 4. Performance Goals
- **WebGL**: Pixel operations must not run on CPU for image layers > 2MP.
- **Tiling**: (Optional) For huge images, implement tile-based rendering.
- **Non-destructive**: Filters should be applied dynamically until export where possible.
## 5. User Interface (UI/UX)
- **Style**: Modern, clean, "Dark Mode" default. Glassmorphism elements.
- **Layout**:
- **Left**: Toolbar (Tools).
- **Top**: Tool Properties Bar (Contextual).
- **Right**: Collapsible Panels (Layers, History, Properties/Filters, Export).
- **Center**: Infinite Canvas viewport.
## 6. Development Strategy & Guidelines (Vibe Coding)
To ensure smooth development with AI ("vibe coding") and maintain a robust codebase:
### A. Technical Stack
- **Language**: **TypeScript**. Uses strict typing to prevent logic errors and helps AI infer context.
- **Build**: **Vite**. Fast HMR and build process.
- **Testing**: **Vitest**.
### B. Architecture Patterns
- **Command Pattern**: Encapsulate all canvas operations as command objects (`execute`, `undo`). This makes History implementation automatic.
- **Event-Driven**: Modules communicate via an event bus (e.g., `EventTarget`) to decouple Logic from UI.
- **Controller-View Separation**: The "Engine" should not know about "Buttons". It exposes an API (e.g., `setExposure(0.5)`) that the UI calls.
### C. QA, Debugging & Versioning
- **Fail Fast**: Use assertions in core logic. If a Layer ID is missing, throw immediately.
- **Incremental Testing**:
- Write small unit tests for math-heavy modules (Vector/Color math) *before* integration.
- Test the "Command Stack" independently of the UI.
- **Versioning & Changelog**:
- **SemVer**: `MAJOR.MINOR.PATCH`.
- **`CHANGELOG.md`**: Master file for developers. Logs every code change.
- **`RELEASE_NOTES.md`**: User-facing file. Updates description (e.g., "New Curve Tool added").
- **Automation**: Use `standard-version` or `semantic-release` to auto-generate changelogs from commit messages.
- **Debug Strategy**:
- **Telemetry**: Implementation of `Logger.log()` in key actions (e.g., "Layer added", "Filter applied").
- **Export Logs**: Button in Settings to "Download Debug Logs" (dump of the ring buffer).
- **metrics**: FPS counter, Memory usage overlay.
### D. AI Context
- Create a `CONTEXT.md` defining domain terms: "Layer", "Mask", "Stroke", "Path".
- Keep a `TODOS.md` or `task.md` active to track small steps.
## 7. Project Bootstrap & File Structure
This section defines how to initialize the repository to ensure scalability and strict adherence to the modular architecture.
### A. Directory Structure
All paths must be relative. The `src` folder is the root for code.
```text
/ (Project Root)
├── .vscode/ # VS Code settings (optional)
├── docs/ # PROCESS CONTROL FILES
│ ├── CONTEXT.md # Glossary & Concepts (What is a Layer? What is a Module?)
│ ├── ARCHITECTURE.md # Dependency Graph & Data Flow
│ ├── GUIDELINES.md # Naming conventions (kebab-case files, PascalCase classes)
│ └── project_specification.md # This Spec
├── public/ # Static assets (icons)
├── src/
│ ├── core/ # The "Brain" (No UI code here!)
│ │ ├── events/ # EventBus
│ │ ├── history/ # CommandStack
│ │ └── state/ # Store
│ ├── modules/ # Independent Functional Blocks
│ │ ├── raster/ # WebGL Context, Filters, Shaders
│ │ ├── vector/ # SVG Layer, Bezier Logic
│ │ ├── gallery/ # File System View
│ │ └── ui/ # UI Components (Panels, Toolbar)
│ ├── shared/ # Utilities (Math, Color, IO)
│ ├── background.ts # Extension Service Worker
│ ├── content.ts # Content Scripts
│ └── popup.ts # Entry point
├── tests/ # Unit & Integration Tests
├── manifest.json # MV3 Manifest
├── package.json
└── vite.config.ts
```
### B. Process Control Files
To force the AI (Antigravity) to stick to the plan, these files must exist and be read at the start of every session:
1. **`docs/project_specification.md`**: The Source of Truth.
2. **`docs/GUIDELINES.md`**: Strict rules.
- *Rule*: "All file names must be kebab-case (e.g., `layer-manager.ts`)."
- *Rule*: "No circular dependencies between modules. Use Core EventBus."
- *Rule*: "Always use relative imports (e.g., `../shared/math`)."
3. **`task.md`** (Root): The active checklist.
### C. Dependency Graph (Abstract)
```mermaid
graph TD
UI[UI Module] -->|Emits Events| Core[Core Module]
UI -->|Reads State| Core
Core -->|Manages| R[Raster Engine]
Core -->|Manages| V[Vector Engine]
R -->|Uses| GPU[WebGL]
V -->|Uses| SVG[SVG DOM]
Gallery[Gallery Module] -->|Loads File| Core
```
2 version
1) Filozofie pluginů (postupné vrstvení bezpečnosti)
-
Fáze 1 (od začátku): „Data-only / Declarative plugins“
-
Fáze 2 (později): „Sandboxed compute plugins“
-
Fáze 3 (až nakonec): „Privileged plugins“
-
síť, OS, AI cloud, native companion
-
striktní entitlement + audit
2) 4 režimy aplikace (nemíchat)
-
Selector
-
preview, ratingy, stavy, kolekce, filtry
-
Photo editor
-
Curve / layer editor
-
PrtScr editor
➡️ Plugin vždy deklaruje, ve kterých režimech smí běžet.
3) Skupiny pluginů (bezpečné hned od začátku)
A) 100% bezpečné (data-only)
-
UI / layout / theme
-
Preset editace (bez masek)
-
Curve presets
-
Export templates
-
Selector rules (štítky, pipeline stavy)
-
Makra (DAG nad built-in akcemi)
-
PrtScr stamps (vektorové tvary)
-
LUT / ICC / curve data
➡️ žádný JS, žádný WASM, jen validovaná data
4) Sandboxed pluginy (později)
-
nové filtry (WASM)
-
analyzátory (histogramy, ostrost, šum)
-
HW benchmark / capability plugin
-
měří CPU/GPU/IO přes povolené API
-
výstup = jen agregovaná data
-
sdílení na X.com jen přes core UI (plugin nikdy neposílá sám)
5) HW-benchmark plugin (bezpečný návrh)
6) Jak zabránit kolizím pluginů (stručně)
7) DB & režimy (jen zásada)
-
DB dělená podle času: den / měsíc / rok
-
export = výběr partitionů
-
plugin nikdy nepřistupuje k DB přímo
Závěr (jednou větou)
Začni s data-only pluginy (bez kódu) pro všechny 4 režimy,
výpočetní a HW/AI pluginy přidej až později přes sandbox + capability router,
a nikdy nenech pluginy mluvit přímo se sítí, FS ani DB.
Pokud chceš další krok:
👉 minimální plugin manifest (data-only vs sandboxed) – 1 stránka, hotová pro implementaci.
MD
# CONTEXT PACK – Photo Selector / Editor Platform (vibe-coding ready)
## 0) Cíl projektu
Navrhnout **extrémně rychlou, modulární a dlouhodobě stabilní platformu** pro selekci,
editaci fotografií a PrtScr, běžící jako **PWA + MV3 rozšíření**, s **konfigurovatelnou DB,
pluginovým ekosystémem (3rd party)**, **automatizací workflow**, **možností monetizace**
a **odděleným vývojovým/konfiguračním režimem**.
---
## 1) Základní filozofie
- **Performance-first**: UI nesmí blokovat, výpočty vždy mimo main thread.
- **Editace = recept, ne bitmapa** (nedestruktivní, textově malé).
- **DB = paměť rozhodnutí**, ne katalog pixelů.
- **Core je malé a stabilní**, vše ostatní jsou vypnutelné moduly.
- **Žádná implicitní funkce** – vše lze zapnout / vypnout / skrýt.
- **Bezpečnost přes capability model**, ne přes „důvěru v plugin“.
---
## 2) 4 pevně oddělené režimy aplikace
1. **Selector**
- extrémně rychlé procházení
- embedded preview / JPEG / proxy
- žádné RAW renderování při listování
2. **Photo editor**
- globální úpravy (expozice, WB, kontrast…)
- nedestruktivní edit-recept
3. **Curve / layer editor**
- křivky
- lokální úpravy
- **primárně vektorové masky**
4. **PrtScr editor**
- text, šipky, zvýraznění, blur / redakce
- čistě vektorové vrstvy
Každý režim:
- samostatný bundle
- samostatné panely
- lze **zcela vypnout**
---
## 3) Selekce fotek (minimální model)
### Minimálně 4 nezávislé osy (kombinovatelné):
1. **Rating** (0–5)
2. **Color label** (např. 8)
3. **Pipeline state**
`new / shortlist / final / delivered / archived`
4. **Collections / bins** (A–D nebo 1–8)
**Bitové flagy**:
- selected
- rejected
- edited
- exported
---
## 4) Editace (datově malá)
- Editace uložena jako **recept (JSON)**:
- seznam operací + parametry
- jednotky kB na fotku
- Masky:
- **vektorové** (tahy, tvary)
- bitmapové jen výjimečně (advanced / placená funkce)
---
## 5) DB a ukládání (konfigurovatelné)
### Time-partition DB (volba uživatele / admina):
- **per den** – `YYYY-MM-DD.sqlite` (default)
- per měsíc – `YYYY-MM.sqlite`
- per rok – `YYYY.sqlite`
- **zvolené období** = výběr partitionů
### Co DB obsahuje:
- metadata + poslední známé cesty
- selekční stavy
- tagy / hashtagy
- edit-recepty
- volitelně: náhledy, historie
### Export / mazání:
- den / týden / měsíc / rok
- export = ZIP vybraných DB souborů (+ volitelně previews)
- DB je **rebuildovatelná**
---
## 6) Runtime a technická architektura
### Core (neměnný, malý)
- job queue + scheduler
- capability router
- storage manager (time-partition)
- render engine (GPU)
### Runtime
- **Web Workers** (výpočty, DB, import)
- **OffscreenCanvas** (render mimo UI)
- **GPU**: WebGL / WebGPU
- **PWA + MV3**:
- MV3 service worker = orchestrace
- offscreen document = DOM / canvas bez UI
---
## 7) Plugin systém (3rd party ready)
### Tři třídy pluginů
#### A) Data-only (prakticky 100 % bezpečné)
- UI theme / layout
- preset editace (bez masek)
- curve presets
- export templates
- selector rules
- makra (DAG nad built-in akcemi)
- PrtScr stamps (vektory)
- LUT / ICC / curve data
#### B) Sandboxed compute (později)
- nové filtry (WASM)
- analyzátory
- HW benchmark
- lokální AI
#### C) Privileged (nejpozději)
- cloud sync
- AI cloud
- import z OS (SD / mobil) přes native companion
### Bezpečnostní zásady
- žádný přímý přístup k:
- DB
- FS
- síti
- vše přes **capability router**
- namespacing
- kvóty, timeouty
- zákaz remote code
---
## 8) Automatizace & workflow
- **Macro engine = deterministický DAG**
- triggery:
- ručně
- po importu
- plán
- kroky:
- jen existující interní akce
- žádný vlastní skriptovací jazyk
---
## 9) Import a automatické ukládání
- konfigurovatelný **import router**:
- zdroj (SD, mobil, watch folder)
- cíl
`E:\foto2026\YYYY-MM-DD – popis`
- plná automatizace OS → **native companion**
- komunikace přes Native Messaging
---
## 10) Moduly (striktně oddělené)
1. **Free**
2. **Paid**
3. **Config / Admin**
4. **Dev / Vibe-coding**
Každý modul:
- enable / disable
- visible / hidden
- lazy-loaded
---
## 11) Dev / Performance modul (oddělený)
- nikdy neběží u běžného uživatele
- měří:
- CPU / GPU / RAM
- worker load
- render time
- DB latency
- loguje:
- plugin calls
- makra
- storage nároky
- používá se i pro:
- detekci regresí po updatech prohlížečů
---
## 12) HW Performance Meter (obecný modul)
- read-only
- anonymní, agregovaná data
- opt-in sdílení
- preview přesně toho, co se odešle
- žádné identifikátory HW
- sdílení **jen přes core UI**
---
## 13) Monetizace (technicky)
- monetizují se **schopnosti**, ne aplikace
- jednorázové / měsíční / roční
- rozhoduje **entitlement layer**, ne plugin
---
## 14) Hlavní zásady pro další návrhy
- žádná funkce bez vypínače
- žádný plugin bez sandboxu
- žádná editace bez receptu
- žádná DB bez time-partition
- žádné sdílení bez preview a opt-in
---
### Použití
Tento dokument je určen jako **první zpráva nového vlákna** nebo jako
základní architektonický podklad pro další specifikace (API, manifesty,
UI, DB schémata).
Plugin
Browser
Timeline
2026-01-21
Žádné komentáře:
Okomentovat