# Kutby Foundation v2 — Implementation Report

**Version:** 2.0.0  
**Approach:** Incremental upgrade — preserve working systems, avoid over-engineering  

---

## 1. Everything Changed

### Build pipeline (Priority 1)
- Added `package.json`, `vite.config.js`, `postcss.config.js` (Autoprefixer + cssnano in production)
- Source entries: `src/main.js`, `src/admin.js`
- Production output in `assets/dist/` with **hashed** `main.min.[hash].css/js` and `admin.min.[hash].css/js`
- `manifest.json` for WordPress to resolve hashed files
- Scripts: `npm run dev` (HMR), `npm run build`

### Design tokens (Priority 2)
- Added `src/css/tokens/tokens.css` (colors, spacing, radius, typography, shadows, z-index, opacity, transitions, breakpoints)
- Build entry imports tokens first
- Theme Options still override color/type/layout tokens via inline CSS variables (unchanged pattern)

### Module architecture (Priority 3) — light touch
- Added `ModuleInterface` (`register()` + `boot()`)
- Added `ModuleLoader` (register all → boot all)
- Existing classes implement the interface (`Setup`, `AssetLoader`, `Performance`, `SEO`, `FrontendHooks`)
- Thin wrappers only where needed: `ThemeOptionsModule`, `AdminModule`, `IntegrationsModule`
- `Theme::boot()` now runs modules via loader + `kutby_modules` filter
- **Kept** `Theme::instance()` singleton for BC

### Assets / environment (Priority 5)
- `Support\Environment` — `KUTBY_DEV` flag
- `Assets\Manifest` — reads Vite manifest
- `AssetLoader` prefers dist; falls back to legacy `assets/css` + `assets/js`
- Dev mode can load Vite client from `:5173`
- Admin enqueue also prefers dist admin entry

### Theme Options (Priority 6) — improve, don’t replace
- Added central `ThemeOptions\Schema` (type, default, label, UI metadata)
- `Defaults::all()` now delegates to `Schema::defaults()` (BC methods kept)
- `Sanitizer` uses `Schema::type()` instead of hardcoded color/url heuristics
- Migrated **General / Colors / Performance** pages to `Schema::fields_for()`
- **Left other page classes as-is** (still work; can migrate gradually)
- Manager / Registry / Dashboard save flow **unchanged**

### Admin + frontend components (Priority 7–8)
- Admin component CSS stubs: tabs, modal, tooltip, dropdown (design language layer)
- Frontend component stubs: section, badge, search-box (token-based)
- **No page redesigns / no homepage UI**

### Code quality scaffolding (Priority 10)
- `phpcs.xml.dist`, `phpstan.neon.dist`, `.eslintrc.json`, `.stylelintrc.json`
- Tooling configs only — not wired into CI yet

### Version
- Theme version bumped to **2.0.0**

---

## 2. Why Each Change Improves the Project

| Change | Benefit |
|--------|---------|
| Vite bundle | Removes runtime `@import` HTTP waterfall; real minify + hash cache busting |
| Manifest loader | Production-safe hashed filenames without hardcoding hashes in PHP |
| Tokens file | One place for visual constants; components can stop inventing magic numbers |
| ModuleInterface | Clear extension point (`kutby_modules`) without a DI container |
| Schema | Ends duplicate default/sanitize definitions for storage; UI can follow over time |
| Fallback paths | Sites without `npm run build` still boot (legacy assets) |
| Quality configs | Ready for PHPCS/PHPStan/ESLint when you add Composer/CI |

---

## 3. Remaining Weaknesses

1. **Not all Options pages use Schema yet** — Typography/Header/Footer/etc. still hand-define fields (works, but still dual UI definitions until migrated).
2. **Admin UI components are CSS-only stubs** — no JS behaviors for modal/tabs/dropdown yet.
3. **No critical CSS extraction** in the Vite pipeline yet (hook exists; empty by default).
4. **Tree shaking is limited** — JS is still small IIFEs, not a modular ESM app tree.
5. **PHPCS/PHPStan/ESLint are not runnable out of the box** without installing WPCS/Composer/stylelint packages.
6. **`Theme::instance()` singleton remains** — acceptable; not removed to avoid BC breaks.
7. **Legacy `assets/css/main.css` still uses `@import`** — only used as fallback when dist missing.
8. **Vite CSS asset naming** uses content hashes (`main.min.CGY9NWsh.css`) — correct for cache busting; not the literal unhashed `main.min.css` filename (hash is the commercial approach).

---

## 4. Technical Debt

- Migrate remaining Options pages to `Schema::fields_for()`.
- Optionally delete or stop shipping fallback `@import` main.css once dist is mandatory in release process.
- Add Composer `require-dev` for WPCS + PHPStan (configs exist, deps don’t).
- Commit policy: `assets/dist` should be built before every release (document in README).
- Admin jQuery dependency remains (wp-admin only — intentional).
- Empty `inc/Services`, `inc/Repositories`, `inc/Traits` folders were prepared earlier; left unused on purpose (no over-engineering).

---

## 5–9. Scores (critical)

| Score | v1 | v2 | Notes |
|-------|----|----|-------|
| **Architecture** | 7.5 | **8.0** | Modules + schema without rewriting core |
| **Performance** | 5.5 | **7.5** | Dist bundle fixes the biggest CWV footgun; critical CSS / font subsetting still open |
| **Scalability** | 6.5 | **7.5** | Filterable modules + schema; still no query/caching layer for platform scale |
| **Security** | 7.5 | **7.5** | Same solid save path; no new attack surface of note |
| **Commercial readiness** | 6.0 | **7.5** | Shipable foundation engine; not a finished product theme |

**Brutal honesty:** This is now a credible **premium foundation**, not yet GeneratePress/Kadence feature parity. Those products have years of Customizer/block integrations, docs, and release tooling. v2 closes the “amateur CSS @import” gap and hardens structure — it does **not** magically make Kutby commercially complete.

---

## 10. What Should Be Built Next (before UI)

1. Migrate remaining Options panels to Schema (1–2 hours, low risk).
2. Document release checklist: `npm run build` → commit/publish `assets/dist`.
3. Add Composer dev toolchain so PHPCS/PHPStan actually run.
4. Implement breadcrumb renderer (settings already exist).
5. **Then** start UI: Header → Footer → Card system → Homepage sections.

Do **not** start visual homepage work until (1)+(2) are done so designers aren’t styling against the fallback `@import` path by accident.

---

## Direct Answers

### What changed philosophically?
Upgrade existing systems. Don’t invent a framework.

### Is it still compatible?
Yes: Manager API, templates, options key, admin panels, and theme activation remain. Dist is preferred; source is fallback.

### Is it commercial-grade yet?
**Foundation: yes (with caveats). Product: no.**  
Commercial-grade *engine base* — not a commercial *finished theme*.

---

*End of Foundation v2 report.*
