MiniFrame

MiniFrame is a high-performance, browser-based vector canvas editor where users can create, position, style, and arrange visual shapes. Built to demonstrate advanced graphics rendering pipeline mechanics, selection state management, and real-time snapping interactions.

---

Key Features

• Multi-Shape Support: Draw, scale, and inspect Rectangles, Ellipses, and wrapping Text elements.
• Dynamic Interaction Engine:
  • Click-and-Drag Creation: Select a drawing tool and click-drag on the canvas to outline shapes.
  • Screen-Space Resize Handles: Corner resizing widgets that maintain a constant clickable size independent of the current canvas zoom level.
  • Viewport Panning & Zoom: Pan the canvas smoothly by holding Space + dragging or using the middle mouse button. Zoom incrementally up to 20x or run a "Zoom to Fit" algorithm to center all active shapes in the window.
• Real-Time Snapping Guides: Automatic alignment snap lines (vertical and horizontal guides) appear when a shape's center or edges align within a 5-pixel threshold of other static shapes.
• Professional Undo/Redo History: Implements double-stack history snapshots. Saves coordinates, sizes, styles, and layer order changes on mouse-up (not on every frame of dragging) to keep history commits clean.
• Interactive Layers Control: List elements ordered from top to bottom. Click layers to select shapes, and shift their stack depth via layer ordering buttons (Bring Forward, Send Backward, Bring to Front, Send to Back).
• Import / Export Operations:
  • JSON Serialization: Save and load the complete canvas model as structured JSON text.
  • High-Res PNG Generation: Renders all shapes onto an offscreen canvas bounding box with margin padding, skipping selection outlines and background grids for a clean asset export.
• Desktop Keyboard Shortcuts:
  • V / R / O / T / H — Switch tools (Select, Rectangle, Ellipse, Text, Pan)
  • Space (Hold) — Temporary Pan tool toggle
  • Delete / Backspace — Delete selected shape
  • Ctrl/Cmd + Z — Undo
  • Ctrl/Cmd + Shift + Z / Ctrl/Cmd + Y — Redo
  • Ctrl/Cmd + D — Duplicate shape
  • Ctrl/Cmd + A — Select all shapes
  • Arrow keys — Precision nudging (adds Shift key for 10px fast nudge)

---

Tech Stack

• Framework: React 19 + Vite (Fast HMR development server)
• Language: TypeScript (Strong compiler contracts for editor types)
• State Store: Zustand (Sleek document state decoupled from the DOM)
• Viewport Workspace: HTML5 Canvas 2D API (High-performance pixel rendering)
• UI Panels: Tailwind CSS (Dark slate theme, frosted glassmorphism overlays)
• Icons: Lucide React

---

Project Architecture

MiniFrame separates visual editor concerns cleanly:

• State & Transactions (src/editor/store.ts & src/editor/history.ts): Zustand handles document records (objects), tool preferences, active selections, and coordinate states. State mutations commit changes to double-history stacks on interaction completion.
• Coordinate Spaces (src/editor/geometry.ts): Maps screen space (mouse coordinates relative to the DOM element) to canvas world space (taking active zoom and pan translations into account) and back: $$\text{worldX} = \frac{\text{screenX} - \text{panX}}{\text{zoom}}$$
• Hit Testing (src/editor/hitTest.ts): Iterates shape models from topmost to bottommost (highest zIndex first). Executes custom bounding calculations or algebraic ellipse boundary formulas to verify clicks.
• Rendering Pipeline (src/editor/renderer.ts): Projective canvas loops. Whenever properties change, the canvas clears, draws a responsive background grid, translates and scales the context, draws shapes, and overlays screen-space selection boundaries.

miniframe/
  src/
    components/
      Topbar.tsx           # Import/export buttons, undo/redo icons, trash
      Toolbar.tsx          # Active tool selector (Select, Rect, Ellipse, Text, Pan)
      CanvasStage.tsx      # Main canvas workspace viewport, zoom buttons, event handlers
      PropertiesPanel.tsx  # Coordinate inputs, color pickers, sliders for selected shapes
      LayersPanel.tsx      # Vertical stack of active objects with layer ordering triggers
    editor/
      types.ts             # Data models for shapes, points, interactions, and stores
      store.ts             # Zustand state container, drag/resize state machines
      history.ts           # Undo/redo stack transitions and deep comparison checks
      hitTest.ts           # World-coordinate raycasts and screen-space handle checks
      renderer.ts          # Drawing loops, infinite grids, outlines, snap guidelines
      geometry.ts          # Screen-to-world conversion matrices and bounding math
      keyboard.ts          # Event bindings for shortcuts (nudge, duplicate, undo/redo)
      export.ts            # JSON formatting and offscreen canvas PNG exporter
    utils/
      id.ts                # Short unique ID generator
    App.tsx                # Stitching of side panels and viewport
    main.tsx               # Client entrypoint mounting App
    index.css              # Custom scrollbars, tailwind imports, reset styles

---

Getting Started

1. Install Dependencies

Clone the repository and install packages:

npm install

2. Run Development Server

Start the local server with hot module reloading (HMR) at http://localhost:5173/:

npm run dev

3. Build for Production

Verify typescript compilation and compile static assets to /dist:

npm run build