---
id: key-on-uelement
name: Add key field to UElement
status: pending
depends_on: []
created: 2026-05-18T16:22:57.098951833Z
modified: 2026-05-18T16:22:57.098952376Z
scope: narrow
risk: low
impact: component
level: implementation
---

# Description

Add `key?: string` as a first-class field on `UElement` in both the TypeScript type and the TypeBox Module schema. This is Reconciler Roadmap Phase 0 (ADR-004).

The `key` field enables identity-based children matching in the reconciler. Without it, reconciliation is positional-only, which breaks when children are reordered, inserted, or removed. `key` is a reconciler concern, not a component concern — it must live outside `props` so that component schemas don't need to declare it and component functions never receive it.

`URoot` does NOT get a `key` field. Roots are unique per `createRoot()` call and are never children of another element.

## Acceptance Criteria

- [ ] `UElement` TypeScript type has `key?: string` field
- [ ] TypeBox Module `UElement` schema includes `Type.Optional(Type.String())` for `key`
- [ ] `URoot` TypeScript type has no `key` field
- [ ] `URoot` TypeBox schema has no `key` field
- [ ] `isUElement` type guard still correctly discriminates UElement from URoot
- [ ] Existing tests pass (`npm run test`)
- [ ] New test: `UElement` with `key` field validates and type-checks
- [ ] New test: `UElement` without `key` field still works (backward compatible)

## References

- docs/architecture/schema.md — Known Gaps: `key` field on `UElement`
- docs/architecture/decisions/004-key-as-first-class-field.md — ADR-004
- docs/architecture/reconciler.md — Reconciler Roadmap Phase 0

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion