# HWLAB Cloud Workbench Reference

Cloud Workbench is the default user-facing frontend at
`http://74.48.78.17:16666/`. It must serve the #99 workbench direction and the
#108 UX constraints while respecting the M3 boundary from
`DC-DCSN-P0-2026-003`.

## Default Route

- `/` must show the Cloud Workbench, not Gate, status, help, or diagnostics.
- The default first screen must not show Gate, `BLOCKED`, `M0-M5`, or
  acceptance-review copy. Those terms may remain in hidden/internal views.
- Checked-in Gate reports and aggregator summaries are read-only support data.
  They must not be rendered as the default homepage or used to rename the
  default route away from Cloud Workbench.
- Gate and diagnostics are secondary routes or right-panel support views.
- `/gate` and `/diagnostics/gate` are internal diagnostic aliases served by the
  same Cloud Web app router. They may carry Gate, blocker, and M0-M5 evidence
  because they are not the default homepage.
- `http://74.48.78.17:16667/` remains the API/edge boundary.
- Browser data sources are same-origin `/v1`, read-only `/json-rpc`, source
  reports, gate reports, and blocked reports.
- Code Agent conversation 使用受控同源 `POST /v1/agent/chat` 通道。直接
  API/edge 访问、source reports、本地 echo、mock replies 或 provider
  credential gaps 不能被写成真实 assistant reply；readiness 权威文档是
  [code-agent-chat-readiness.md](code-agent-chat-readiness.md).

## Required Layout

The default workbench follows the #99 VS Code-style structure:

| Region | Required role |
| --- | --- |
| Left | Activity rail, project/function/resource navigation, hardware resources. |
| Center top | Agent messages, execution process, trace, selected operation context. |
| Center bottom | Agent input or equivalent command composer. |
| Right top | BOX-SIMU, Gateway-SIMU, and patch-panel hardware state. |
| Right bottom | Controls, wiring, trusted records, Audit, and Diagnostics tabs. |

Unavailable or future controls must be disabled with blocker context. The
frontend must not imply generic direct hardware control.

The `panel-wiring` / `hwlab-patch-panel` view must use a two-column long table
instead of an eight-column wide table. The first table row/header names the two
connected devices, for example `res_boxsimu_1` and `res_boxsimu_2`; following
rows map IO ports, for example `DO1` to `DI1`. The patch-panel service,
status, evidence source, and trace/evidence details remain visible in Chinese
summary or row detail text, but they must not become separate horizontal
columns that force the right sidebar to scroll sideways.

## UX Constraints

The #108 constraints are current baseline:

- no page-level vertical scroll on the outer shell; scrolling belongs inside
  workbench panels;
- user-visible UI text is Chinese except machine identifiers, protocol names,
  API paths, IDs, commits, endpoints, and source labels that need their exact
  spelling;
- an internal help page exists, but it is not the homepage;
- help content is maintained as `web/hwlab-cloud-web/help.md` and rendered by
  the frontend instead of being only a JS string.

## Evidence And Labels

Visible runtime or evidence state must keep `SOURCE`, `LOCAL`, `DRY-RUN`,
`DEV-LIVE`, and `BLOCKED` distinct. Loading the page from `16666` proves only
that Cloud Web is reachable. It does not prove DB readiness, M3, M4, M5, or a
hardware loop.

The frontend may show read-only DEV observations when they are tied to the
exact route or component. It must not upgrade source fixtures, dry-run output,
front-end state, or edge-only health into M3 DEV-LIVE.

如果 `/v1/agent/chat` 返回 `provider_unavailable` 或报告缺少
`OPENAI_API_KEY`，可见状态必须保持 `BLOCKED/credential`。在同源 DEV 请求按
[Code Agent readiness](code-agent-chat-readiness.md) 合同返回 completed
且非空的 assistant response 前，Workbench 不得暗示已有真实 assistant reply。

## Lightweight Checks

Use the existing lightweight checks unless a task explicitly authorizes a
heavier browser run:

```sh
node web/hwlab-cloud-web/scripts/check.mjs
node web/hwlab-cloud-web/scripts/build.mjs
node scripts/dev-cloud-workbench-smoke.mjs --static
node scripts/dev-cloud-workbench-layout-smoke.mjs --static
node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:16666/
```

`npm run web:check` 是 Cloud Workbench 的 repo-owned 前端检查入口。它会
运行源码合同、移动视口 smoke、本地 Code Agent fixture，以及 #273
SOURCE/static layout smoke；默认不访问公网 DEV，不部署、不重启服务，也不调用
M3 IO。

The static smoke checks both sides of the route contract: `/` remains the
user-facing workbench, while `/gate` and `/diagnostics/gate` remain available
for internal diagnostics. This PR-class check is intentionally source-only and
does not deploy, restart services, call public DEV, or run the full live Code
Agent browser journey.

Live checks against `http://74.48.78.17:16666/` are read-only and must report
blocked/skip instead of false green when the browser or network path is not
available.

`--dom-only` keeps the runtime and web-asset identity preflight checks, then
continues with read-only DOM/help validation for the deployed workbench even
when identity drift blocks the full journey. It never sends `POST
/v1/agent/chat`; the Code Agent journey is recorded as `not_applicable` and
must not be used as a DEV-LIVE reply, Secret, mutation, or M3/M4/M5 acceptance
claim.

## Layout Smoke

`scripts/dev-cloud-workbench-layout-smoke.mjs` 是 #273 前端布局/遮挡护栏的
runner 入口。它使用 Playwright 覆盖 `1366x768`、`1024x768` 和 `390x844`
三档视口，检查 M3 控制区、Code Agent 输入区、右侧硬件/可信记录容器、当前
`/gate` 内部页、外层滚动锁和内部面板滚动。命中测试使用真实 Playwright
点击与 `document.elementsFromPoint()`；不得使用 `force: true` 或纯 DOM
dispatch 绕过用户命中。

常用命令：

```sh
npm run web:check
npm run web:layout
npm run web:layout:build
npm run web:layout:live
```

三种模式分工：

| Mode | Command | When |
| --- | --- | --- |
| SOURCE/static | `npm run web:check` 或 `npm run web:layout` | PR/source gate 默认运行，不依赖公网 DEV。 |
| local-build | `npm run web:layout:build` | Cloud Web build/publish 前运行；会先刷新本地 `dist`。 |
| DEV live | `npm run web:layout:live` | DEV deploy 后对 `http://74.48.78.17:16666/` 运行，只证明 UI layout/clickability。 |

报告字段必须能定位 `status=pass|blocked|skip`、`viewport`、`selector`、
`failureType` 和 artifact 路径。当前允许的 `failureType` 包括 `overlap`、
`covered-hit-target`、`overflow`、`outer-scroll-regression`、`screenshot-diff`
以及未上线覆盖项的 `skip`。脚本会保存右侧面板、M3 控制表单、Code Agent
输入区和 `/gate` 当前页局部截图，但不做整页像素 diff 门禁。

默认 `web:check` 失败时会把完整 JSON 报告写入
`tmp/dev-cloud-workbench-layout-web-check.json`，终端断言只输出 compact
blockers/failures：`viewport`、`selector`、`failureType`、summary 和 artifact
路径。`reports/dev-gate/dev-cloud-workbench-layout*.json` 是显式 `web:layout*`
命令的报告路径；它们属于 #273 UI layout blocker 证据，不属于 M3 trusted green
证据。

#287 的硬件状态标签化和 #288 的 `/gate` 单一大表如果尚未上线，layout smoke
只能把对应覆盖项记录为 `skip`，同时继续检查当前可见容器的溢出、遮挡和外层
滚动。该 UI smoke 只能证明布局/可点击性护栏通过，不等于 M3 DEV-LIVE 硬件
闭环通过，也不能替代 #227 的 DO/DI 功能验收。

该脚本同时覆盖 #276 的接线面板：打开右侧 `接线` 标签，断言
`panel-wiring` 是两列长表、表头为 `res_boxsimu_1` / `res_boxsimu_2`、IO
行为 `DO1` 对 `DI1`，并记录右侧接线面板 `scrollWidth <= clientWidth`，禁止
内部横向滚动。该证据仍只证明 UI 布局，不等于 M3 trusted green。

## Stable Sources

- [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99): default
  Cloud Workbench direction.
- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108): no
  outer scroll, Chinese UI, internal Markdown help.
- [pikasTech/HWLAB#273](https://github.com/pikasTech/HWLAB/issues/273):
  Playwright layout and overlap guardrail.
- [pikasTech/HWLAB#276](https://github.com/pikasTech/HWLAB/issues/276):
  patch-panel wiring panel two-column long-table feedback.
- [code-agent-chat-readiness.md](code-agent-chat-readiness.md): Code Agent
  chat 同源 readiness 和 provider credential blocker 边界。
- [docs/cloud-web-workbench.md](../cloud-web-workbench.md): detailed frontend
  contract.
- [docs/dev-deploy-apply.md](../dev-deploy-apply.md): Cloud Web manual rollout
  path.