Touch gestures cheatsheet
Generated from
docs/features/touch-gestures-cheatsheet.md— edit that file, not this page.
Canonical reference for the touch/iPad interaction model of the Tinkerspace 3D editor. Two audiences:
- New users — the onboarding gesture guide (this is the source of truth for the in-app first-run guide).
- Everyone — the command / gesture cheat sheet you can pull up any time.
Status: proposed touch redesign. Grounded 1:1 on the shipped desktop interactions (
SelectionTool,CladdingTransformHandles,CutoutTransformHandles,WallDrawingTool,CarpentrySchematic,OrbitControls). Nothing here is invented — the work is re-binding those to touch and growing the hit targets. Visual companion:../wireframes/ipad-touch-wireframes.html.
1. The grammar — finger count decides intent
Section titled “1. The grammar — finger count decides intent”One rule resolves every conflict: one finger acts on what you touch, two fingers always drive the camera. No gesture ever means two things.
| Gesture | Means | Notes |
|---|---|---|
| ☝ One finger | Act — run the active tool on whatever is under it (select, move, draw a wall, toggle a cell) | On empty space with the Select tool = marquee box-select |
| ✌ Two fingers | Navigate the camera — orbit (3D) / pan (2D), pinch to zoom | Never manipulates an object; frees one finger for direct manipulation |
| ✋ Long-press (~0.4s) | Context menu — Duplicate · Delete · Paint · Rotate · Copy · Lock | Replaces right-click and the tiny in-scene toolbar |
| ☝☝ Double-tap | Drill / fit — enter edit-in-group on a grouped item; zoom-to-fit on empty canvas | Matches today’s double-click behavior |
2. Desktop keys → touch equivalents (the hidden dependencies)
Section titled “2. Desktop keys → touch equivalents (the hidden dependencies)”Almost every current interaction leans on a modifier key. Touch has none — each maps to an always-visible control.
| Today (mouse + key) | Touch equivalent | Where it lives |
|---|---|---|
Alt — bypass snap |
⌁ Snap toggle (default on) | Selection HUD, near the object |
Shift — multi-select / detach corner |
◫ Multi toggle · deliberate drag to detach | Selection HUD |
⌘Z / ⌘Y — undo / redo |
↶ ↷ buttons | Top bar (left) |
⌘D / ⌘C / ⌘V — duplicate · copy · paste |
Long-press context menu | On the object |
Esc — cancel in-flight tool |
Done / Cancel button · or tap-away | Tool HUD (wall chain, zones…) |
| Right-click | Long-press | On the object |
Tool hotkeys V W O … |
Dock tiles (56×56) | Bottom-center dock |
3. Camera — by view mode
Section titled “3. Camera — by view mode”| Mode | Gesture | Notes |
|---|---|---|
| 2D · top-down plan | ✌ drag = pan · pinch = zoom | No orbit (camera locked overhead). Height handles auto-hide; steppers do vertical edits. |
| 3D · perspective | ✌ drag = orbit · pinch = zoom · ✌ hold+drag = pan | Camera auto-locks the instant a handle/object drag starts. |
| Walk · first-person | left half = move stick (WASD) · right half drag = look around | No pointer-lock on touch → on-screen sticks + Build/Paint toggles + tap hotbar. |
4. Manipulate a selected object — one finger on the enlarged handle
Section titled “4. Manipulate a selected object — one finger on the enlarged handle”| Action | Gesture | Feedback / notes |
|---|---|---|
| Move | ☝ drag the body on the floor (8px deadzone) | Red alignment + amber spacing guides. Snap governed by ⌁ toggle. |
| Resize | ☝ drag a ~44px corner handle (+ hit-slop) | Dimension-snaps to neighbours; min-size clamp. Exact values → Size sheet steppers. |
| Rotate | ☝ drag the rotate ring | Snaps 15° with a live degree readout. ⌁ off = free angle. |
| Height / elevate | ☝ drag the top (green) or base (purple) vertical handle | Snaps to floor / ceiling / neighbour. 3D only — hidden in 2D. |
5. Full command cheat sheet — every scenario
Section titled “5. Full command cheat sheet — every scenario”| Area | Scenario | Touch gesture | Feedback |
|---|---|---|---|
| Select | Pick / deselect | ☝ tap object / empty | Outline + HUD appear |
| Select | Multi-select | ☝ drag empty (marquee) · or ◫ Multi + tap | Rubber-band rect; count badge |
| Move | Slide furniture / wall / opening | ☝ drag body (8px deadzone) | Red align + amber spacing guides |
| Resize | Cabinet width / depth | ☝ drag corner handle | Dimension snap; live size chip |
| Rotate | Spin an item | ☝ drag rotate ring | 15° snap; degree readout |
| Height | Top / base elevation | ☝ drag vertical handle | Floor / ceiling snap line |
| Camera | Orbit / pan / zoom | ✌ drag · pinch | — |
| Carpentry | Open / close door · drawer | ☝ tap cell (≥44px grid) | 3D syncs live |
| Carpentry | Add / remove row · col | ± steppers (44px) | Grid reflows |
| Carpentry | Move a cutout | ☝ drag in Cells sheet / face handle in 3D | Snaps flush to carcass |
| Wall | Draw a run | ☝ tap to drop corners · Done to end | Angle + length badge; snap ring |
| Wall | Edit / detach a corner | ☝ drag corner node (deliberate = detach) | Align guides; angle readout |
| Object | Duplicate / Delete / Paint | ✋ long-press → menu | Menu at finger |
| Delete | Delete tool active | ☝ tap target | Removed immediately (undoable) |
| System | Undo / redo | ↶ ↷ top-bar buttons | Step boundary on pointer-up |
6. Suggested onboarding order (in-app first-run guide)
Section titled “6. Suggested onboarding order (in-app first-run guide)”Teach the grammar first, then the exceptions:
- Two fingers move the world (orbit / pan / pinch) — so users never feel “stuck”.
- One finger does the tool — tap to select, drag to move.
- Handles appear on a selected object — drag a corner to resize, the ring to rotate.
- Long-press for the action menu (duplicate / delete / paint).
- The HUD chips (⌁ Snap, ◫ Multi, Done) and ↶ ↷ Undo/Redo replace the keyboard.
Implementer notes
Section titled “Implementer notes”Source interactions to re-bind (all in packages/engine/src/react/ unless noted):
- Selection, move, rotate, marquee, edit-in-group —
SelectionTool.tsx - Corner-resize / height / base handles —
CladdingTransformHandles.tsx(handle-scale.tsx→HANDLE_TARGET_PX) - Cutout face / cap / radius handles —
CutoutTransformHandles.tsx - Wall draw / corner drag / detach / snap —
WallDrawingTool.tsx,CornerHandles.tsx - Carpentry cells / cutouts / row-col —
apps/web/app/projects/[id]/CarpentrySchematic.tsx - Camera — drei
OrbitControls(3D/2D) + customWalkthroughControls(walk) - Undo/redo + shortcuts —
apps/web/app/projects/[id]/ProjectClient.tsx
Touch targets today are well under Apple’s 44pt minimum (top-bar 32px, handles 22px, carpentry cells ~20px); the redesign sizes every tap surface to 44pt min / 56pt primary and replaces hover-only affordances with always-visible controls + long-press menus.