继续完成 web-rtcp-5axis-sim-plan

结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
2026-06-21 16:44:29 +08:00
parent a6eda3fbff
commit 626bcfe8e3
101 changed files with 101586 additions and 770 deletions
--- a/web-rtcp-5axis-sim-plan/docs/development-continuation.md
+++ b/web-rtcp-5axis-sim-plan/docs/development-continuation.md
@@ -0,0 +1,357 @@
+# 5 轴数控系统 Web 仿真编写过程接续文档
+
+生成时间：2026-06-20 CST
+
+## 1. 当前结论
+
+已确定：
+
+- Web 前端界面可实现；
+- 首选界面风格为 `gmoccapy_5_axis.png`；
+- 前端不使用 React/Vue 等框架，采用原生 HTML/CSS + TypeScript/JavaScript ES modules；
+- 3D 使用 Three.js；
+- LinuxCNC Python GUI 只做界面参考；
+- LinuxCNC C/C++/WASM/source-derived boundary 才能作为 CNC 语义和五轴运动学依据。
+
+当前准备文档已完成：
+
+```text
+README.md
+docs/implementation-plan.md
+docs/technical-roadmap.md
+docs/program-implementation-guide.md
+docs/development-continuation.md
+docs/traceability-matrix.md
+docs/linuxcnc-python-gui-reference.md
+docs/linuxcnc-gui-reference-gallery.md
+```
+
+## 2. 下一轮直接开工任务
+
+下一轮不再继续扩展方案，直接进入实现。
+
+第一批任务：
+
+```text
+M1-web-shell-gmoccapy
+```
+
+状态：
+
+```text
+completed_with_build_gate
+```
+
+目标：
+
+- 创建 `app/`；
+- 创建原生 HTML/CSS/TS 项目；
+- 实现 gmoccapy 风格静态 shell；
+- 复制必要的参考图路径到 docs；
+- 加 browser smoke 验证页面区域存在。
+
+已补齐 M1 工程化验收：
+
+- `app/tsconfig.json` 已创建；
+- `npm run build` 已可输出静态产物；
+- build 产物目录 `app/dist/` 已加入 `.gitignore`；
+- browser smoke 已检查无 React/Vue/Angular/Svelte 依赖和 DOM 标记。
+
+## 3. M1 任务拆分
+
+### M1.1 初始化 app
+
+创建：
+
+```text
+app/index.html
+app/package.json
+app/tsconfig.json
+app/src/main.ts
+app/src/styles/gmoccapy.css
+```
+
+要求：
+
+- 不安装 React/Vue；
+- 可使用 Vite；
+- `npm run dev` 能启动；
+- `npm run build` 能输出静态产物。
+
+### M1.2 静态 shell
+
+创建：
+
+```text
+app/src/ui/gmoccapy-shell.ts
+```
+
+渲染区域：
+
+```text
+titlebar
+preview
+dro
+gcode
+status-sidebar
+info-tabs
+override
+spindle-coolant
+bottom-controls
+```
+
+### M1.3 CSS layout
+
+目标：
+
+- 视觉接近 `gmoccapy_5_axis.png`；
+- 黑底 preview；
+- 绿色 DRO；
+- 灰色面板；
+- 橙色 override；
+- 右侧竖向大按钮；
+- 底部大按钮栏。
+
+### M1.4 smoke
+
+创建：
+
+```text
+tests/browser/gmoccapy_shell_smoke.html
+tests/browser/verify_gmoccapy_shell_browser.sh
+```
+
+检查：
+
+- 页面加载；
+- 关键 `data-region` 存在；
+- DRO 文本非空；
+- G-code rows 存在；
+- preview 容器非空；
+- 无 React/Vue 依赖标记。
+
+当前 gate：
+
+```text
+gmoccapy_static_build=ok
+gmoccapy_shell_smoke=ok
+```
+
+## 4. M2 任务
+
+```text
+M2-state-and-controls
+```
+
+状态：
+
+```text
+completed_with_rtcp_frame_and_control_wiring
+```
+
+目标：
+
+- 实现 store；
+- 实现 Run/Stop/Pause/Step action；
+- G-code active line；
+- DRO state update；
+- Node smoke。
+
+本轮追加 RTCP 最小可验证链路：
+
+- 新增 `xyzac-trt` profile source reference；
+- 新增 `web-rtcp-5axis-motion-frame`；
+- store 输出 `axisPose`、`jointPose`、`tcpPose`、`toolAxisVector`、`rtcpFrame`；
+- 右侧 TCP/IDENTITY 按钮可切换 `rtcpState=on/off`；
+- DRO 和 info tabs 显示 TCP pose、tool axis vector、RTCP frame readiness；
+- browser smoke 验证 RTCP DOM 和状态同步；
+- node smoke 验证 frame/store 行为。
+
+本轮继续补齐 M2 控件接线：
+
+- preview X/Y/Z/Fit/Clear 按钮接入 store；
+- Rapid Override / Feed Rate 加减按钮接入 store；
+- Spindle override 加减按钮接入 store；
+- Flood / Mist 冷却按钮接入 store；
+- Reload / Home / Full 底部按钮接入 store；
+- `operatorMessage` 记录最近一次仿真操作；
+- Node smoke 和 browser smoke 覆盖上述控制链路。
+
+边界说明：
+
+```text
+sourceMode=fixture-ui-only
+semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof
+linuxCncKinematicsReady=false
+promotionAllowed=false
+```
+
+也就是说，Web 仿真界面现在已经具备 RTCP 状态链路和显示链路，但尚未把 LinuxCNC/source-derived 五轴运动学 WASM 接入为最终语义源。
+
+## 5. M3 任务
+
+```text
+M3-threejs-preview
+```
+
+状态：
+
+```text
+completed_with_canvas_smoke
+```
+
+目标：
+
+- Three.js canvas；
+- 基础五轴机床；
+- tool marker；
+- simple path；
+- canvas nonblank browser smoke。
+
+M3 需要消费 M2 的 `rtcpFrame`：
+
+- Three.js tool marker 使用 `tcpPose`；
+- 刀轴显示使用 `toolAxisVector`；
+- RTCP on/off 需要在预览中产生可见姿态差异；
+- canvas smoke 需要检查 frame 与预览数据同步。
+
+已完成：
+
+- 新增 `app/src/vendor/three/three.module.js` 和 `three.core.js`；
+- 新增 `app/src/visualization/five-axis-scene.js`；
+- gmoccapy preview 区域由真实 WebGL canvas 渲染；
+- 预览显示基础五轴工作区、工作台、刀具/TCP marker、刀轴和刀路；
+- Three.js canvas 消费 `tcpPose`、`toolAxisVector`、`rtcpState`、`rtcpFrame`；
+- browser smoke 验证 canvas nonblank、scene objects、path points、RTCP on/off 同步和 STEP 后 TCP pose 更新。
+
+当前 gate：
+
+```text
+gmoccapy_static_build=ok
+rtcp_store_smoke=ok
+gmoccapy_shell_smoke=ok
+```
+
+## 6. M4 任务
+
+```text
+M4-profile-and-linuxcnc-boundary
+```
+
+状态：
+
+```text
+completed_with_profile_boundary_smoke
+```
+
+目标：
+
+- `xyzac-trt` profile；
+- source reference map；
+- PyVCP/HAL panel schema；
+- LinuxCNC adapter 接入点；
+- traceability update。
+
+已完成：
+
+- 扩展 `app/src/profiles/xyzac-trt.js`，记录 INI、PyVCP XML、postgui HAL、generated HAL、tool table、remap、switchkins type、HAL pins、offsets、sample programs；
+- 进一步按 LinuxCNC `xyzac-trt.ini`/`xyzac-trt_cmds.hal`/`*.tbl`/`428-430remap.ngc` 整理 machine name、DISPLAY/RS274NGC/TRAJ、axis/joint limits、HALCMD nets、HALUI MDI commands、tool table 条目；
+- 新增 `app/src/profiles/source-reference-map.js`，建立 `xyzac-trt` source/config/reference map；
+- 新增 `app/src/panel-schema/xyzac-trt-pyvcp.js`，把 `xyzac-trt.xml` 与 `switchkins_postgui.hal` 的 SWITCHKINS 控件整理为 Web panel schema；
+- 新增 `app/src/runtime/linuxcnc-boundary-adapter.js`，作为后续 LinuxCNC interpreter/kinematics WASM 的接入点；
+- store 输出 `linuxCncBoundaryAdapter` 和 `linuxCncBoundaryReadiness`；
+- info tabs 显示 adapter、panel schema、source map 和 boundary readiness；
+- 新增 `tests/node/verify_profile_boundary.mjs`，并接入 `npm run smoke:node`；
+- browser smoke 验证 LinuxCNC boundary adapter/schema/readiness DOM 状态。
+
+边界说明：
+
+```text
+sourceMapBoundary=profile_source_map_only_not_runtime_proof
+panelSchemaBoundary=pyvcp_hal_schema_reference_only
+adapterBoundary=adapter_entrypoint_only_runtime_not_connected
+linuxCncKinematicsReady=false
+promotionAllowed=false
+```
+
+说明：
+
+```text
+M4 现在可视为在 profile/source-map/panel-schema/adapter 层面完全满足；
+但这不等于 LinuxCNC interpreter/kinematics runtime 已接入。
+```
+
+## 7. M5 任务
+
+```text
+M5-operator-program-workflow
+```
+
+状态：
+
+```text
+completed_with_operator_program_smoke
+```
+
+目标：
+
+- 上电、急停、自动、手动、JOG、MDI、复位等操作；
+- 加载 G-code 文件；
+- 刀具预览；
+- 执行程序并显示执行的当前行。
+
+已完成：
+
+- store 新增 `machine.powerOn`、`machine.estopActive`、`machine.mode`、JOG/MDI/reset 状态；
+- 右侧按钮栏新增 POWER、E-STOP、RESET、AUTO、MANUAL、JOG、MDI；
+- 底部控制栏新增本地 G-code 文件输入、JOG X/Y、MDI run；
+- `LOAD_PROGRAM` 可从浏览器 FileReader 或 public dispatch 加载 operator G-code 文本；
+- G-code 面板显示程序来源、当前执行行，并按当前行高亮；
+- Three.js 预览区域新增刀具预览卡，显示 T 号、直径、长度和 holder；
+- RUN/STEP 会在上电且非急停状态下推进当前行，未上电时明确 blocked；
+- node/browser smoke 覆盖上电、加载程序、运行、高亮当前行、JOG、MDI、复位和急停。
+
+边界说明：
+
+```text
+operatorWorkflowBoundary=browser_ui_runtime_fixture
+gcodeLoadBoundary=file_text_staging_only
+programExecutionBoundary=fixture_line_playback_not_linuxcnc_interpreter
+linuxCncKinematicsReady=false
+promotionAllowed=false
+```
+
+## 8. 每批完成后必须更新
+
+每批完成后更新：
+
+- 本文件的“当前状态”；
+- `docs/traceability-matrix.md`；
+- 如果新增 UI 或 runtime 约束，更新 `docs/program-implementation-guide.md`；
+- 如果新增参考来源，更新 `docs/linuxcnc-python-gui-reference.md` 或 `docs/linuxcnc-gui-reference-gallery.md`。
+
+## 9. 当前状态
+
+```text
+status=M6_linuxcnc_kinematics_frame_proof_complete
+active_style=gmoccapy_5_axis
+frontend_framework=none
+ui_stack=html_css_typescript_es_modules
+preview_stack=threejs
+semantic_boundary=linuxcnc_owned
+latest_batch=M6-linuxcnc-kinematics-frame-proof
+latest_gate=linuxcnc_kinematics_runtime_smoke=ok,profile_boundary_smoke=ok,rtcp_store_smoke=ok,gmoccapy_shell_smoke=ok,gmoccapy_static_build=ok
+rtcp_ui_state=implemented_fixture_fallback_and_node_kinematics_wasm_frame
+control_wiring=power_estop_reset_auto_manual_jog_mdi_run_stop_pause_step_overrides_coolant_spindle_preview_home_reload_full
+gcode_loading=implemented_browser_file_text_staging
+program_current_line=implemented_fixture_line_playback_and_highlight
+tool_preview=implemented_tool_card_and_threejs_marker
+threejs_preview=implemented_basic_canvas_scene
+profile_source_map=implemented_xyzac_trt
+pyvcp_hal_schema=implemented_xyzac_trt_switchkins
+linuxcnc_boundary_adapter=kinematics_runtime_connected_node_interpreter_remap_missing
+linuxcnc_kinematics_wasm=node_proof_ready_xyzac_trt
+browser_kinematics_wasm=not_connected_fixture_fallback
+full_program_execution=not_promoted_fixture_line_playback
+next_batch=browser_kinematics_wasm_asset_worker_or_interpreter_execution_source
+```
--- a/web-rtcp-5axis-sim-plan/docs/implementation-plan.md
+++ b/web-rtcp-5axis-sim-plan/docs/implementation-plan.md
@@ -0,0 +1,396 @@
+# 基于 Web 的 RTCP 五轴联动数控系统仿真实现方案
+
+生成时间：2026-06-20 CST
+
+## 1. 项目定位
+
+本项目建设一个独立的 Web 数控系统仿真界面，重点支持五轴联动与 RTCP/TCP 模式展示。系统以 LinuxCNC 源码、`configs/sim` 案例和 LinuxCNC Python 图形界面程序为参考基础，复用当前项目已经完成的 WASM、OPFS、virtual HAL、AXIS 风格 UI、G-code 执行仿真和 5 轴 source coverage 成果。
+
+边界必须清晰：
+
+- 这是 Web 数控系统仿真，不是硬实时机床控制器。
+- 浏览器不直接驱动真实伺服、IO 或 Linux kernel realtime ABI。
+- G-code 解释、canonical event、五轴运动学、remap 语义、tool/parameter 行为应尽量保持 LinuxCNC-owned。
+- JavaScript 只做 UI、会话、文件 staging、WASM 调用、状态编排和可视化映射。
+- 前端界面采用原生 HTML/CSS + TypeScript/JavaScript ES modules，不使用 React/Vue 等 UI 框架。
+- LinuxCNC Python GUI 是界面和仿真结构参考，不是浏览器 runtime 依赖；Web 侧不直接运行 Tk/OpenGLTk、PyQt、GTK/Glade 或 native HAL GUI 进程。
+
+## 2. 当前项目完成情况基线
+
+当前 `wasm-port` 已经具备以下可继承能力：
+
+- 浏览器真实仿真页面：`wasm-port/runtime/ui/simulation/index.html` 已实现 AXIS 风格界面、程序选择、编辑器、DRO、状态栏、Three.js 预览、播放控制和 browser smoke。
+- LinuxCNC 解释器 WASM：已有 `createLinuxCncInterpSdk()` 路径，可运行内置和用户输入的 G-code，并输出 LinuxCNC canonical 事件。
+- OPFS/session：已有 INI、参数文件、刀具表、G-code 程序、会话快照的浏览器侧持久化和加载工作流。
+- virtual HAL：已有仿真级 HAL pin/signal/param、halcmd 风格命令、motion feedback stepping 和浏览器状态展示。
+- 5 轴源码覆盖：已 vendored LinuxCNC `5axiskins.c`、`trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`switchkins.*`、`userkfuncs.c` 等，且 source reuse 文档明确这些文件的验证边界。
+- 5 轴案例覆盖：已纳入 LinuxCNC `configs/sim/axis/vismach/5axis/bridgemill`、`table-dual-rotary`、`table-rotary-tilting` 的 INI/HAL/NGC/remap assets。
+- 当前 sim config inventory 基线：`executed=82`、`passed=82`、`skipped=77`、`unexpected_fail=0`；77 个 skipped row 已有实现覆盖账本，但不是全部 promotion。
+- 本地 LinuxCNC 源码中可参考 Python 图形界面：`src/emc/usr_intf/axis/scripts/axis.py`、`lib/python/vismach.py`、`configs/sim/axis/vismach/5axis/*`、`configs/sim/gmoccapy/*`、`configs/sim/qtvcp_screens/*`。
+
+未完成或不能直接宣称完成的点：
+
+- RTCP/TCP 五轴联动还没有作为独立 Web 产品能力完整闭环。
+- 当前浏览器页面主要是通用 AXIS 风格仿真，还不是专门的五轴/RTCP 操作界面。
+- TRT/bridge 五轴运动学虽然有 source coverage 和 probe 基础，但需要形成面向 UI 的统一五轴 pose/joint/TCP 数据模型。
+- Python remap、tool DB、external user-M process 等 hard block 仍不能伪装成浏览器 PASS。
+- Python GUI 的 native 控件、HAL component 进程、Tk/PyQt/GTK 主循环和 OpenGLTk 不能直接作为 Web 运行时使用，需要转换成 Web 组件、Three.js 场景和 virtual HAL 数据绑定。
+
+## 3. LinuxCNC 参考案例选择
+
+第一阶段建议聚焦 LinuxCNC 已有 5 轴 sample，不泛化到任意机型。
+
+优先参考案例：
+
+```text
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
+configs/sim/axis/vismach/5axis/bridgemill/5axis.ini
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.ini
+```
+
+优先参考源码：
+
+```text
+src/emc/kinematics/trtfuncs.c
+src/emc/kinematics/xyzac-trt-kins.c
+src/emc/kinematics/xyzbc-trt-kins.c
+src/emc/kinematics/5axiskins.c
+src/emc/kinematics/switchkins.c
+src/emc/kinematics/switchkins.h
+src/emc/kinematics/userkfuncs.c
+src/emc/kinematics/kins_util.c
+```
+
+关键 LinuxCNC 机制：
+
+- `M428`：切换到 TCP/RTCP 相关五轴运动学模式，示例中设置 `motion.switchkins-type=1`。
+- `M429`：恢复 identity/trivkins 模式，示例中设置 `motion.switchkins-type=0`。
+- `M430`：切换到 user kinematics，作为后续扩展，不作为第一阶段必做。
+- `HAL_PIN_VARS=1`：remap 子程序通过 `_hal[motion.switchkins-type]` 读取 HAL 状态。
+- `M68`/`M66`：设置 analog output 并同步 HAL 状态。
+- TRT 参数：`x-rot-point`、`y-rot-point`、`z-rot-point`、`x/y/z-offset`、`tool-offset`、`conventional-directions`。
+
+## 4. Python 图形界面参考范围
+
+LinuxCNC 的五轴仿真界面大量使用 Python 图形界面程序和 XML/HAL 配置组合。Web 项目应参考这些界面形态，但不把 Python GUI 作为浏览器依赖。
+
+优先参考对象：
+
+```text
+src/emc/usr_intf/axis/scripts/axis.py
+lib/python/vismach.py
+configs/sim/axis/vismach/5axis/bridgemill/5axis.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
+configs/sim/axis/vismach/5axis/*/*postgui.hal
+configs/sim/gmoccapy/gmoccapy_XYZAC.ini
+configs/sim/qtvcp_screens/qtdragon/*
+```
+
+可借鉴的界面能力：
+
+- AXIS 的菜单、工具栏、Manual/MDI、预览、DRO、G-code 高亮、状态栏。
+- vismach 的层级机床模型：`Translate`、`Rotate`、`HalTranslate`、`HalRotate`，通过 HAL pin 驱动几何体姿态。
+- PyVCP XML 的 `SWITCHKINS` 多状态标签、`TCP:XYZAC`/`IDENTITY`/`USERK` 按钮、joint 数值显示和 `vismach-clear` 操作。
+- gmoccapy 的操作员面板、jog increment、override、嵌入式右侧面板和多轴配置。
+- QtVCP/QtDragon 的现代面板布局、探测/刀具/状态区和大屏操作方式。
+- LinuxCNC 文档中已有实际界面截图，可先用 `docs/linuxcnc-gui-reference-gallery.md` 中的图册做界面选型。
+
+Web 转换规则：
+
+```text
+Python Tk/OpenGLTk/PyQt/GTK 控件 -> Web components
+vismach OpenGL scene graph -> Three.js scene graph
+HAL pin widget binding -> virtual HAL subscription/render binding
+PyVCP XML controls -> declarative Web panel schema
+AXIS/gmoccapy workflow -> browser operator workflow
+native GUI process -> no direct browser dependency
+```
+
+前端实现规则：
+
+```text
+HTML/CSS: 页面结构、布局、主题、响应式约束
+TypeScript/JavaScript ES modules: UI 控件、状态订阅、WASM/OPFS 调用、事件编排
+Three.js: 五轴机床和刀路 3D 预览
+Web Worker: LinuxCNC interpreter/kinematics WASM 计算隔离
+Vite/esbuild: 只做开发服务器、TypeScript 编译和模块打包
+```
+
+禁止引入 React/Vue 等框架作为默认 UI 架构，避免把 CNC runtime 状态包进框架生命周期，增加调试和验证复杂度。
+
+## 5. 总体架构
+
+建议独立项目采用四层架构。
+
+### 5.1 Web UI 层
+
+职责：
+
+- 五轴数控系统主界面；
+- 程序编辑/加载/保存；
+- 机床配置选择；
+- RTCP 开关状态、kins 类型、刀具长度、旋转中心、A/B/C 角度展示；
+- DRO、关节坐标、工件坐标、TCP 坐标、距离到达、运行状态；
+- 三维机床模型、刀具姿态、刀尖中心点轨迹、已执行轨迹与完整轨迹；
+- 报警、边界、未支持功能提示。
+
+界面首选按 `gmoccapy_5_axis.png` 的工业操作台风格实现，并同时吸收 vismach/PyVCP/QtVCP 的界面结构。新项目界面要更偏向“五轴联动仿真工作台”：
+
+```text
+顶部：gmoccapy 风格标题栏，显示 machine/profile/session/run state
+左侧：黑底 Three.js 五轴机床和 TCP 刀路预览
+右上：大号绿色 DRO，显示 X/Y/Z/A/B/C、TCP、RTCP、DTG
+中右：G-code 当前行列表和运行进度
+右侧：竖向模式按钮栏，参考 gmoccapy 大按钮
+中下：tool info / G-code properties / RTCP diagnostics tabs
+下方：velocity、rapid/feed override、coolant、spindle 面板
+底部：open、reload、run、stop、pause、step、home、fullscreen
+```
+
+额外要求：
+
+- 左侧或右侧保留 PyVCP 风格的 `SWITCHKINS` 面板，清楚显示 `IDENTITY`、`TCP:XYZAC`、`TCP:XYZBC`、`USERK`。
+- DRO 同时显示 axis pose、joint pose、TCP pose，不把关节坐标和工件坐标混在一起。
+- Three.js 机床模型按 vismach 层级构建，所有旋转/平移节点都能追溯到 HAL pin 或 kinematics frame。
+- 操作按钮参考 AXIS/gmoccapy 的 F1/F2/home/jog/run/step/stop/reset 逻辑，但只触发仿真 runtime。
+
+### 5.2 Web Runtime/Session 层
+
+职责：
+
+- OPFS 会话管理；
+- INI、HAL、tool table、parameter、G-code 文件 staging；
+- 运行模式管理：standalone、machine-session、5axis-rtcp-session；
+- program run summary；
+- status/event history；
+- diagnostics artifact。
+
+已有 `runtime/opfs` 能作为参考，但新目录后续应建立独立命名空间，避免直接把原页面做成越来越大的单文件。
+
+### 5.3 LinuxCNC WASM/Source Boundary 层
+
+职责：
+
+- 调用 LinuxCNC 解释器 WASM；
+- 调用 LinuxCNC 五轴运动学 C/WASM ABI；
+- 提供 `forwardKinematics()`、`inverseKinematics()`、`switchKinsType()` 这类窄接口；
+- 捕获 canonical events、modal state、named parameters、tool offsets；
+- 输出 source-derived motion frames。
+
+关键要求：
+
+```text
+RTCP/五轴姿态计算必须优先由 vendored LinuxCNC kinematics 源码编译到 WASM 暴露；
+JavaScript 不直接复写 trtfuncs.c / 5axiskins.c 的公式作为最终语义源。
+```
+
+### 5.4 Visualization/Playback 层
+
+职责：
+
+- 将 LinuxCNC 输出的 motion frame 映射为 Three.js 对象；
+- 插值播放已验证 motion events；
+- 显示 TCP 点、刀轴向量、刀具长度补偿、旋转中心、工作台/主轴姿态；
+- 区分 programmed path、joint path、TCP executed path；
+- 显示 RTCP on/off 对比。
+- 用 Three.js 重建 vismach 的机床树，不直接移植 Python OpenGLTk 绘制代码。
+- 支持显示 PyVCP/vismach 示例中的旋转中心、偏置点、真实旋转点、刀具长度和关节反馈。
+
+注意：插值只用于显示，不能成为新的运动规划器。
+
+## 6. RTCP 功能实现定义
+
+本项目中的 RTCP 功能定义为仿真级 RTCP/TCP 能力：
+
+- 读取或配置五轴机床类型：XYZAC、XYZBC、XYZBCW、XYZAB 等；
+- 能识别 `M428/M429` 或 UI 切换产生的 kinstype 状态；
+- 在 RTCP 模式下，以刀尖中心点为显示核心，展示旋转轴变化时 TCP 位置保持或按程序轨迹运动；
+- 同时展示关节坐标和笛卡尔/TCP 坐标；
+- 支持刀具长度、旋转中心、偏置参数改变后重新计算预览；
+- 以 LinuxCNC forward/inverse kinematics 结果作为验算基础；
+- 浏览器 smoke 能证明同一段 5 轴程序在 RTCP 模式下产生非空 A/B/C 姿态和 TCP 轨迹。
+
+第一阶段不承诺：
+
+- 真实伺服周期硬实时；
+- 完整 LinuxCNC task/motion 进程；
+- 任意 Python remap runtime；
+- 任意 external user-M process；
+- 完整工业级碰撞检测；
+- CAM 后处理器。
+
+## 7. 数据模型
+
+建议定义统一 frame：
+
+```text
+FiveAxisMotionFrame
+  sequence
+  sourceLine
+  time
+  kinsType
+  rtcpEnabled
+  workPose: X/Y/Z/A/B/C/U/V/W
+  jointPose: joint[0..N]
+  tcpPose: x/y/z + toolAxisVector
+  toolOffset
+  pivot/rotPoint
+  feed
+  spindle
+  canonicalEventRef
+  diagnostics
+```
+
+建议定义 machine profile：
+
+```text
+FiveAxisMachineProfile
+  id
+  title
+  family: xyzac-trt | xyzbc-trt | bridge-xyzbcw | tdr-xyzab
+  iniPath
+  coordinates
+  joints
+  kinematicsSource
+  halPins
+  remapCodes
+  limits
+  toolTable
+  samplePrograms
+  pythonGuiReferences
+  pyvcpControls
+  vismachModelNodes
+```
+
+## 8. 阶段计划
+
+### Phase 0：方案和边界文档
+
+当前交付。
+
+输出：
+
+- 独立目录；
+- 实现方案；
+- 技术路线；
+- 明确当前完成情况和未完成边界。
+
+### Phase 1：独立 Web 仿真骨架
+
+目标：
+
+- 新建独立 Web app；
+- 复用或引入现有 SDK/WASM 产物；
+- 页面能加载、选择五轴机床、显示 G-code、运行普通 LinuxCNC-backed 程序；
+- Three.js 显示一个基础五轴机床模型和非空刀路。
+- UI 布局参考 AXIS/gmoccapy，包含菜单、工具栏、Manual/MDI、预览、DRO、G-code、状态栏。
+
+验收：
+
+- 本地 dev server 可启动；
+- browser smoke 截图非空；
+- 运行现有线性/圆弧/G81 程序不回退。
+
+### Phase 2：五轴 profile 和 5 轴 demo 接入
+
+目标：
+
+- 接入 `xyzac-trt`、`xyzbc-trt` 两个 profile；
+- staging 对应 INI/HAL/tool table/remap_subs/demo；
+- UI 能显示 kinematics 参数、HAL pins、M428/M429 状态；
+- 执行 LinuxCNC 5 轴 sample 或经过裁剪的 representative demo。
+- 解析 PyVCP XML/HAL 参考，生成 `SWITCHKINS`、joint value、offset/rot-point 等 Web 面板。
+
+验收：
+
+- 能展示 A/C 或 B/C 角度；
+- 能显示 kinstype 0/1 切换；
+- browser smoke 验证 `motion.switchkins-type` 状态。
+
+### Phase 3：LinuxCNC 五轴运动学 WASM ABI
+
+目标：
+
+- 将 `trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`5axiskins.c` 的 forward/inverse 调用通过窄 C ABI 暴露给 Web runtime；
+- 建立 HAL pin shim，为旋转中心、偏置、刀具长度提供输入；
+- 输出 joint/work/TCP frame。
+
+验收：
+
+- Node smoke：forward -> inverse roundtrip；
+- browser smoke：同一 frame 显示 joint pose、work pose、TCP pose；
+- source sync guard 仍通过。
+
+### Phase 4：RTCP/TCP 预览与播放
+
+目标：
+
+- RTCP mode on/off 可视化；
+- 显示 programmed path、TCP path、joint path；
+- 刀轴方向随 A/B/C 变化；
+- 刀尖中心点轨迹与 LinuxCNC kinematics frame 对齐。
+- Three.js 机床层级与 vismach Python 示例的几何层级一致：工作台、转台、摆头、主轴、刀具和工件分别建模。
+
+验收：
+
+- RTCP 开启时，旋转轴变化不导致 UI 随机漂移；
+- 对 `M428/M429` 状态有明确显示；
+- 截图 smoke 校验 canvas 非空、刀具姿态非默认、路径点数非零。
+
+### Phase 5：操作级数控系统仿真
+
+目标：
+
+- Manual/MDI、单段、连续、暂停、复位；
+- 程序行高亮、motion segment 高亮；
+- 坐标系、刀具长度、旋转中心参数编辑和重新仿真；
+- OPFS 保存/恢复完整 5 轴会话。
+
+验收：
+
+- 保存 -> 恢复 -> 重新运行结果一致；
+- UI 提供 operator-facing 状态，不只是 diagnostics dashboard。
+
+### Phase 6：扩展验证和发布
+
+目标：
+
+- 建立 release gate；
+- 建立 regression fixtures；
+- 添加更多 LinuxCNC 5 轴案例；
+- 文档化不支持范围。
+
+验收：
+
+- `git diff --check`；
+- source/vendor sync；
+- Node/browser smoke；
+- screenshot/canvas-pixel check；
+- release readiness artifact。
+
+## 9. 风险与处理
+
+主要风险：
+
+- 把 RTCP 公式写在 JS 中，破坏 LinuxCNC semantic boundary。
+- 5 轴 demo 依赖 remap/HAL 同步，直接跑全量程序可能遇到 runtime boundary。
+- Vismach Python GUI 不能直接迁移到浏览器。
+- 把 Python GUI 参考误解成要在浏览器中运行 Python/Tk/PyQt，会导致架构失控。
+- WebGL 3D 和 G-code 执行状态容易脱节。
+- 过早承诺完整工业 RTCP 会扩大范围。
+
+处理策略：
+
+- 第一阶段只做 source-derived kinematics ABI，不做 JS-owned CNC semantics。
+- demo 程序分 representative subset 和 full upstream demo 两级。
+- Vismach 只作为机床结构参考，浏览器用 Three.js 重建可视化，不移植 Python GUI。
+- PyVCP/gmoccapy/QtVCP 只作为 panel schema 和 operator workflow 参考，控件用 Web 原生实现。
+- 所有 UI frame 都要带 canonical/ref 或 kinematics/ref 追踪字段。
+- hard block 保持显式 blocked，不因为 UI 能显示就 promotion。
+
+## 10. 结论
+
+当前项目已经具备 Web 数控系统仿真的基础设施，但 RTCP 五轴联动还需要单独产品化。下一步应在独立目录中先搭建五轴 Web 仿真骨架，界面形态参考 LinuxCNC 的 AXIS、vismach、PyVCP、gmoccapy 和 QtVCP Python 图形界面，再把 LinuxCNC TRT/bridge 五轴运动学通过 WASM ABI 接入，最后形成 RTCP/TCP 轨迹、关节姿态、刀尖中心点和机床模型同步显示的浏览器仿真界面。
--- a/web-rtcp-5axis-sim-plan/docs/linuxcnc-gui-reference-gallery.md
+++ b/web-rtcp-5axis-sim-plan/docs/linuxcnc-gui-reference-gallery.md
@@ -0,0 +1,226 @@
+# LinuxCNC 原始界面参考图册
+
+生成时间：2026-06-20 CST
+
+## 1. 目的
+
+本图册收集 LinuxCNC 源码树自带的实际界面截图，用于选择 Web 五轴数控系统仿真界面的视觉和布局方向。
+
+图片来源：
+
+```text
+linuxcnc/docs/src/gui/images/
+```
+
+已复制到本项目：
+
+```text
+web-rtcp-5axis-sim-plan/assets/reference/linuxcnc-gui/
+```
+
+这些图片只作为界面参考，不代表 Web 项目会直接移植 LinuxCNC 原生 GUI runtime。
+
+## 2. 优先参考图
+
+### 2.1 QtVCP Vismach 5 Axis Gantry
+
+![QtVCP Vismach 5 Axis Gantry](../assets/reference/linuxcnc-gui/qtvismach_5axis_gantry.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/qtvismach_5axis_gantry.png
+```
+
+推荐用途：
+
+- 五轴机床模型参考优先级最高。
+- 可参考其 3D 机床视图、动态轴显示和仿真模型表达。
+- 适合作为 Web 版 Three.js 五轴机床主视口的方向。
+
+建议选择程度：高。
+
+### 2.2 gmoccapy 5 Axis
+
+![gmoccapy 5 Axis](../assets/reference/linuxcnc-gui/gmoccapy_5_axis.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/gmoccapy_5_axis.png
+```
+
+推荐用途：
+
+- 操作员界面参考。
+- 大按钮、DRO、运行控制、状态区、手动操作面板可以借鉴。
+- 适合触控屏或工业操作台风格。
+
+建议选择程度：高。
+
+### 2.3 AXIS
+
+![AXIS](../assets/reference/linuxcnc-gui/axis.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/axis.png
+```
+
+推荐用途：
+
+- 经典 LinuxCNC 操作布局参考。
+- 菜单、工具栏、G-code、预览、DRO、状态栏结构清晰。
+- 适合作为第一版 Web 五轴仿真工作台的主布局骨架。
+
+建议选择程度：高。
+
+### 2.4 AXIS + PyVCP
+
+![AXIS PyVCP](../assets/reference/linuxcnc-gui/axis-pyvcp.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/axis-pyvcp.png
+```
+
+推荐用途：
+
+- 右侧 PyVCP 面板参考。
+- `SWITCHKINS`、joint value、offset/rot-point、RTCP 状态面板可以采用类似侧栏。
+- 适合把五轴专用控件放在主预览旁边。
+
+建议选择程度：高。
+
+## 3. 现代操作屏参考
+
+### 3.1 QtDragon
+
+![QtDragon](../assets/reference/linuxcnc-gui/qtdragon.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/qtdragon.png
+```
+
+推荐用途：
+
+- 现代化大屏 CNC 操作界面参考。
+- 面板区、状态区、按钮区和探测/刀具相关布局可借鉴。
+- 如果目标是更接近工业触控屏，可参考此方向。
+
+建议选择程度：中高。
+
+### 3.2 QtDragon HD
+
+![QtDragon HD](../assets/reference/linuxcnc-gui/qtdragon_hd.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/qtdragon_hd.png
+```
+
+推荐用途：
+
+- 大屏布局参考。
+- 适合后续做宽屏 Web 版操作台。
+
+建议选择程度：中。
+
+## 4. Vismach 机床仿真参考
+
+### 4.1 Vismach
+
+![Vismach](../assets/reference/linuxcnc-gui/vismach.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/vismach.png
+```
+
+推荐用途：
+
+- Python `vismach.py` 原始机床仿真窗口参考。
+- 可参考机床模型、坐标轴、视角控制和独立仿真窗口表达。
+
+建议选择程度：中。
+
+### 4.2 QtVismach
+
+![QtVismach](../assets/reference/linuxcnc-gui/qtvismach.png)
+
+原始文件：
+
+```text
+linuxcnc/docs/src/gui/images/qtvismach.png
+```
+
+推荐用途：
+
+- QtVCP 嵌入式机床仿真面板参考。
+- 适合思考 Three.js 视口如何嵌入主操作界面。
+
+建议选择程度：中。
+
+## 5. 推荐界面方案
+
+用户已选择 `gmoccapy_5_axis.png` 作为目标界面风格。建议第一版 Web 五轴 RTCP 仿真界面以 gmoccapy 5 轴界面为主风格，再吸收 QtVismach 5 Axis Gantry 的机床模型表达和 PyVCP 的五轴状态控件。
+
+```text
+主风格：gmoccapy_5_axis.png
+3D 机床视口：QtVCP Vismach 5 Axis Gantry
+五轴专用状态：PyVCP SWITCHKINS / joint values
+经典布局参考：AXIS
+后续大屏扩展：QtDragon / QtDragon HD
+```
+
+具体布局建议：
+
+```text
+顶部：gmoccapy 风格标题栏 + machine/session/run state
+左侧：黑底 Three.js 五轴机床和刀路预览
+右上：大号绿色 DRO，显示 X/Y/Z/A/B/C、TCP、RTCP、DTG
+中右：G-code 当前行列表和运行进度
+右侧：竖向模式按钮栏，参考 gmoccapy 大按钮
+中下：tool info / G-code properties / RTCP diagnostics tabs
+下方：velocity、rapid/feed override、coolant、spindle 面板
+底部：open、reload、run、stop、pause、step、home、fullscreen
+```
+
+## 6. 图片清单
+
+```text
+assets/reference/linuxcnc-gui/qtvismach_5axis_gantry.png
+assets/reference/linuxcnc-gui/gmoccapy_5_axis.png
+assets/reference/linuxcnc-gui/axis.png
+assets/reference/linuxcnc-gui/axis-pyvcp.png
+assets/reference/linuxcnc-gui/qtdragon.png
+assets/reference/linuxcnc-gui/qtdragon_hd.png
+assets/reference/linuxcnc-gui/vismach.png
+assets/reference/linuxcnc-gui/qtvismach.png
+```
+
+## 7. 选择建议
+
+当前选择：
+
+```text
+gmoccapy 5 Axis + QtVismach 5 Axis Gantry + PyVCP SWITCHKINS
+```
+
+如果后续需要更经典 LinuxCNC 桌面风格，可退回：
+
+```text
+AXIS + PyVCP + QtVismach 5 Axis Gantry
+```
+
+如果后续需要更现代大屏触控风格，可扩展：
+
+```text
+gmoccapy + QtDragon HD
+```
--- a/web-rtcp-5axis-sim-plan/docs/linuxcnc-python-gui-reference.md
+++ b/web-rtcp-5axis-sim-plan/docs/linuxcnc-python-gui-reference.md
@@ -0,0 +1,194 @@
+# LinuxCNC Python 图形界面参考
+
+生成时间：2026-06-20 CST
+
+## 1. 目的
+
+本文件补充说明：五轴数控系统仿真界面的设计不仅参考 LinuxCNC 的 C/C++ 解释器、运动学和配置案例，也参考 LinuxCNC 使用 Python 编写的图形界面和机床仿真程序。
+
+这些 Python GUI 是 Web 界面的产品和结构参考，不是 Web 运行时依赖。浏览器版本不直接运行 Tk、OpenGLTk、PyQt、GTK/Glade、native HAL component 或 Python GUI process。
+
+## 2. 参考对象
+
+### AXIS
+
+参考文件：
+
+```text
+src/emc/usr_intf/axis/scripts/axis.py
+share/axis/*
+configs/sim/axis/*
+```
+
+参考内容：
+
+- 菜单栏、工具栏、运行/暂停/单段/停止/复位。
+- Manual、MDI、Preview、DRO、G-code 文本区。
+- G-code 当前行高亮。
+- OpenGL 刀路预览和视图控制。
+- E-stop、machine on、homing、坐标模式、状态栏。
+
+Web 对应实现：
+
+```text
+AXIS main window -> 单页 Web operator workspace
+AXIS toolbar -> Web icon toolbar
+AXIS preview -> Three.js viewport
+AXIS DRO -> Web DRO panel
+AXIS G-code list -> Web editor/source pane
+```
+
+### vismach
+
+参考文件：
+
+```text
+lib/python/vismach.py
+configs/sim/axis/vismach/5axis/bridgemill/*
+configs/sim/axis/vismach/5axis/table-dual-rotary/*
+configs/sim/axis/vismach/5axis/table-rotary-tilting/*
+configs/sim/axis/vismach/5axis/table-rotary_spindle-rotary-nutating/vismach/*.py
+```
+
+参考内容：
+
+- 机床几何树。
+- `Translate`、`Rotate` 静态变换。
+- `HalTranslate`、`HalRotate` 基于 HAL pin 的动态变换。
+- 工作台、转台、摆头、主轴、刀具、工件的层级关系。
+- `vismach-clear` 清空轨迹。
+- STL/几何体组合机床模型。
+
+Web 对应实现：
+
+```text
+vismach Collection -> Three.js Group
+vismach Translate/Rotate -> Three.js transform node
+vismach HalTranslate/HalRotate -> virtual HAL-bound transform node
+vismach component pins -> profile-declared observable values
+vismach OpenGLTk scene -> Three.js scene
+```
+
+### PyVCP
+
+参考文件：
+
+```text
+configs/sim/axis/vismach/5axis/bridgemill/5axis.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
+configs/sim/axis/vismach/5axis/*/*postgui.hal
+```
+
+参考内容：
+
+- `SWITCHKINS` multilabel。
+- `IDENTITY`、`TCP:XYZAC`、`TCP:XYZBC`、`USERK` 按钮。
+- joint 数值显示。
+- offset / rot-point 参数显示或调节。
+- HAL pin 到 GUI 控件的绑定。
+
+Web 对应实现：
+
+```text
+PyVCP XML -> Web panel schema
+halpin -> virtual HAL binding
+multilabel -> segmented/status indicator
+button -> command/action button
+number -> read-only numeric DRO field
+```
+
+### gmoccapy
+
+参考文件：
+
+```text
+configs/sim/gmoccapy/gmoccapy_XYZAC.ini
+configs/sim/gmoccapy/gmoccapy_*.ini
+configs/sim/gmoccapy/*.glade
+configs/sim/gmoccapy/*postgui.hal
+```
+
+参考内容：
+
+- 面向操作员的大按钮布局。
+- jog increment、feed override、spindle override、rapid override。
+- 右侧嵌入面板。
+- 多轴配置和状态显示。
+
+Web 对应实现：
+
+```text
+gmoccapy operator panel -> compact touch-friendly control panel
+gladevcp embedded tab -> Web side panel
+override controls -> sliders/steppers
+jog increment -> segmented controls
+```
+
+### QtVCP / QtDragon
+
+参考文件：
+
+```text
+configs/sim/qtvcp_screens/*
+configs/sim/qtvcp_screens/qtdragon/*
+share/qtvcp/*
+```
+
+参考内容：
+
+- 现代化 CNC 操作屏布局。
+- 状态区、工具区、探测区、程序区。
+- 大屏/触控操作方式。
+- panel handler 和 widget 分层。
+
+Web 对应实现：
+
+```text
+QtVCP screen -> responsive Web layout
+QtVCP widgets -> reusable Web components
+handler state -> runtime store/actions
+```
+
+## 3. 五轴界面重点参考项
+
+第一阶段必须吸收这些界面元素：
+
+- `SWITCHKINS` 状态：显示当前 kinstype。
+- `M428/M429/M430` 操作：切换 TCP/identity/userk 模式。
+- joint values：至少显示 J0-J6 或当前 profile joints。
+- axis pose：显示 X/Y/Z/A/B/C/W。
+- TCP pose：显示刀尖中心点和刀轴方向。
+- offset/rot-point：显示旋转点和几何偏置。
+- tool offset：显示刀具长度补偿。
+- preview clear：清空已执行轨迹。
+- status bar：显示 E-stop、machine on、session、run mode、RTCP state。
+
+## 4. 不移植内容
+
+以下内容不直接移植到 Web runtime：
+
+- Tkinter 主循环。
+- `rs274.OpenGLTk`。
+- PyQt/QTVCP native widget。
+- GTK/Glade native UI。
+- native `hal.component()` 进程。
+- LinuxCNC GUI 与 task/motion 的 native IPC。
+- Python remap runtime。
+
+如果后续需要 Python runtime，只能作为单独受控 milestone，不得混入 UI 参考转换。
+
+## 5. 验收方式
+
+文档和实现需要用机器可验证方式证明参考关系：
+
+- profile 中记录 Python GUI source references。
+- panel schema 中记录 PyVCP XML 和 postgui HAL source path。
+- browser smoke 检查 `SWITCHKINS`、joint values、DRO、preview、statusbar 存在。
+- canvas smoke 检查 Three.js 机床模型非空。
+- state smoke 检查 `M428/M429` 或 kinstype 切换能反映到 UI。
+
+## 6. 结论
+
+Web 五轴仿真界面应以 LinuxCNC Python GUI 为交互和可视化参考，以 LinuxCNC C/C++ 源码为 CNC 语义和运动学参考。Python GUI 提供“界面长什么样、机床模型如何组织、HAL 控件如何连接”的依据；浏览器实现负责把这些参考转换为 Web 组件、Three.js 场景、virtual HAL 绑定和 WASM 调用链。
--- a/web-rtcp-5axis-sim-plan/docs/program-implementation-guide.md
+++ b/web-rtcp-5axis-sim-plan/docs/program-implementation-guide.md
@@ -0,0 +1,445 @@
+# 5 轴数控系统 Web 仿真程序具体实施文档
+
+生成时间：2026-06-20 CST
+
+## 1. 实施目标
+
+本文件用于指导后续正式编写 5 轴数控系统 Web 仿真程序。第一版目标是做出一个可运行、可验证、可继续扩展的浏览器前端：
+
+- 界面风格按 `gmoccapy_5_axis.png` 实现；
+- 前端使用原生 HTML/CSS + TypeScript/JavaScript ES modules；
+- 3D 预览使用 Three.js；
+- G-code 执行、五轴运动学、RTCP/TCP 相关计算必须来自 LinuxCNC/WASM 或 source-derived 边界；
+- 不引入 React/Vue/Angular/Svelte；
+- 不把 Python GUI、GTK/Glade、Tk/OpenGLTk、native HAL process 直接作为浏览器 runtime。
+
+## 2. 第一版完成定义
+
+第一版完成时应具备：
+
+- 一个可启动的 Web app；
+- gmoccapy 风格布局：黑底 3D 预览、大号绿色 DRO、G-code 列表、右侧模式按钮、override/spindle/coolant 区、底部运行控制；
+- 至少一个 5 轴 profile：优先 `xyzac-trt`；
+- 能加载 representative G-code；
+- 能显示 X/Y/Z/A/B/C、joint pose、TCP pose、RTCP state、kins type；
+- Three.js 视口非空，能显示机床、刀具、刀路；
+- browser smoke 能截图、检查 canvas 非空、检查关键 DOM 区域存在；
+- 文档明确 LinuxCNC source references 和 unsupported runtime boundary。
+
+## 3. 推荐目录结构
+
+后续直接在本目录中扩展：
+
+```text
+web-rtcp-5axis-sim-plan/
+  app/
+    index.html
+    package.json
+    tsconfig.json
+    src/
+      main.ts
+      state/
+        store.ts
+        events.ts
+      ui/
+        gmoccapy-shell.ts
+        gmoccapy-dro-panel.ts
+        gmoccapy-gcode-panel.ts
+        gmoccapy-status-sidebar.ts
+        gmoccapy-override-panel.ts
+        gmoccapy-spindle-coolant-panel.ts
+        gmoccapy-bottom-controls.ts
+        gmoccapy-info-tabs.ts
+      visualization/
+        five-axis-scene.ts
+        machine-model.ts
+        toolpath-layer.ts
+        camera-controls.ts
+      runtime/
+        simulation-runtime.ts
+        frame-builder.ts
+        playback-controller.ts
+        linuxcnc-adapter.ts
+      profiles/
+        index.ts
+        xyzac-trt.ts
+        xyzbc-trt.ts
+      panel-schema/
+        controls.ts
+        pyvcp-reference.ts
+      workers/
+        linuxcnc-worker.ts
+      styles/
+        gmoccapy.css
+  core/
+    linuxcnc_kinematics_wasm/
+  tests/
+    browser/
+    node/
+```
+
+## 4. 实施顺序
+
+### Step 1：Web shell
+
+目标：
+
+- 创建 `app/index.html`；
+- 创建 CSS layout；
+- 创建 `gmoccapy-shell.ts`；
+- 页面静态呈现 gmoccapy 风格区域。
+
+必须有的 DOM 区域：
+
+```text
+data-region="titlebar"
+data-region="preview"
+data-region="dro"
+data-region="gcode"
+data-region="status-sidebar"
+data-region="info-tabs"
+data-region="override"
+data-region="spindle-coolant"
+data-region="bottom-controls"
+```
+
+验收：
+
+- 浏览器打开页面非空；
+- 页面区域与 `gmoccapy_5_axis.png` 基本一致；
+- 无 React/Vue 依赖。
+
+### Step 2：状态模型
+
+目标：
+
+- 实现 `GmoccapySimulationState`；
+- 实现 `createStore()`、`getState()`、`subscribe()`、`dispatch()`；
+- UI 面板从 state 渲染，不直接互相读写 DOM。
+
+初始 state：
+
+```text
+machineProfile=xyzac-trt
+runState=idle
+rtcpState=off
+kinsType=identity
+axisPose={X,Y,Z,A,B,C}
+jointPose=[]
+tcpPose={x,y,z,toolAxisVector}
+```
+
+验收：
+
+- Node smoke 验证 store 更新；
+- DOM renderer 能响应 state 变化。
+
+当前 M2 已实现：
+
+```text
+app/src/runtime/rtcp-frame.js
+app/src/profiles/xyzac-trt.js
+tests/node/verify_rtcp_store.mjs
+```
+
+状态模型已经输出：
+
+```text
+axisPose
+jointPose
+tcpPose
+toolAxisVector
+rtcpFrame
+feed
+spindle
+coolant
+preview
+operatorMessage
+```
+
+当前 RTCP frame 已支持双来源：
+
+```text
+apiName=web-rtcp-5axis-motion-frame
+fixture fallback:
+  sourceMode=fixture-ui-only
+  semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof
+  linuxCncKinematicsReady=false
+  promotionAllowed=false
+LinuxCNC kinematics proof:
+  sourceMode=source-derived-kinematics-wasm
+  semanticBoundary=linuxcnc_kinematics_wasm_c_abi
+  linuxCncKinematicsReady=true
+  promotionAllowed=true for kinematics frame source only
+```
+
+这表示 Web 仿真已经具备 RTCP 状态链路、TCP pose 显示、刀轴向量显示和控制按钮切换；Node proof 路径已通过 `createLinuxCncKinematicsSdk({ moduleId: "xyzac-trt" })` 加载 LinuxCNC kinematics WASM 并生成 frame。浏览器 smoke 仍保留 fixture fallback，不把 fallback 冒充 LinuxCNC runtime proof。
+
+### Step 3：gmoccapy UI 组件
+
+目标：
+
+- DRO；
+- G-code panel；
+- right status sidebar；
+- override panel；
+- spindle/coolant panel；
+- bottom controls；
+- info tabs。
+
+要求：
+
+- 按 gmoccapy 风格做大按钮、大数字、黑底预览、灰色面板；
+- 所有按钮先连接仿真 action，不连接真实机床控制；
+- 文本不能溢出按钮或面板。
+
+验收：
+
+- browser smoke 检查关键按钮、DRO、G-code rows；
+- `Run/Stop/Pause/Step` 能改变仿真 state。
+
+当前 M2 已接入的 UI action：
+
+```text
+RUN
+STOP
+PAUSE
+STEP
+SET_KINS_TYPE
+SET_VIEW
+RESET_VIEW
+CLEAR_PREVIEW
+ADJUST_OVERRIDE
+ADJUST_SPINDLE_OVERRIDE
+TOGGLE_COOLANT
+RELOAD_PROGRAM
+HOME
+TOGGLE_FULLSCREEN
+```
+
+这些 action 只改变 Web 仿真状态，不连接真实机床控制。
+
+当前 M5 已补齐 operator workflow：
+
+```text
+TOGGLE_POWER
+ESTOP
+RESET
+SET_MODE(auto/manual/jog/mdi)
+JOG
+RUN_MDI
+LOAD_PROGRAM
+```
+
+实现状态：
+
+- 右侧按钮栏提供 POWER、E-STOP、RESET、AUTO、MANUAL、JOG、MDI；
+- 底部控制栏提供 Open、Run/Stop/Pause/Step/Home、JOG X/Y、MDI；
+- Open 使用浏览器 FileReader 读取本地 G-code 文本并进入 `LOAD_PROGRAM`；
+- G-code 面板显示当前程序来源、当前执行行和高亮行；
+- preview 区域显示刀具预览卡；
+- RUN/STEP 仍是 fixture line playback，不是 LinuxCNC interpreter execution proof。
+
+### Step 4：Three.js 五轴预览
+
+目标：
+
+- 创建基础五轴机床模型；
+- 显示坐标轴、工作空间、刀具、TCP 点、刀路；
+- 支持 fit/reset/clear path。
+
+模型优先参考：
+
+```text
+qtvismach_5axis_gantry.png
+lib/python/vismach.py
+src/hal/user_comps/vismach/5axisgui.py
+src/hal/user_comps/vismach/xyzac-trt-gui.py
+src/hal/user_comps/vismach/xyzbc-trt-gui.py
+```
+
+验收：
+
+- canvas 非空；
+- tool marker 可见；
+- path points 非零；
+- 视口尺寸变化不破坏布局。
+
+当前 M3 已实现：
+
+```text
+app/src/vendor/three/three.module.js
+app/src/vendor/three/three.core.js
+app/src/visualization/five-axis-scene.js
+```
+
+当前 Three.js 预览会渲染基础五轴工作区、工作台、刀具/TCP marker、刀轴和刀路，并消费：
+
+```text
+tcpPose
+toolAxisVector
+rtcpState
+rtcpFrame.apiName
+preview.selectedView
+```
+
+browser smoke 已检查 canvas nonblank、scene objects、path points、RTCP on/off 同步和 STEP 后 TCP pose 更新。
+
+### Step 5：profile 和 panel schema
+
+目标：
+
+- 建立 `xyzac-trt` profile；
+- 后续补 `xyzbc-trt`；
+- 把 PyVCP XML 和 HAL 绑定整理成 Web panel schema。
+
+`xyzac-trt` 必须记录：
+
+```text
+iniPath
+coordinates=XYZAC
+kinematics=xyzac-trt-kins
+remap=M428/M429/M430
+halPins=motion.switchkins-type, xyzac-trt-kins.tool-offset, y-offset, z-offset
+samplePrograms
+sourceReferences
+```
+
+验收：
+
+- Node smoke 验证 profile 完整；
+- UI 能显示 profile title、coordinates、kins type、source references。
+
+当前 M4 已实现：
+
+```text
+app/src/profiles/xyzac-trt.js
+app/src/profiles/source-reference-map.js
+app/src/panel-schema/xyzac-trt-pyvcp.js
+tests/node/verify_profile_boundary.mjs
+```
+
+`xyzac-trt` profile 现在记录：
+
+```text
+iniPath
+pyvcpXmlPath
+postguiHalPath
+generatedHalPath
+toolTablePath
+coordinates=XYZAC
+kinematics=xyzac-trt-kins
+sparm=identityfirst
+remaps=M428/M429/M430
+switchkinsTypes=identity/TCP:XYZAC/USERK
+halPins
+offsets
+samplePrograms
+sourceReferences
+```
+
+`xyzac-trt-switchkins-pyvcp` panel schema 记录 SWITCHKINS multilabel、IDENTITY/TCP:XYZAC/USERK/vismach-clear buttons、HAL nets 和对应 MDI commands。
+
+### Step 6：LinuxCNC adapter
+
+目标：
+
+- 第一阶段可接现有 interpreter WASM SDK；
+- 若未接入完整 WASM，则先用明确标记的 fixture frame 验证 UI，不声称 CNC semantics pass；
+- 所有 runtime result 必须带 `sourceMode` 字段。
+
+允许：
+
+```text
+sourceMode=linuxcnc-wasm
+sourceMode=source-derived-kinematics-wasm
+sourceMode=fixture-ui-only
+```
+
+禁止：
+
+```text
+sourceMode=js-cnc-semantics
+```
+
+验收：
+
+- UI-only fixture 不能被标记为 LinuxCNC pass；
+- LinuxCNC/WASM 接入后更新 traceability。
+
+当前 M4 已实现 adapter 接入点：
+
+```text
+app/src/runtime/linuxcnc-boundary-adapter.js
+apiName=web-rtcp-5axis-linuxcnc-boundary-adapter
+readinessApi=web-rtcp-5axis-linuxcnc-boundary-readiness
+semanticBoundary=adapter_entrypoint_only_runtime_not_connected | linuxcnc_kinematics_wasm_runtime_connected
+linuxCncKinematicsReady=false for fixture fallback, true for loaded kinematics WASM
+promotionAllowed=true only for kinematics frame source proof
+fullLinuxCncProgramExecutionReady=false until interpreter/remap is connected
+```
+
+store 已输出：
+
+```text
+linuxCncBoundaryAdapter
+linuxCncBoundaryReadiness
+```
+
+info tabs 和 browser smoke 会检查 adapter、panel schema、source map 和 boundary readiness。Node smoke 已验证 kinematics-only runtime ready；interpreter/remap 仍显示为 missing，不得声明 full LinuxCNC program execution ready。
+
+### Step 7：RTCP/kinematics frame
+
+目标：
+
+- 定义 `FiveAxisMotionFrame`；
+- 将 canonical event 和 kinematics output 转成统一 frame；
+- 显示 RTCP on/off、TCP pose、tool axis vector。
+
+M2 阶段先落地 `web-rtcp-5axis-motion-frame` 的 fixture contract，M6 阶段已加入 LinuxCNC kinematics WASM frame contract：
+
+```text
+profileId
+sourceMode
+semanticBoundary
+activeLine
+kinsType
+rtcpState
+axisPose
+jointPose
+tcpPose
+toolAxisVector
+compensation
+readiness
+```
+
+后续 LinuxCNC/source-derived kinematics WASM 接入时，必须替换 frame builder 的运动学来源，并把 `sourceMode` 从 `fixture-ui-only` 改为明确的 LinuxCNC/WASM 边界值。
+当前 Node proof 已使用 `linuxCncKinematicsResult.forward.pose` 和 `linuxCncKinematicsResult.inverse.joints` 填充 `tcpPose` / `jointPose`，并输出 `kinematicsModuleId`、forward/inverse rc、flags 和 `linuxcnc_kinematics_wasm_c_abi`。
+
+验收：
+
+- Node smoke：frame schema；
+- Browser smoke：DRO 和 Three.js 同步显示同一 frame；
+- fixture fallback 必须显示 pending；Node LinuxCNC kinematics proof 必须显示 ready；interpreter/remap 未接入时仍不得显示 full program execution ready。
+
+### Step 8：测试和验收
+
+至少需要：
+
+- `git diff --check`；
+- Node profile/store/frame smoke；
+- Browser shell smoke；
+- Browser canvas nonblank smoke；
+- 文档 traceability 检查。
+
+## 5. 禁止事项
+
+- 不在 JavaScript 中实现 G-code 解释器。
+- 不在 JavaScript 中实现 LinuxCNC 五轴运动学公式作为最终语义源。
+- 不把 gmoccapy Python/GTK runtime 移植进浏览器。
+- 不把 Python remap/tool DB/external user-M process 伪装成已支持。
+- 不用 UI fixture 结果冒充 LinuxCNC runtime proof。
+
+## 6. 开工建议
+
+当前已完成 Step 1 到 Step 7 的 Node 侧 LinuxCNC kinematics proof。下一轮应把 browser asset copy/worker 接入完成，让真实浏览器也能加载 kinematics WASM；或继续推进 interpreter/remap/planner，使 program execution 从 fixture line playback 升级。
--- a/web-rtcp-5axis-sim-plan/docs/technical-roadmap.md
+++ b/web-rtcp-5axis-sim-plan/docs/technical-roadmap.md
@@ -0,0 +1,551 @@
+# RTCP 五轴 Web 仿真技术路线
+
+生成时间：2026-06-20 CST
+
+## 1. 技术选型
+
+推荐技术栈：
+
+```text
+UI: 原生 HTML + CSS + TypeScript/JavaScript ES modules
+Build: Vite 或 esbuild，仅作为 TypeScript/ES module 打包工具，不引入 React/Vue 等 UI 框架
+3D: Three.js
+WASM: Emscripten
+Core CNC reference: vendored LinuxCNC source
+GUI reference: LinuxCNC Python GUI sources, PyVCP XML, HAL postgui wiring
+Storage: OPFS
+Tests: Node smoke + Playwright/Chromium browser smoke
+Docs/gates: Markdown + machine-readable JSON/TSV artifacts
+```
+
+前端界面不使用 React、Vue、Angular、Svelte 等 UI 框架。原因是本项目核心复杂度在 LinuxCNC/WASM、五轴运动学、RTCP 数据流、Three.js 机床模型和验证链路，不在通用 UI 框架。直接使用 HTML/CSS + TypeScript/JavaScript ES modules 更贴近当前 `wasm-port/runtime/ui/simulation` 的实现方式，也更容易保持 WASM、OPFS、virtual HAL 和 Three.js 的边界清晰。
+
+不使用框架不等于写成单个巨大脚本。必须按模块拆分 `ui/`、`runtime/`、`visualization/`、`profiles/`、`panel-schema/`、`workers/`、`state/`。LinuxCNC 的 Python GUI 只作为参考输入：AXIS 的操作界面、vismach 的机床模型层级、PyVCP XML 面板、gmoccapy/QtVCP 的操作面板都需要转换成 Web 组件和 Three.js 场景。
+
+## 2. 目录建议
+
+后续实现可在本目录扩展为：
+
+```text
+web-rtcp-5axis-sim-plan/
+  README.md
+  docs/
+    implementation-plan.md
+    technical-roadmap.md
+    linuxcnc-python-gui-reference.md
+    linuxcnc-gui-reference-gallery.md
+    linuxcnc-reference-map.md
+    rtcp-data-contract.md
+    validation-plan.md
+  app/
+    index.html
+    package.json
+    src/
+      main.ts
+      ui/
+      ui-reference/
+      runtime/
+      visualization/
+      profiles/
+      workers/
+      panel-schema/
+      state/
+  core/
+    linuxcnc_kinematics_wasm/
+      include/
+      src/
+      build.sh
+  tests/
+    node/
+    browser/
+```
+
+第一轮实现可以只创建 `app/`，后续再把 C/WASM ABI 放入 `core/`。
+
+## 3. gmoccapy 5 轴风格 Web 实现方案
+
+结论：`gmoccapy_5_axis.png` 的界面风格可以实现为 Web 前端，而且适合作为本项目第一版数控系统仿真界面的首选风格。
+
+参考图：
+
+![gmoccapy 5 Axis](../assets/reference/linuxcnc-gui/gmoccapy_5_axis.png)
+
+原始来源：
+
+```text
+linuxcnc/docs/src/gui/images/gmoccapy_5_axis.png
+```
+
+### 3.1 可实现性判断
+
+gmoccapy 5 轴界面由清晰的操作区域组成，适合直接拆成 Web 组件：
+
+- 左侧大面积刀路/机床预览：可用 Three.js 实现。
+- 右上大号绿色 DRO：可用 HTML/CSS 数字面板实现。
+- 中右 G-code 当前行列表：可用虚拟滚动或普通 scroll list 实现。
+- 右侧竖向模式按钮：可用原生 button + icon 实现。
+- 下方信息面板：可用 tabs 和 table 实现。
+- 中下 override、spindle、coolant 面板：可用 slider、stepper、toggle 实现。
+- 底部运行控制：可用 icon button 实现。
+
+这些控件不需要 React/Vue；原生 HTML/CSS + TypeScript/JavaScript ES modules 足够实现。核心状态由一个小型 runtime store 驱动，所有 CNC 语义仍来自 LinuxCNC/WASM/kinematics 边界。
+
+### 3.2 页面布局
+
+建议第一版按 gmoccapy 截图拆为固定操作台布局：
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ 顶部标题栏：machine/profile/session/run state                         │
+├───────────────────────────────┬──────────────────────────────┬───────┤
+│                               │ DRO + active G-code          │ 右侧   │
+│ Three.js 五轴机床/刀路预览     │ X/Y/Z/A/B/C + G-code list     │ 模式栏 │
+│                               │                              │       │
+├───────────────────────────────┼──────────────────────────────┴───────┤
+│ Tool info / G-code properties │ Velocity / Override / Spindle/Coolant │
+├───────────────────────────────┴──────────────────────────────────────┤
+│ 底部：open / reload / run / stop / pause / step / home / fullscreen    │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+适配 Web 五轴 RTCP 后，右上 DRO 应扩展为：
+
+```text
+X Y Z A B C
+Abs / Rel / DTG
+TCP X/Y/Z
+Tool axis vector
+RTCP: on/off
+Kins: identity / TCP / userk
+```
+
+### 3.3 Web 组件映射
+
+建议模块：
+
+```text
+ui/gmoccapy-shell.ts
+ui/gmoccapy-dro-panel.ts
+ui/gmoccapy-preview-toolbar.ts
+ui/gmoccapy-gcode-panel.ts
+ui/gmoccapy-status-sidebar.ts
+ui/gmoccapy-override-panel.ts
+ui/gmoccapy-spindle-coolant-panel.ts
+ui/gmoccapy-bottom-controls.ts
+ui/gmoccapy-info-tabs.ts
+```
+
+组件职责：
+
+- `gmoccapy-shell`：整体布局和区域挂载。
+- `dro-panel`：大号绿色坐标显示，显示 axis/joint/TCP/DTG。
+- `preview-toolbar`：视角、缩放、清除预览、适配窗口。
+- `gcode-panel`：程序行、当前行、运行进度。
+- `status-sidebar`：E-stop、machine on、manual/mdi/auto、settings、tool 等模式按钮。
+- `override-panel`：current velocity、rapid override、feed override。
+- `spindle-coolant-panel`：spindle rpm、spindle override、coolant state。
+- `bottom-controls`：open、reload、run、stop、pause、step、home、fullscreen。
+- `info-tabs`：tool info、G-code properties、RTCP diagnostics、session readiness。
+
+### 3.4 状态模型
+
+gmoccapy 风格页面需要一个小型 store，不需要前端框架：
+
+```text
+GmoccapySimulationState
+  machineProfile
+  sessionReadiness
+  runState
+  activeProgram
+  activeLine
+  dro
+  jointPose
+  tcpPose
+  rtcpState
+  kinsType
+  feedOverride
+  rapidOverride
+  spindleOverride
+  coolantState
+  previewState
+  diagnostics
+```
+
+状态更新路线：
+
+```text
+LinuxCNC/WASM canonical events
+  -> frame builder
+  -> GmoccapySimulationState
+  -> DOM renderers + Three.js scene
+```
+
+### 3.5 样式原则
+
+保持 gmoccapy 的工业操作台气质：
+
+- 黑色 3D 预览背景。
+- 大号绿色 DRO 数字。
+- 灰色面板和分区边框。
+- 橙色 override 进度条。
+- 大尺寸图标按钮。
+- 底部运行控制固定高度。
+- 右侧模式栏固定宽度。
+
+Web 版需要改进的点：
+
+- 适配 1366x768、1920x1080 和平板尺寸。
+- 字体和按钮要避免溢出。
+- 3D 预览和 G-code 面板可以响应式分配宽度。
+- RTCP/TCP 专用状态必须比原图更明确。
+
+### 3.6 与 LinuxCNC 源码边界
+
+可 Web 化：
+
+- 页面布局。
+- 操作按钮。
+- DRO 显示。
+- override/coolant/spindle 仿真状态。
+- G-code 当前行高亮。
+- Three.js 五轴预览。
+- RTCP/TCP 状态展示。
+
+必须仍由 LinuxCNC/WASM 或 source-derived runtime 提供：
+
+- G-code 解释。
+- canonical event。
+- modal state。
+- tool/parameter 语义。
+- 五轴 kinematics。
+- RTCP/TCP frame。
+- M428/M429/M430 remap 状态。
+
+不直接实现：
+
+- gmoccapy native GTK/Glade runtime。
+- LinuxCNC native task/motion IPC。
+- 真实 HAL component process。
+- Python remap runtime。
+- 真实机床 IO。
+
+### 3.7 第一版验收标准
+
+第一版 gmoccapy 风格 Web 前端完成时，应满足：
+
+- 页面整体布局与 `gmoccapy_5_axis.png` 对齐：预览、DRO、G-code、右侧模式栏、底部控制、override/spindle/coolant 区都存在。
+- 使用原生 HTML/CSS + TypeScript/JavaScript ES modules，无 React/Vue 等框架。
+- Three.js 预览非空，能显示五轴机床、刀具和路径。
+- DRO 显示 X/Y/Z/A/B/C 和 TCP 坐标。
+- G-code 面板能高亮当前行。
+- Run/Stop/Pause/Step 控件能驱动仿真 playback。
+- RTCP/TCP 和 kinstype 状态在界面中可见。
+- Browser smoke 做截图和 canvas 非空验证。
+
+## 4. 核心模块拆分
+
+### 4.1 `profiles`
+
+管理 LinuxCNC 五轴机型 profile：
+
+- `xyzac-trt`
+- `xyzbc-trt`
+- `bridge-xyzbcw`
+- `tdr-xyzab`
+
+每个 profile 记录：
+
+- LinuxCNC config source path；
+- coordinates/joints；
+- kinematics source files；
+- HAL pins；
+- M428/M429/M430 remap；
+- sample programs；
+- limits 和默认参数。
+- Python GUI 参考文件；
+- PyVCP/HAL panel 控件；
+- vismach model node 映射。
+
+### 4.2 `runtime`
+
+管理运行状态：
+
+- machine session；
+- G-code staging；
+- interpreter run；
+- kinematics frame calculation；
+- RTCP mode state；
+- diagnostics。
+
+建议 API：
+
+```text
+loadMachineProfile(profileId)
+stageProgram(programText)
+runProgram()
+buildFiveAxisFrames(canonicalEvents, machineProfile)
+setRtcpEnabled(enabled)
+setKinsType(type)
+updateMachineParameter(name, value)
+exportSessionSnapshot()
+restoreSessionSnapshot(snapshot)
+```
+
+### 4.3 `linuxcnc_kinematics_wasm`
+
+提供窄 C ABI：
+
+```text
+linuxcnc_xyzac_trt_forward(input, output)
+linuxcnc_xyzac_trt_inverse(input, output)
+linuxcnc_xyzbc_trt_forward(input, output)
+linuxcnc_xyzbc_trt_inverse(input, output)
+linuxcnc_bridge_5axis_forward(input, output)
+linuxcnc_bridge_5axis_inverse(input, output)
+linuxcnc_set_hal_float(pin, value)
+linuxcnc_set_hal_bit(pin, value)
+linuxcnc_get_last_error()
+```
+
+输入输出应使用稳定结构，不让 UI 直接理解 LinuxCNC 内部全局状态。
+
+### 4.4 `visualization`
+
+Three.js 负责：
+
+- 机床底座、工作台、转台、摆头、主轴、刀具；
+- 坐标轴和工作空间；
+- TCP path；
+- joint path；
+- active segment；
+- tool axis vector；
+- RTCP on/off overlay。
+
+机床模型初期可以用几何体组合，不要先追求 CAD 级模型。重点是五轴姿态和 TCP 点正确、可验证。
+
+vismach 转换规则：
+
+- `Collection` -> Three.js `Group`；
+- `Translate` / `Rotate` -> 静态 transform node；
+- `HalTranslate` / `HalRotate` -> 绑定 virtual HAL pin 的动态 transform node；
+- STL/workpiece asset -> glTF/STL loader 或简化几何体；
+- vismach plot clear -> Web runtime 的 path clear action；
+- HAL component pin -> profile 中声明的 observable runtime value。
+
+### 4.5 `ui`
+
+界面组件：
+
+- machine profile selector；
+- RTCP/kins panel；
+- G-code editor；
+- run controls；
+- DRO；
+- joint position panel；
+- HAL/diagnostics；
+- Three.js viewport；
+- session save/restore。
+- gmoccapy-style shell；
+- gmoccapy-style DRO / override / spindle / coolant / status sidebar。
+
+UI 参考转换：
+
+- AXIS：菜单、工具栏、Manual/MDI、预览、DRO、G-code、状态栏。
+- PyVCP：`SWITCHKINS`、joint 数值、offset/rot-point 控件、`vismach-clear`。
+- gmoccapy：首选界面风格；大按钮操作、jog increment、override、右侧模式栏、底部运行控制、黑底预览和绿色 DRO。
+- QtVCP/QtDragon：现代触控面板、状态区、工具/探测/大屏布局。
+
+### 4.6 `panel-schema`
+
+把 PyVCP XML 和 postgui HAL 的参考关系整理为 Web 面板 schema。
+
+建议 schema：
+
+```text
+PanelControl
+  id
+  type: label | multilabel | button | number | slider | toggle
+  halpin
+  signal
+  sourceFile
+  command
+  displayFormat
+  readonly
+```
+
+第一阶段不需要完整 XML parser，可以先把 `xyzac-trt.xml`、`xyzbc-trt.xml`、`5axis.xml`、`xyzab-tdr.xml` 手工整理成 JSON/TS profile。后续再决定是否写 PyVCP XML importer。
+
+## 5. LinuxCNC 源码接入路线
+
+### Step 1：建立引用清单
+
+形成 `linuxcnc-reference-map.md`，记录每个能力引用哪些 LinuxCNC 文件。
+
+第一批：
+
+```text
+trtfuncs.c
+xyzac-trt-kins.c
+xyzbc-trt-kins.c
+5axiskins.c
+switchkins.c / switchkins.h
+kins_util.c
+kinematics.h
+emcpose.h / emcpose.c
+```
+
+Python GUI / panel 第一批：
+
+```text
+src/emc/usr_intf/axis/scripts/axis.py
+lib/python/vismach.py
+configs/sim/axis/vismach/5axis/bridgemill/5axis.xml
+configs/sim/axis/vismach/5axis/bridgemill/5axisgui.hal
+configs/sim/axis/vismach/5axis/bridgemill/5axis_postgui.hal
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr-postgui.hal
+configs/sim/gmoccapy/gmoccapy_XYZAC.ini
+configs/sim/qtvcp_screens/qtdragon/README
+```
+
+### Step 2：建立 C ABI shim
+
+不要把 LinuxCNC HAL module lifecycle 原样暴露给浏览器。应构造最小 shim：
+
+- 初始化 profile；
+- 分配 HAL 参数存储；
+- 设置 HAL pin 值；
+- 调用 forward/inverse；
+- 输出 frame。
+
+### Step 3：编译 WASM
+
+使用 Emscripten 编译 kinematics core。初期可与当前 `wasm-port` 构建脚本分离，等稳定后再合并。
+
+### Step 4：Node 验证
+
+至少验证：
+
+- `xyzac` forward/inverse；
+- `xyzbc` forward/inverse；
+- tool offset 变化影响 TCP；
+- rot point 变化影响结果；
+- kinstype 0/1 切换状态；
+- source file hash 与 vendor 一致。
+
+### Step 5：Browser 验证
+
+至少验证：
+
+- WASM 在浏览器加载；
+- Three.js canvas 非空；
+- 五轴姿态非默认；
+- RTCP 开关改变显示状态；
+- 加载 sample program 后 path 点数非零。
+- `SWITCHKINS` 面板能显示 `IDENTITY` / `TCP` / `USERK` 状态。
+- joint value 面板与 five-axis frame 中的 joint pose 对齐。
+- `vismach-clear` 类操作能清空预览路径，不改变 LinuxCNC semantic state。
+
+### Step 6：Python GUI 参考验收
+
+该步骤不是运行 Python GUI，而是证明 Web 界面已经吸收其关键设计：
+
+- AXIS 区域齐全：toolbar、Manual/MDI、preview、DRO、G-code、statusbar。
+- PyVCP 控件齐全：switchkins multilabel、type buttons、joint values、clear path。
+- vismach 模型层级齐全：动态平移、动态旋转、工具、工作台、旋转点。
+- gmoccapy/QtVCP 操作形态齐全：大按钮、override、jog increment、operator status。
+
+## 6. RTCP 数据流
+
+推荐数据流：
+
+```text
+LinuxCNC G-code text
+  -> interpreter WASM
+  -> canonical events / modal output
+  -> five-axis frame builder
+  -> LinuxCNC kinematics WASM forward/inverse
+  -> FiveAxisMotionFrame[]
+  -> Three.js visualization + DRO + status panels
+```
+
+`FiveAxisMotionFrame` 是 UI 的唯一运动数据输入。这样可以避免 UI 从多个地方拼状态导致错位。
+
+## 7. 测试路线
+
+### Node smoke
+
+- profile inventory；
+- source reference map；
+- kinematics ABI；
+- frame builder；
+- OPFS/session pure helpers；
+- no JS CNC semantics guard。
+
+### Browser smoke
+
+- 页面加载；
+- profile 切换；
+- sample program run；
+- RTCP status；
+- canvas pixel 非空；
+- tool marker 移动；
+- active G-code line；
+- session save/restore。
+
+### Visual regression
+
+先做轻量检查：
+
+- canvas 非空；
+- tool marker 坐标在视口内；
+- path bounding box 合理；
+- A/B/C 非零时刀轴方向变化。
+
+## 8. 里程碑
+
+建议按以下顺序推进：
+
+1. `M0-docs`：当前方案和技术路线。
+2. `M1-web-shell`：独立 Web app、Three.js 空机床、普通 G-code 执行接通。
+3. `M2-python-gui-reference-panels`：AXIS/PyVCP/vismach/gmoccapy/QtVCP 参考界面转换为 Web panel/schema。
+4. `M3-profile-loader`：`xyzac-trt` / `xyzbc-trt` profile、INI/HAL/remap asset 可见。
+5. `M4-kinematics-wasm`：LinuxCNC 五轴运动学 C/WASM ABI。
+6. `M5-rtcp-preview`：RTCP/TCP path、joint/work/TCP 同步显示。
+7. `M6-kinematics-frame-proof`：Web RTCP frame/boundary adapter 接入 `xyzac-trt` kinematics WASM Node proof。
+8. `M7-browser-kinematics-runtime`：浏览器 asset copy/worker 加载 kinematics WASM。
+9. `M8-session`：OPFS 保存/恢复五轴仿真会话。
+10. `M9-release-gate`：Node/browser/docs/release gate。
+
+## 9. 验收标准
+
+最小可验收版本：
+
+- 浏览器中可以选择 `xyzac-trt`；
+- 可以加载并运行一个 5 轴 sample 或 representative program；
+- 可以看到 XYZAC 或 XYZBC 轴值；
+- 可以切换或识别 RTCP/TCP 状态；
+- Three.js 中显示机床、刀具姿态和 TCP 轨迹；
+- UI 中有参考 PyVCP 的 `SWITCHKINS` 面板和 joint 数值区；
+- Three.js 机床模型能体现 vismach Python 示例的动态层级；
+- 结果来自 LinuxCNC interpreter + LinuxCNC kinematics WASM 边界；
+- browser smoke 通过；
+- 文档明确哪些功能 blocked。
+
+## 10. 下一步动作
+
+当前已完成到 `M6-kinematics-frame-proof`。建议下一轮优先做：
+
+- 在 build-static 中复制 `wasm-port/build/wasm/kinematics` 所需产物，或新增 worker 隔离 kinematics WASM 加载；
+- 让 `app/src/main.js` 在浏览器中 attach `xyzac-trt` kinematics runtime；
+- 保持 fixture fallback，不把 browser fixture smoke 标记为 LinuxCNC proof；
+- 或转向 LinuxCNC interpreter/remap/planner 接入，把 program execution 从 fixture line playback 升级。
+- 使用 Vite + Three.js；
+- 先接入现有普通 G-code program inventory；
+- 画出五轴机床基本结构；
+- 按 AXIS/PyVCP/gmoccapy 参考放置 toolbar、Manual/MDI、DRO、SWITCHKINS、joint values、preview；
+- 加 Playwright smoke；
+- 启动本地 dev server 给出访问地址。
--- a/web-rtcp-5axis-sim-plan/docs/traceability-matrix.md
+++ b/web-rtcp-5axis-sim-plan/docs/traceability-matrix.md
@@ -0,0 +1,467 @@
+# 5 轴数控系统 Web 仿真实现追溯文档
+
+生成时间：2026-06-20 CST
+
+## 1. 目的
+
+本文件用于追溯后续实现中的每个主要功能来自哪里、参考了哪些 LinuxCNC 源文件/配置/图片、属于什么边界、如何验证。
+
+追溯原则：
+
+```text
+界面形态可参考 LinuxCNC Python GUI；
+CNC 语义必须来自 LinuxCNC source/WASM/source-derived boundary；
+浏览器代码只负责 UI、状态编排、文件会话、可视化和调用边界；
+任何 fixture 或 UI-only 结果不得冒充 LinuxCNC runtime proof。
+```
+
+## 2. 总体追溯表
+
+| 功能 | Web 实现位置 | LinuxCNC 参考 | 边界分类 | 验证方式 |
+| --- | --- | --- | --- | --- |
+| gmoccapy 风格 shell | `app/src/ui/gmoccapy-shell.ts` | `docs/src/gui/images/gmoccapy_5_axis.png`, `configs/sim/gmoccapy/gmoccapy_XYZAC.ini` | UI reference | browser shell smoke |
+| 大号 DRO | `app/src/ui/gmoccapy-dro-panel.ts` | gmoccapy 5 axis screenshot, LinuxCNC DRO conventions | UI rendering of runtime state | DOM smoke + state smoke |
+| 右侧模式按钮栏 | `app/src/ui/gmoccapy-status-sidebar.ts` | gmoccapy screenshot | UI action dispatch | browser button/action smoke |
+| 底部运行控制 | `app/src/ui/gmoccapy-bottom-controls.ts` | gmoccapy/AXIS run controls | UI action dispatch | playback smoke |
+| G-code 当前行 | `app/src/ui/gmoccapy-gcode-panel.ts` | AXIS/gmoccapy program display | LinuxCNC output rendering | active-line smoke |
+| 上电/急停/复位/模式操作 | `app/src/state/store.js`, `app/src/ui/gmoccapy-shell.js` | gmoccapy/AXIS operator workflow | browser UI runtime fixture | node smoke + browser operator smoke |
+| JOG/MDI 操作 | `app/src/state/store.js`, `app/src/ui/gmoccapy-shell.js` | AXIS Manual/MDI workflow | browser UI runtime fixture | node smoke + browser operator smoke |
+| G-code 文件加载 | `app/src/ui/gmoccapy-shell.js`, `app/src/state/store.js` | AXIS/gmoccapy open program workflow | file text staging only, not LinuxCNC interpreter proof | node smoke + browser operator smoke |
+| 程序执行当前行显示 | `app/src/state/store.js`, `app/src/ui/gmoccapy-shell.js` | AXIS/gmoccapy current line display | fixture line playback until LinuxCNC interpreter is connected | node smoke + browser operator smoke |
+| 刀具预览 | `app/src/ui/gmoccapy-shell.js`, `app/src/visualization/five-axis-scene.js` | gmoccapy/vismach tool display | visualization/runtime state display | browser operator smoke |
+| 3D 五轴预览 | `app/src/visualization/five-axis-scene.js` | `qtvismach_5axis_gantry.png`, `lib/python/vismach.py` | visualization | canvas nonblank smoke |
+| Vismach transform tree | `app/src/visualization/machine-model.ts` | `lib/python/vismach.py`, `src/hal/user_comps/vismach/*.py` | visualization from GUI reference | scene graph smoke |
+| `xyzac-trt` profile | `app/src/profiles/xyzac-trt.js` | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini` | source/config reference | profile boundary node smoke |
+| `xyzac-trt` source reference map | `app/src/profiles/source-reference-map.js` | `xyzac-trt.ini`, `xyzac-trt.xml`, `switchkins_postgui.hal`, `xyzac-trt_cmds.hal`, `xyzac-trt-kins.c`, `trtfuncs.c`, `switchkins.c` | profile/source map only, not runtime proof | profile boundary node smoke |
+| `xyzbc-trt` profile | `app/src/profiles/xyzbc-trt.ts` | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini` | source/config reference | profile node smoke |
+| SWITCHKINS panel | `app/src/panel-schema/xyzac-trt-pyvcp.js` | `xyzac-trt.xml`, `switchkins_postgui.hal` | UI/HAL binding reference | profile boundary node smoke + browser DOM smoke |
+| M428/M429/M430 state | `app/src/profiles/xyzac-trt.js`, `app/src/panel-schema/xyzac-trt-pyvcp.js` | `remap_subs/428remap.ngc`, `429remap.ngc`, `430remap.ngc` | LinuxCNC remap/source reference only until runtime adapter is connected | profile boundary node smoke |
+| LinuxCNC boundary adapter | `app/src/runtime/linuxcnc-boundary-adapter.js` | LinuxCNC interpreter/kinematics WASM future adapter point | adapter entrypoint only, runtime not connected | profile boundary node smoke + browser DOM smoke |
+| Five-axis kinematics | `core/linuxcnc_kinematics_wasm` | `trtfuncs.c`, `xyzac-trt-kins.c`, `xyzbc-trt-kins.c`, `5axiskins.c` | LinuxCNC source-derived WASM | Node roundtrip smoke |
+| RTCP/TCP frame | `app/src/runtime/rtcp-frame.js` | LinuxCNC kinematics output + canonical events | fixture frame plumbing until kinematics WASM is ready | RTCP/store node smoke + browser DOM smoke |
+| OPFS session | `app/src/runtime/session-*` | current `wasm-port/runtime/opfs` | host-side persistence | save/restore smoke |
+
+## 3. 源文件追溯清单
+
+### UI 图片
+
+```text
+linuxcnc/docs/src/gui/images/gmoccapy_5_axis.png
+linuxcnc/docs/src/gui/images/qtvismach_5axis_gantry.png
+linuxcnc/docs/src/gui/images/axis.png
+linuxcnc/docs/src/gui/images/axis-pyvcp.png
+linuxcnc/docs/src/gui/images/qtdragon.png
+linuxcnc/docs/src/gui/images/qtdragon_hd.png
+```
+
+本项目副本：
+
+```text
+assets/reference/linuxcnc-gui/
+```
+
+### Python GUI
+
+```text
+src/emc/usr_intf/axis/scripts/axis.py
+lib/python/vismach.py
+src/hal/user_comps/vismach/5axisgui.py
+src/hal/user_comps/vismach/xyzac-trt-gui.py
+src/hal/user_comps/vismach/xyzbc-trt-gui.py
+configs/sim/gmoccapy/gmoccapy_XYZAC.ini
+configs/sim/qtvcp_screens/qtdragon/README
+```
+
+使用方式：
+
+```text
+UI/visualization reference only
+```
+
+### 5 轴配置
+
+```text
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
+configs/sim/axis/vismach/5axis/bridgemill/5axis.ini
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.ini
+```
+
+### PyVCP/HAL
+
+```text
+configs/sim/axis/vismach/5axis/bridgemill/5axis.xml
+configs/sim/axis/vismach/5axis/bridgemill/5axis_postgui.hal
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr-postgui.hal
+```
+
+### 5 轴运动学源码
+
+```text
+src/emc/kinematics/trtfuncs.c
+src/emc/kinematics/xyzac-trt-kins.c
+src/emc/kinematics/xyzbc-trt-kins.c
+src/emc/kinematics/5axiskins.c
+src/emc/kinematics/switchkins.c
+src/emc/kinematics/switchkins.h
+src/emc/kinematics/userkfuncs.c
+src/emc/kinematics/kins_util.c
+```
+
+## 4. 边界状态
+
+| 边界 | 当前状态 | 说明 |
+| --- | --- | --- |
+| gmoccapy UI style | ready | 可直接 Web 化 |
+| Three.js preview | implemented_basic_canvas_scene | 已显示基础五轴机床、刀具/TCP marker、刀轴、刀路，并消费 `rtcpFrame` |
+| LinuxCNC interpreter WASM | existing_project_capability | 可参考 `wasm-port` 现有 SDK |
+| LinuxCNC 5-axis kinematics WASM | node_proof_ready | `createLinuxCncKinematicsSdk({ moduleId: "xyzac-trt" })` 已由 web adapter 加载，Node smoke 验证 forward/inverse frame |
+| RTCP frame UI plumbing | implemented_fixture_and_kinematics_wasm | fixture fallback 仍为 `linuxCncKinematicsReady=false`；Node kinematics proof 为 `source-derived-kinematics-wasm` / `linuxcnc_kinematics_wasm_c_abi` |
+| Operator workflow | implemented_fixture_only | 上电/急停/复位/模式/JOG/MDI/G-code 加载/当前行显示已闭环；执行仍是 fixture line playback |
+| LinuxCNC boundary adapter | kinematics_runtime_connected_node | `web-rtcp-5axis-linuxcnc-boundary-adapter` 可区分 kinematics-only ready 与 interpreter/remap missing |
+| PyVCP/HAL panel schema | implemented_reference_only | `xyzac-trt-switchkins-pyvcp` 已整理 SWITCHKINS 控件与 HAL nets；不执行 native HAL |
+| Python GUI runtime | not_ported | 只参考，不运行 |
+| Python remap runtime | blocked | 不在第一版实现 |
+| tool DB runtime | blocked | 不在第一版实现 |
+| external user-M process | blocked | 不在第一版实现 |
+| native hard realtime | out_of_scope | Web 仿真不实现 |
+
+## 5. 每批开发追溯记录模板
+
+后续每批完成后追加：
+
+```text
+Batch:
+Date:
+Files changed:
+Feature:
+LinuxCNC references:
+Boundary:
+Tests:
+Result:
+Remaining risk:
+Next:
+```
+
+## 6. 首批追溯记录
+
+```text
+Batch: M0-docs-preparation
+Date: 2026-06-20 CST
+Files changed:
+  README.md
+  docs/implementation-plan.md
+  docs/technical-roadmap.md
+  docs/program-implementation-guide.md
+  docs/development-continuation.md
+  docs/traceability-matrix.md
+  docs/linuxcnc-python-gui-reference.md
+  docs/linuxcnc-gui-reference-gallery.md
+Feature:
+  完成 5 轴数控系统 Web 仿真程序开发前准备文档。
+LinuxCNC references:
+  gmoccapy_5_axis.png
+  qtvismach_5axis_gantry.png
+  axis.py
+  vismach.py
+  xyzac-trt.ini
+  xyzbc-trt.ini
+  trtfuncs.c
+  5axiskins.c
+Boundary:
+  docs_only
+Tests:
+  git diff --check -- web-rtcp-5axis-sim-plan
+Result:
+  ready_for_M1_web_shell_gmoccapy
+Remaining risk:
+  尚未实现 app 代码；LinuxCNC kinematics WASM ABI 尚未建立。
+Next:
+  M1-web-shell-gmoccapy
+```
+
+## 7. M1 追溯记录
+
+```text
+Batch: M1-web-shell-gmoccapy
+Date: 2026-06-20 CST
+Files changed:
+  .gitignore
+  app/index.html
+  app/package.json
+  app/tsconfig.json
+  app/scripts/build-static.mjs
+  app/src/main.js
+  app/src/state/store.js
+  app/src/ui/gmoccapy-shell.js
+  app/src/styles/gmoccapy.css
+  tests/browser/gmoccapy_shell_smoke.html
+  tests/browser/verify_gmoccapy_shell_browser.sh
+Feature:
+  实现 gmoccapy 5 轴风格 Web shell，并补齐 M1 build gate。
+LinuxCNC references:
+  docs/src/gui/images/gmoccapy_5_axis.png
+  docs/src/gui/images/qtvismach_5axis_gantry.png
+  configs/sim/gmoccapy/gmoccapy_XYZAC.ini
+Boundary:
+  ui_reference_only
+  sourceMode=fixture-ui-only
+Tests:
+  npm --prefix web-rtcp-5axis-sim-plan/app run build
+  web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
+  git diff --check -- web-rtcp-5axis-sim-plan
+Result:
+  gmoccapy_static_build=ok
+  gmoccapy_shell_smoke=ok
+Remaining risk:
+  M1 shell/build gate 已闭环；Three.js 真实场景、LinuxCNC interpreter/WASM、5 轴 kinematics ABI 仍未接入。
+Next:
+  M2-state-and-controls
+```
+
+## 8. M2 追溯记录
+
+```text
+Batch: M2-state-and-controls
+Date: 2026-06-20 CST
+Files changed:
+  app/package.json
+  app/src/profiles/xyzac-trt.js
+  app/src/runtime/rtcp-frame.js
+  app/src/state/store.js
+  app/src/ui/gmoccapy-shell.js
+  app/src/styles/gmoccapy.css
+  tests/node/verify_rtcp_store.mjs
+  tests/browser/gmoccapy_shell_smoke.html
+  docs/development-continuation.md
+  docs/traceability-matrix.md
+Feature:
+  实现 gmoccapy store/control 链路，并加入 RTCP fixture frame plumbing。
+  Run/Step 会推进 fixture motion frame；TCP/IDENTITY 会切换 RTCP on/off；
+  DRO、preview badge 和 info diagnostics 显示 TCP pose、tool axis vector、frame readiness。
+  Preview view/Fit/Clear、Rapid/Feed override、Spindle override、Flood/Mist、
+  Reload/Home/Full 已接入 store action，并由 node/browser smoke 覆盖。
+LinuxCNC references:
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
+  src/emc/kinematics/xyzac-trt-kins.c
+  src/emc/kinematics/trtfuncs.c
+Boundary:
+  sourceMode=fixture-ui-only
+  semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof
+  linuxCncKinematicsReady=false
+  promotionAllowed=false
+Tests:
+  npm --prefix web-rtcp-5axis-sim-plan/app run build
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
+Result:
+  gmoccapy_static_build=ok
+  rtcp_store_smoke=ok
+  gmoccapy_shell_smoke=ok
+Remaining risk:
+  RTCP 当前是 UI/runtime frame plumbing，不是 LinuxCNC/source-derived kinematics WASM proof；
+  Three.js 仍是 SVG placeholder，M3 需要接入真实 canvas scene 并消费 rtcpFrame。
+Next:
+  M3-threejs-preview
+```
+
+## 9. M3 追溯记录
+
+```text
+Batch: M3-threejs-preview
+Date: 2026-06-21 CST
+Files changed:
+  app/src/vendor/three/three.module.js
+  app/src/vendor/three/three.core.js
+  app/src/visualization/five-axis-scene.js
+  app/src/ui/gmoccapy-shell.js
+  tests/browser/gmoccapy_shell_smoke.html
+  docs/development-continuation.md
+  docs/traceability-matrix.md
+Feature:
+  将 preview 区域从占位内容升级为 Three.js WebGL canvas。
+  场景显示基础五轴工作区、工作台、刀具/TCP marker、刀轴和刀路；
+  tool marker 消费 store 的 tcpPose，刀轴消费 toolAxisVector，RTCP on/off 影响可见刀轴长度和姿态数据。
+LinuxCNC references:
+  docs/src/gui/images/qtvismach_5axis_gantry.png
+  lib/python/vismach.py
+  src/hal/user_comps/vismach/xyzac-trt-gui.py
+Boundary:
+  visualization_only
+  sourceMode=fixture-ui-only
+  semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof
+Tests:
+  npm --prefix web-rtcp-5axis-sim-plan/app run build
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
+Result:
+  gmoccapy_static_build=ok
+  rtcp_store_smoke=ok
+  gmoccapy_shell_smoke=ok
+Remaining risk:
+  Three.js 当前消费 fixture frame；五轴运动学仍未接入 LinuxCNC/source-derived WASM。
+Next:
+  M4-profile-and-linuxcnc-boundary
+```
+
+## 10. M4 追溯记录
+
+```text
+Batch: M4-profile-and-linuxcnc-boundary
+Date: 2026-06-21 CST
+Files changed:
+  app/package.json
+  app/src/profiles/xyzac-trt.js
+  app/src/profiles/source-reference-map.js
+  app/src/panel-schema/xyzac-trt-pyvcp.js
+  app/src/runtime/linuxcnc-boundary-adapter.js
+  app/src/state/store.js
+  app/src/ui/gmoccapy-shell.js
+  tests/node/verify_rtcp_store.mjs
+  tests/node/verify_profile_boundary.mjs
+  tests/browser/gmoccapy_shell_smoke.html
+  docs/development-continuation.md
+  docs/program-implementation-guide.md
+  docs/traceability-matrix.md
+Feature:
+  建立 `xyzac-trt` profile/source reference map、PyVCP/HAL SWITCHKINS panel schema
+  和 LinuxCNC boundary adapter 接入点。store/UI 暴露 boundary readiness，
+  并明确保持 `linuxCncKinematicsReady=false`、`promotionAllowed=false`。
+  本批后续已进一步按 LinuxCNC `xyzac-trt.ini`、`xyzac-trt_cmds.hal`、
+  `switchkins_postgui.hal`、`xyzac-trt.tbl`、`428/429/430remap.ngc` 显式整理
+  DISPLAY/RS274NGC/TRAJ、axis/joint limits、HALCMD feedback/offset nets、
+  HALUI MDI commands、tool table 和 remap IO 约束，使 M4 在 source-aligned
+  profile/schema/adapter 层面完整闭环。
+LinuxCNC references:
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt_cmds.hal
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/428remap.ngc
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/429remap.ngc
+  configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/430remap.ngc
+  src/emc/kinematics/xyzac-trt-kins.c
+  src/emc/kinematics/trtfuncs.c
+  src/emc/kinematics/switchkins.c
+Boundary:
+  sourceMapBoundary=profile_source_map_only_not_runtime_proof
+  panelSchemaBoundary=pyvcp_hal_schema_reference_only
+  adapterBoundary=adapter_entrypoint_only_runtime_not_connected
+  linuxCncKinematicsReady=false
+  promotionAllowed=false
+Tests:
+  npm --prefix web-rtcp-5axis-sim-plan/app run build
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
+Result:
+  gmoccapy_static_build=ok
+  rtcp_store_smoke=ok
+  profile_boundary_smoke=ok
+  gmoccapy_shell_smoke=ok
+Remaining risk:
+  Adapter 目前只是接入点；尚未连接 LinuxCNC interpreter/kinematics WASM ABI。
+Next:
+  linuxcnc_kinematics_wasm_abi
+```
+
+## 11. M5 追溯记录
+
+```text
+Batch: M5-operator-program-workflow
+Date: 2026-06-21 CST
+Files changed:
+  app/src/state/store.js
+  app/src/ui/gmoccapy-shell.js
+  app/src/styles/gmoccapy.css
+  tests/node/verify_rtcp_store.mjs
+  tests/browser/gmoccapy_shell_smoke.html
+  docs/development-continuation.md
+  docs/traceability-matrix.md
+Feature:
+  补齐 operator workflow：上电、急停、AUTO/MANUAL/JOG/MDI、复位、
+  本地 G-code 文件加载、刀具预览、程序执行当前行显示和高亮。
+LinuxCNC references:
+  gmoccapy operator workflow
+  AXIS program loading/current-line workflow
+  vismach tool preview conventions
+Boundary:
+  operatorWorkflowBoundary=browser_ui_runtime_fixture
+  gcodeLoadBoundary=file_text_staging_only
+  programExecutionBoundary=fixture_line_playback_not_linuxcnc_interpreter
+  linuxCncKinematicsReady=false
+  promotionAllowed=false
+Tests:
+  npm --prefix web-rtcp-5axis-sim-plan/app run build
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
+Result:
+  gmoccapy_static_build=ok
+  rtcp_store_smoke=ok
+  profile_boundary_smoke=ok
+  gmoccapy_shell_smoke=ok
+Remaining risk:
+  程序执行仍是 fixture line playback；下一步必须接 LinuxCNC interpreter/WASM 或
+  source-derived kinematics WASM，才能把执行来源升级为 LinuxCNC-owned。
+Next:
+  linuxcnc_interpreter_or_kinematics_wasm_execution_source
+```
+
+## 12. M6 追溯记录
+
+```text
+Batch: M6-linuxcnc-kinematics-frame-proof
+Date: 2026-06-21 CST
+Files changed:
+  app/package.json
+  app/src/runtime/linuxcnc-kinematics-runtime.js
+  app/src/runtime/linuxcnc-boundary-adapter.js
+  app/src/runtime/rtcp-frame.js
+  app/src/state/store.js
+  tests/node/verify_linuxcnc_kinematics_runtime.mjs
+  tests/node/verify_rtcp_store.mjs
+  tests/node/verify_profile_boundary.mjs
+  docs/program-implementation-guide.md
+  docs/development-continuation.md
+  docs/traceability-matrix.md
+Feature:
+  将 RTCP frame/boundary adapter 从 fixture-only 接到
+  createLinuxCncKinematicsSdk({ moduleId: "xyzac-trt" })。
+  新增 web runtime adapter，只加载共享 wasm-port SDK 并返回 LinuxCNC
+  forward/inverse 结果；frame builder 使用 forward.pose 和 inverse.joints
+  生成 source-derived kinematics frame。
+LinuxCNC references:
+  wasm-port/runtime/sdk/src/linuxcnc-kinematics.js
+  wasm-port/build/wasm/kinematics/linuxcnc_xyzac_trt_kinematics.wasm
+  src/emc/kinematics/xyzac-trt-kins.c
+  src/emc/kinematics/trtfuncs.c
+  src/emc/kinematics/switchkins.c
+Boundary:
+  sourceMode=source-derived-kinematics-wasm
+  semanticBoundary=linuxcnc_kinematics_wasm_c_abi
+  linuxCncKinematicsReady=true
+  kinematicsFramePromotionAllowed=true
+  fullLinuxCncProgramExecutionReady=false
+  browserFallback=fixture-ui-only
+Tests:
+  npm --prefix web-rtcp-5axis-sim-plan/app run build
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
+  npm --prefix web-rtcp-5axis-sim-plan/app run smoke
+Result:
+  gmoccapy_static_build=ok
+  linuxcnc_kinematics_runtime_smoke=ok
+  rtcp_store_smoke=ok
+  profile_boundary_smoke=ok
+  gmoccapy_shell_smoke=ok
+Remaining risk:
+  Browser path still runs fixture fallback because kinematics WASM asset copy/worker
+  is not wired into app/src/main.js. Program RUN/STEP still advances fixture lines;
+  LinuxCNC interpreter/remap/planner execution is not promoted.
+Next:
+  browser_kinematics_wasm_asset_worker_or_interpreter_execution_source
+```