---

name: web-ui description: "Guides React/Vite PyCaret Control Plane UI work: routes, typed API client, auth state, data-driven experiment forms, run/trial/deployment pages, LLM widgets, and npm verification." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

web-ui

Use this sub-skill for PyCaret Control Plane frontend work under apps/web: route wiring, page/component edits, the typed API client, auth state, TanStack Query integration, dynamic experiment forms, live run/trial screens, deployment/model-registry views, LLM advisory widgets, and npm-based verification.

First read

• Component and route map for the route table, major page roles, component ownership, and where to add a screen.
• API client and state before changing HTTP calls, WebSocket URLs, auth refresh, Zustand stores, query keys, or API type mirrors.
• Testing and build before editing tests or running checks.
• Troubleshooting when the browser shows auth loops, 404s, schema/form issues, WebSocket failures, Plotly problems, or npm/Node mismatch.

Helper scripts bundled with this sub-skill:

bash scripts/ui_static_check.sh --help
node scripts/list_ui_routes.mjs --help

Route this way

• Frontend UI implementation: stay here.
• Backend route behavior, database rows, schemas, auth policy, or LLM provider semantics: route to the control-plane API skill.
• Engine task semantics, describe_setup_params, model registry contents, RunConfig execution, or event-kind generation: route to the engine workflow skill.
• Docker, nginx production proxy, Compose, Helm, Terraform, ports in deploy files: route to platform operations.

Non-negotiables for UI edits

• Keep DynamicForm data-driven from the describe/setup-params schema. Do not hard-code setup parameter names inside DynamicForm; it renders only structural kinds (bool, int, float, enum, column, string) and honors schema.groups, choices, minimum, maximum, required, default, and description.
• If using the curated ExperimentConfigForm, read defaults and descriptions from the schema and keep the fallback for engine parameters that do not have a dedicated widget.
• Add or change API calls in src/api/endpoints.ts and mirror response/request shapes in src/api/types.ts; call sites should import endpoint groups, not raw axios.
• Preserve the axios auth contract: bearer token attached by interceptor, refresh once on 401, no refresh recursion on /auth/refresh.
• Use @/ imports for src/, prefer named exports, and use import type for TypeScript types because verbatimModuleSyntax is enabled.
• Keep React Query keys stable and scoped by entity IDs. Poll only while useful, and stop on terminal states when possible.
• Use existing design primitives (card, btn-*, input, field, hint, error, h-page, h-section, pill-*) before inventing new styles.
• LLM UI is advisory only: render suggested_config_json, suggested_action, reasoning_summary, and risk_flags; do not let an LLM response directly trigger a destructive action.
• Run relevant npm checks from apps/web before handoff. For a full frontend gate: npm run typecheck && npm run lint && npm test && npm run build.

Common workflows

Add a page

1. Add or reuse typed endpoint methods and types first; see API client and state.
2. Create a named-export page under src/pages/<Name>.tsx.
3. Import it in src/App.tsx and add a <Route> under the authenticated <Layout> unless it is intentionally public (/setup, /login) or a catch-all.
4. Add sidebar/command-palette links only when the page is a first-class navigation surface.
5. Add at least one Vitest/Testing Library test for non-trivial UI behavior.
6. Verify with bash scripts/ui_static_check.sh --typecheck --lint --test --build.

Add a component that calls the API

1. Put all HTTP functions in src/api/endpoints.ts and all mirrors in src/api/types.ts.
2. Wrap reads with useQuery and writes with useMutation; invalidate only the affected query keys.
3. Use errorMessage() for user-facing axios errors.
4. Mock endpoint groups in tests instead of making network calls.

Work on run/trial/deployment experiences

Read Component and route map first. The important split is:

• RunDetail: run status, event drawer, worker/load charting, trials leaderboard, request snapshot, promoted versions.
• TrialsCard / ExperimentTrialsCard: run-level vs experiment-level trial lists.
• TrialDetail: one candidate model, metrics, pipeline diagram, plots, prediction tester, validation, tune/ensemble/promote actions.
• DeploymentDetail: endpoint metrics, interactive prediction, versions/rollback, prediction logs, drift reports.

Quick validation commands

From the repository root:

cd apps/web
npm run typecheck
npm run lint
npm test
npm run build

Or use the bundled wrapper:

bash scripts/ui_static_check.sh --typecheck --test
bash scripts/ui_static_check.sh --lint --build

To inspect route wiring without installing packages:

node scripts/list_ui_routes.mjs REPO_ROOT