docs: week 3 task 3 docs

Week-3/Task-3/ProductLens.md

@@ -1,5 +1,14 @@
 ## Product Lens
-- Is this pattern useful for real customers? Yes / Partial / No
+- Is this pattern useful for real customers? Yes
 - What kind of customer use case does this support?
+	- Product explainers with step-by-step reveal of features.
+	- Guided tours where camera framing and object visibility change by narrative step.
+	- Sales/demo journeys that require reliable forward/backward and jump navigation.
 - Does Thob feel strong enough for this use case?
+	- Partial to strong, depending on expectations.
+	- For reliability, yes: using three prebuilt meshes and radio-button visibility toggles gave consistent step switching in any order, including reset/default.
+	- For presentation quality, partial: transitions are instant, so the narrative feels less smooth than vanilla and r3f.
 - What would improve the experience?
+	- Native guided-flow primitive that groups camera + transform + visibility per step.
+	- Built-in transition controls (duration/easing) for cinematic step changes.
+	- Better editor UX for step ordering, jump behavior, and reset/default definition.

Week-3/Task-3/TaskNotes.md

@@ -1,60 +1,119 @@
-# Task: [Feature Name]
+# Task: 3-Step Guided Flow Reliability Audit
 
 ## Objective
-What is the feature trying to do?
+Take the 3-step guided scene flow and test it like a real customer journey, including forward/backward sequencing, direct jumps, repeated runs, reset behavior, and consistency of camera + visibility + transforms.
 
 ## Vanilla three.js
--Possible: Yes / Partial / No
+-Possible: Yes
+-Reliability verdict: Reliable
 -Notes:
+  - The flow is defined by a single `STEPS` array that includes camera position, look target, and object A/B transform + visibility for each step.
+  - `step 1 -> 2 -> 3` works as expected via next button, numbered buttons, or keys.
+  - `3 -> 2 -> 1` is supported by direct step selection or previous button (index clamp prevents out-of-range issues).
+  - Direct jump `1 -> 3` is supported and stable.
+  - Repeating the sequence multiple times remains consistent because each `applyStep` fully overwrites target values.
+  - Reset works by returning to Step 1 (`applyStep(0)`).
+  - Camera + visibility + transforms stay synchronized through target updates and per-frame interpolation.
+  - No hidden state leakage is expected because each step writes all required state for both objects and camera target.
+  - Transitions are smooth (lerp/eased rotation updates).
 -Key concepts:
--Complexity: Easy / Medium / Hard
+  - Data-driven guided steps
+  - Full-state overwrite per step
+  - Camera look target interpolation
+  - Deterministic sequencing
+-Complexity: Medium
 
 ## R3F
--Possible: Yes / Partial / No
+-Possible: Yes
+-Reliability verdict: Reliable
 -Notes:
+  - Uses the same `STEPS` model with React state (`stepIndex`) and a scene controller component.
+  - Supports forward, backward, direct jump, and repeated runs using buttons/keyboard.
+  - Reset is straightforward by setting `stepIndex` to 0.
+  - `useEffect` updates targets/visibility; `useFrame` interpolates transforms and camera each frame.
+  - Flow is deterministic because each step writes full state for camera and both objects.
+  - No obvious hidden state leakage from code structure.
+  - Transitions are smooth and predictable.
 -What R3F abstracted:
--Complexity: Easy / Medium / Hard
+  - Declarative step state management
+  - Scene update lifecycle through hooks
+  - Cleaner separation between UI controls and scene orchestration
+-Complexity: Medium
 
 ## Thob Page Builder
--Possible: Yes / Partial / No
+-Possible: Yes
+-Reliability verdict: Reliable
 -Notes:
+  - I used the same pattern as Task 2: created 3 separate meshes (one per guided step state) and used radio buttons to toggle visibility.
+  - Sequencing stayed reliable in my test:
+    - `1 -> 2 -> 3` worked
+    - `3 -> 2 -> 1` worked
+    - direct `1 -> 3` worked
+    - repeated toggling in any order stayed correct
+  - Reset/default is the default selected radio option (Step 1).
+  - Camera + visibility + transform consistency stayed stable because each step is pre-authored as an isolated mesh state.
+  - Same limitation as last task: no transition animation; state changes are instant.
+  - For multi-step narratives, correctness is good, but cinematic quality is limited without interpolation.
 -Builder steps:
--Complexity: Easy / Medium / Hard
+  1. Build three mesh setups representing Step 1, Step 2, and Step 3 visuals.
+  2. Set camera and object arrangement per step mesh.
+  3. Add radio buttons for step selection.
+  4. Bind each radio option to mesh visibility toggles.
+  5. Validate forward/backward/direct jumps and repeated runs.
+-Complexity: Easy
 
 ## Comparison Summary
--Possible in all 3? Yes / Partial / No
+-Possible in all 3? Yes
 -Main differences:
+  - Vanilla and R3F orchestrate true step transitions on shared scene objects/camera.
+  - Thob implementation is reliable via isolated prebuilt states + visibility switching.
+  - Thob currently lacks smooth transitions between steps in this flow.
 -Where Thob is better:
+  - Fast no-code setup for deterministic guided-state switching.
 -Where Thob is weaker:
+  - Multi-step storytelling polish due to missing transition primitives.
 -What feels awkward or unclear:
+  - How to author one guided flow that blends camera and object states over time instead of instant switches.
+
+## Missing Primitives / Classification
+-Runtime orchestration: Missing built-in state-to-state interpolation/timeline for guided steps.
+-Event system: Basic step triggering works with radio buttons in this workaround.
+-Schema / data model: Missing first-class step-flow schema (step bundles camera + object states + transition config).
+-Editor UX: Needs clearer guided-flow authoring panel for step order, jump rules, and reset/default behavior.
 
 ## Limitation Type (if any)
--[ ] Editor UX limitation
--[ ] Runtime limitation
--[ ] Schema / data model limitation
--[ ] Component limitation
+-[x] Editor UX limitation
+-[x] Runtime limitation
+-[x] Schema / data model limitation
+-[x] Component limitation
 -[ ] Event system limitation
 -[ ] Asset pipeline limitation
 -[ ] Unknown / needs investigation
 
 ## Workaround
 -Is there a workaround?
+  - Yes.
 -If yes, what is it?
+  - Prebuild each step as a separate mesh/group and toggle visibility using radio buttons for reliable sequencing and reset.
 
 ## Suggested Improvement
 -What should improve in Thob?
+  - Add a first-class guided flow component (Step 1/2/3 bundles).
+  - Support transition duration/easing for camera, transform, and visibility.
+  - Add reset/default step control and optional sequencing constraints.
+  - Provide timeline/preview UI for multi-step narrative authoring.
 -Is it:
-  -editor
-  -runtime
-  -component
-  -UX
-  -schema/data
+  - editor
+  - runtime
+  - component
+  - UX
+  - schema/data
 
 ## Difficulty Estimate
--Easy / Medium / Hard
+-Medium
 
 ## Business Value
--Low / Medium / High
+-High
 
 ## Recommendation
-Should Thob support this better? Why?
+Yes, Thob should support this better. Reliability for step switching is already strong with the visibility workaround, and adding native transition/orchestration primitives would make it fully suitable for customer-facing multi-step narratives.