fixed most ( still units error )

docs/transformation_system.md

@@ -0,0 +1,73 @@
+# Transformation Flow and Synchronization System
+
+This document describes how transformations are applied and synchronized between the interactive 3D viewport, the visualization puppets, and the underlying mathematical models within the `uLib` framework.
+
+## Architecture Overview
+
+The system follows a Model-View-Controller (MVC) like pattern where:
+- **Model**: `uLib::AffineTransform` (or derived classes like `ContainerBox`).
+- **View/Puppet**: `uLib::Vtk::Puppet` (and specialized derivations like `Vtk::Assembly`).
+- **Controller/Interaction**: `vtkHandlerWidget` (the transformation gizmo).
+
+---
+
+## 1. Interaction Flow (Gizmo -> Model)
+
+When a user interacts with the `vtkHandlerWidget` (dragging arrows, rings, or cubes), the following chain of events occurs:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant HW as vtkHandlerWidget
+    participant VP as vtkViewport
+    participant P as vtkPuppet
+    participant M as uLib Model
+
+    User->>HW: Drag handle (MouseMove)
+    HW->>HW: Calculate Delta Matrix (op)
+    HW->>HW: Total = StartState * op
+    HW->>HW: Decompose Total into P, O, S
+    HW->>P: SetPosition, SetOrientation, SetScale
+    HW-->>VP: Invoke InteractionEvent
+    VP->>P: SyncFromVtk()
+    P->>P: Get local matrix from VTK Prop
+    P->>M: SetMatrix(matrix)
+    M-->>M: Update local properties (P, O, S)
+    M-->>P: Emit Updated signal
+    P->>P: Puppet::Update()
+    P->>P: (Redundant sanity write to Prop)
+```
+
+### Key Principles:
+- **Single Source of Truth**: The `uLib::AffineTransform` is the owner of the transformation state.
+- **Internal TRS vs UserMatrix**: We apply transformations directly to VTK's internal `Position`, `Orientation`, and `Scale` properties. This ensures the data is "visible" to VTK actors and simplifies decomposition.
+- **Cumulative Bias Avoidance**: The `HandlerWidget` calculates transformations relative to the state at the start of the click, preventing numerical drift during a single drag operation.
+
+---
+
+## 2. Synchronization Loop Resolution
+
+To prevent infinite loops and "double-transformation" artifacts (especially in assemblies), the following protections are in place:
+
+1. **Hierarchy Isolation**: The `Puppet` base class distinguishes between the **Root Property** (which receives the puppet's master transformation) and **Sub-Parts** (which only receive appearance updates like color/visibility). This prevents parts from inheriting the same displacement twice.
+2. **Re-entrancy Guards**: Puppets use an `m_InUpdate` flag to prevent a feedback loop where `SyncFromVtk` triggers a Model Update, which then re-triggers the Puppet Update.
+3. **Signal Blocking**: In specialized cases (like `vtkAssembly`), `m_BlockUpdate` is used to prevent the model-to-puppet push during a puppet-to-model sync.
+
+---
+
+## 3. Undo System (Ctrl-Z)
+
+### Current Implementation (Delta Chain)
+Currently, the system maintains a `m_TransformChain` of delta matrices.
+- **Record**: After every drag, a delta matrix ($M_{delta} = M_{end} \cdot M_{start}^{-1}$) is appended to the chain.
+- **Undo**: The last delta is removed, and the prop is reconstructed by reapplying the remaining chain from a `BaseMatrix`.
+
+### Planned Improvement (TRS Snapshots)
+We are migrating to a `uLib::TRS` snapshot system for Undo.
+- **Record**: At the start of a drag, the current `TRS` state of the object is pushed to the `m_UndoStack`.
+- **Undo**: The top `TRS` is popped and applied directly to the model.
+
+This approach is more robust because:
+- It eliminates matrix multiplication error accumulation.
+- It bypasses rotation convention/order issues (Gimbal lock in deltas).
+- It returns the object to exactly its previous property values.