Skip to content

Walkthrough

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

/walkthrough/[id] lets an invited client explore a project’s live 3D scene in first person, measure spaces, make light edits, and request a photorealistic restyle of any view via ComfyCloud — giving designers a client-review surface that reflects the real, editable scene rather than a static export.

The system SHALL render the walkthrough from the project’s live collaborative scene, not a static snapshot, so edits made elsewhere while a client is walking through are reflected in real time.

  • WHEN a designer moves or adds furniture in the main project editor while a client is walking through the same project’s walkthrough
  • THEN the client’s view updates to reflect the change without reloading the page

Requirement: Authenticated access required

Section titled “Requirement: Authenticated access required”

The system SHALL require the visiting user to be authenticated before loading a walkthrough, and SHALL NOT expose an unauthenticated public link.

Scenario: Unauthenticated visit is blocked

Section titled “Scenario: Unauthenticated visit is blocked”
  • WHEN a user without a session opens a walkthrough URL
  • THEN they are redirected to sign in rather than shown the scene

Requirement: First-person navigation with collision

Section titled “Requirement: First-person navigation with collision”

The system SHALL let the client move through the scene in first person using keyboard movement and mouse-look, with sprint and crouch modifiers, and SHALL prevent the camera from passing through walls or floor-level furniture via capsule collision.

Scenario: Walking into a wall stops forward motion

Section titled “Scenario: Walking into a wall stops forward motion”
  • WHEN the client moves toward a wall
  • THEN the camera slides along the wall surface instead of passing through it

Scenario: Tall furniture is walkable-under

Section titled “Scenario: Tall furniture is walkable-under”
  • WHEN the client walks toward furniture whose lowest point is above the walk-under height threshold
  • THEN the camera passes beneath it rather than colliding with it

The system SHALL let the client measure the distance between two points in the scene by raycasting from the view reticle.

Scenario: Two clicks produce a distance label

Section titled “Scenario: Two clicks produce a distance label”
  • WHEN the client clicks once to place a first measurement point and clicks again on a second point
  • THEN a line is drawn between the two points labeled with the distance in metres

Scenario: A third click resets the measurement

Section titled “Scenario: A third click resets the measurement”
  • WHEN the client clicks a third time after a measurement is already shown
  • THEN the previous measurement is cleared and a new first point is placed at the click location

Requirement: In-walkthrough edit mode with shared write access

Section titled “Requirement: In-walkthrough edit mode with shared write access”

The system SHALL let any user who can open the walkthrough toggle into an edit mode that can add, rotate, and delete scene items, with changes persisted through the same collaborative document as the main editor, and SHALL NOT restrict this capability to designers only.

  • WHEN a client toggles to edit mode and deletes or repositions a furniture item
  • THEN the change is saved to the project’s shared document and is visible to a designer editing the same project
  • WHEN any authenticated user with the walkthrough URL open toggles to edit mode
  • THEN they can modify the scene — there is no separate check distinguishing an invited viewer from an editor

Requirement: Editor reuses the walkthrough surface

Section titled “Requirement: Editor reuses the walkthrough surface”

The system SHALL let the main project editor’s own walk view mode reuse the same first-person navigation, measurement, and photo-capture behavior as the standalone walkthrough, rather than a separate implementation.

  • WHEN a designer switches the main project editor into its walk view mode
  • THEN the same navigation, collision, and measurement behavior available in the standalone walkthrough is available there too

Requirement: Photo-mode capture without a tainted canvas

Section titled “Requirement: Photo-mode capture without a tainted canvas”

The system SHALL capture the current first-person view as an image without throwing a browser canvas-security error, even though the scene contains cross-origin textures that would otherwise taint the canvas.

Scenario: Capture succeeds with cross-origin assets loaded

Section titled “Scenario: Capture succeeds with cross-origin assets loaded”
  • WHEN the client triggers photo capture while the scene includes furniture models or environment imagery loaded from a different origin
  • THEN a captured image is produced without a canvas security error

Requirement: Restyle request in a named preset

Section titled “Requirement: Restyle request in a named preset”

The system SHALL let the client submit a captured photo for a photorealistic restyle in one of a set of named interior-design style presets.

Scenario: Submitting a captured photo with a chosen preset

Section titled “Scenario: Submitting a captured photo with a chosen preset”
  • WHEN the client captures a photo and selects a style preset (such as Scandinavian, industrial, Japandi, or mid-century)
  • THEN the system submits a restyle request carrying that preset and shows the request as pending

Requirement: Restyle output is retrievable independent of the upstream provider

Section titled “Requirement: Restyle output is retrievable independent of the upstream provider”

The system SHALL make a completed restyle’s output image retrievable from Tinkerspace’s own infrastructure, independent of the upstream image-generation provider’s own time-limited output URLs.

Scenario: Output remains viewable after the provider’s URL would have expired

Section titled “Scenario: Output remains viewable after the provider’s URL would have expired”
  • WHEN a restyle job completes and enough time passes that the upstream provider’s signed output URL would no longer be valid
  • THEN the client can still retrieve the restyled image through the walkthrough’s own output endpoint

Requirement: Restyle does not mutate the live scene

Section titled “Requirement: Restyle does not mutate the live scene”

The system SHALL treat a restyle result as a standalone image and SHALL NOT apply it back onto the project’s floorplan, furniture placement, or materials.

Scenario: Scene state is unchanged after restyle

Section titled “Scenario: Scene state is unchanged after restyle”
  • WHEN a restyle completes and the client views the before/after result
  • THEN the underlying project’s scene data (walls, furniture placement, materials) is unchanged — only a new image is available to view