Walkthrough
Generated from
openspec/specs/walkthrough/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”/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.
Requirements
Section titled “Requirements”Requirement: Live-scene walkthrough
Section titled “Requirement: Live-scene walkthrough”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.
Scenario: Designer edit appears live
Section titled “Scenario: Designer edit appears live”- 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
Requirement: Tap-to-measure distance tool
Section titled “Requirement: Tap-to-measure distance tool”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.
Scenario: Client edits persist
Section titled “Scenario: Client edits persist”- 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
Scenario: No viewer-only restriction
Section titled “Scenario: No viewer-only restriction”- 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.
Scenario: Walk mode inside the editor
Section titled “Scenario: Walk mode inside the editor”- 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