Engine
Generated from
openspec/specs/engine/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”The engine (@ideight/engine) is the single headless model of a floorplan that every editor surface — 2D plan, 3D orbit, walkthrough — renders from and mutates through. It guarantees that all surfaces, and all collaborators editing at once, stay consistent by construction: one shared document, one mutation path, one room-detection algorithm, one unit-conversion boundary.
Requirements
Section titled “Requirements”Requirement: Single source of truth across editor surfaces
Section titled “Requirement: Single source of truth across editor surfaces”The system SHALL render the 2D plan, 3D orbit, and walkthrough views from the same floorplan document, so a change made in one surface is immediately visible, in the same form, in the others.
Scenario: A wall edit in one surface appears in another
Section titled “Scenario: A wall edit in one surface appears in another”- WHEN a wall is moved while the 2D plan view is active
- THEN the 3D orbit and walkthrough views reflect the moved wall without any separate save/reload step
Requirement: Atomic, facade-only mutation
Section titled “Requirement: Atomic, facade-only mutation”The system SHALL apply every floorplan change through a single mutation facade, as one atomic operation, so partial edits are never observed or persisted.
Scenario: A multi-field edit is not observed half-applied
Section titled “Scenario: A multi-field edit is not observed half-applied”- WHEN an edit changes multiple related fields as one logical operation (e.g. splitting a wall into two segments)
- THEN collaborators and the undo history see it as a single applied step, never an intermediate state with only some of the fields changed
Requirement: Structural invariants are enforced on mutation
Section titled “Requirement: Structural invariants are enforced on mutation”The system SHALL reject a mutation that would violate a structural (HDB load-bearing) invariant, rather than silently applying it.
Scenario: Moving a corner shared by a load-bearing wall is rejected
Section titled “Scenario: Moving a corner shared by a load-bearing wall is rejected”- WHEN a user attempts to move a corner that is an endpoint of a load-bearing wall
- THEN the mutation is rejected and the floorplan is left unchanged
Requirement: Rooms are detected per enclosed cycle
Section titled “Requirement: Rooms are detected per enclosed cycle”The system SHALL detect rooms as individual closed cycles in the wall graph and render/label each one independently, rather than treating the whole floorplan as a single shape.
Scenario: An unenclosed area renders no floor
Section titled “Scenario: An unenclosed area renders no floor”- WHEN a set of walls does not form a closed loop (e.g. a corner is left dangling)
- THEN no floor is rendered for that area, while enclosed rooms elsewhere in the same floorplan still render their floors
Scenario: A room keeps its label after an unrelated wall edit
Section titled “Scenario: A room keeps its label after an unrelated wall edit”- WHEN a room has been given a name and a wall in a different part of the floorplan is subsequently edited
- THEN the named room keeps its name, because room identity follows the room’s own set of corners rather than the order rooms were last computed in
Requirement: Unit display is consistent and reversible
Section titled “Requirement: Unit display is consistent and reversible”The system SHALL let a user view and enter lengths in either metric or imperial units while always storing an unambiguous value underneath, so switching display units never changes the underlying measurement.
Scenario: A length displays correctly in both unit systems
Section titled “Scenario: A length displays correctly in both unit systems”- WHEN a stored length is displayed under the metric unit system and then under the imperial unit system
- THEN both displayed values represent the same underlying length, each formatted idiomatically for its system (e.g. metres/millimetres vs. feet-and-inches)
Scenario: A user-entered length round-trips
Section titled “Scenario: A user-entered length round-trips”- WHEN a user types a length in the unit system currently active (e.g.
"1.5m"in metric, or13' 9"in imperial) - THEN the entered value is parsed to the same underlying length regardless of which unit system was active when it was typed
Requirement: Placement validation accounts for openings
Section titled “Requirement: Placement validation accounts for openings”The placement validator SHALL receive the floorplan’s openings and SHALL refuse a placement that covers a window above its sill. The refusal SHALL name the window, so that a caller can report which opening was blocked rather than reporting a generic collision.
Scenario: An item standing inside a doorway is already refused
Section titled “Scenario: An item standing inside a doorway is already refused”- WHEN a scene item’s footprint overlaps the span a door opening occupies through its wall
- THEN the placement is invalid as a wall collision, because a wall’s footprint is not cut by its openings — no separate doorway rule is needed for this case
Scenario: A tall item covering a window is refused
Section titled “Scenario: A tall item covering a window is refused”- WHEN a scene item’s footprint overlaps a window opening’s wall span
- AND the item’s height reaches or exceeds the window’s sill height
- THEN the placement is invalid
- AND the result names the window
Scenario: A low item under a window is allowed
Section titled “Scenario: A low item under a window is allowed”- WHEN a scene item’s footprint overlaps a window opening’s wall span
- AND the item’s height stays below the window’s sill height
- THEN the placement is valid, because a bench under a window is normal
Scenario: An opening whose wall is missing is ignored
Section titled “Scenario: An opening whose wall is missing is ignored”- WHEN an opening references a wall that is not in the floorplan
- THEN it constrains nothing and the placement is judged on the remaining rules, because this happens mid-edit and must not throw
Scenario: Omitting openings preserves the previous behaviour
Section titled “Scenario: Omitting openings preserves the previous behaviour”- WHEN a caller supplies no openings
- THEN validation behaves exactly as it did before openings existed
Requirement: Generated layouts keep door swings and approaches clear
Section titled “Requirement: Generated layouts keep door swings and approaches clear”Room furnishing SHALL treat a door’s swing arc and approach zone as unusable floor when choosing where to place a station, and SHALL fall through to another slot or another candidate asset rather than placing into them. When no position avoids them, the station SHALL be reported as skipped with a reason naming the door. This SHALL apply identically to joinery a station builds and to furniture it places from the catalogue — built carpentry gets no relaxed validation path.
Scenario: A recipe prefers a slot that leaves the door clear
Section titled “Scenario: A recipe prefers a slot that leaves the door clear”- WHEN a station’s first candidate slot lies in a door’s swing arc
- AND a later slot does not
- THEN the item is placed in the later slot
Scenario: A station that cannot avoid a door is skipped, and says why
Section titled “Scenario: A station that cannot avoid a door is skipped, and says why”- WHEN no slot and no candidate asset for a station avoids the door zones
- THEN the station is reported as skipped
- AND the reason names the door rather than saying only that there was no room
Scenario: A designer may still place into a swing arc by hand
Section titled “Scenario: A designer may still place into a swing arc by hand”- WHEN a person drags an item into a door’s swing arc or approach zone
- THEN the placement is allowed and reported as an advisory note, not refused, because a designer may be placing it temporarily or know something the model does not
Scenario: A built cabinet run obeys the same door rules
Section titled “Scenario: A built cabinet run obeys the same door rules”- WHEN the wall a cabinet run would be built against carries a door whose swing or approach the run would cover
- THEN the run is shortened to the clear stretch of that wall, built against another wall, or skipped with a reason naming the door — never built across the door
Requirement: Blocked openings reach the assistant as correctable errors
Section titled “Requirement: Blocked openings reach the assistant as correctable errors”When the chat assistant’s placement is refused for blocking an opening, the tool result SHALL be an error naming the opening, so the assistant can move the item and retry rather than reporting a success the user can see is wrong.
Scenario: The assistant is told which opening it blocked
Section titled “Scenario: The assistant is told which opening it blocked”- WHEN a tool call places an item standing in a doorway
- THEN the tool result is an error
- AND it names the blocked opening
Requirement: A named position can be resolved for an already-placed item
Section titled “Requirement: A named position can be resolved for an already-placed item”The system SHALL resolve a named position — a wall of the room with an optional position along it, a position beside another item, or the room’s centre — into a legal pose for a specific item’s dimensions in a specific room, using the same slot geometry and the same placement validation that furnishing uses.
Resolution SHALL consider the item being moved as absent from the room, so a piece is never found to collide with itself.
Scenario: A wall resolves to a pose that fits
Section titled “Scenario: A wall resolves to a pose that fits”- WHEN a named wall is resolved for an item whose footprint fits along it
- THEN the returned pose sits the item against that wall, facing into the room, inside the usable floor rather than on the wall centreline
Scenario: The item does not collide with itself
Section titled “Scenario: The item does not collide with itself”- WHEN a position is resolved for an item that is already in the room
- THEN the item’s current footprint is excluded from the collision check
Scenario: An item too large for the wall resolves to nothing there
Section titled “Scenario: An item too large for the wall resolves to nothing there”- WHEN the named wall is shorter than the item
- THEN that position yields no pose, so the caller can fall through to another
Scenario: Resolution obeys the same rules as placement
Section titled “Scenario: Resolution obeys the same rules as placement”- WHEN a named position is resolved
- THEN walls, the structural perimeter, openings and already-placed items are respected exactly as they are when furnishing places a piece
Requirement: A station’s dependent pieces are placed with it
Section titled “Requirement: A station’s dependent pieces are placed with it”Room furnishing SHALL place the pieces a station declares as dependent on its anchor — a nightstand beside a bed, a coffee table in front of a sofa, chairs around a table — positioned by the relation the station names rather than chosen a slot of their own. A dependent that cannot be placed SHALL be reported with a reason and SHALL NOT fail its station, since a dependent is by definition the part of a station the room can do without.
A station is the unit a room is arranged in. Placing only its anchor produces furniture dropped in a room rather than a room that was arranged, and leaves the empty middle a homeowner notices first.
Scenario: A flanking dependent is placed on both sides
Section titled “Scenario: A flanking dependent is placed on both sides”- WHEN a station declares a flanking dependent and the room has space for both
- THEN one is placed each side of the anchor, and neither is placed on top of the other
Scenario: A dependent that does not fit is reported, not dropped
Section titled “Scenario: A dependent that does not fit is reported, not dropped”- WHEN no position satisfying the relation is free, or the catalogue offers nothing matching it
- THEN the dependent is reported with a reason, its station is still counted as placed, and the plan can still succeed overall
Scenario: A skipped dependent is distinguishable from a skipped station
Section titled “Scenario: A skipped dependent is distinguishable from a skipped station”- WHEN a plan’s skipped entries are inspected
- THEN each states whether it is the station’s own piece or one of its dependents, so a station standing one lamp short is not reported as a station that failed
Requirement: A room can be planned around a piece held in place
Section titled “Requirement: A room can be planned around a piece held in place”Room planning SHALL accept a piece pinned at a given pose and plan the room’s remaining generated stations around it, treating the pinned piece as already placed. The pinned piece SHALL NOT be moved by the plan.
Items the planner did not generate SHALL be treated as obstacles and never re-placed, so a plan cannot undo work done by hand.
Scenario: The pinned piece keeps the pose it was given
Section titled “Scenario: The pinned piece keeps the pose it was given”- WHEN a room is planned with a piece pinned at a requested pose
- THEN the resulting plan places that piece at exactly that pose, and arranges the other generated pieces around it
Scenario: Hand-placed items constrain the plan without being moved
Section titled “Scenario: Hand-placed items constrain the plan without being moved”- WHEN the room contains items the planner did not generate
- THEN the plan treats them as occupied floor and does not propose new positions for them
Scenario: A pinned piece that cannot legally be placed fails the plan
Section titled “Scenario: A pinned piece that cannot legally be placed fails the plan”- WHEN the pinned pose is itself invalid — outside the room, inside a wall, or blocking a door
- THEN planning fails and says so, rather than returning an arrangement built around an impossible position
Scenario: Re-planning obeys the same rules as first planning
Section titled “Scenario: Re-planning obeys the same rules as first planning”- WHEN a room is planned around a pinned piece
- THEN wall collisions, door swings and approaches, open-plan thresholds and fitted zones are enforced exactly as they are when the room is planned from empty
Requirement: A plan can be returned with enough geometry to be drawn
Section titled “Requirement: A plan can be returned with enough geometry to be drawn”A planning result SHALL carry, for every piece it would place and every unit it would build, the position, orientation and footprint it would occupy, together with the boundary of the room it was planned against — so that a caller can draw the plan without planning the room a second time.
Scenario: A dry run reports poses, not just names
Section titled “Scenario: A dry run reports poses, not just names”- WHEN a room is planned without writing
- THEN the result carries each piece’s position, rotation and footprint dimensions, not only its name and the slot it was assigned
Scenario: The drawing and the writing agree by construction
Section titled “Scenario: The drawing and the writing agree by construction”- WHEN a plan that was drawn is subsequently applied
- THEN the pieces are written at the poses that were drawn, because the same planning result supplies both — re-planning between the two would allow the drawing to be a picture of something else
Scenario: The room’s own outline is carried with the plan
Section titled “Scenario: The room’s own outline is carried with the plan”- WHEN a planning result is returned for drawing
- THEN it carries the polygon the room was planned against, so the plan can be drawn in the room’s real shape rather than a generic rectangle
See also
Section titled “See also”- domain-schemas spec — the zod schema every floorplan entity validates against, including the schema-version gate and cross-field structural invariants enforced at the schema layer.
- realtime-collab spec — how the same document this spec describes stays synchronized across peers.
- packages/engine/AGENTS.md — implementation conventions (Y.Doc as source of truth, mm/m unit boundary, per-room rendering, engine ID scheme, no-Three.js layering) that back these requirements.