# Clean-Room Implementation Record: Xeno Framework-Neutral UI

## Identity

- Component: Xeno-owned agent UI controller, semantic view model, and DOM renderer
- Replacement milestone: PROPRIETARY-UI-1
- Repository and paths: `xeno-agent-sdk/src/ui/`, `src/electron/setupAIHandlers.ts`, `src/context/ScreenCapture.ts`
- Record owner: Xeno engineering, final owner assignment pending
- Implementer(s): Codex implementation assistant; human accessibility and UI review pending
- Contract author(s): Xeno engineering requirements in `switch-to-proprietary.md`
- Started at (UTC): 2026-07-12
- Candidate revision: `87ae64b55aa1b8c2e126294e717b229e0945db65` plus recorded working-tree changes
- Status: engineering implementation and package removal complete; independent review and release-version approval pending

## Frozen behavioral contract

- Public API: renderer API version 1 exports `createAgentUiController`, `createAgentUiView`, `dispatchAgentUiAction`, and `mountAgentUi`.
- State behavior: immutable snapshots project ordered messages, streaming text, tool execution, errors, token usage, processing state, and one current permission request.
- Interaction behavior: multiline composition, Ctrl/Command+Enter submission, duplicate-send guard, cancellation, clearing, retry, permission request identity checks, focus, subscription, and explicit disposal.
- Accessibility behavior: labelled region, polite status and log live regions, busy state, article/status/alert timeline roles, alert-dialog permission prompt, labelled controls, focus-visible styling, and reduced-motion handling.
- Security and resource limits: DOM output uses created nodes and `textContent`; active URL schemes are rejected; tool details are bounded to 64 KiB; stale permission actions cannot resolve a newer prompt.
- Host boundary: Electron package discovery is removed. IPC registration and desktop capture require explicit host adapters.
- Intentional incompatibilities: former React components/hooks and hidden Electron auto-discovery are breaking changes reserved for the next major SDK release and documented in `docs/migrations/sdk-ui-v1.md`.

## Normative and permitted inputs

| Source | Revision/date | Purpose | Terms reviewed by | Evidence path |
| --- | --- | --- | --- | --- |
| Xeno proprietary migration specification | 2026-07-12 | UI ownership, package removal, compatibility, and release constraints | Engineering; counsel pending | `switch-to-proprietary.md` |
| Existing Xeno-owned UI behavior and types | candidate working tree | Product behavior to preserve without copying third-party implementation | Engineering | removed `src/ui/*` React components and focused tests |
| HTML DOM and accessibility platform contracts | accessed 2026-07-12 | DOM creation, events, roles, live regions, labels, and focus | Engineering | public web-platform and WAI-ARIA documentation |
| Xeno AgentLoop callback and permission contracts | candidate working tree | Streaming, tool, token, cancellation, and permission projection | Engineering | `src/core/agent-loop.ts`, `src/security/permissions.ts` |

## Contributor source-exposure disclosure

| Contributor | Inspected replaced source? | Date/range | Separation or review decision | Counsel reference |
| --- | --- | --- | --- | --- |
| Codex implementation assistant | No React or Electron implementation source was inspected. Xeno-owned prior components, Xeno contracts, and public platform behavior were used. | 2026-07-12 | Independent UI, accessibility, and provenance review required | Pending |
| Human contributors | Disclosure not yet collected | Pending | Must be completed before capability approval | Pending |

## Implementation log

| Date (UTC) | Decision | Contract/source basis | Author | Evidence path |
| --- | --- | --- | --- | --- |
| 2026-07-12 | Replace hook state with an observable controller and immutable snapshots | Phase 4 deliverable 1 | Codex implementation assistant | `src/ui/controller.ts` |
| 2026-07-12 | Version the semantic renderer contract independently from host frameworks | Phase 4 deliverable 2 | Codex implementation assistant | `src/ui/types.ts`, `src/ui/view-model.ts` |
| 2026-07-12 | Provide a safe owned DOM renderer with coalesced frame updates | Phase 4 exit gate | Codex implementation assistant | `src/ui/dom-renderer.ts`, `src/ui/styles.ts` |
| 2026-07-12 | Remove React components, hook, peer, types, lock edges, and build externals | Phase 4 deliverables 4-5 | Codex implementation assistant | package, lock, source, bundle, and ownership audit |
| 2026-07-12 | Replace hidden Electron package discovery with explicit host injection | framework-neutral host boundary | Codex implementation assistant | `setupAIHandlers.ts`, `ScreenCapture.ts` |
| 2026-07-12 | Publish the next-major migration contract | versioned migration requirement | Codex implementation assistant | `docs/migrations/sdk-ui-v1.md` |
| 2026-07-12 | Forbid React, React DOM, and Electron reintroduction in SDK/CLI policy | ownership regression gate | Codex implementation assistant | ownership policy revision 7 |
| 2026-07-12 | Grow the multiline composer to a bounded 144 px height while preserving plain Enter editing and Ctrl/Command+Enter submission | browser interaction contract | Codex implementation assistant | `src/ui/dom-renderer.ts`, browser audit fixture |
| 2026-07-12 | Preserve permission-dialog DOM/focus for an unchanged request, focus the first decision, and restore the prior composer focus after resolution | alert-dialog keyboard accessibility contract | Codex implementation assistant | `src/ui/dom-renderer.ts`, fake-DOM and real-browser tests |
| 2026-07-12 | Add a dependency-free real-browser evidence runner with fresh screenshot integrity checks | automated desktop/narrow layout and accessibility evidence | Codex implementation assistant | `scripts/run-ui-browser-smoke.mjs`, `docs/compliance/ui-browser-smoke.json` |

## AI assistance

- Models/tools used: OpenAI Codex coding agent, local PowerShell, TypeScript, tsup, Node test runner, and installed Google Chrome 150 in headless audit mode.
- Prompt or retained prompt-summary path: active Xeno proprietary migration goal and `switch-to-proprietary.md`.
- Confirmation that no third-party source entered the prompt: no React or Electron implementation source was supplied or inspected; public platform contracts and Xeno-owned behavior were used.
- Human review performed: pending.

## Verification evidence

- Focused tests: 7/7 pass across controller projection, accessible semantic view, permission identity, cancel/retry, markdown URL safety, multiline DOM interaction, explicit IPC injection, and desktop-capture injection.
- Full SDK regression: 501 passed, 2 platform-dependent skips, 0 failures.
- Type verification: source and test TypeScript checks pass.
- Build/package: `dist/ui/index.js` is 17,037 bytes and `dist/ui/index.d.ts` is 12,673 bytes; release package smoke passes.
- Dependency proof: React, React DOM, React types, and Electron are absent from package metadata, lock graph, installed graph, source runtime imports, UI bundle, and generated ownership reports.
- Ownership proof: SDK ownership audit reports 0 violations after policy revision 7.
- Source hashes:
  - `controller.ts`: `c9a5344d94fc6ef16f741cc3d5b8da85a28cee364b4364702ace28b8834aa0d0`
  - `view-model.ts`: `383e137272f231cf2d3eea13fffd45e7e9aac8ee2b0b3c17d91dc2e89da82916`
  - `dom-renderer.ts`: `3c1aa9c75b08842a934d6ce17ea8f80276d402cb4b64467b824332d1fddb0b48`
  - `types.ts`: `c127a4e06d7cba5e2a1459334ee934adf0edf86c3b41fcc8192f2bd445c4bb0c`
  - `markdown.ts`: `ec4d45a21b3b27b2ffb149a398c504584b6e66adc5648bbd11395032b0692819`
  - `styles.ts`: `5819fb44aa8aef3551c5ec0a225244f82a0e57aa6c74ea1b15431cb79bff548f`
- Consumer scan: no first-party imports of the former React UI were found in the SDK, CLI, Hub, or xeno-use trees.
- Automated browser QA: Google Chrome 150 passes 15 desktop and 16 narrow/mobile-breakpoint checks covering labelled/live semantics, viewport containment, document overflow, bounded multiline growth, plain Enter editing, Ctrl+Enter submission, permission dialog description/focus/restore, WCAG AA text contrast, 40 px control targets, timeline/composer separation, and mobile stacking. The report is `docs/compliance/ui-browser-smoke.json`.
- Screenshot evidence: desktop `ui-browser-desktop.png` is 1280x800 with SHA-256 `f82a80ce5b3e29acae0b446a7119ff2b6ff0b07eeabe19cba3d84e5189d8d217`; narrow/mobile-breakpoint `ui-browser-mobile.png` is 500x844 with SHA-256 `538f8ec9bc04c515e87c421dffc3ea840d2fe24a11d433409b5839f8ff587a55`. The runner removes prior screenshots and rejects missing, stale-dimension, clipped-viewport, or failed-check evidence.
- Browser evidence boundary: the in-app browser binding was unavailable, so the audit used the installed system browser. Automated Chrome evidence does not represent human Electron, physical mobile-device, high-contrast-mode, or screen-reader approval.

## Open legal or provenance questions

- Independent accessibility and DOM security review is pending.
- Human Electron desktop, physical mobile-device, high-contrast, keyboard, and screen-reader smoke is pending.
- Contributor disclosures and counsel disposition are pending.
- The package version for the breaking UI and explicit host-injection migration must be approved before publication.

## Handoff

- Engineering implementation complete: yes
- Evidence complete: no
- Capability gate may be marked achieved: no
- Ready for independent provenance review: after human visual/accessibility smoke and contributor disclosure collection
- Author/date: Codex implementation assistant, 2026-07-12