Update architecture and roadmap documentation for whiteboxing features

architecture.md

@@ -7,12 +7,12 @@ This project is a browser-based 3D scene authoring tool with a built-in runtime
 It has two primary modes:
 
 1. **Editor mode**
-   - author spatial scenes using brush primitives, entities, materials, and imported assets
+   - author interactive 3D environments using whitebox solids, entities, materials, and imported assets
 
 2. **Runner mode**
    - load and play those scenes in-browser using configurable navigation and interaction modes
 
-The architecture is designed to preserve old-school level-editor ergonomics while staying web-native and maintainable.
+The architecture is designed to preserve intuitive level-authoring ergonomics while staying web-native and maintainable.
 
 ---
 
@@ -20,7 +20,7 @@ The architecture is designed to preserve old-school level-editor ergonomics whil
 
 ### Primary goals
 
-- fast and precise brush-based scene authoring
+- fast and precise whitebox-based scene authoring
 - modern browser runtime delivery
 - native support for imported GLB/GLTF assets
 - robust material/texture workflows
@@ -107,10 +107,10 @@ Do not introduce `/apps` + `/packages` or monorepo packaging until the current c
 - saved projects must keep binary assets via embedded data or project-packaged storage
 - never persist only ephemeral Blob URLs or runtime-only browser object references
 
-### Early brush representation
+### Current box-solid foundation
 
-The first supported brush kind is an axis-aligned box.
+The first implemented shape was an axis-aligned box with stable face IDs.
-Do not support arbitrary brush rotation in Slice 1.1.
+That is historical starting context, not the long-term geometry constraint.
 
 Use stable face IDs:
 
@@ -142,6 +142,22 @@ interface BoxBrush {
 
 `size` values should be positive and non-zero.
 
+### Whitebox geometry direction
+
+The product is moving away from grid-bound brush thinking toward intuitive whitebox solids for level blocking.
+
+Directionally, this means:
+
+- floating point transforms are allowed
+- free object rotation is allowed
+- the grid becomes a snap/reference aid, not a hard restriction
+- object, face, edge, and vertex editing should share one coherent transform-driven interaction model
+- non-planar quad faces are acceptable; derived rendering/build should triangulate them deterministically
+- solids do not need to remain convex
+- collision should come from the solid-collider pipeline rather than assumptions about convexity or axis alignment
+
+Near-term implementation can keep existing `BoxBrush`/box-solid structures where useful, but future geometry slices should treat them as the first whitebox solid type rather than the entire long-term model.
+
 ### Early UV representation
 
 Store actual UV transform values canonically per face.
@@ -191,10 +207,16 @@ Only activate actions for systems that already exist.
 - sound actions should land with the audio slice
 - animation actions should land with the animation slice
 
-### Clipping scope
+### Whitebox editing scope
 
-Until a dedicated convex-brush slice exists, clipping must stay constrained to results representable by the currently supported brush kinds.
+The geometry roadmap should prioritize:
-If the first clip implementation only supports axis-aligned box brushes and principal-axis clip planes, that is acceptable.
+
+- object transforms
+- component selection modes
+- face/edge/vertex editing
+- robust derived triangulation/collision for edited solids
+
+before adding topology-changing tools such as clipping/extrusion in earnest.
 
 ---
 
@@ -215,7 +237,7 @@ Properties:
 
 Contains:
 - world settings
-- brush definitions
+- whitebox solid definitions
 - face UV/material assignments
 - entity instances
 - model instances
@@ -241,7 +263,7 @@ Contains:
 - selection outlines
 - gizmos
 - helper icons
-- grids
+- grids and snap guides
 - temporary tool feedback
 
 ### 3. Runtime representation
@@ -437,29 +459,27 @@ Contains:
 
 This is one of the most critical modules.
 
-### Canonical brush representation
+### Canonical whitebox representation
 
-Brushes should not be stored as raw triangle meshes.
+Whitebox solids should not be stored as hidden renderer-only mesh state.
 
 Preferred progression:
 
-#### Early v1
+#### Current transition
 
-Explicit parametric primitives with per-face data:
+- box-based whitebox solids with stable face identity
-
+- object transforms plus component selection/editing
-- box
+- derived triangulation for rendering and collision
-- wedge/ramp
-- cylinder prism
-- stairs
-- arch
 
 #### Later
 
-Plane-based convex solids and clipping-based editing.
+- richer whitebox solid topology tools
+- clipping/extrusion/bevel-like operations if they fit the product cleanly
+- broader solid editing without turning the product into arbitrary mesh modeling
 
 ### Derived outputs
 
-From brush data, generate:
+From canonical whitebox data, generate:
 
 - editor mesh
 - pick mesh

roadmap.md

@@ -27,9 +27,9 @@ If a roadmap item is too large for one implementation pass, split it into smalle
 
 ## Product north star
 
-A browser-based brush editor with a built-in runner, enabling users to quickly create and share lightweight interactive 3D spaces with:
+A browser-based engine/editor with a built-in runner, enabling users to quickly create and share lightweight interactive 3D spaces with:
 
-- brush-authored layout
+- intuitive whiteboxing / level blocking
 - material/texture workflows
 - imported GLB/GLTF assets
 - spatial audio
@@ -46,7 +46,7 @@ These are locked for the early milestones:
 - early repo shape is a single Vite app with domain folders under `src/`
 - canonical document state lives outside the React tree
 - the document is versioned from day one
-- early box brushes are axis-aligned only with fixed face IDs
+- early slices began with axis-aligned box brushes and fixed face IDs
 - placed imported models are `modelInstances`, not `entities`
 - local draft persistence plus explicit JSON import/export is acceptable early
 - once scenes depend on external binary assets, portable save/load must move to a project package containing canonical scene JSON plus bundled assets
@@ -60,7 +60,7 @@ These are locked for the early milestones:
 Foundation and repo discipline
 
 ### Milestone 1
-First real room: brush layout + materials + play mode
+First real room: box-based layout + materials + play mode
 
 ### Milestone 2
 Entities and runtime interaction
@@ -69,7 +69,7 @@ Entities and runtime interaction
 Imported models, lighting, animation, and audio
 
 ### Milestone 4
-Better brush editing and authoring ergonomics
+Whiteboxing and direct geometry editing
 
 ### Milestone 5
 Project portability, deployment, and quality improvements
@@ -120,7 +120,7 @@ Create the minimum project skeleton that supports fast vertical slicing without
 
 ### Vision
 
-The user can create a box brush, assign materials to faces, save the scene, reload it, and run around it.
+The user can create a box-based room, assign materials to faces, save the scene, reload it, and run around it.
 
 This is the first proof that the product is real.
 
@@ -239,7 +239,7 @@ This is the first proof that the product is real.
 
 ### Vision
 
-The user can place non-brush entities and author simple interactive scenes without scripting.
+The user can place non-whitebox entities and author simple interactive scenes without scripting.
 
 ### Slice 2.1 — Entity system foundation