yvcodesnap/docs/spec.md

Spec: Lightweight Code Canvas for Social Media Images

1. Vision & Scope

• Purpose: A simple, fast web canvas to compose export-ready images featuring code blocks, text, and arrows with customizable backgrounds.
• Success Criteria: Create and export high-quality visuals in under 2 minutes, without complex design steps.
• Out of Scope (initial): Slides, animations/video, multi-user collaboration, online sharing/embedding, AI features.

2. Target Users & Jobs

• Developer/content creator: Creates quick, branded code images for X/LinkedIn/Instagram.
• Educator: Highlights parts of code with arrows and captions.
• OSS maintainer: Shares release notes with styled code examples.

3. Core User Flows

1. Start a new canvas → pick aspect ratio → set background → add code block → add text → add arrows → export PNG/JPEG.
2. Highlight lines in code to focus attention.

4. Functional Requirements

4.1 Canvas & Layout

• Create canvas with selectable aspect ratios: 1080x1080 (Square), 1920x1080 (16:9), 1600x900 (16:9), 1200x627 (LinkedIn), 1080x1350 (Portrait), 1080x1920 (Story), custom.
• Safe area guides & snapping lines for alignment.
• Grid overlay toggle and configurable spacing.
• Zoom in/out (25%–400%) and pan.

4.2 Backgrounds

• Solid color (picker + hex), gradient presets, custom gradient.
• Optional brand strip (top/bottom) with color.

4.3 Elements

• Element types: Code Block, Text, Arrow.
• Common element actions: add, select, move, resize, rotate, duplicate, delete, bring to front/back, lock, hide.
• Layers panel: reorder, lock, visibility toggles.

4.3.1 Code Block

• Paste/edit code inline.
• Syntax highlighting with selectable themes (e.g., light/dark). Supported languages: Kotlin, Java, extensible.
• Font family selection (e.g., Fira Code, JetBrains Mono), size, line height.
• Optional line numbers.
• Highlight line ranges and single lines; mark as “added” or “removed” styling.
• Indentation width and tab/space display.
• Padding, corner radius, drop shadow.

4.3.2 Text

• Rich text minimal: bold/italic/underline, color, size, line spacing, alignment.
• Font family selection (brand fonts if available).
• Background fill, padding, corner radius, drop shadow.

4.3.3 Arrow

• Styles: straight, curved.
• Properties: color, thickness, arrowhead style (filled/outline), start/end caps.
• Waypoints for curved arrows (2–3 control points).
• Optional text label attached to arrow.

4.4 Selection & Snapping

• Smart guides for center/edge alignment and spacing.
• Magnetic snapping to guides and grid.
• Nudge via arrow keys; modifiers for 1px/10px increments.

4.5 Export

• Formats: PNG and JPEG.
• Resolution: scale factor 1x/2x/3x; max 4096px on longest edge.
• Export metadata: remember last export settings.

4.6 Persistence

• Local storage autosave per snap.
• Import/export snap as JSON file.
• Open recent snaps list.

4.7 Shortcuts

• New snap: Cmd+N; Duplicate: Cmd+D; Delete: Backspace.
• Undo/Redo: Cmd+Z / Shift+Cmd+Z.
• Copy/Paste: Cmd+C / Cmd+V.
• Group/Ungroup: Cmd+G / Shift+Cmd+G.
• Toggle grid: Cmd+; Zoom: Cmd+Plus / Cmd+Minus.

4.8 Settings

• Global defaults: theme, default fonts, line numbers on/off, grid spacing.
• Language detection (best-effort) for code block from pasted content.

6. Data Model (JSON Schema – indicative)

{
  "version": "1.0.0",
  "meta": {"title": "My Snap", "aspect": "16:9", "width": 1920, "height": 1080},
  "background": {
    "type": "solid|gradient|image",
    "solid": {"color": "#101022"},
    "gradient": {"from": "#101022", "to": "#1f1f3a", "angle": 45},
    "image": {"src": "data:url|path", "scale": 1, "x": 0, "y": 0, "blur": 0, "opacity": 1}
  },
  "elements": [
    {
      "id": "el_1",
      "type": "code",
      "x": 200, "y": 180, "width": 800, "height": 420, "rotation": 0,
      "props": {
        "code": "console.log('Hello');",
        "language": "javascript",
        "theme": "dark",
        "fontFamily": "JetBrains Mono",
        "fontSize": 16,
        "lineHeight": 1.4,
        "lineNumbers": true,
        "highlights": [{"from": 2, "to": 3, "style": "focus"}],
        "padding": 24,
        "cornerRadius": 12,
        "shadow": {"blur": 24, "spread": 0, "color": "#00000066"}
      }
    },
    {
      "id": "el_2",
      "type": "text",
      "x": 1040, "y": 180, "rotation": 0,
      "props": {
        "text": "How it works",
        "fontFamily": "Inter",
        "fontSize": 24,
        "color": "#ffffff",
        "bold": true,
        "align": "left",
        "background": {"color": "#00000033"},
        "padding": 8,
        "cornerRadius": 8
      }
    },
    {
      "id": "el_3",
      "type": "arrow",
      "points": [{"x": 980, "y": 220}, {"x": 880, "y": 260}],
      "props": {
        "style": "straight",
        "color": "#60a5fa",
        "thickness": 3,
        "head": "filled"
      }
    }
  ]
}

7. UI Layout

• Top Bar: New/Open, aspect ratio, background settings, export button.
• Left Toolbar: element add (Code/Text/Arrow), move/rotate tools, grid toggle.
• Right Inspector: context panel showing properties for selected element; canvas settings when none selected.
• Bottom Bar: zoom, canvas size, snap guides toggle.
• Canvas: center stage with safe area and grid.

8. Tech Stack Assumptions (modifiable)

• Frontend: React + TypeScript, Vite.
• Canvas: React Konva (Konva.js) for performant transforms and export to image.
• Syntax highlighting: Shiki (serverless, on-the-fly) or Prism.js; pre-bundled themes.
• State: Zustand (simple, fast) + Immer.
• Persistence: LocalStorage for autosave; file import/export for JSON.
• Export: Konva stage to toDataURL(); optional html-to-image for mixed DOM.
• Styling: Tailwind CSS or minimal CSS modules.

9. Milestones

• M1 (MVP, 1–2 weeks): Canvas, add/move/resize elements; backgrounds; basic code highlighting; text; arrows; PNG/JPEG export; local autosave.
• M2: Grid/safe guides, snapping, line numbers & highlights; themes; shortcuts.
• M3: Layers panel, curved arrows, brand strip, custom fonts.
• M4: Import/export JSON; recent snaps; performance polish.

10. Acceptance Criteria (samples)

• Export: Given a 1920x1080 canvas with 3 elements, exporting PNG at 2x produces a 3840x2160 image in < 1s with correct positioning and anti-aliased edges.
• Code Block: Pasting TypeScript auto-detects TS and renders highlighting; toggling line numbers updates instantly; highlighting lines 3–5 changes their background.
• Arrow: Changing thickness updates rendering at 60fps while dragging; arrowhead style persists to export.
• Persistence: Closing and reopening restores last snap state within 1s.

11. Accessibility & Internationalization

• Keyboard operations for select/move/resize; screen-reader labels on buttons.
• Localizable UI strings; default English.

12. Risks & Open Questions

• Font licensing for bundled fonts (JetBrains Mono, Inter).
• Shiki bundle size vs Prism performance and theme parity.
• Very large exports (>4096px) may be slow; consider worker-based rasterization.
• How many languages/themes to ship in MVP?

13. Future Enhancements (post-MVP)

• Templates, brand profiles, watermark/avatars.
• Line diff (add/remove styles), blur/opacity regions.
• Drag-to-connect anchors for arrows.
• SVG export, batch export.
• VS Code extension to send selection → canvas.

---

Owner assumptions are placeholders. Please mark any sections to adjust (features, stack, constraints), and we’ll refine before implementation.