# Foundation Sprint 1 Report

**Theme:** Kutby  
**Sprint:** Foundation Sprint 1 (audit debt burn-down)  
**Date:** 2026-07-24  
**Mode:** Refactor only — no new features, no contract edits, no ModuleManager/Theme boot changes

---

## Completed Tasks

### P0

1. **Removed orphan Pages system** — Deleted 14 unused page classes that duplicated field definitions (English/`__()` maps). Active path is exclusively Schema → FieldRegistry → SchemaDrivenPage → AbstractPage → Components.
2. **FieldRegistry is the public API** — `PageFactory` / `SchemaDrivenPage` / `Defaults` call FieldRegistry. `Schema` remains internal (documented).
3. **Unified save pipeline** — Admin form + AJAX both use `FieldRegistry::store()` → validate → `Manager::save()` (sanitize + cache refresh + events).
4. **Single `options_saved` emit** — Removed duplicate `Dispatcher::emit` from SettingsBridge; Manager emits once (optional context: `via`, `panel`).

### P1

5. **Font preload via manifest** — `AssetManifestManager::font_url()` resolves hashed `assets/dist/*` URLs; dist mode never preloads unhashed paths.
6. **SVG icon request memoization** — `Utils::icon()` caches sanitized markup per request.
7. **WidgetsModule owns sidebars** — Registration moved from `FrontendHooks`; BC no-op stub retained on `FrontendHooks::register_sidebars()`.
8. **Conditional Admin assets** — Color picker / media library load only when the active panel’s FieldRegistry schema needs `color` / `media` (Showcase still gets media).

---

## Files Changed

| File | Change |
|------|--------|
| `inc/Pages/*Page.php` (14 files) | **Deleted** orphan field-map pages |
| `inc/Pages/SchemaDrivenPage.php` | FieldRegistry API |
| `inc/Pages/PageFactory.php` | FieldRegistry API |
| `inc/ThemeOptions/FieldRegistry.php` | Canonical `store()` → Manager |
| `inc/ThemeOptions/Manager.php` | Optional `$context` on save; single event emit |
| `inc/ThemeOptions/Defaults.php` | Delegates to FieldRegistry |
| `inc/ThemeOptions/Schema.php` | Marked internal |
| `inc/Admin/Dashboard.php` | `store()` save path; conditional enqueue |
| `inc/Live/SettingsBridge.php` | `store()` only; no duplicate event |
| `inc/Assets/AssetManifestManager.php` | `font_url()` |
| `inc/Performance/Performance.php` | Manifest-based preload |
| `inc/Helpers/Utils.php` | Icon static cache |
| `inc/Modules/WidgetsModule.php` | Sidebar registration |
| `inc/Hooks/FrontendHooks.php` | Sidebars removed; BC stub |

---

## Architectural Improvements

- One field definition source (Schema internal / FieldRegistry public).
- One save orchestration entry (`FieldRegistry::store`).
- Clearer module ownership for widgets.
- Dead English page maps removed — eliminates future Schema drift.

---

## Performance Improvements

- Font preload matches Vite hashed assets (no double-fetch of unhashed + hashed).
- SVG icons read once per name per request.
- Admin color picker / media not loaded on every Kutby panel.

---

## Backward Compatibility Notes

- Public hooks unchanged (`kutby_options_saved`, `kutby_booted`, `kutby_modules`, `kutby_widgets_module_ready`, `kutby_preload_fonts`, etc.).
- Option key unchanged (`kutby_options`).
- `Manager::save( $options )` still works; optional second `$context` argument added.
- `kutby_preload_fonts` still accepts legacy `tajawal/…` paths (normalized in `font_url()`).
- `FrontendHooks::register_sidebars()` remains callable but is a no-op (registration in WidgetsModule).
- `Defaults::*` retained as BC facades over FieldRegistry.
- Custom panels (`dashboard`, `appearance`, `import_export`, `system`) unchanged in behavior.
- ModuleManager / Theme boot untouched.

---

## Remaining Technical Debt (out of Sprint 1 scope)

- Legacy Admin shell CSS hardcoded tokens (Design System P0 from audit).
- Modal focus trap / Escape (Design System).
- Custom Admin pages still bypass Components (Dashboard/Appearance/System/ImportExport).
- Frontend empty states weak.
- Field renderers still duplicate some Components markup.
- Dormant `register_setting` on `KUTBY_OPTION_KEY` (Settings API dual path).
- TemplateTags still thin (`footer`/`sidebar`/`front-page` logic).
- Tabs/tooltip a11y gaps.
- Search JS outside Vite manifest.

These belong to later sprints — **not started**.

---

## Estimated Foundation Readiness after Sprint 1

| Dimension | Pre-sprint (audit) | Post-sprint (est.) |
|-----------|--------------------|--------------------|
| Architecture | 82 | **86** |
| Performance | 80 | **84** |
| Design System | 72 | 72 (unchanged — UI debt deferred) |
| Maintainability | 76 | **82** |
| Scalability | 81 | **84** |
| **Overall** | **78** | **~83** |

Sprint 1 closed the highest-value architecture/performance debt without expanding surface area. Design System shipping CSS/a11y gaps remain the main ceiling on Overall.

---

**Sprint 1 complete. Sprint 2 not started.**
