refactor(web): migrate the Web workbench UI to React by 6iKUN6 · Pull Request #384 · openpi-dev/openpi

6iKUN6 · 2026-09-04T09:50:56Z

Problem

Related to #76.

The OpenPI Web UI is currently implemented as one imperative browser script. As workspace and Session management, streaming messages, tool evidence, capability activity, and responsive interactions grow, that structure lacks clear component boundaries, typed browser state, and focused tests.

This PR validates a React migration of the browser projection while preserving Pi/OpenPI runtime ownership and the existing Web protocol. PR #352 at head 1b340f2 is the frozen behavior and visual reference. This PR does not depend on #352 merging, but the maintainers should decide whether this migration follows or supersedes that implementation.

Value

Establish typed component, state, and protocol boundaries for the Web UI.
Make workspace, Session, composer, transcript, and activity behavior easier to test and extend.
Add UI HMR for day-to-day Web development.
Keep production Web delivery self-contained, without requiring users to install frontend tooling or load remote assets.
Provide a maintainable frontend base for the existing Web roadmap without introducing a second agent runtime.

Approach

Runtime boundary

Pi remains authoritative for Sessions, providers/models, tools, and execution lifecycle. PiWebRuntime, PiWebAdapter, TypeBox contracts, authenticated commands, and SSE cursor semantics remain the browser boundary. React consumes canonical snapshots/events and sends bounded commands; it does not infer terminal execution state from presentation.

The browser persists only process-scoped authentication and local navigation preferences in sessionStorage. It does not create a second Session, model, capability, or configuration source of truth.

Frontend stack

React 19 and TypeScript
Vite 8
Zustand vanilla store with React bindings
Tailwind CSS 4
Astryx Core with the neutral theme for Dialog, Menu, and Tooltip primitives
Lucide React
Fetch-based authenticated SSE with eventsource-parser
react-markdown, remark-gfm, and rehype-sanitize
i18next and react-i18next
Vitest, React Testing Library, Playwright, and axe-core

Astryx owns generic interaction primitives only. OpenPI-specific transcript evidence, capability projections, and the animated logo remain local React components.

Development workflow

bun install --frozen-lockfile
bun run dev:web
bun run dev:web -- /absolute/path/to/workspace

Vite provides HMR for web/ui/. Backend/runtime changes rebuild the Web-owned Pi runtime. The combined development command selects bounded fallback ports when defaults are occupied; explicitly requested occupied ports fail with an actionable diagnostic.

Validation entry points:

bun run check:web
bun run test:web:e2e
bun run check
bun run test

See docs/development/OPENPI_WEB_DEVELOPMENT.md for lifecycle and HMR boundaries.

Build and release

bun run build:web writes deterministic production assets to web/dist/. The built directory is committed as a package runtime asset, and WebHost serves only its fixed allowlist. npm and GitHub installs therefore start Web without Vite, a CDN, or remote fonts.

CI rebuilds and rejects web/dist drift, checks Node 22.19.0 and Node 24, runs browser E2E, smoke-tests the packed npm CLI, and smoke-tests a source-only git archive checkout. See docs/design/OPENPI_WEB_REACT_MVP.md for the complete design and evidence record.

Validation

Optional follow-up work (not required to merge this PR):

Confirm or port any remaining accepted reliability semantics from bug(web): 长 workflow/subagent 回合期间 Web UI 卡在"正在准备任务..."数小时不更新，新输入提示词也不显示 #363 / fix(web): preserve running state for queued prompts #364 / fix(web): recover from quiet or stalled connections #370
Expand component-level coverage for Session/workspace actions, composer gates, search lifecycle, and activity projections
Complete forced reconnect and long-running Subagent/Workflow manual acceptance

Impact

User-visible behavior

The Web browser UI moves to React while retaining the #352 layout and interaction baseline, including the animated logo, workspace and Session navigation, transcript/tool evidence, activity projection, and responsive layout. Development mode gains HMR and bounded port avoidance.

Model-visible context and tools

None. This PR does not add or change model-facing tools, schemas, prompts, or child capability classifications.

Runtime and lifecycle

The canonical Pi/Web runtime and Session ownership boundaries remain unchanged. The development launcher and packaged static resource path are updated to serve the React build.

Persisted config/data

No canonical persisted configuration or Session data changes. Browser-local token and navigation preferences remain process/local UI state.

Compatibility and risk

Minimum Node version remains 22.19.0; CI covers Node 22.19.0 and Node 24.
The production build is approximately 708 KB JavaScript raw / 211 KB gzip and 224 KB CSS raw / 39 KB gzip.
The npm tarball grows by approximately 260 KB compressed.
Primary risks are behavior parity with feat(web): restore polished workbench UI and conversation rendering #352, active bug(web): 长 workflow/subagent 回合期间 Web UI 卡在"正在准备任务..."数小时不更新，新输入提示词也不显示 #363 reliability work, bundle size, and the migration diff size.

Follow-up roadmap work remains tracked in #342, #343, #344, #345, #346, #347, #348, #349, #350, and #363. Pi-native slash command discovery and Web bundle/render performance should be proposed as separate follow-up issues after the migration direction is accepted.

Record the frozen PR openpi-dev#352 behavior baseline, Pi-native ownership boundaries, selected frontend stack, static delivery contract, and validation matrix for the local migration experiment.

Document default port fallback, strict explicit ports, fast startup diagnostics, and TUI error projection for the local React validation branch.

- replace the imperative browser UI with typed React and Zustand projections - add Vite HMR, production asset builds, and bounded port conflict handling - cover the Web store, packaged host, responsive browser flows, and artifact drift in CI

6iKUN6 · 2026-09-04T09:53:32Z

@tt-a1i Could you please review the technical direction and implementation of this React Web MVP? Thanks.

tt-a1i · 2026-09-04T09:54:38Z

来了涂少坤 ***@***.***

…

---Original--- From: ***@***.***> Date: Fri, Sep 4, 2026 17:53 PM To: ***@***.***>; Cc: ***@***.******@***.***>; Subject: Re: [openpi-dev/openpi] refactor(web): migrate the Web workbench UI to React (PR #384) 6iKUN6 left a comment (openpi-dev/openpi#384) @tt-a1i 麻烦帮忙 review 一下这个 React Web MVP 的技术方向和实现，谢谢。 — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

- disable npm peer resolution for Pi-provided host packages - guard the Git install contract and record the production smoke rationale

tt-a1i

The React direction is sound and keeps Pi as the runtime source of truth, but this draft is not ready to merge yet. I found two user-visible parity regressions, an unenforced development-startup bound, a supported-Node test failure, and a distribution-notice gap.

I reviewed exact head 13f3032decdcc600e7d46d848b2cc0097fd54d7e. Locally, bun run check and bun run test:web:e2e pass (3/3). On Node 26.3.0, the focused Web store suite fails 21/21 because the tests access an unavailable unqualified localStorage. The required Node 22 CI job is also currently red: the packed standalone CLI smoke attempts to fetch unavailable @earendil-works/pi-tui@0.85.0 and receives 404, so the recorded installed-package validation is not current.

Please also update the design record's source boundary to identify this PR and an exact implementation head when the evidence is frozen, rather than only a mutable local branch plus the base and PR #352.

tt-a1i · 2026-09-04T10:31:53Z

+    if (startupFailure) throw startupFailure;
    try {
-      const response = await fetch(endpoint);
+      const response = await fetch(endpoint, {


[P1] Enforce the advertised readiness deadline on each probe. The outer 15-second loop does not bound this awaited fetch: a peer can accept the TCP connection and never return headers, leaving dev:web stuck here forever and preventing startup.waitForFailure() from being observed. Please abort each request at the remaining deadline (and when startup fails), and add a hanging-peer regression test.

tt-a1i · 2026-09-04T10:31:53Z

+        }
+      },
+      setQuery(query) {
+        set({ query: query.trim() });


[P2] Preserve the raw value of this controlled input. Trimming in the setter rewrites "foo " to "foo" immediately; typing the next character then produces "foobar" instead of "foo bar". Keep the raw query in state and trim only the value used for matching, with a test covering spaces in a search term.

tt-a1i · 2026-09-04T10:31:54Z

+  return (
+    <div className="markdown">
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}


[P2] Preserve the frozen baseline's soft-line-break behavior. PR #352 configured Marked with breaks: true, while GFM alone renders "first line\nsecond line" without a <br>; this component sits under .message-content, so it does not inherit the user-message white-space: pre-wrap rule and the browser collapses the newline. Add remark-breaks (or an equivalent rendering rule) and a parity test.

tt-a1i · 2026-09-04T10:31:54Z

+
+afterEach(() => {
+  sessionStorage.clear();
+  localStorage.clear();


[P2] Keep this suite compatible with the declared node >=22.19.0 range. Under Node 26.3.0, the native Web Storage global shadows jsdom and unqualified localStorage is undefined, so all 21 store tests fail in this cleanup. I reproduced the same failure at this head. Use window.localStorage (including the assertion below) or explicitly configure the test environment, then cover a supported newer Node in CI.

tt-a1i · 2026-09-04T10:31:54Z

    "undici": "8.9.0"
  },
  "devDependencies": {
+    "@astryxdesign/core": "0.5.2",


[P1] Add notices for the code now shipped in the committed production bundle. web/dist/app.js embeds React/ReactDOM, Zustand, Lucide, i18next, eventsource-parser, React Markdown/remark/rehype, Astryx, and related runtime code, but THIRD_PARTY_NOTICES.md still lists only the Sessions extension. The relevant MIT/ISC terms and retained copyright notices need to accompany distribution before this can leave draft.

tt-a1i · 2026-09-04T10:32:11Z

Reviewed at exact head 13f3032decdcc600e7d46d848b2cc0097fd54d7e and submitted REQUEST_CHANGES.

The React/Pi-native direction looks good, but the draft still needs fixes for the unbounded development readiness probe, controlled-search whitespace regression, Markdown soft-break parity, Node 26 Web-store test compatibility, and bundled frontend notices. The required Node 22 packed-CLI smoke is also currently failing with an unavailable @earendil-works/pi-tui@0.85.0 tarball.

Use an explicitly referenced timer for each readiness probe so Node 22 does not let the test process or launcher exit while the fetch is still pending. Clear the timer after every probe.

Advance the design evidence boundary to the readiness timer fix and record the focused Node 22 and Node 24 regression runs.

Replace the superseded load-sensitive test note with the successful Node 24 full-suite result observed after the readiness fix.

Ensure the CLI cannot advertise a ready Web Host before its SIGINT and SIGTERM cleanup handlers are installed.

Advance the implementation boundary and distinguish focused CLI evidence from unrelated full-suite timing failures.

6iKUN6 · 2026-09-04T16:43:52Z

@tt-a1i The review feedback has been addressed, the merge conflict is resolved, and CI is green. Could you please re-review when convenient?

6iKUN6 added 3 commits September 3, 2026 16:11

docs(web): define React migration MVP

2bc452f

Record the frozen PR openpi-dev#352 behavior baseline, Pi-native ownership boundaries, selected frontend stack, static delivery contract, and validation matrix for the local migration experiment.

docs(web): define development port conflict handling

036dd9c

Document default port fallback, strict explicit ports, fast startup diagnostics, and TUI error projection for the local React validation branch.

feat(web): migrate workbench UI to React

645e4b6

- replace the imperative browser UI with typed React and Zustand projections - add Vite HMR, production asset builds, and bounded port conflict handling - cover the Web store, packaged host, responsive browser flows, and artifact drift in CI

github-actions Bot added documentation Improvements or additions to documentation area:github GitHub workflows, templates, ownership, or tests labels Sep 4, 2026

fix(packaging): stabilize Git source installs

13f3032

- disable npm peer resolution for Pi-provided host packages - guard the Git install contract and record the production smoke rationale

github-actions Bot added the area:setup OpenPI setup, configuration, or setup documentation label Sep 4, 2026

tt-a1i requested changes Sep 4, 2026

View reviewed changes

This was referenced Sep 4, 2026

feat(web): add bounded file and image attachments with safe rendering #344

Open

feat(web): add attachment staging lifecycle #388

Open

6iKUN6 added 8 commits September 4, 2026 20:39

fix(web): address React MVP review feedback

5eb4509

fix(ci): provide Pi host peers to source smoke

31128f2

docs(web): record React MVP review validation

4d54fb0

fix(web): keep backend readiness deadline alive

30346f0

Use an explicitly referenced timer for each readiness probe so Node 22 does not let the test process or launcher exit while the fetch is still pending. Clear the timer after every probe.

docs(web): record Node 22 readiness validation

70b46fe

Advance the design evidence boundary to the readiness timer fix and record the focused Node 22 and Node 24 regression runs.

docs(web): record green full test run

d0bfaa4

Replace the superseded load-sensitive test note with the successful Node 24 full-suite result observed after the readiness fix.

fix(web): install shutdown handlers before ready output

c461d4a

Ensure the CLI cannot advertise a ready Web Host before its SIGINT and SIGTERM cleanup handlers are installed.

docs(web): record CLI shutdown race validation

acb5066

Advance the implementation boundary and distinguish focused CLI evidence from unrelated full-suite timing failures.

6iKUN6 marked this pull request as ready for review September 4, 2026 13:42

6iKUN6 requested a review from a team as a code owner September 4, 2026 13:42

6iKUN6 requested a review from tt-a1i September 4, 2026 13:46

tt-a1i mentioned this pull request Sep 4, 2026

fix(web): preserve running state for queued prompts #364

Open

Merge upstream/main into codex/web-react-mvp

df63e43

Navigation Menu

Uh oh!

refactor(web): migrate the Web workbench UI to React - #384

refactor(web): migrate the Web workbench UI to React#384
6iKUN6 wants to merge 13 commits into
openpi-dev:mainfrom
6iKUN6:codex/web-react-mvp

6iKUN6 commented Sep 4, 2026 •

edited

Loading

Uh oh!

6iKUN6 commented Sep 4, 2026 •

edited

Loading

Uh oh!

tt-a1i commented Sep 4, 2026 via email

Uh oh!

tt-a1i left a comment

Uh oh!

tt-a1i Sep 4, 2026

Uh oh!

tt-a1i Sep 4, 2026

Uh oh!

tt-a1i Sep 4, 2026

Uh oh!

tt-a1i Sep 4, 2026

Uh oh!

tt-a1i Sep 4, 2026

Uh oh!

tt-a1i commented Sep 4, 2026

Uh oh!

6iKUN6 commented Sep 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

6iKUN6 commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Value

Approach

Runtime boundary

Frontend stack

Development workflow

Build and release

Validation

Impact

User-visible behavior

Model-visible context and tools

Runtime and lifecycle

Persisted config/data

Compatibility and risk

Uh oh!

6iKUN6 commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tt-a1i commented Sep 4, 2026 via email

Uh oh!

tt-a1i left a comment

Choose a reason for hiding this comment

Uh oh!

tt-a1i Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

tt-a1i Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

tt-a1i Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

tt-a1i Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

tt-a1i Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

tt-a1i commented Sep 4, 2026

Uh oh!

6iKUN6 commented Sep 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

6iKUN6 commented Sep 4, 2026 •

edited

Loading

6iKUN6 commented Sep 4, 2026 •

edited

Loading