Skip to content

Simplify checkpoint onboarding, deduplicate OpenUI questions, and refine Agree - #264

Merged
raphael merged 2 commits into
mainfrom
ux-default-view
Nov 20, 2026
Merged

raphael merged 2 commits into
mainfrom
ux-default-view

Conversation

@raphael

@raphael raphael commented Nov 20, 2026

Copy link
Copy Markdown
Member

Opening Surla's browser window on a new project greeted first-time users with a multi-row navigation header, empty Agreed and Next slots, five secondary workspace tabs, a Current view details disclosure, and a false Needs you: Guide status unknown. warning whenever the coding agent connected over MCP outside a Herdr pane (herdr_mode: "available"). Once the first Change Card arrived, the user still had to click through from Changes, and the Agree view repeated question choices and [Selected draft answer: ...] readouts between OpenUI decision cards and Open Questions, rendered Concrete Examples twice (as static prose above editable fields), showed empty Preserved Contract Invariants (0), scattered seven Details identifier blocks across the form, and left the confirmation button below a tall page without a direct jump to unanswered items.

This change replaces the empty start state with a focused welcome card that opens the first Change Card automatically when proposed, removes the false outside-Herdr status warning, deduplicates OpenUI and form controls onto shared accessible components, and keeps the next confirmation action reachable in the top frame and mobile bottom bar.

Resulting behavior

  • Calm zero-state welcome and automatic first-card open: When a project has zero Change Cards and no active error, Surla hides the stage tabs and status slots, moves secondary views (Team, Story, Live target, Architecture, Diagnostics) into a compact keyboard-accessible Inspect menu (Escape and outside-click dismiss with focus restoration), and centers a three-step welcome card directing the developer to describe their change in their coding agent. When list_changes transitions from 0 to 1 card while viewing the empty state, Surla opens that Change Card automatically in Agree. Separating guideInHerdr (herdr_mode === "attached") from herdrWorkerAvailable removes the false "unknown" alert for coding agents attached outside Herdr while preserving real worker "unknown" and error alerts.
  • Single-surface OpenUI and Agree editing: OpenUI AmbiguityChoiceCard and PolicySimulatorTable components and the Agree form share a roving-tabindex ChoiceGroup component with arrow-key navigation and 44px mobile touch targets. When a validated OpenUI block already renders a question's ChoiceGroup, Open Questions omits that question instead of repeating it; [Selected draft answer: ...] echoes, raw option bullets, duplicate Concrete Example prose headers, and zero-count Preserved Contract Invariants (0) are removed; and scattered technical IDs collapse into quiet Agreement identifiers and Technical identifiers disclosures.
  • Reachable Next actions, plain "coding agent" wording, and preserved recovery guidance: While a Change Card needs confirmation on Agree, the Next slot (sticky in the header on desktop and docked at the bottom of the viewport on narrow screens with scroll padding) provides a direct button to focus the next unanswered question (Jump to unanswered question), focus an incomplete example field (Review example), or submit confirmation (Confirm intent). User-facing browser copy replaces internal "Guide" labels with "your coding agent" (showing "Coding agent (guide)" on Team and Open Surla Window in session recovery), while preserving unsaved drafts across conflicts and incoming revisions, local-validation versus server-request error alerts, and Build drop/stale-card recovery guidance.

Verification

Verified with TypeScript typechecking, node ui/checkpoint/build.mjs --check, Node client build tests, Go served-page and race suites, and headless Chromium journey, keyboard/focus, dark/light, and 1280px/375px layout checks across empty onboarding, 0 -> 1 auto-open, OpenUI and fallback Agree flows, Team, and Build recovery.

@raphael
raphael merged commit 2d0393b into main Nov 20, 2026
25 checks passed
@raphael
raphael deleted the ux-default-view branch November 20, 2026 09:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant