Lighting
Generated from
openspec/specs/lighting/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”Tinkerspace renders floorplan scenes across several contexts (editor, walkthrough, catalog thumbnails, vendor/staging views), each needing correctly-lit, PBR-plausible output without every view reimplementing a rig. This capability defines the lighting behavior guaranteed in each context: a legacy fixed rig as the universal default, an opt-in physically-based day/night rig driven by real sun/moon positions, a self-contained thumbnail rig for consistent catalog imagery, and per-asset lamp emission.
Requirements
Section titled “Requirements”Requirement: Default fixed lighting rig
Section titled “Requirement: Default fixed lighting rig”A plan without an environment configuration SHALL render with the legacy fixed lighting rig (hemisphere + directional sun + ambient lights), and this SHALL be the only rig used for /preview, vendor scenes/stage views, and the sample scene regardless of their plan’s environment field.
Scenario: Plan with no environment meta uses the fixed rig
Section titled “Scenario: Plan with no environment meta uses the fixed rig”- WHEN a floorplan’s
meta.environmentis absent - THEN the viewer mounts
defaultLightingRig()plus a static drei<Environment preset="apartment" background={false}>, and no time-of-day rig is mounted
Scenario: Vendor/staging and preview views ignore environment settings
Section titled “Scenario: Vendor/staging and preview views ignore environment settings”- WHEN the vendor scene/stage view or the
/previewroute renders a plan - THEN the fixed rig is used even if the underlying plan data has an
environmentconfiguration set
Requirement: Exactly one lighting rig mounted per view
Section titled “Requirement: Exactly one lighting rig mounted per view”The system SHALL mount exactly one lighting rig (fixed or dynamic) at a time for a given viewer instance, selected solely by the presence of meta.environment on that plan.
Scenario: Legacy plans render unchanged
Section titled “Scenario: Legacy plans render unchanged”- WHEN a plan has no
environmentmeta and is opened in the editor or walkthrough - THEN rendering output matches the pre-daylight-feature fixed-rig output byte-for-byte, since only the fixed rig is mounted
Scenario: Environment present switches to the dynamic rig
Section titled “Scenario: Environment present switches to the dynamic rig”- WHEN a plan’s
meta.environmentis set and is opened in the editor or walkthrough - THEN the viewer mounts
<EnvironmentLighting settings={...}>instead of the fixed rig, not both
Requirement: Physically-based sun/moon positions from clock time and location
Section titled “Requirement: Physically-based sun/moon positions from clock time and location”When a plan opts into daylight mode via FloorplanMeta.environment, the system SHALL compute real sun and moon altitude/azimuth from the configured date, time, latitude/longitude, and north offset, and SHALL drive scene lighting and the sky dome from that computed position.
Scenario: Auto mode follows real time
Section titled “Scenario: Auto mode follows real time”- WHEN
environment.modeis"auto" - THEN the solar/lunar position is recomputed from the current wall-clock time (
nowMs) on a periodic tick, so the rig’s lighting drifts with real time while mounted
Scenario: Manual mode uses a fixed local time
Section titled “Scenario: Manual mode uses a fixed local time”- WHEN
environment.modeis"manual"with a giventimeMinutesanddateIso - THEN the solar/lunar position is computed for that specific local time and date, not the current wall-clock time
Scenario: North offset reorients the sun for plan orientation
Section titled “Scenario: North offset reorients the sun for plan orientation”- WHEN a plan sets a non-zero
northOffsetDegin its environment settings - THEN the computed sun/moon direction vectors are rotated by that offset so true-north-relative daylight aligns with the plan’s local orientation
Requirement: Daylight-driven descriptor governs all dynamic lighting parameters
Section titled “Requirement: Daylight-driven descriptor governs all dynamic lighting parameters”The system SHALL derive sun/moon intensity and color, hemisphere/ambient light palettes, sky/night background choice, star visibility, environment map intensity, and tone-mapping exposure from a single daylight factor ramped across sunrise/sunset transitions, computed by a pure, unit-tested function independent of any rendering component.
Scenario: Twilight blends lighting smoothly
Section titled “Scenario: Twilight blends lighting smoothly”- WHEN the sun’s altitude is within the −6°→+6° twilight band
- THEN sun intensity/color, hemi/ambient palettes, and
envMapIntensityare interpolated across that band rather than switching abruptly between day and night values
Scenario: Night raises moon contribution
Section titled “Scenario: Night raises moon contribution”- WHEN the sun is below the twilight band (night) and the moon is above the horizon with nonzero illuminated fraction
- THEN the moon contributes light scaled by elevation and illumination fraction, and stars become visible
Scenario: Manual exposure override is respected
Section titled “Scenario: Manual exposure override is respected”- WHEN
environment.exposureis explicitly set - THEN the descriptor uses that value instead of computing an exposure from the daylight factor
Requirement: Shadow camera fits the plan footprint in dynamic mode
Section titled “Requirement: Shadow camera fits the plan footprint in dynamic mode”When the dynamic rig is mounted, the shadow-casting ortho camera SHALL be auto-fitted to the current plan’s footprint (corner bounds plus ceiling height) rather than using the legacy fixed extent.
Scenario: Large plan gets a wider shadow frustum
Section titled “Scenario: Large plan gets a wider shadow frustum”- WHEN a plan’s footprint bounds exceed the legacy fixed rig’s default shadow extent
- THEN the dynamic rig’s shadow camera is sized to cover the actual footprint so shadows are not clipped
Requirement: Catalog thumbnails render with consistent IBL regardless of scene lighting
Section titled “Requirement: Catalog thumbnails render with consistent IBL regardless of scene lighting”Catalog thumbnails SHALL be rendered by a self-contained, off-screen renderer using its own fixed image-based lighting setup, independent of any plan’s environment settings, so thumbnails look uniform across the catalog.
Scenario: Thumbnail ignores plan daylight settings
Section titled “Scenario: Thumbnail ignores plan daylight settings”- WHEN a thumbnail is generated for a catalog asset or craft composition
- THEN the renderer builds its own hemi + directional lights plus a
RoomEnvironment-derived PMREM environment map, producing the same lighting regardless of any floorplan’senvironmentconfiguration
Scenario: Thumbnail output is a capped JPEG
Section titled “Scenario: Thumbnail output is a capped JPEG”- WHEN the off-screen thumbnail renderer produces output
- THEN it is encoded as JPEG (not PNG) at a quality that stays under the API’s accepted upload size cap
Requirement: Per-asset lamp emission with budgeted shadow casting
Section titled “Requirement: Per-asset lamp emission with budgeted shadow casting”A placed scene item SHALL be able to opt into emitting its own point light (SceneItem.lightEmission), and the system SHALL cap the number of such lights that cast shadows to protect frame budget.
Scenario: Opted-in item emits a point light
Section titled “Scenario: Opted-in item emits a point light”- WHEN a scene item has
lightEmissionconfigured with color, intensity, and range - THEN a
pointLightis rendered at the item’s vertical midpoint with those parameters, converted from millimeters to scene units
Scenario: Only the first four shadow-casting lamps cast shadows
Section titled “Scenario: Only the first four shadow-casting lamps cast shadows”- WHEN more than four scene items in a plan have
lightEmission.castShadowenabled - THEN only the first four (in stable item order) actually render a shadow pass; the remainder emit light without casting shadows