fix(angular-3d): resolve lifecycle hooks and test issues

Author: Abdallah-khalil

docs/angular-3d-library/09-angular-gsap-directives-and-consumers.md

@@ -0,0 +1,199 @@
+# Angular GSAP directives (current implementation) + consumers
+
+This doc captures the **exact GSAP/ScrollTrigger-based directives/components currently living inside `dev-brand-ui`** and every known consumer, as the source-of-truth for extracting a new standalone library: **`@hive-academy/angular-gsap`**.
+
+Scope:
+
+- ✅ Document existing behavior and public APIs (as implemented today).
+- ✅ List all components that use these directives/components.
+- ✅ Describe how they should move into the new `@hive-academy/angular-gsap` workspace.
+
+## Why a separate `@hive-academy/angular-gsap` library
+
+Right now the GSAP directives live under the Angular 3D area:
+
+- `apps/dev-brand-ui/src/app/core/angular-3d/directives/*`
+
+But they are **not 3D-specific**:
+
+- `scrollAnimation` animates regular DOM elements.
+- `hijackedScroll` is a generic “scroll-jacked” content sequence.
+
+Extracting them into `@hive-academy/angular-gsap` lets the 3D package (`@hive-academy/angular-3d`) stay focused on Three.js primitives while still reusing scroll UX patterns.
+
+## Current GSAP directives (to migrate)
+
+### 1) `ScrollAnimationDirective`
+
+- File: [apps/dev-brand-ui/src/app/core/angular-3d/directives/scroll-animation.directive.ts](apps/dev-brand-ui/src/app/core/angular-3d/directives/scroll-animation.directive.ts)
+- Selector: `[scrollAnimation]`
+- What it does:
+  - Creates a paused GSAP timeline, binds it to a `ScrollTrigger`.
+  - Supports predefined animation types (`fadeIn`, `slideUp`, `scaleIn`, `parallax`, etc.) and fully custom `from/to`.
+  - Cleans up on destroy and re-initializes when config changes.
+
+**Primary input**
+
+- `scrollConfig: ScrollAnimationConfig` (signal-based input)
+  - Defaults: `{ animation: 'fadeIn', start: 'top 80%', duration: 1, ease: 'power2.out' }`
+
+**Key config fields**
+
+- ScrollTrigger: `trigger`, `start`, `end`, `scrub`, `pin`, `pinSpacing`, `markers`, `once`, `toggleActions`
+- Animation: `duration`, `delay`, `ease`, `stagger`, `from`, `to`
+- Callbacks: `onEnter`, `onLeave`, `onEnterBack`, `onLeaveBack`, `onUpdate(progress)`
+
+**Important behavior notes**
+
+- It currently guards against being attached to non-`HTMLElement` targets and will log a warning.
+
+### 2) `HijackedScrollDirective`
+
+- File: [apps/dev-brand-ui/src/app/core/angular-3d/directives/hijacked-scroll.directive.ts](apps/dev-brand-ui/src/app/core/angular-3d/directives/hijacked-scroll.directive.ts)
+- Selector: `[hijackedScroll]`
+- What it does:
+  - Pins the container while scrolling through “steps”.
+  - Builds a GSAP master timeline where each step fades/slides in/out.
+  - Emits current step index and overall progress.
+  - Supports per-step “decoration” animations via `[data-decoration-index]` + `.decoration-inner`.
+
+**Inputs**
+
+- `scrollHeightPerStep` (vh per step, default `100`)
+- `animationDuration` (seconds, default `0.3`)
+- `ease` (default `power2.out`)
+- `markers` (default `false`)
+- `minHeight` (default `100vh`)
+- `start` (default `top top`)
+- `end` (optional; otherwise calculated)
+
+**Outputs**
+
+- `currentStepChange: number`
+- `progressChange: number`
+
+**Child dependency**
+
+- Discovers its steps via `contentChildren(HijackedScrollItemDirective, { descendants: true })`.
+
+### 3) `HijackedScrollItemDirective`
+
+- File: [apps/dev-brand-ui/src/app/core/angular-3d/directives/hijacked-scroll-item.directive.ts](apps/dev-brand-ui/src/app/core/angular-3d/directives/hijacked-scroll-item.directive.ts)
+- Selector: `[hijackedScrollItem]`
+- What it does:
+  - Marks an element as a step inside a hijacked scroll container.
+  - Provides per-step config used by `HijackedScrollDirective`.
+
+**Inputs**
+
+- `slideDirection: 'left' | 'right' | 'up' | 'down' | 'none'` (default `none`)
+- `fadeIn: boolean` (default `true`)
+- `scale: boolean` (default `true`)
+- `customFrom?: Record<string, unknown>`
+- `customTo?: Record<string, unknown>`
+
+## Components that wrap or use these directives
+
+### 1) `HijackedScrollTimelineComponent` (wrapper)
+
+- File: [apps/dev-brand-ui/src/app/shared/components/hijacked-scroll-timeline.component.ts](apps/dev-brand-ui/src/app/shared/components/hijacked-scroll-timeline.component.ts)
+- Selector: `app-hijacked-scroll-timeline`
+- What it does:
+  - Thin wrapper around `HijackedScrollDirective` via `hostDirectives`.
+  - Pass-through inputs/outputs, with `ng-content` so each feature section can own its markup.
+
+### 2) `ScrollingCodeTimelineComponent` (direct user)
+
+- File: [apps/dev-brand-ui/src/app/shared/components/scrolling-code-timeline.component.ts](apps/dev-brand-ui/src/app/shared/components/scrolling-code-timeline.component.ts)
+- What it does:
+  - Uses `HijackedScrollDirective` + `HijackedScrollItemDirective` directly.
+  - Implements an `@for`-driven progressive “story” layout.
+
+## Consumers inventory (who uses what)
+
+### Uses `ScrollAnimationDirective` (`[scrollAnimation]`)
+
+Landing page sections importing/using `ScrollAnimationDirective`:
+
+- [temp/capabilities-matrix-section.component.ts](temp/capabilities-matrix-section.component.ts)
+- [temp/problem-solution-section.component.ts](temp/problem-solution-section.component.ts)
+- [temp/value-propositions-section.component.ts](temp/value-propositions-section.component.ts)
+- [temp/workflow-examples-section.component.ts](temp/workflow-examples-section.component.ts)
+- [temp/neo4j-section.component.ts](temp/neo4j-section.component.ts)
+- [temp/langgraph-memory-section.component.ts](temp/langgraph-memory-section.component.ts)
+- [temp/langgraph-core-section.component.ts](temp/langgraph-core-section.component.ts)
+- [temp/hero-section.component.ts](temp/hero-section.component.ts)
+- [temp/developer-experience-section.component.ts](temp/developer-experience-section.component.ts)
+- [temp/cta-section.component.ts](temp/cta-section.component.ts)
+- [temp/chromadb-section.component.ts](temp/chromadb-section.component.ts)
+
+Also present (currently commented out DOM overlay):
+
+- [temp/hero-section-space.component.ts](temp/hero-section-space.component.ts)
+
+### Uses `HijackedScrollTimelineComponent` (`<app-hijacked-scroll-timeline>`)
+
+- [temp/langgraph-core-section.component.ts](temp/langgraph-core-section.component.ts)
+- [temp/langgraph-memory-section.component.ts](temp/langgraph-memory-section.component.ts)
+- [temp/neo4j-section.component.ts](temp/neo4j-section.component.ts)
+- [temp/chromadb-section.component.ts](temp/chromadb-section.component.ts)
+
+### Uses `HijackedScrollDirective` / `HijackedScrollItemDirective` directly
+
+- [apps/dev-brand-ui/src/app/shared/components/scrolling-code-timeline.component.ts](apps/dev-brand-ui/src/app/shared/components/scrolling-code-timeline.component.ts)
+
+## Extraction guide: `@hive-academy/angular-gsap`
+
+### Recommended library surface
+
+For the new workspace package, treat these as the initial public API:
+
+- `ScrollAnimationDirective`
+- `HijackedScrollDirective`
+- `HijackedScrollItemDirective`
+- `HijackedScrollTimelineComponent` (optional, but it’s already a stable convenience wrapper)
+- Types:
+  - `ScrollAnimationConfig`, `AnimationType`
+  - `HijackedScrollConfig`, `HijackedScrollItemConfig`, `SlideDirection`
+
+### Suggested folder layout
+
+- `libs/angular-gsap/src/lib/scroll/scroll-animation.directive.ts`
+- `libs/angular-gsap/src/lib/scroll/hijacked-scroll.directive.ts`
+- `libs/angular-gsap/src/lib/scroll/hijacked-scroll-item.directive.ts`
+- `libs/angular-gsap/src/lib/components/hijacked-scroll-timeline.component.ts`
+- `libs/angular-gsap/src/index.ts` (public exports)
+
+### Dependencies and packaging
+
+- `gsap` should be a dependency (or peerDependency if you want app-level control).
+- `@angular/*` should follow the workspace Angular version (peer deps for publishing).
+
+### SSR / platform note (important)
+
+Today, both directives call `gsap.registerPlugin(ScrollTrigger)` at module load time.
+
+In the new library, prefer registering ScrollTrigger only in the browser (e.g., via `isPlatformBrowser`), so SSR builds don’t accidentally execute DOM-dependent code.
+
+## “Related GSAP usage” to consider later
+
+Not part of the directive set above, but these are additional GSAP touchpoints you may want to fold into `@hive-academy/angular-gsap` (or a separate animation lib):
+
+- [apps/dev-brand-ui/src/app/core/angular-3d/services/animation.service.ts](apps/dev-brand-ui/src/app/core/angular-3d/services/animation.service.ts) (GSAP-driven service, currently also depends on `angular-three`)
+- [apps/dev-brand-ui/src/app/core/angular-3d/components/primitives/planet.component.ts](apps/dev-brand-ui/src/app/core/angular-3d/components/primitives/planet.component.ts) (uses GSAP tween for rotation)
+
+## Quick “known-good” usage patterns (from current code)
+
+### `scrollAnimation` on hero elements
+
+See patterns in:
+
+- [temp/developer-experience-section.component.ts](temp/developer-experience-section.component.ts)
+- [temp/workflow-examples-section.component.ts](temp/workflow-examples-section.component.ts)
+
+### Hijacked scroll timeline with projected content
+
+See:
+
+- [temp/chromadb-section.component.ts](temp/chromadb-section.component.ts)
+- [temp/langgraph-core-section.component.ts](temp/langgraph-core-section.component.ts)

docs/angular-3d-library/DOCUMENT-INDEX.md

@@ -12,14 +12,15 @@
 6. **[05-angular-3d-package-requirements.md](./05-angular-3d-package-requirements.md)** - Minimal replacement checklist (explicitly includes copying angular-3d + scene-graphs into a new workspace)
 7. **[06-new-workspace-blueprint.md](./06-new-workspace-blueprint.md)** - Template migration vs ngt-tag compatibility + how to reuse threejs-vanilla docs
 8. **[07-threejs-vanilla-to-angular-mapping.md](./07-threejs-vanilla-to-angular-mapping.md)** - Chapter-by-chapter mapping into package folders
-9. **[08-git-hooks-linting-standards.md](./08-git-hooks-linting-standards.md)** - Husky + lint-staged + commitlint + ESLint standards to mirror this repo
+9. **[09-angular-gsap-directives-and-consumers.md](./09-angular-gsap-directives-and-consumers.md)** - GSAP/ScrollTrigger directives + all current consumers (for new `@hive-academy/angular-gsap`)
+10. **[08-git-hooks-linting-standards.md](./08-git-hooks-linting-standards.md)** - Husky + lint-staged + commitlint + ESLint standards to mirror this repo
 
 ### 🚧 Planned (Component Patterns)
 
-10. **06-primitive-components.md** - Wrapping Three.js meshes (Planet, Box, Sphere)
-11. **07-material-management.md** - Reactive material updates with signals
-12. **08-geometry-handling.md** - BufferGeometry, instancing patterns
-13. **09-loader-components.md** - GLTF, SVG, texture loaders
+11. **06-primitive-components.md** - Wrapping Three.js meshes (Planet, Box, Sphere)
+12. **07-material-management.md** - Reactive material updates with signals
+13. **08-geometry-handling.md** - BufferGeometry, instancing patterns
+14. **09-loader-components.md** - GLTF, SVG, texture loaders
 
 ### 🚧 Planned (Directive Patterns)
 

libs/angular-3d/src/lib/primitives/box.component.ts

@@ -1,7 +1,6 @@
 import {
   Component,
   ChangeDetectionStrategy,
-  OnInit,
   OnDestroy,
   inject,
   input,
@@ -16,7 +15,7 @@ import { NG_3D_PARENT } from '../types/tokens';
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '',
 })
-export class BoxComponent implements OnInit, OnDestroy {
+export class BoxComponent implements OnDestroy {
   // Transformation inputs
   public readonly position = input<[number, number, number]>([0, 0, 0]);
   public readonly rotation = input<[number, number, number]>([0, 0, 0]);
@@ -61,45 +60,63 @@ export class BoxComponent implements OnInit, OnDestroy {
       }
     });
     effect(() => {
-      // Re-create geometry if args change (expensive but necessary for geometry params)
+      // Re-create geometry and material if args or material props change
+      // Note: Typically geometry and material are separate concerns.
+      // But for primitives, it's often cleaner to rebuild everything or use distinct effects.
+      // Optimally:
+      // 1. Geometry effect (depends on args)
+      // 2. Material effect (depends on color, wireframe)
+      // 3. Mesh effect (depends on geometry, material)
+      // Let's do that for clarity and performance.
+
       const [width, height, depth] = this.args();
-      if (this.geometry) {
-        this.geometry.dispose();
-      }
-      this.geometry = new THREE.BoxGeometry(width, height, depth);
+      const newGeometry = new THREE.BoxGeometry(width, height, depth);
+
+      // Dispose old
+      if (this.geometry) this.geometry.dispose();
+      this.geometry = newGeometry;
+
+      // Update mesh
       if (this.mesh) {
         this.mesh.geometry = this.geometry;
+      } else {
+        // First run? We need to ensure mesh exists.
+        // But constructor runs before ngOnInit used to.
+        // We can create the mesh container in constructor?
+        // Or create it here?
+        // If we split effects, we need a common coordinate.
+        // Pattern: Create mesh structure in a main effect logic?
+        this.mesh = new THREE.Mesh(this.geometry, this.material);
+        this.mesh.position.set(...this.position());
+        this.mesh.rotation.set(...this.rotation());
+        this.mesh.scale.set(...this.scale());
+        this.addToParent();
       }
     });
-  }
 
-  public ngOnInit(): void {
-    // Initialize geometry
-    const [width, height, depth] = this.args();
-    this.geometry = new THREE.BoxGeometry(width, height, depth);
+    effect(() => {
+      // Material updates
+      const color = this.color();
+      const wireframe = this.wireframe();
 
-    // Initialize material
-    this.material = new THREE.MeshStandardMaterial({
-      color: this.color(),
-      wireframe: this.wireframe(),
+      if (this.material) {
+        this.material.color.set(color);
+        this.material.wireframe = wireframe;
+        this.material.needsUpdate = true;
+      } else {
+        this.material = new THREE.MeshStandardMaterial({ color, wireframe });
+        if (this.mesh) this.mesh.material = this.material;
+      }
     });
+  }
 
-    // Initialize mesh
-    this.mesh = new THREE.Mesh(this.geometry, this.material);
-    this.mesh.position.set(...this.position());
-    this.mesh.rotation.set(...this.rotation());
-    this.mesh.scale.set(...this.scale());
-
-    // Add to parent
-    if (this.parentFn) {
+  // Helper to add to parent safely
+  private addToParent(): void {
+    if (this.parentFn && this.mesh) {
       const parent = this.parentFn();
       if (parent) {
         parent.add(this.mesh);
-      } else {
-        console.warn('BoxComponent: Parent not ready');
       }
-    } else {
-      console.warn('BoxComponent: No parent found');
     }
   }