Skip to content

feat: refactor the Control UI architecture#100024

Merged
shakkernerd merged 289 commits into
mainfrom
control-ui-refactor
Jul 4, 2026
Merged

feat: refactor the Control UI architecture#100024
shakkernerd merged 289 commits into
mainfrom
control-ui-refactor

Conversation

@shakkernerd

@shakkernerd shakkernerd commented Jul 4, 2026

Copy link
Copy Markdown
Member

What Problem This Solves

The Control UI had accumulated routing, page state, session behavior, data loading, and rendering inside a large shared application host. This made page behavior difficult to isolate, increased unnecessary update work, and made further development riskier.

Why This Change Was Made

This refactors the complete Control UI around the published @openclaw/uirouter package and clear app, pages, components, lib, and api boundaries.

Routes now coordinate page loading and navigation, individual pages own their lifecycle and state, and the application shell retains only shared application behavior. The migration also removes the obsolete host, duplicated controllers, legacy routing paths, and superseded session orchestration.

Existing design and behavior remain intact, including sidebar sessions, breadcrumbs, gateway selection, command handling, settings presentation, chat behavior, and mobile pairing.

User Impact

Users retain the existing Control UI experience while benefiting from faster, more predictable navigation and better isolation between pages.

Routes can preload on navigation intent, reuse cached data, revalidate in the background, and update without unnecessarily rerendering the shared shell. No user-facing workflows were intentionally removed.

Evidence

  • Rebased onto current origin/main.
  • Control UI production build passed.
  • Focused nodes and device tests passed: 2 files, 7 tests.
  • Mobile pairing Playwright flow passed.
  • Touched-path formatting and lint checks passed.
  • Manually verified migrated pages, route transitions, sidebar behavior, breadcrumbs, settings, gateway selection, command picker behavior, chat flows, and mobile pairing.

@shakkernerd
shakkernerd requested a review from a team as a code owner July 4, 2026 17:03
@openclaw-barnacle openclaw-barnacle Bot added app: web-ui App: web-ui gateway Gateway runtime scripts Repository scripts extensions: qa-lab labels Jul 4, 2026
@github-actions github-actions Bot added the dependencies-changed PR changes dependency-related files label Jul 4, 2026
@github-actions

github-actions Bot commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

Dependency Guard

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

  • pnpm-lock.yaml
  • pnpm-workspace.yaml
  • ui/package.json

Maintainer follow-up:

  • Review whether the dependency changes are intentional.
  • Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
  • Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
  • Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

@openclaw-barnacle openclaw-barnacle Bot added the maintainer Maintainer-authored PR label Jul 4, 2026
@github-actions

github-actions Bot commented Jul 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Dependency graph changes are blocked

OpenClaw does not accept dependency graph changes through PRs unless a repository admin or security explicitly authorizes the current head SHA. Dependency updates are generated internally by maintainers so external PRs cannot change the resolved graph.

Detected dependency graph changes:

  • pnpm-lock.yaml changed.
  • ui/package.json changed dependencies.

Auto-scrub was not attempted because this PR changes package manifest dependency graph fields:

  • ui/package.json changed dependencies.

Dependency graph changes must be reviewed by security or handled by maintainers internally. Please remove lockfile changes manually if they are not needed.

To remove lockfile changes, restore them from the target branch:

git fetch origin
git checkout 'origin/main' -- 'pnpm-lock.yaml'
git commit -m 'chore: remove dependency lockfile change'
git push

If this PR intentionally needs a dependency graph change, ask a repository admin or member of @openclaw/openclaw-secops to comment:

/allow-dependencies-change

The action will approve the current head SHA (bd51b6fa76ec057fde19bc31f93fb4aad70416d3) when it reruns. A later push requires a fresh approval.

@clawsweeper

clawsweeper Bot commented Jul 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 4, 2026, 6:16 PM ET / 22:16 UTC.

Summary
The PR refactors the Control UI from the current monolithic host into routed app, page, component, lib, and API boundaries, while updating tests, QA references, scripts, i18n baselines, package metadata, and the lockfile.

Reproducibility: not applicable. this is an architecture refactor PR rather than a bug report. Source inspection checked current main, PR-head route files, dependency metadata, and the overlapping replacement PR instead of reproducing a failure.

Review metrics: 1 noteworthy metric.

  • Dependency graph change: 1 runtime dependency added, 1 lockfile changed, 1 workspace release-age exception added. The new Control UI router package changes shipped package resolution and is the remaining security/authorization gate before merge.

Stored data model
Persistent data-model change detected: serialized state: src/cron/cron-protocol-conformance.test.ts, serialized state: ui/src/ui/controllers/sessions.ts, serialized state: ui/src/ui/device-auth.ts, serialized state: ui/src/ui/views/channel-config-extras.ts, unknown-data-model-change: ui/src/ui/controllers/sessions.test.ts, unknown-data-model-change: ui/src/ui/controllers/sessions.ts, and 2 more. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Get security/admin authorization for the exact dependency graph change or internalize/remove the dependency.
  • [P2] Refresh final CI and add visual Control UI smoke proof if maintainers want higher browser confidence.

Mantis proof suggestion
A real browser visual smoke would materially help reviewers verify visible route, sidebar, settings, command picker, chat, and mobile-pairing behavior after the architecture migration. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify Control UI route transitions, sidebar sessions, settings, command picker, chat flow, and mobile pairing after the router migration.

Risk before merge

  • [P1] The dependency graph change adds a published runtime package plus lockfile and workspace release-age exception changes; the live dependency guard still requires security/admin authorization for the exact head before merge.
  • [P1] The refactor replaces the current monolithic Control UI host with a broad routed architecture, so maintainers still need final acceptance of the route lifecycle, session behavior, and browser smoke evidence.
  • [P1] A newer open overlapping PR exists, but it is not yet a safe superseding target because it still has review findings and missing real behavior proof.

Maintainer options:

  1. Authorize the exact router dependency
    A security/admin reviewer can inspect @openclaw/[email protected], the lockfile delta, the release-age exception, and final CI for head 4160b95ed8b05f9689a552f3a6ebc7f18cdc35af, then approve the dependency guard if this package is intended.
  2. Internalize or workspace the router first
    If maintainers do not want a published runtime router package in the Control UI bundle, move the router code into an owned internal/workspace surface and remove the external dependency graph delta before merge.
  3. Pause in favor of the narrower route-module branch
    If the smaller overlapping route-module PR becomes clean and proven first, maintainers can use that as the preferred path and leave this broader branch unmerged.

Next step before merge

  • [P2] Human maintainer/security review is required for the protected maintainer-labeled PR, dependency graph authorization, and choice between this branch and the overlapping route-module PR; there is no narrow automated repair from this pass.

Security
Needs attention: The dependency graph change is security-sensitive and still needs security/admin authorization before merge.

Review details

Best possible solution:

Land this routed Control UI refactor only after maintainers either authorize the exact router dependency or choose an internalized route-module path, then verify final CI and visible Control UI smoke behavior for route transitions, sessions, settings, chat, and mobile pairing.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is an architecture refactor PR rather than a bug report. Source inspection checked current main, PR-head route files, dependency metadata, and the overlapping replacement PR instead of reproducing a failure.

Is this the best way to solve the issue?

Unclear as the final best merge shape. The routed architecture is coherent and the prior scanner gap is fixed, but maintainers still need to choose between approving the external router dependency, internalizing it, or using the narrower overlapping route-module PR once it is clean and proven.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 832cb3c48880.

Label changes

Label changes:

  • add merge-risk: 🚨 session-state: The PR moves route loaders, browser history, chat navigation, and session page ownership into a new lifecycle where stale or mis-associated session state would be user-visible.

Label justifications:

  • P2: This is a broad Control UI architecture improvement with concrete merge gates, but it is not an urgent production outage.
  • merge-risk: 🚨 compatibility: The PR replaces the Control UI host/routing architecture and test routing, which can affect existing browser workflows and upgrades even when unit tests pass.
  • merge-risk: 🚨 session-state: The PR moves route loaders, browser history, chat navigation, and session page ownership into a new lifecycle where stale or mis-associated session state would be user-visible.
  • merge-risk: 🚨 security-boundary: The PR adds a new published runtime dependency and lockfile graph change that the repository dependency guard requires security/admin authorization for before merge.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this member-authored PR; the PR body lists build, focused tests, Playwright mobile pairing, and manual UI verification.
Evidence reviewed

Security concerns:

  • [medium] Authorize the router dependency — ui/package.json:16
    ui/package.json adds @openclaw/[email protected], with matching lockfile and minimum-release-age exception changes; the live dependency guard blocks this until the exact head is approved or the dependency is removed/internalized.
    Confidence: 0.95

What I checked:

  • Root and scoped policy read: Root AGENTS.md plus the UI, scripts, test, extensions, and gateway scoped guides were read; dependency graph changes, lockfiles, broad UI refactors, and protected maintainer-labeled PRs affect this review. (AGENTS.md:1, 832cb3c48880)
  • Live PR state: Live metadata shows the PR is open, member-authored, has the protected maintainer label, changes 569 files, and has dependency-guard comments blocking dependency graph changes until security/admin authorization. (4160b95ed8b0)
  • Current main behavior: Current main still uses the large Control UI host that imports app channels, chat, gateway, lifecycle, render, scroll, settings, and tool-stream behavior from ui/src/ui/app.ts, so the central routed architecture is not already implemented on main. (ui/src/ui/app.ts:1, 832cb3c48880)
  • PR route entry point: The PR head imports @openclaw/uirouter, defines APP_ROUTE_TREE, and creates the application router from the page route modules. (ui/src/app-routes.ts:1, 4160b95ed8b0)
  • Previous finding fixed: The current PR head raw-copy scanner now scans the migrated app, components, lib, and pages Control UI roots, addressing the prior ClawSweeper scanner finding. (scripts/control-ui-i18n.ts:114, 4160b95ed8b0)
  • Dependency contract inspected: The published @openclaw/[email protected] package is MIT-licensed, ESM, side-effect-free, ships six files, exposes the route/navigation/preload APIs used by this PR, and has no runtime dependencies in its package metadata. (ui/package.json:16, 4160b95ed8b0)

Likely related people:

  • steipete: Blame and log history show Peter Steinberger carrying the current monolithic Control UI host and recent gateway/session-related UI surfaces that this branch reorganizes. (role: adjacent owner; confidence: high; commits: d9dbee7676fb, 7e8ea61b0886, 6df0fb818d67; files: ui/src/ui/app.ts, ui/vite.config.ts, ui/src/ui/app-render.ts)
  • vincentkoc: History shows Vincent Koc worked on the Control UI locale pipeline and unit-ui test routing areas touched by this refactor. (role: recent area contributor; confidence: medium; commits: ee4fe4fb1e1d, 1840611fe67e, 2285429aa210; files: scripts/control-ui-i18n.ts, test/vitest/vitest.ui.config.ts, ui/src/i18n/locales/en.ts)
  • shakkernerd: Beyond this PR, history shows prior merged Control UI fixes in app rendering, scroll control, and safe URL handling. (role: recent area contributor; confidence: medium; commits: 01ce144fa9ab, 13db0489c871, 2af977f947c9; files: ui/src/ui/app-render.ts, ui/src/ui/app.ts, ui/src/ui/open-external-url.test.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.
Review history (3 earlier review cycles)
  • reviewed 2026-07-04T17:08:14.955Z sha b7efe84 :: found issues before merge. :: [P2] Include the migrated pages in raw-copy scanning
  • reviewed 2026-07-04T17:13:27.793Z sha b7efe84 :: found issues before merge. :: [P2] Include the migrated pages in raw-copy scanning
  • reviewed 2026-07-04T22:10:33.279Z sha 4160b95 :: needs maintainer review before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. labels Jul 4, 2026
@shakkernerd
shakkernerd force-pushed the control-ui-refactor branch from b7efe84 to 4160b95 Compare July 4, 2026 22:05
@clawsweeper clawsweeper Bot added status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jul 4, 2026
@shakkernerd shakkernerd self-assigned this Jul 4, 2026
@shakkernerd
shakkernerd force-pushed the control-ui-refactor branch from 4160b95 to bd51b6f Compare July 4, 2026 22:19
@shakkernerd
shakkernerd merged commit 65e1232 into main Jul 4, 2026
41 checks passed
@shakkernerd
shakkernerd deleted the control-ui-refactor branch July 4, 2026 22:19
This was referenced Jul 4, 2026
Merged
Closed
This was referenced Jul 4, 2026
Merged
Open
@steipete steipete mentioned this pull request Jul 4, 2026
Merged
This was referenced Jul 5, 2026
Closed
Closed
This was referenced Jul 9, 2026
Closed
Closed
Merged
@clawsweeper clawsweeper Bot mentioned this pull request Jul 11, 2026
Merged
This was referenced Jul 12, 2026
Closed
Closed
Closed
@clawsweeper clawsweeper Bot mentioned this pull request Jul 12, 2026
Closed
@harjothkhara harjothkhara mentioned this pull request Jul 16, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@shakkernerd shakkernerd

Labels

app: web-ui App: web-ui dependencies-changed PR changes dependency-related files extensions: qa-lab gateway Gateway runtime maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. scripts Repository scripts size: XL status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@shakkernerd