Skip to content

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:

  1. New users — the onboarding gesture guide (this is the source of truth for the in-app first-run guide).
  2. 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

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:

  1. Two fingers move the world (orbit / pan / pinch) — so users never feel “stuck”.
  2. One finger does the tool — tap to select, drag to move.
  3. Handles appear on a selected object — drag a corner to resize, the ring to rotate.
  4. Long-press for the action menu (duplicate / delete / paint).
  5. The HUD chips (⌁ Snap, ◫ Multi, Done) and ↶ ↷ Undo/Redo replace the keyboard.

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) + custom WalkthroughControls (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.