Skip to content

Engine

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

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.

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

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, or 13' 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
  • 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.