Floorplan editor
Generated from
openspec/specs/floorplan-editor/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”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.
Requirements
Section titled “Requirements”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
Scenario: One name per room
Section titled “Scenario: One name per room”- 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
Requirement: Edit Mode vs. View Mode
Section titled “Requirement: Edit Mode vs. View Mode”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.
Scenario: View mode blocks tool switching
Section titled “Scenario: View mode blocks tool switching”- 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
Scenario: Escape exits the current tool
Section titled “Scenario: Escape exits the current tool”- 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
Scenario: Redo restores the undone change
Section titled “Scenario: Redo restores the undone change”- 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
Requirement: Touch Marquee Box-Select
Section titled “Requirement: Touch Marquee Box-Select”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
Scenario: Three-finger tap redoes
Section titled “Scenario: Three-finger tap redoes”- 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
Scenario: Swiping anywhere looks around
Section titled “Scenario: Swiping anywhere looks around”- 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
Bkeyboard 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
Scenario: Guide can be reopened on demand
Section titled “Scenario: Guide can be reopened on demand”- 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
Scenario: Design mode is the full editor
Section titled “Scenario: Design mode is the full editor”- 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
Scenario: Mode persists across sessions
Section titled “Scenario: Mode persists across sessions”- 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.
Scenario: Focusing a room frames it
Section titled “Scenario: Focusing a room frames it”- 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