Canvas Layout

Overview

Canvas is the most flexible layout engine, giving you unrestricted control over block placement.

Best for:

• Creative portfolios
• Artistic websites
• Unique, custom layouts
• Designs requiring overlapping elements
• Horizontal scrolling experiences

Canvas Orientations

Canvas supports two orientation modes to suit different design needs:

Vertical Canvas (Default)

• Standard top-to-bottom scrolling behavior
• Content centered horizontally in viewport
• Auto height adjusts to content
• Traditional web layout approach

Horizontal Canvas

• Side-to-side scrolling experience
• Content flows horizontally with scrollable viewport
• Fixed width containers with max-content width
• Ideal for timeline layouts, portfolios, and immersive experiences

Horizontal Canvas Features:

• Automatic wheel scroll translation (vertical scroll becomes horizontal)
• Configurable scroll speed (2x fallback)
• Visual scroll indicators at left/right edges
• Height constraints respect viewport bounds
• Transform origin anchored at top-left (0% 0%)

Positioning Blocks

Drag & Drop

Click and drag blocks to position them anywhere on the canvas. Blocks can be placed with pixel-level precision.

• Single Block Drag - Click and drag any block to reposition
• Multi-Select - Hold Shift or Ctrl/Cmd to select multiple blocks
• Multi-Block Drag - Drag one selected block to move all selected blocks together

Drag Threshold

A 3-pixel movement threshold prevents accidental dragging during clicks, ensuring precise selection control.

Grid Snapping

Enable grid snapping for more structured placement:

• Toggle snap to grid on/off
• Grid size: configurable (20px fallback)
• Grid overlay shows alignment guides when enabled

Layering (Z-Index)

Control block depth with layering:

• Bring to Front - Make block topmost
• Send to Back - Make block bottommost
• Rotation - Blocks support rotation with rotate handles
• Blocks sort by z-index, then by creation order

Orientation-Aware Positioning

Vertical Canvas:

• Transform origin: horizontal center (50% 0%)
• Blocks positioned relative to center axis
• Standard viewport centering

Horizontal Canvas:

• Transform origin: top-left (0% 0%)
• Blocks positioned from left edge
• Scroll-aware placement accounts for current scroll position
• New blocks appear in visible scroll area

Block Sizing

Resize Handles

Different block types have different resize behaviors:

Image/Video/Page Blocks:

• Corner resize handle maintains aspect ratio
• Image blocks: 300px default width
• Rotation handles for artistic positioning

Text Blocks:

• Width-only resizing (240px - 1024px range)
• Default width: 400px
• Height adjusts automatically based on content
• Text editing state prevents dragging during editing

Block Dimensions

Horizontal Canvas Scrolling

When horizontal orientation is enabled, the canvas provides a unique side-scrolling experience:

Wheel Scroll Translation

Vertical mouse wheel movements are automatically converted to horizontal scrolling:

• Wheel Scroll Speed - Configurable multiplier (2x fallback)
• Edge Detection - Scrolling stops at content boundaries
• Page Scroll Integration - At scroll edges, allows page to scroll to next/previous section
• Zoom Override - Ctrl/Cmd + wheel still controls zoom level

Scroll Indicators

Visual indicators show scroll position and available content:

• Left Indicator - Visible when content exists to the left
• Right Indicator - Visible when content exists to the right
• Opacity Control - Indicators fade at scroll boundaries (atStart/atEnd detection)
• Background Integration - Uses canvas backgroundColor for seamless appearance

Content Width Management

Minimum Width: Uses maxWidth (1920px fallback) as baseline for consistent positioning

Height Constraints

In horizontal mode, height is intelligently managed:

• Viewport Height Mode - Capped at 100vh minus navigation offset
• Auto Height Mode - Limited to available viewport space
• Navigation Detection - Automatically detects stacked vs overlay navigation

Liquid Scaling System

Liquid Scaling is Canvas layout's responsive solution that automatically adapts your design to different screen sizes without breaking your carefully crafted positioning.

How Liquid Scaling Works

Instead of traditional responsive breakpoints, Liquid Scaling applies a dynamic scale factor to your entire canvas based on the viewport width:

• Desktop View (1200px+) - Full scale (0.5x - 2.0x range)
• Tablet View (768-1199px) - Proportional scaling based on container width
• Mobile View (under 500px) - Automatic scale reduction with configurable minimum
• Mobile Optimization - Reduces padding to 10px for better space utilization

Scale Calculation

The scaling system uses your canvas maxWidth (1920px fallback) as the base reference:

Scale Factor = Container Width / Max Canvas Width

Example:

• Canvas Max Width: 1920px
• Mobile Container: 400px
• Calculated Scale: 400px / 1920px = 0.21x
• Applied Scale: max(0.3, 0.21) = 0.3x (respects mobile minimum)

Mobile Scale Factor

Configure the minimum scale for mobile devices to ensure usability (0.3 fallback):

Liquid Scaling vs Fixed Layouts

Orientation-Specific Scaling

Vertical Canvas:

• Transform origin: 50% 0% (horizontal center)
• Centered scaling maintains visual balance

Horizontal Canvas:

• Transform origin: 0% 0% (top-left)
• Left-aligned scaling for consistent scroll experience

Canvas Viewport & Controls

Manual Zoom Controls

• Zoom In/Out - Ctrl/Cmd + scroll wheel (0.3x - 3.0x range)
• Pan View - Click and drag canvas background to pan (scale-aware movement)
• Reset View - Return to 1.0x zoom and center position

Canvas Bounds

The canvas operates within a maximum content area (1920px fallback width) to maintain design consistency across different viewport sizes.

Viewport Centering

Canvas content positioning varies by orientation:

Vertical Canvas:

• Transform origin set to horizontal center (50% 0%)
• Liquid scaling maintains visual center
• Pan operations respect center positioning

Horizontal Canvas:

• Transform origin set to top-left (0% 0%)
• Content flows from left edge
• Scroll position determines visible area

Visual Guides

Toggle visual guides through the editor interface:

• Canvas Bounds - Shows the maximum content area with center crosshair
• Grid Overlay - Alignment grid for precise positioning
• Guides are controlled by editor events, not persistent settings

Panning System

Scale-aware panning adjusts movement speed based on current zoom level:

• Zoomed Out (scale under 1.0x) - Faster movement for easier navigation
• Zoomed In (scale over 1.0x) - Slower movement for precise positioning
• Pan Position Persistence - Automatically saved with debounced updates (500ms)

Canvas Height Modes

Choose how the canvas determines its vertical space:

Auto Height Calculation

In Auto mode, canvas height is intelligently calculated:

1. Content Measurement - Scans all block positions and dimensions using DOM measurement
2. Pan Adjustment - Accounts for current pan offset and elements above y:0
3. Padding Application - Uses configured section margins (respects user's padding choices)
4. Minimum Enforcement - Ensures 600px minimum for usability (500px when elements exist)
5. Scale Compensation - Adjusts for current zoom level with debounced updates

Empty Canvas Default: 600px for better initial experience

Navigation Integration

Height calculations automatically detect and compensate for navigation:

• Overlay Navigation - Fixed/absolute positioned nav doesn't affect height
• Stacked Navigation - Static/relative positioned nav reduces available height
• Vertical Sidebar Detection - Tall navigation (over 80% viewport height) treated as sidebar

Horizontal Canvas Height

In horizontal orientation, height management has special considerations:

• Viewport Height Modes - Automatically capped at available viewport space
• Auto Height Mode - Limited to prevent vertical scrolling conflicts
• Navigation Offset - Compensates for stacked navigation to prevent overflow

Adding Blocks

Smart Block Placement

New blocks are intelligently positioned based on viewport visibility and configuration:

Viewport-Centered Placement:

• Blocks appear at the center of your current view
• Accounts for current zoom and pan position
• Cascading offset (25px) prevents overlap for multiple additions
• Element counter tracks placement for consistent positioning

Orientation-Aware Placement:

Vertical Canvas:

• Centers blocks horizontally in viewport
• Uses transform-adjusted coordinates
• Pan-aware positioning

Horizontal Canvas:

• Positions blocks in currently visible scroll area
• Accounts for scroll position: (scrollLeft + containerWidth / 2) / scale
• Maintains horizontal flow consistency

Position Options:

• Bottom Placement - New blocks added after existing content using element count for z-index
• Top Placement - New blocks added with maximum z-index + 1 and negative timestamp order

Position Calculation Process

1. Detect visible canvas area accounting for scroll position
2. Find viewport center point within canvas bounds
3. Convert to canvas coordinates with transform compensation
4. Apply cascading grid for multiple uploads (wrapping rows when needed)
5. Use maxWidth-based positioning for consistent placement

Text Blocks

• Default Dimensions - 400px width, auto height (minimum 50px)
• Font Settings - Uses preference store default font size
• Content - Starts with "Enter text here" placeholder and HTML
• Styling - Satoshi font family, unified style system for consistent formatting
• Width Constraints - Resizable from 240px to 1024px

Image Blocks

• Default Width - 300px for new uploads and viewport-centered placement
• Aspect Ratio - Automatically calculated and cached for performance
• Upload Processing - Dimensions cached in imageCache for faster subsequent loads
• Grid Cascading - Multiple uploads arrange in flowing grid pattern

Block Positioning Migration

Canvas automatically detects and fixes blocks migrated from other layouts:

• From Justified Layout - Repositions oversized images (over 1000px) at origin (0,0)
• From Fixed Width Layout - Repositions square 200x200px blocks
• Aspect Ratio Preservation - Maintains proper proportions during migration

Auto Layout System

Intelligent algorithms to organize your canvas content with visual feedback:

Layout Algorithms

Layout Options

Auto Layout Process

1. Layout Calculation - Apply chosen algorithm with maxWidth constraints and viewport bounds
2. Visual Feedback - Canvas opacity reduces to 0.7 during processing
3. Parallel Updates - Batch update all block positions simultaneously for performance
4. Overlap Resolution - Intelligent overlap detection and resolution
5. View Reset - Automatically reset zoom to 1.0x and center pan
6. Completion Animation - Smooth opacity restoration with progress tracking

Performance Features:

• Progress tracking with status events (started, applying, completed, error)
• Automatic height recalculation based on new element positions
• Maximum 5-second timeout prevents hanging operations
• Movement detection triggers completion phase

Orientation Compatibility

Auto layout algorithms work with both canvas orientations:

• Vertical Canvas - Standard algorithm application with centered positioning
• Horizontal Canvas - Algorithms adapt to horizontal flow and scrolling context
• Viewport Integration - Uses actual canvas dimensions (maxWidth) for consistent results

Layout Configuration

Canvas layout supports various configuration options that customize behavior and appearance. These settings use fallback values when not explicitly configured.

Core Canvas Options

Scrolling Options

Padding & Spacing

Grid & Alignment

Visual Options

Note: Canvas scale and pan positions are automatically saved to preserve your workspace view between sessions.