feat(ui): add reusable developer surface system

[BunsDev]

Objective

Evolve OpenCoven UI from a component specimen library into a reusable development-surface system for project context, SDK/CLI integration state, daemon/runtime authority cues, and verifiable execution receipts — without turning this repository into another runtime or product authority.

This PR is stacked on #2 (which is stacked on #1) so the new surface inherits the responsive shell and visual-review lane.

Architecture

The integration boundary follows current OpenCoven ownership:

• @opencoven/sdk is represented as an experimental, read-only data source; UI does not imply deferred mutation APIs exist.
• @opencoven/cli / coven is the canonical user-facing CLI; the SDK repository's private @opencoven/dev-cli is not presented as public product surface.
• Coven remains daemon/session/runtime authority.
• Threads/Psyche/Coven remain canonical producers of protected mutation/orchestration state.
• Cave remains production application/UI behavior authority.
• @opencoven/ui accepts normalized view models and renders state; it performs no discovery, credential access, transport negotiation, or mutation.

What changed

• adds ConnectionStatus for SDK/CLI/daemon/runtime/project health plus explicit authority level
• adds CommandReceipt for CLI/SDK/daemon/runtime invocation evidence
• adds DeveloperSurface, a responsive assembled block combining project context, integrations, receipts, and adapter guidance
• exports all three from the package and package subpaths
• adds an isolated /developer reference surface showing canonical CLI, experimental read-only SDK, daemon authority, and coven-code runtime state
• removes fake/no-op showcase controls so affordances never imply an operation the host cannot perform
• adds accessibility/unit coverage for textual state, invocation evidence, assembled semantics, and axe
• adds docs/developer-surface.md with the SDK/CLI adapter contract and current release caveats
• adds a dedicated shadcn registry fragment for all three new public items
• expands the clean-consumer test to install and type-check developer-surface from the generated registry
• makes Vercel generate the registry before the specimen build so new registry items cannot be omitted from deployed /r/* routes merely because committed generated files lag source
• adds explicit architecture contracts preventing UI-package dependencies on SDK/CLI runtimes and enforcing the presentation-only boundary
• adds dedicated /developer desktop and 390px mobile visual receipts alongside the existing specimen-browser review matrix

Deliberate non-goals

• no dependency on @opencoven/sdk or @opencoven/cli
• no runtime I/O inside UI components
• no new authority semantics
• no production Cave behavior changes
• no claim that the experimental SDK is mutation-ready
• no replacement for product-specific Cave integration testing

Verification

Current head: eaa83d3f79dceee9cec0ce461d0e1f85373ecd3b

• canonical opencoven-ui Vercel preview: success
• PR mergeability: clean
• no review threads currently open on this PR
• GitHub CI and Visual review jobs are queued on the hosted runner at this head

The hosted gates cover:

• formatting and lint
• workspace type checking
• unit + accessibility tests
• architecture/design contracts
• registry validation and deterministic build
• clean consumer install of Composer + Developer Surface
• package/specimen production build
• deploy-output verification
• existing library/lab viewport receipts
• /developer desktop and 390px mobile receipts

The PR remains draft until those hosted gates finish green and the resulting visual artifact is inspected.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
opencoven-ui	Ready	Preview	Aug 30, 2026 2:34pm
ui	Error		Aug 30, 2026 2:34pm

[Copilot]

Pull request overview

This PR evolves @opencoven/ui from a specimen-focused component library into a reusable “developer surface system” by introducing new presentation-only components/blocks for integration health, authority cues, and execution receipts, plus a dedicated /developer reference surface and stronger registry/CI verification.

Changes:

• Adds new public UI primitives: ConnectionStatus, CommandReceipt, and the assembled DeveloperSurface block (plus registry fragment + docs).
• Adds a /developer specimen route and expands automated verification with new visual/mobile quality receipts and updated registry consumer checks.
• Tightens registry determinism by composing a new developer registry fragment and enforcing clean generated output in CI and Vercel builds.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
vercel.json	Ensures registry artifacts are generated before building the specimen app on Vercel.
scripts/verify-contracts.mjs	Expands contract checks to cover developer surface exports/docs/registry and new responsive/mobile guards.
scripts/test-registry-consumer.mjs	Extends clean-consumer install/typecheck to include developer-surface.
scripts/mobile-quality-review.mjs	New CDP-based script to capture screenshots + assert mobile layout/overflow/targets across scenarios.
scripts/developer-visual-review.mjs	New script to validate /developer rendered text and capture desktop/mobile screenshots.
scripts/compose-registry.mjs	Includes new developer registry fragment in composed registry.json.
scripts/check-registry-clean.mjs	New script enforcing committed generated registry output (including untracked files).
registry/developer/registry.fragment.json	New registry fragment describing the new developer-facing component/block items.
public/r/transcript-turn.json	Updates generated registry payload for TranscriptTurn (mobile wrapping/spacing tweaks).
public/r/tabs.json	Updates generated registry payload for Tabs (orientation handling + min-width fixes).
public/r/session-header.json	Updates generated registry payload for SessionHeader (mobile grid reflow + truncation fixes).
packages/ui/tests/tabs.test.tsx	Adds unit coverage for Tabs orientation behavior.
packages/ui/tests/mobile-blocks.test.tsx	Adds unit coverage for mobile reflow behavior of TranscriptTurn and SessionHeader.
packages/ui/tests/developer-surface.test.tsx	Adds unit + a11y coverage for the new developer surface primitives (includes axe).
packages/ui/src/index.ts	Exports DeveloperSurface, ConnectionStatus, and CommandReceipt from the package root.
packages/ui/src/components/ui/tabs.tsx	Fixes orientation propagation and layout behavior (adds min-w-0 to content).
packages/ui/src/components/connection-status.tsx	New component for integration health + explicit authority labeling.
packages/ui/src/components/command-receipt.tsx	New component for presentation-safe invocation evidence with explicit lifecycle states.
packages/ui/src/blocks/transcript-turn.tsx	Mobile-focused spacing and wrapping adjustments to prevent intrinsic-width overflow.
packages/ui/src/blocks/session-header.tsx	Mobile grid layout to avoid ellipsis/clipping and keep metadata reflowable.
packages/ui/src/blocks/developer-surface.tsx	New assembled block combining project context, integrations, receipts, and guidance.
package.json	Updates registry:check to validate cleanliness via the new check-registry-clean script.
docs/developer-surface.md	New integration/adapter contract and protected-data guidance for developer surface usage.
apps/specimens/src/specimens-fixes.css	New layered CSS “fixes” file for mobile/layout regression guards.
apps/specimens/src/main.tsx	Adds /developer route rendering and loads specimens-fixes.css.
apps/specimens/src/developer-showcase.tsx	New dedicated /developer reference surface demonstrating canonical developer UI semantics.
.github/workflows/visual-review.yml	Builds registry before preview and runs additional developer + mobile quality scripts; uploads new artifact.
.github/workflows/refine-visual-clipping-check.yml	Removes an experimental workflow used for refining visual clipping assertions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.