# Phase Handover — Experience 11.2 Component Library & Versioning

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | `experience-11.2` |
| Title | Component Library & Versioning |
| Status | Complete |
| Service(s) | `experience` (`experience_db`) |
| Version | `0.11.2.0` |
| Date | 2026-07-26 |
| ADR(s) | [ADR-016](../architecture/adr/ADR-016.md) |

## Discovery Summary

Prior phase delivered sites/pages. Gap: versioned reusable components with immutable published revisions and page composition pins. Themes/layouts deferred to 11.3.

## Reusable Components

| Component | Location | Reuse notes |
| --- | --- | --- |
| Component catalog | `app/models/components.py`, `services/components.py` | Lifecycle + kinds |
| Immutable versions | `ExperienceComponentVersion.is_immutable` | Publish locks content |
| Composition shells | `PageComponentPlacement` | Slot pins only — no layout engine |
| Policies / specs | `app/policies/`, `app/specifications/` | Transition + list UX |
| Commands / queries | `app/commands/`, `app/queries/` | CQ separation |

## Public APIs

| Method | Path | Permission |
| --- | --- | --- |
| CRUD + activate/deprecate/archive | `/api/v1/components` | `experience.components.*` |
| CRUD + publish/retire | `/api/v1/component-versions` | `experience.components.*` |
| CRUD | `/api/v1/page-component-placements` | `experience.components.*` |

## Events

| Event type | Notes |
| --- | --- |
| `experience.component.*` | Catalog lifecycle |
| `experience.component_version.*` | Version lifecycle + immutability |
| `experience.page_component.*` | Placement create/update/remove |

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| `definition_schema` / `props_defaults` | Theme/layout phases consume props | Store theme tokens as layout engine in 11.2 |
| `render_hint` | Future render engines | Bind foreign DB rows |
| `menu_ref` / `catalog_ref` kinds | Vertical entity refs via API | Shared Hospitality/Marketplace tables |

## Known Limitations

- No theme/layout engines (11.3)
- No visual section tree / page builder UI
- Placement requires published version only
- Metrics remain discovery-oriented

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | `0003_phase_112_components` |
| Upgrade steps | `alembic upgrade head` |
| Downgrade support | Drops placements, versions, components |
| Breaking changes | None (additive) |

## Dependencies

| Dependency | Type |
| --- | --- |
| experience-11.1 sites/pages | Required parent |
| ADR-016 | Boundaries |

## Quality Gates

- [x] Discovery complete
- [x] Architecture / boundaries preserved
- [x] Tests green (unit, API, architecture, migration, docs, tenant, security-compatible)
- [x] Documentation + manifests + registries updated
- [x] Self audit: no theme/layout leakage; published versions immutable

## Next Phase Entry

| Field | Value |
| --- | --- |
| Recommended next phase | `experience-11.3` Theme & Layout Engine |
| Entry checklist | Read this handover + phase doc; implement themes/layouts only — no template catalog yet |

## Completion Sign-Off

- [x] Quality gates passed
- [x] Tests green
- [x] Documentation updated
- [x] Progress / next-steps / registries updated
- [x] Self audit completed

## Related Documents

- [Experience Phase 11.2](../experience-phase-11-2.md)
- [Experience Roadmap](../experience-roadmap.md)
- [ADR-016](../architecture/adr/ADR-016.md)