# Kutby Hero Engine

**Status:** Architecture + visual foundation (Phase 1)  
**Version:** 2.8.0  
**Mirrors:** `HEADER-ENGINE.md`, `FOOTER-ENGINE.md`

**Related:** `ARCHITECTURE.md`, `PERFORMANCE.md`, `DESIGN_SYSTEM.md`

Hero is the **third core Layout Engine**. Not a page builder. Not a slider.

---

## 1. Architecture

```
HeroRegistry
  → HeroManager
    → HeroRenderer
      → HeroContext (+ HeroQuery pool)
        → HeroVisibility (Admin/save)
          → Layouts (HeroLayoutInterface)
            → Components
```

No layout `switch` in Renderer or templates.

---

## 2. Rendering flow

```
front-page.php
  → HeroRenderer::render()
       → abort if homepage.hero disabled
       → HeroManager::layout()
       → HeroContext::from_request()
       → Layout::render($ctx)
            → Components (FeaturedArticle, ArticleCard, …)
       → emit kutby/hero_rendered
```

---

## 3. Data (HeroContext / HeroQuery)

| Method | Source |
|--------|--------|
| `featured()` | First post in memoized pool |
| `secondary(n)` | Next n posts |
| `grid_posts()` | First `posts_count` |
| `trending(n)` | Same pool sorted by `comment_count` |
| `latest(n)` | Chronological slice of pool |

**One `WP_Query` per request** (memoized). Args filtered via `kutby_hero_query_args` for future providers.

`featured_source`: `latest` | `sticky` | `category` | `tag` | `manual`

---

## 4. Layouts

| Id | Composition |
|----|-------------|
| `classic` | Featured + 4 ArticleCards |
| `magazine` | Featured + TrendingList + LatestPosts |
| `grid` | HeroGrid of ArticleCards |
| `minimal` | Title/subtitle (+ optional featured backdrop) |

Register extras:

```php
add_action( 'kutby_hero_register_layouts', function ( \Kutby\Hero\Services\HeroRegistry $r ) {
    $r->add( 'split', \Kutby\Hero\Layouts\SplitHero::class );
});
```

---

## 5. Components

FeaturedArticle, ArticleCard, TrendingList, LatestPosts, CategoryBadge, ArticleMeta, HeroGrid, HeroSection, Overlay, ReadMoreButton, BackgroundImage, Skeleton, LoadingState

Rules: Context + `$args` only; never check layout id; tokens only; featured image eager, secondary lazy.

---

## 6. Theme Options

- Group: `hero` (panel **قسم البطل**)
- Master enable: `homepage.hero` (existing homepage toggle)
- Visibility SSOT: `HeroVisibility` (+ Dashboard save path)
- Always-on Admin key: `layout`

---

## 7. CSS

| File | Role |
|------|------|
| `assets/css/layout/hero.css` | Shared |
| `assets/css/components/hero/layout-*.css` | Per layout |

---

## 8. How to add a layout

1. Implement `HeroLayoutInterface` under `inc/Hero/Layouts/`
2. Register on `kutby_hero_register_layouts` (or in `HeroModule`)
3. Add Schema keys under `hero()` + `option_keys()`
4. Add `layout-{id}.css` and import in main CSS
5. Do **not** edit Renderer / Manager / Theme / `functions.php`

---

## 9. Best practices

- Derive all post subsets from `HeroContext` — never query inside components
- Prefer composing existing components over new markup
- Keep visual polish in layout CSS files, shared chrome in `hero.css`
- Gate unfinished features; do not fake ESP/builders/sliders
