# Requirements — Kerf

> Auto-generated from GSD-INITIATE.md. Canonical source: `.gsd/gsd.db`

## Engine Requirements

| ID | Description | Status | Primary Owner | Validation |
|----|-------------|--------|---------------|------------|
| R001 | Engine accepts raster images (PNG, JPG, BMP, TIFF, WebP) and returns clean vector output (SVG, DXF, JSON) | active | M001/S01 | POST /engine/trace returns valid SVG/DXF/JSON for each format |
| R002 | Engine accepts existing SVG input for simplification passes via /engine/simplify | active | M001/S02 | Node count drops, shape preserved on complex SVG input |
| R003 | Preprocessing pipeline: grayscale, denoise (bilateral), CLAHE contrast, Otsu threshold, optional Canny edge, dilation/erosion — all tunable | active | M001/S01 | Each preprocessing param produces measurable output difference |
| R004 | Mode A vectorization via Potrace with tunable params (turdsize, alphamax, opticurve, opttolerance) | active | M001/S01 | Potrace params affect output; clean SVG from high-contrast logo |
| R005 | Mode B vectorization via VTracer with tunable params (colormode, hierarchical, filter_speckle, etc.) | active | M001/S01 | VTracer produces better output on noisy/photographic inputs |
| R006 | Post-processing: RDP path simplification (epsilon tunable), island detection, open path detection/repair, node count reporting | active | M001/S02 | Simplification reduces nodes; islands flagged; open paths detected |
| R007 | DXF output AC1015+ compatible, openable in Inkscape/LightBurn with clean geometry | active | M001/S02 | DXF opens in target apps with closed paths, no errors |
| R008 | Preset system: sign, patch, stencil, detailed, custom — stored as JSON in /engine/presets/ | active | M001/S03 | GET /engine/presets returns all; each preset produces distinct output |
| R009 | Engine API is stateless, REST over HTTP, JSON responses with metadata | active | M001/S01 | Concurrent requests succeed; no server-side session state |
| R010 | Output metadata includes format, path_count, node_count_total, open_paths, warnings, processing_ms | active | M001/S02 | Metadata fields present and accurate in all responses |

## App Requirements

| ID | Description | Status | Primary Owner | Validation |
|----|-------------|--------|---------------|------------|
| R011 | React SPA with three views: Import & Convert → Design Canvas → Export | active | M002 | Navigation between views works, state carries forward |
| R012 | View 1: Upload raster/vector, select preset, tune sliders with live preview, accept output | active | M002/S01 | Slider changes produce visible preview updates within 300ms debounce |
| R013 | View 2: Konva.js 2D canvas with artboard shapes (rect, square, circle, oval, shield, pennant, custom) | active | M002/S02 | Each artboard shape renders at correct real-world proportions |
| R014 | Canvas text objects: font picker from fonts.json manifest, opentype.js rendering, convert-to-paths | active | M002/S03 | Text renders with loaded font; path conversion produces matching vectors |
| R015 | Canvas shape objects: rectangle, circle, ellipse, line (solid/dashed/dotted/double/centerline), stroke/fill | active | M002/S02 | Each shape type renders and is selectable/moveable/resizable |
| R016 | Object panel: layer stack, reorder via drag, visibility toggle, lock toggle per object | active | M002/S02 | Layer order affects rendering; visibility/lock toggles work |
| R017 | Alignment tools: align left/center/right/top/middle/bottom, distribute H/V, center on artboard | active | M002/S02 | Selected objects align correctly relative to artboard or selection |
| R018 | Undo/redo with full history stack | active | M002/S02 | Actions reversible; redo restores after undo |
| R019 | View 3: Export as DXF/SVG/PNG; DXF layer assignment; text-to-paths enforcement; pre-export validation | active | M003/S01 | Export produces valid files; validation catches open paths and unconverted text |
| R020 | DXF export at real-world scale with correct units (inches/mm) | active | M003/S01 | DXF dimensions match artboard size in target application |

## Deployment & Integration Requirements

| ID | Description | Status | Primary Owner | Validation |
|----|-------------|--------|---------------|------------|
| R021 | Docker Compose deployment: kerf-engine, kerf-app, kerf-server as separate services | active | M003/S02 | docker-compose up starts all services healthy |
| R022 | kerf-engine deployable independently for API-only consumers | active | M003/S02 | Engine container starts alone, API responds |
| R023 | Embed mode: script tag + div, Shadow DOM scoped styles, postMessage events | active | M003/S03 | Component renders in host page; no style bleed; download works |
| R024 | Font system: local .otf files + fonts.json manifest, volume-mounted | active | M002/S03 | Fonts load from volume; adding new font = drop file + update manifest |
| R025 | Engine and App architecturally decoupled — App consumes Engine via HTTP API | active | M001 | Engine has zero imports from App; App calls Engine only via HTTP |