Skip to content

Floorplan editor

Generated from openspec/specs/floorplan-editor/spec.md — edit that file, not this page.

The floorplan editor is the main design surface at /projects/[id]: a full-screen 3D canvas where a designer draws walls, cuts openings, places catalog furniture, builds carpentry, and walks through the unit in first person. It exists to let one or more collaborators edit a project’s floorplan in real time with every change automatically synced and undoable, across desktop pointer input and touch/iPad gestures.

Requirement: Collaborative Editing Through a Single Model

Section titled “Requirement: Collaborative Editing Through a Single Model”

Every edit a tool makes SHALL be applied through the shared floorplan model rather than local-only UI state, so that any change is simultaneously collaborative (visible to other connected users) and undoable.

Scenario: A tool mutation is visible to a peer

Section titled “Scenario: A tool mutation is visible to a peer”
  • WHEN one collaborator draws a wall, places furniture, or edits a property in the editor
  • THEN every other collaborator connected to the same project sees the change applied without a manual refresh or sync action

Scenario: Local-only UI state never represents plan geometry

Section titled “Scenario: Local-only UI state never represents plan geometry”
  • WHEN the editor renders walls, openings, scene items, cladding, or annotations
  • THEN the rendered geometry is derived from the shared model’s current state, not from a separate copy kept only in the local UI

Requirement: View Mode Switching (2D / 3D / Walk)

Section titled “Requirement: View Mode Switching (2D / 3D / Walk)”

The system SHALL support switching the editor’s camera between a flat 2D plan view, an orbiting 3D perspective view, and a first-person walkthrough view, without altering the underlying floorplan data.

Scenario: Switching to 2D shows plan symbols

Section titled “Scenario: Switching to 2D shows plan symbols”
  • WHEN the user switches the view mode to 2D
  • THEN the canvas shows flat printed-plan symbols — wall footprints, door swing arcs, window pane lines, and dimensions — instead of extruded 3D geometry

Scenario: Switching to 3D shows perspective geometry

Section titled “Scenario: Switching to 3D shows perspective geometry”
  • WHEN the user switches the view mode to 3D
  • THEN the canvas shows an orbiting perspective camera over full extruded walls, ceiling, and materials

Scenario: Switching to Walk enters first-person mode

Section titled “Scenario: Switching to Walk enters first-person mode”
  • WHEN the user switches the view mode to Walk
  • THEN the camera moves to a first-person viewpoint at the user’s saved eye height inside the unit

Requirement: A room keeps its name when its walls are edited

Section titled “Requirement: A room keeps its name when its walls are edited”

The system SHALL keep a user-supplied room name attached to that room when wall edits change which corners enclose it, re-associating the name with the room now occupying the same place. A name that cannot be placed SHALL be retained as recoverable rather than discarded. A name the user gave once is not something an unrelated wall edit may take away — and because the assistant and the recipe library both address rooms by name, losing it makes the room unreachable, not merely unlabelled.

Scenario: A wall edit that reshapes a room keeps its name

Section titled “Scenario: A wall edit that reshapes a room keeps its name”
  • WHEN walls are edited so a named room gains, loses, or replaces one of its corners
  • THEN the name still applies to that room, and the assistant and recipe library can still address it by that name

Scenario: A name that no longer describes anywhere is kept, not dropped

Section titled “Scenario: A name that no longer describes anywhere is kept, not dropped”
  • WHEN a stored name refers to a set of corners that no longer encloses a room anywhere in the plan
  • THEN the name is retained as an unplaced name rather than silently discarded
  • WHEN two stored names would resolve to the same room
  • THEN exactly one is applied, and the same one for every collaborator viewing the plan

Requirement: Choosing a room to work on from the plan

Section titled “Requirement: Choosing a room to work on from the plan”

The system SHALL let the user choose which room they are working on by clicking it in the 2D plan view, and SHALL make the chosen room identifiable on screen. Plan view is the one view in which every room is visible at once, so the drawing itself is the room picker; without this, a room can only be worked on if something else — an assistant result, a label — named it first.

Scenario: Clicking a room’s floor chooses it

Section titled “Scenario: Clicking a room’s floor chooses it”
  • WHEN the editor is in 2D and the user clicks inside a room’s floor area
  • THEN that room becomes the room being worked on and the camera frames it

Scenario: The chosen room is named on screen

Section titled “Scenario: The chosen room is named on screen”
  • WHEN a room is the one being worked on
  • THEN its name is shown, so which room the editor considers active does not depend on the camera happening to still be framing it

Scenario: Choosing a room does not disturb the design

Section titled “Scenario: Choosing a room does not disturb the design”
  • WHEN the user chooses a room from the plan
  • THEN no furniture, wall or opening is moved, added or removed, and the choice is not something the user has to undo

Scenario: Clicking outside every room chooses nothing

Section titled “Scenario: Clicking outside every room chooses nothing”
  • WHEN the user clicks a point in 2D that falls in no room
  • THEN the room being worked on is left as it was, rather than cleared or guessed at from the nearest room

Scenario: A click that a tool wants is not a room choice

Section titled “Scenario: A click that a tool wants is not a room choice”
  • WHEN a drawing, placement or manipulation tool is active and consumes the click
  • THEN the click does not also choose a room, so choosing a room never competes with the gesture the user meant

The system SHALL support a read-only View mode that pins the canvas to the Select tool, distinct from Edit mode where every tool is selectable.

  • WHEN the editor is in View mode
  • THEN the active tool remains Select and the user cannot activate a drawing, placement, or deletion tool

Requirement: Single Active Tool With Return-to-Select

Section titled “Requirement: Single Active Tool With Return-to-Select”

Exactly one tool SHALL be active in the editor at a time, and a one-shot tool (a tool that completes after a single placement or action) SHALL return the editor to the Select tool when it finishes, unless the user explicitly enters a mode where placement repeats.

Scenario: Placing a furniture item returns to Select

Section titled “Scenario: Placing a furniture item returns to Select”
  • WHEN the user places a catalog furniture item with the Furniture tool
  • THEN after the item is placed, the active tool reverts to Select
  • WHEN the user presses Escape while a drawing or placement tool is active
  • THEN the editor exits that tool and the active tool becomes Select

Requirement: Multi-Entity Selection and Property Editing

Section titled “Requirement: Multi-Entity Selection and Property Editing”

The system SHALL let the user select one or more walls, openings, scene items, cladding, or solids, and edit their properties through a selection-driven panel.

Scenario: Selecting a scene item opens its properties

Section titled “Scenario: Selecting a scene item opens its properties”
  • WHEN the user clicks a placed furniture item with the Select tool
  • THEN the item becomes the current selection and its editable properties (position, rotation, dimensions, material) are shown in the properties panel

Scenario: Switching tools clears the selection

Section titled “Scenario: Switching tools clears the selection”
  • WHEN the user activates a different tool while an entity is selected
  • THEN the previous selection is cleared

Requirement: Selecting a wall never moves it

Section titled “Requirement: Selecting a wall never moves it”

The system SHALL treat a click on a wall as a selection only, and SHALL NOT displace the wall or the walls sharing its corners unless the pointer travels far enough to be a deliberate drag — measured so that the distance permitted does not change with the zoom level. Once a wall drag does begin, the system SHALL report how far the wall has moved while the drag is live, and SHALL restore the wall’s original position if the drag is cancelled.

Scenario: A click with pointer drift leaves the geometry untouched

Section titled “Scenario: A click with pointer drift leaves the geometry untouched”
  • WHEN the user presses and releases on a wall body with only incidental pointer movement, at any zoom level
  • THEN the wall and every wall sharing its corners stay at their original coordinates, and no undo entry is created

Scenario: A deliberate drag starts from where it was recognised

Section titled “Scenario: A deliberate drag starts from where it was recognised”
  • WHEN the pointer travels past the drag threshold on a movable wall
  • THEN the wall begins moving from that point rather than jumping by the distance already travelled, and a live readout shows the distance moved

Scenario: Cancelling a wall drag puts it back

Section titled “Scenario: Cancelling a wall drag puts it back”
  • WHEN the user presses Escape during a wall drag, or the browser cancels the gesture
  • THEN the wall’s corners return to their pre-drag positions rather than keeping the displacement

Requirement: Per-User Undo and Redo Excluding Remote Edits

Section titled “Requirement: Per-User Undo and Redo Excluding Remote Edits”

The system SHALL let each user undo and redo their own edits without undoing edits made concurrently by other collaborators.

Scenario: Undo reverts only the local user’s last change

Section titled “Scenario: Undo reverts only the local user’s last change”
  • WHEN a user issues undo after making an edit, while a peer has made unrelated edits in the same session
  • THEN only the local user’s edit is reverted; the peer’s edits remain in place
  • WHEN a user issues redo immediately after an undo
  • THEN the previously undone change is reapplied

Requirement: Asset Placement With Snap-to-Surface Stacking

Section titled “Requirement: Asset Placement With Snap-to-Surface Stacking”

The system SHALL let the user place a catalog asset onto the floor, a wall, or the top surface of another placed item, with placement on a supporting item causing the new item to follow that item if it later moves.

Scenario: Item dropped on a surface follows its anchor

Section titled “Scenario: Item dropped on a surface follows its anchor”
  • WHEN the user places a catalog item on top of another placed item’s surface (for example a bottle on a shelf)
  • THEN the new item is attached to that surface, and moving the supporting item moves the attached item with it

Requirement: Idea Pins for Undecided Design Spots

Section titled “Requirement: Idea Pins for Undecided Design Spots”

The system SHALL let the user drop a placeholder pin at any point on the floor to mark an undecided design idea, without placing any catalog geometry.

Scenario: Placing an idea pin adds no scene geometry

Section titled “Scenario: Placing an idea pin adds no scene geometry”
  • WHEN the user drops an idea pin on the floor
  • THEN a pin marker appears at that location and no wall, opening, or scene item is added to the plan

Scenario: Opening a pin lets the user attach a note

Section titled “Scenario: Opening a pin lets the user attach a note”
  • WHEN the user taps an existing idea pin
  • THEN an editor opens where the user can set the pin’s text, a link, or an image, or delete the pin

Requirement: Touch Finger-Count Camera Routing

Section titled “Requirement: Touch Finger-Count Camera Routing”

On touch input, the system SHALL route one-finger gestures to the active tool and two- or three-finger gestures to camera movement, so that camera control and tool interaction never both respond to the same touch.

Scenario: One finger acts on the touched object

Section titled “Scenario: One finger acts on the touched object”
  • WHEN the user touches and drags with a single finger over a wall, opening, or scene item
  • THEN the active tool (for example Select, dragging the item) responds, and the camera does not orbit or pan

Scenario: Two fingers orbit or pan the camera even with a selection active

Section titled “Scenario: Two fingers orbit or pan the camera even with a selection active”
  • WHEN the user places two fingers on the canvas and drags, regardless of whether an entity is currently selected
  • THEN the camera orbits (in 3D) or pans (in 2D) and no tool receives the gesture

Scenario: Three fingers translate the view

Section titled “Scenario: Three fingers translate the view”
  • WHEN the user places three fingers on the canvas and drags
  • THEN the camera translates without rotating or zooming

On touch input, the system SHALL provide a box-select gesture equivalent to the desktop Shift-drag marquee.

Scenario: Two-finger hold-then-drag starts a marquee

Section titled “Scenario: Two-finger hold-then-drag starts a marquee”
  • WHEN the user holds two fingers stationary on empty floor for about a third of a second and then drags
  • THEN a selection box grows from the hold point, and releasing the fingers selects every wall or opening intersecting the box

Requirement: Touch Long-Press Action Sheet

Section titled “Requirement: Touch Long-Press Action Sheet”

On touch input, the system SHALL offer a long-press gesture on any selectable entity that opens an action menu, standing in for the desktop right-click context menu.

Scenario: Long-pressing an item opens actions

Section titled “Scenario: Long-pressing an item opens actions”
  • WHEN the user holds a finger on a wall, opening, scene item, cladding, or solid for about 450 ms without moving
  • THEN an action menu appears near the touch point offering at least Duplicate, Delete, and Deselect

Requirement: Touch Tap-to-Undo and Tap-to-Redo

Section titled “Requirement: Touch Tap-to-Undo and Tap-to-Redo”

On touch input, outside Walk mode and outside text-entry fields, the system SHALL provide multi-finger tap gestures equivalent to the desktop undo/redo keyboard shortcuts.

Scenario: Two-finger tap undoes the last change

Section titled “Scenario: Two-finger tap undoes the last change”
  • WHEN the user taps the canvas with two fingers briefly and without significant movement, while not in Walk mode and not focused in a text field
  • THEN the most recent local edit is undone
  • WHEN the user taps the canvas with three fingers briefly and without significant movement, under the same conditions
  • THEN the most recently undone edit is redone

Requirement: Walk-Mode Touch Movement and Look Controls

Section titled “Requirement: Walk-Mode Touch Movement and Look Controls”

In Walk mode on touch devices, the system SHALL provide an on-screen joystick for movement and a swipe-anywhere gesture for looking around, since WASD and pointer-lock mouse-look are unavailable.

Scenario: Joystick drag moves the walk camera

Section titled “Scenario: Joystick drag moves the walk camera”
  • WHEN the user drags within the on-screen move joystick while in Walk mode on a touch device
  • THEN the walkthrough camera moves forward/backward and strafes proportionally to the joystick deflection
  • WHEN the user drags a finger anywhere on the canvas (outside the joystick) while in pure Walk mode
  • THEN the camera’s look direction (yaw and pitch) rotates proportionally to the swipe, and stops the instant the finger lifts

Requirement: Walk Sub-Mode Switching (Build / Paint / Edit)

Section titled “Requirement: Walk Sub-Mode Switching (Build / Paint / Edit)”

Walk mode SHALL support three sub-modes — Build, Paint, and Edit — each reachable from both a keyboard shortcut and a tappable on-screen control, so the capability is available on touch devices without a keyboard.

Scenario: Tapping the Build pill enters Build sub-mode

Section titled “Scenario: Tapping the Build pill enters Build sub-mode”
  • WHEN the user taps the Build pill while in Walk mode
  • THEN the editor enters Walk-Build sub-mode, matching what the B keyboard shortcut does on desktop

Scenario: Tapping the active sub-mode pill again exits it

Section titled “Scenario: Tapping the active sub-mode pill again exits it”
  • WHEN the user taps a currently-active sub-mode pill
  • THEN the editor exits that sub-mode and returns to plain Walk mode

Requirement: Getting Started Onboarding Guide

Section titled “Requirement: Getting Started Onboarding Guide”

The system SHALL present a single onboarding guide covering editor basics and, on coarse-pointer (touch) devices, touch gestures, automatically on a user’s first visit to the editor and on demand afterward.

Scenario: First-time visitor sees the guide automatically

Section titled “Scenario: First-time visitor sees the guide automatically”
  • WHEN a user opens the editor in a browser that has never shown the guide before
  • THEN the Getting Started guide opens automatically without the user requesting it
  • WHEN a user selects “Getting started” from the editor’s overflow menu
  • THEN the same guide opens again, regardless of whether it auto-opened previously in that browser

Scenario: Touch devices see gesture guidance instead of keyboard shortcuts

Section titled “Scenario: Touch devices see gesture guidance instead of keyboard shortcuts”
  • WHEN the Getting Started guide opens on a coarse-pointer (touch) device
  • THEN its shortcuts section shows touch gestures rather than desktop keyboard shortcuts

Requirement: Read-Only Rendering Reuse Outside the Editor

Section titled “Requirement: Read-Only Rendering Reuse Outside the Editor”

The system SHALL be able to render a floorplan’s current state without mounting any editing tool, so the same model and view layer serve read-only surfaces such as thumbnails and the walkthrough viewer.

Scenario: A read-only surface reflects the same floorplan state

Section titled “Scenario: A read-only surface reflects the same floorplan state”
  • WHEN a read-only surface (for example a thumbnail or the standalone walkthrough viewer) renders a project’s floorplan
  • THEN it shows the same walls, openings, scene items, and materials currently present in the editor for that project, without exposing any drawing or placement tool

Requirement: Guided and Design modes with progressive tool disclosure

Section titled “Requirement: Guided and Design modes with progressive tool disclosure”

The editor SHALL offer two chrome modes. Guided mode SHALL present a reduced tool set sufficient to review and adjust a generated design; Design mode SHALL present the full tool set. Guided mode SHALL NOT remove capability — invoking anything it hides SHALL promote the editor to Design mode and carry out the requested action.

Scenario: Guided mode reduces the visible tool set

Section titled “Scenario: Guided mode reduces the visible tool set”
  • WHEN the editor is in Guided mode
  • THEN selection, furniture placement and deletion are available, and the structural, carpentry and custom-build tools are not shown

Scenario: Reaching for a hidden capability promotes rather than blocks

Section titled “Scenario: Reaching for a hidden capability promotes rather than blocks”
  • WHEN the user in Guided mode invokes a capability that Guided hides — by keyboard shortcut, by the “all tools” affordance, or by any other entry point
  • THEN the editor switches to Design mode and the requested action proceeds; the action is not discarded and the user is not asked to change mode first
  • WHEN the editor is in Design mode
  • THEN every tool, panel and rail available before this change is available, and no capability is reachable only from Guided mode
  • WHEN a user who last worked in Design mode reopens any project
  • THEN the editor opens in Design mode

Scenario: A user with no recorded preference opens an empty project

Section titled “Scenario: A user with no recorded preference opens an empty project”
  • WHEN a user with no recorded mode preference opens a project whose floorplan contains no furniture
  • THEN the editor opens in Guided mode

Scenario: An existing populated project is not downgraded to Guided

Section titled “Scenario: An existing populated project is not downgraded to Guided”
  • WHEN a user with no recorded mode preference opens a project that already contains furniture
  • THEN the editor opens in Design mode, so that work in progress is never met with a reduced tool set the user did not ask for

Requirement: The camera can be focused on a named room

Section titled “Requirement: The camera can be focused on a named room”

The editor SHALL be able to move the camera so that a given room fills the view. Focusing SHALL be a view operation only.

  • WHEN the editor is asked to focus a room that exists in the floorplan
  • THEN the camera moves so that room is centred and framed in the viewport

Scenario: Focusing does not mutate the floorplan

Section titled “Scenario: Focusing does not mutate the floorplan”
  • WHEN a room is focused
  • THEN no walls, openings, furniture or room labels change, nothing is added to the undo stack, and no change is broadcast to other collaborators

Scenario: Focusing a room that no longer exists

Section titled “Scenario: Focusing a room that no longer exists”
  • WHEN the editor is asked to focus a room that is not present in the current floorplan
  • THEN the camera does not move and the editor reports nothing to focus, rather than moving to an arbitrary position

Requirement: The assistant is a first-class surface in Guided mode

Section titled “Requirement: The assistant is a first-class surface in Guided mode”

In Guided mode the editor SHALL present the assistant as a persistent primary surface rather than one tab of a collapsed dock, and SHALL keep its conversation when the user switches modes.

Scenario: The assistant is open on entering Guided mode

Section titled “Scenario: The assistant is open on entering Guided mode”
  • WHEN a project opens in Guided mode
  • THEN the assistant is visible and ready for input without the user opening a dock or choosing a tab

Scenario: The conversation survives a mode switch

Section titled “Scenario: The conversation survives a mode switch”
  • WHEN the user switches from Guided to Design mode and reopens the assistant
  • THEN the existing conversation, including previously reported results, is still present

Scenario: Notes and Tasks keep their existing behaviour

Section titled “Scenario: Notes and Tasks keep their existing behaviour”
  • WHEN the user opens Notes or Tasks
  • THEN they behave as they did before this change, including notes scoped to a region from an in-canvas chip

Scenario: The assistant does not obstruct the canvas in Design mode

Section titled “Scenario: The assistant does not obstruct the canvas in Design mode”
  • WHEN the editor is in Design mode
  • THEN the assistant occupies no more space than the collapsed dock did before this change, and the 3D canvas is not reduced by it

Requirement: A project created through onboarding opens ready to look at

Section titled “Requirement: A project created through onboarding opens ready to look at”

The editor SHALL open a project created through the onboarding flow already furnished and in Guided mode, so the first thing a homeowner sees is their flat rather than an empty shell and a toolbar.

Scenario: A furnished project opens in Guided

Section titled “Scenario: A furnished project opens in Guided”
  • WHEN a homeowner completes onboarding for a unit that could be furnished
  • THEN the editor opens with the furniture already placed and the assistant presented as the primary surface

Scenario: Mode selection is not duplicated

Section titled “Scenario: Mode selection is not duplicated”
  • WHEN the editor decides which mode to open a newly onboarded project in
  • THEN it uses the existing rule that keys off a stored preference and the scene’s contents, not a separate decision made by the onboarding flow