Skip to content

Realtime collab

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

Every project’s design state (floorplan, scene items, notes, vendor scenes) is shared through a single live document rather than owned by one client. This capability keeps all peers viewing the same project converged on the same state in real time, while keeping transient UI state (selection, hover, tool mode, cursors) local to each peer instead of polluting the shared project.

Requirement: Automatic Cross-Peer Synchronization

Section titled “Requirement: Automatic Cross-Peer Synchronization”

The system SHALL synchronize floorplan, scene item, note, and vendor scene edits across all peers connected to the same project in real time, so that edits made by one peer become visible to the others without manual refresh or merge, and edits to different parts of the project made concurrently by different peers SHALL all be preserved in the resulting state.

Scenario: Edit in one tab appears in another

Section titled “Scenario: Edit in one tab appears in another”
  • WHEN a user editing a project in one browser tab moves a wall
  • THEN a second tab open on the same project shows the wall in its new position without the user reloading the page

Scenario: Concurrent edits to different data both survive

Section titled “Scenario: Concurrent edits to different data both survive”
  • WHEN two peers connected to the same project each edit a different scene item at the same time
  • THEN both edits are present in the project afterward for every peer

Requirement: Ephemeral Presence Never Persists

Section titled “Requirement: Ephemeral Presence Never Persists”

The system SHALL broadcast each connected peer’s cursor position, current selection, and identity to the other connected peers as live presence information, and this presence information SHALL NOT be written to the project’s persisted state.

Scenario: Peer sees another peer’s live selection

Section titled “Scenario: Peer sees another peer’s live selection”
  • WHEN peer A selects an object in the shared project
  • THEN peer B sees an indicator of peer A’s selection while both remain connected

Scenario: Presence does not survive reload

Section titled “Scenario: Presence does not survive reload”
  • WHEN peer A selects an object and then peer A’s tab is closed
  • THEN peer B no longer sees peer A’s selection indicator, and reopening the project later shows no trace of peer A’s past selection

Requirement: New Peer Receives Full Current State

Section titled “Requirement: New Peer Receives Full Current State”

The system SHALL provide a peer that connects to a project with the complete current state of that project’s document, not only edits made after the peer connects.

Scenario: Joining late still shows prior edits

Section titled “Scenario: Joining late still shows prior edits”
  • WHEN a peer opens a project that other peers have already been editing
  • THEN the newly connected peer immediately sees all edits made before they connected

The system SHALL durably persist edits made to a project so that they survive every peer disconnecting and remain available when the project is reopened later.

  • WHEN a user edits a project and then closes every tab with that project open
  • THEN reopening the project afterward shows the edit still present

Requirement: Save Status Reflects Server-Confirmed Persistence

Section titled “Requirement: Save Status Reflects Server-Confirmed Persistence”

The system SHALL indicate to the user whether their most recent edits have been confirmed as durably saved by the server, distinct from merely having been sent.

Scenario: Saving indicator clears on server confirmation

Section titled “Scenario: Saving indicator clears on server confirmation”
  • WHEN a user makes an edit
  • THEN the UI shows a saving-in-progress state until the server confirms the edit was persisted, after which it shows the edit as saved

Requirement: New Project Seeded With Initial State

Section titled “Requirement: New Project Seeded With Initial State”

The system SHALL initialize a newly created project’s shared document with its starting floorplan (e.g. a preset or base layout) exactly once at creation, so the project is never presented to a viewer as an empty document when it was created from a non-empty starting point.

Scenario: New project opens with its preset already loaded

Section titled “Scenario: New project opens with its preset already loaded”
  • WHEN a user creates a new project from an HDB unit preset
  • THEN opening that project immediately shows the preset’s floorplan already in place

Requirement: Project Duplication Copies Current State

Section titled “Requirement: Project Duplication Copies Current State”

The system SHALL initialize a duplicated project’s shared document from a copy of the source project’s current state at the moment of duplication.

Scenario: Duplicate reflects source project’s latest edits

Section titled “Scenario: Duplicate reflects source project’s latest edits”
  • WHEN a user duplicates a project that has been edited since it was created
  • THEN the duplicate opens showing those edits, not the project’s original starting state
  • engine spec — the Floorplan facade and 3D view layer built on top of the synchronized document.