Spatial Canvas Layout
Relevant source files
The following files were used as context for generating this wiki page:
The Spatial Canvas Layout is a visual thinking environment within ThinkEx that allows users to organize knowledge assets—such as PDFs, videos, notes, and quizzes—spatially on a large digital desk. Unlike traditional linear note-taking apps, this layout enables users to see multiple sources side-by-side, spot patterns, and connect dots between disparate pieces of information. Sources: README.md:16-24
Core Architecture and Components
The canvas is built as a hierarchical structure of React components that manage state, user interaction, and item rendering.
Component Hierarchy
The layout is orchestrated by the WorkspaceSection, which serves as the primary container for the canvas area. It manages the high-level UI state, including item selection, deletion logic, and modal management. Sources: src/components/workspace-canvas/WorkspaceSection.tsx:88-144
This diagram shows the component hierarchy from the main section down to individual card content.
Key Functional Components
| Component | Responsibility |
|---|---|
WorkspaceSection | Handles global canvas events (shortcuts, bulk deletes), selection state, and coordinates with workspace operations. |
WorkspaceContent | Manages the display mode (Grid vs JSON), handles file uploads, and provides auto-scroll logic during drag operations. |
WorkspaceGrid | The underlying grid system that manages the positioning (x, y, w, h) of individual cards. |
WorkspaceCardContent | A polymorphic renderer that displays content based on the item type (PDF, Quiz, Document, etc.). |
Sources: src/components/workspace-canvas/WorkspaceSection.tsx:146-210, src/components/workspace-canvas/WorkspaceContent.tsx:43-100
Asset Positioning and Grid Logic
Items on the canvas are positioned using a coordinate system defined in the item's layout property. This includes horizontal and vertical coordinates (x, y) and dimensions (w, h).
Automated Layout Generation
When a workspace is automatically generated via the autogen API, the system uses predefined layout footprints to ensure a logical arrangement of different item types. Sources: src/app/api/workspaces/autogen/route.ts:43-50
The automated layout flow ensures that generated documents, quizzes, and videos do not overlap.
Default Dimensions (Autogen)
| Item Type | Width (w) | Height (h) | Default X/Y |
|---|---|---|---|
| YouTube | 2 | 7 | 0, 0 |
| Document | 2 | 9 | 2, 0 |
| Quiz | 2 | 13 | 0, 7 |
| 1 | 4 | Dynamic | |
| Image | 2 | 8 | Dynamic |
Sources: src/app/api/workspaces/autogen/route.ts:44-49, src/app/api/workspaces/autogen/route.ts:250-275
Canvas Interaction Systems
The spatial canvas supports several interaction patterns to manage large sets of information.
Selection and Bulk Actions
Users can select cards via individual clicks or by using a MarqueeSelector for rectangular region selection. Selected items are tracked in a selectedCardIds set, enabling bulk operations. Sources: src/components/workspace-canvas/WorkspaceSection.tsx:165-200
- Bulk Delete: Removes all selected items from the
AgentState. Sources: src/components/workspace-canvas/WorkspaceSection.tsx:265-274 - Bulk Move: Moves multiple selected items into a folder. Sources: src/components/workspace-canvas/WorkspaceSection.tsx:288-297
Navigation and Auto-Scroll
To maintain context in a large spatial area, the system implements:
- Auto-Scroll: Triggered during drag-and-drop operations when an item is moved near the edge of the viewport. Sources: src/components/workspace-canvas/WorkspaceContent.tsx:75-78
- Breadcrumbs: Used in conjunction with
activeFolderIdto navigate deep folder structures without losing the spatial context of the parent. Sources: src/components/workspace-canvas/WorkspaceContent.tsx:135-139
Content Rendering Modes
The canvas supports two primary viewing modes for the entire workspace:
- Grid View: The default spatial arrangement using
WorkspaceGrid. - JSON View: A technical view rendering the underlying
AgentStateas a formatted JSON object, allowing for copying or downloading the workspace data. Sources: src/components/workspace-canvas/WorkspaceContent.tsx:114-145
Polymorphic Card Content
Individual cards render differently based on their type. Sources: src/components/workspace-canvas/WorkspaceCardContent.tsx:48-60
Card rendering logic branches based on item type to provide specialized viewers for various media.
Context and AI Integration
The spatial arrangement of cards is not just visual; it informs the AI's understanding of the workspace.
Metadata Formatting
The system formats item metadata—including the "virtual path" (folder structure) and whether an item is "currently viewing"—into a specialized <workspace> XML-like block. This allows the AI assistant to prioritize items that are open or selected on the canvas. Sources: src/lib/utils/format-workspace-context.ts:100-115
Priority Logic
- Selected Cards: Primary context for the AI. Sources: src/lib/utils/format-workspace-context.ts:117-122
- Currently Viewing: Highest priority items; used to resolve ambiguous references like "this" or "what I'm looking at". Sources: src/lib/utils/format-workspace-context.ts:145-155
Summary
The Spatial Canvas Layout provides a high-agency environment for knowledge synthesis. By combining a flexible grid-based positioning system with specialized renderers and AI-aware context formatting, it allows users to transcend the limitations of linear document management and leverage spatial reasoning in their workflows. Sources: README.md:16-29, src/lib/utils/format-workspace-context.ts:100-110