Fix web homing motion and synchronize preview state

docs/linuxcnc-axis-web-control-panel-source-logic.md

@@ -155,7 +155,7 @@ families because their cardinality comes from the selected INI.
 | Optional Stop and Block Delete | `toggle_optional_stop`, `toggle_block_delete` | Visible `SOURCE_BLOCKED`; block delete's source wait, MANUAL switch and preview reload must not be approximated by a local checkbox |
 | MDI history clear/copy/paste/select/double-click/Up/Down | `clear_mdi_history`, `mdi_history_hist2clip`, `mdi_history_clip2hist`, `mdi_history_butt_1`, `mdi_history_double_butt_1`, `mdi_up_cmd`, `mdi_down_cmd` | Select/Up/Down/local history: `SOURCE_ADAPTER`; clipboard/file persistence variants are browser/host boundaries |
 | Calibration, HAL Configuration, HAL Meter, HAL Scope, LinuxCNC Status, Debug Level | external `exec` commands in Machine menu | Desktop-process boundary; not rendered and never mapped to Diagnostics as though it were the same action |
-| Home all/joint and Unhome all/joint | `home_all_joints`, `home_joint_number`, `unhome_all_joints`, `unhome_joint_number` | Home all: `SOURCE_ADAPTER`; world-axis Home rejects for KINEMATICS_BOTH; individual joint selection and Unhome remain `SOURCE_BLOCKED` |
+| Home all/joint and Unhome all/joint | `home_all_joints`, `home_joint_number`, `unhome_all_joints`, `unhome_joint_number` | Home all: `SOURCE_ADAPTER`; Web Home Axis maps the fixed XYZAC axis selection to a numeric joint and retains the source KINEMATICS_BOTH restriction; individual joint selection and Unhome remain `SOURCE_BLOCKED` |
 | Zero P1..P9 and G92 coordinate systems | `clear_offset` | `SOURCE_BLOCKED`; Touch Off is not an alias for clearing a coordinate system |
 | Tool touch-off target workpiece/fixture | `toggle_tto_g11` selecting `G10 L10`/`G10 L11` | `SOURCE_BLOCKED` with Tool Touch Off; no local target state is exposed |
 | Top/Z2/Side/Front/Y2/Perspective, zoom and rotate | `set_view_*`, `zoomin`, `zoomout`, rotate Tcl command | `SOURCE_ADAPTER`; Y2 is toolbar-only in the native layout |
@@ -165,7 +165,7 @@ families because their cardinality comes from the selected INI.
 | Clear Live Plot | `clear_live_plot` -> `LivePlotter.clear` -> `positionlogger.clear` | `SOURCE_ADAPTER`; this is the only native live-trace deletion action |
 | Axis/joint selection and jog increment | `ja_rbutton`, `jogincrement`, `activate_ja_widget` | XYZAC axis and increment selection: `SOURCE_ADAPTER`; native joint selection is `SOURCE_BLOCKED` |
 | Jog negative/positive and key jog | `jog_minus`, `jog_plus`, `jog_on`, `jog_off` | `SOURCE_ADAPTER`; press/release semantics and Manual-tab guard apply |
-| Home Axis, Touch Off, Tool Touch Off, Override Limits | corresponding `zerohome`/`override` widgets | World-axis Home reproduces source rejection for KINEMATICS_BOTH; Touch Off: selected-coordinate adapter; Tool Touch Off/Override Limits: visible `SOURCE_BLOCKED` |
+| Home Axis, Touch Off, Tool Touch Off, Override Limits | corresponding `zerohome`/`override` widgets | Home Axis: fixed XYZAC axis-to-joint `SOURCE_ADAPTER` with source mode transaction; Touch Off: selected-coordinate adapter; Tool Touch Off/Override Limits: visible `SOURCE_BLOCKED` |
 | Spindle CCW/Stop/CW, slower/faster, brake | `spindle`, `spindle_decrease`, `spindle_increase`, `spindle_constant`, `brake` | `SOURCE_ADAPTER`; button-state formulas and press/release ordering apply |
 | Mist and Flood | `mist`, `flood`, `mist_toggle`, `flood_toggle` | `SOURCE_ADAPTER`; independent canonical IO bits |
 | MDI entry, Go, Enter, history activation | `send_mdi`, `send_mdi_command` | `SOURCE_ADAPTER`; source trim, mode and adjacent-history de-duplication apply |
@@ -184,7 +184,7 @@ command are blocked instead of being silently mapped to another operation.
 | --- | --- | --- |
 | `F1`, `F2`, lowercase `o`, `r`, `t`, `p`, `s`, `Escape`, `Ctrl-r`, `F7`-`F12` | E-stop, power, open, run, step, pause, resume, stop, reload, coolant and spindle handlers | Worker-backed commands where the corresponding control is supported. Display labels remain `O/R/T/P/S`. |
 | uppercase `R`, `F` | `task_reverse`, `task_forward` | Source controls are recorded as blocked because the selected WASM program ABI has no reverse/forward command; they are never mapped to Run. |
-| `Home`, `Ctrl-Home`, `Shift-Home`, `End`, `Ctrl-End` | selected joint home, home all, zero selected G54 axis, system touch off, tool touch off | Home and system Touch Off have adapters; zero-G54 and Tool Touch Off are blocked. |
+| `Home`, `Ctrl-Home`, `Shift-Home`, `End`, `Ctrl-End` | selected joint home, home all, zero selected G54 axis, system touch off, tool touch off | Home uses the fixed XYZAC axis-to-joint adapter (and Home All uses the all-joint transaction); system Touch Off has an adapter; zero-G54 and Tool Touch Off are blocked. |
 | lowercase `x`, `y`, `z`, `a` | Select the first four source axes | Axis selection adapter. Native AXIS does **not** bind lowercase `c` to C-axis selection; `c` selects continuous jog. C remains selectable only through its radio control. |
 | `-`, `=`, arrows/Page keys/`[`/`]` and their Shift variants | `jog_on_map`/`jog_off_map` or selected-axis `jog_minus`/`jog_plus` | Jog key semantics require keydown start and keyup stop. Pointer controls are supported; unavailable key bindings are not reassigned. |
 | lowercase `c`, lowercase `i`, uppercase `I` | Continuous, next incremental and previous incremental jog modes | Represented by the jog increment selector; no second machine-mode state is created. |
@@ -221,9 +221,13 @@ command are blocked instead of being silently mapped to another operation.
    与原生 NML 指令细分仍是需单独验证的适配边界，不能用行数相同替代运动断言。
 5. **回零类型不能混同。** `switchkins.c::kinematicsType()` 始终返回
    `KINEMATICS_BOTH`；M429 的 `active_type=0` 不代表 KINEMATICS_IDENTITY。
-   `home_joint` 对世界坐标字母会拒绝，而数字 joint 允许回零。
-   当前面板的轴字母按钮不能冒充 joint 模式；Home Axis 保留原 UI 公式，
-   点击返回 `home_joint_requires_joint_mode`。Home All 仍可用。
+   原生 `home_joint` 在这种配置下只接受数字 joint；直接把世界坐标字母传给
+   `home_joint` 会被源码拒绝。固定的 XYZAC TRT Web 面板没有原生 joint
+   单选组，因此 `Home Axis` 使用明确记录的 Web 适配：
+   `X/Y/Z/A/C -> joint 0/1/2/3/4`，Worker 只把这个映射后的数字 joint
+   交给 WASM home-limit authority，并在结果中回显 `source_axis`、
+   `joint` 和 `motion_mode`。它不是把 `KINEMATICS_BOTH` 冒充成
+   `KINEMATICS_IDENTITY`，也不是用坐标轴字母绕过 joint 约束。
 6. **自动恢复标签模式。** `axis.tcl::update_state` 在 ON+IDLE 的状态边沿，
    当前 task_mode 为 AUTO 时调用 `set_mode_from_tab`；显式 Open/Reload 完成后
    也调用它。Web 必须通过排队的 `SET_MODE` 恢复所选 Manual/MDI 页，不能只
@@ -250,7 +254,7 @@ command are blocked instead of being silently mapped to another operation.
 | 功能 | 原生行为 / 当前边界 | 禁止的错误结论 |
 | --- | --- | --- |
 | Run 警告 | `run_warn` 对 XYZ 预览边界给出确认；当前 WASM 没有完整含刀偏 extents 警告事务 | 不得声称已复制 run_warn 的确认/取消交互 |
-| Joint/World、Home Axis | KINEMATICS_BOTH 需要 joint 数字选择与 FREE/TELEOP 状态；当前世界轴面板只支持 Home All | 不得用 switchkins 编号判断是否允许坐标轴回零 |
+| Joint/World、Home Axis | KINEMATICS_BOTH 需要 joint 数字选择与 FREE/TELEOP 状态；固定 XYZAC Web 面板以 X/Y/Z/A/C 的明确一对一映射提供 Home Axis 适配，执行时仍切入 FREE/joint 并由 WASM 返回数字 joint 结果 | 不得用 switchkins 编号判断 kinematics 类型，不得把世界轴字母直接交给 `home_joint`，不得把本地坐标归零冒充 joint home |
 | 速度滑块 | 原生线性/角速度独立，显示物理单位；当前 Jog/Max 的百分比与 6% 下限属于已公开的 Web 适配 | 不得把单一比例视为独立 angular jog 控制 |
 | 预览图层 | limits 现从 WASM XYZ 软限位 getter 读取；offsets 使用已实现的 G5x 平移；extents 使用 canonical 采样包围框 | G92/旋转/刀具偏置范围与原生文字标注仍未全量覆盖，不能称完整原生图层复刻 |
 | commanded/actual | 仿真当前两者相同，需要分别存在的 canonical 字段才可声明跟随误差显示 | 不得从 React 标签推导真实反馈差异 |
@@ -352,8 +356,8 @@ safety adaptation, not attributed to AXIS.
 | Manual / MDI tabs | `SET_MODE` | `SOURCE_ADAPTER`: native tab callbacks are `ensure_manual` and `ensure_mdi`, including `set_motion_teleop` transitions. `axis.tcl::update_state` calls `set_mode_from_tab` only when returning to ON+IDLE from a non-idle/task-state transition while task mode is AUTO. No unrelated React effect may force a mode. |
 | Joint/World (teleop) mode | not exposed | AXIS View menu calls `set_teleop_mode`/`c.teleop_enable`; the selected WASM motion ABI has no canonical teleop setter, so Web does not pretend its coordinate mode is a joint/world toggle. |
 | Jog `-` / `+` | `JOG_START`, `SIM_STEP`, `JOG_STOP` | `SOURCE_ADAPTER`: source requires `manual_ok` and the visible Manual tab. Incremental sends one `JOG_INCREMENT`; Continuous sends one `JOG_CONTINUOUS` and motion continues until the deferred release issues `JOG_STOP`. Web servo sampling is transport/runtime work, not repeated user jog commands. |
-| Home Axis | `HOME {axis}` | `manual_ok`, then `home_joint` checks axis versus joint selection. The selected switchkins module is always KINEMATICS_BOTH, so a world-axis letter is rejected with `home_joint_requires_joint_mode`; M429 does not change this type. |
-| Home All / Re-home All | `HOME {all:true}` | `SOURCE_ADAPTER`: `manual_ok`, ensure MANUAL, if `all_homed()` ask the native re-home confirmation, then `set_motion_teleop(0)`, `c.home(-1)`, wait. Native text remains Home All; the Web `RE-HOME ALL` label is presentation-only and cannot trigger a hidden home during load. |
+| Home Axis | `HOME {axis,joint}` | `SOURCE_ADAPTER`: UI uses the fixed map `x/y/z/a/c -> 0/1/2/3/4`; Worker validates the pair, applies the source `manual_ok` gate, enters MANUAL, switches to FREE/joint for the `c.home(joint)` equivalent, waits for the WASM home-limit result, then publishes the canonical joint mask. An unmapped axis, mismatched joint or invalid numeric joint is rejected before any mode/home mutation. |
+| Home All / Re-home All | `HOME {all:true}` | `SOURCE_ADAPTER`: `manual_ok`, ensure MANUAL, if `all_homed()` ask the native re-home confirmation, then switch to FREE/joint, call the WASM equivalent of `c.home(-1)`, wait, and publish all five homed bits. The fixed Web axis adapter restores its prior world-axis presentation mode after the completed transaction; the source mode used for homing is still recorded. Native text remains Home All; the Web `RE-HOME ALL` label is presentation-only and cannot trigger a hidden home during load. |
 | Touch Off | `TOUCH_OFF {axis,value,system,units}` | `SOURCE_ADAPTER`: source UI condition is the Touch Off formula above; task-layer MDI additionally enforces homing unless `NO_FORCE_HOMING`. Prompt for `P0 Current` through `P9 G59.3`, save mode, ensure MDI, scale linear units, issue `G10 L20 <P-token> <axis>[value*scale]`, wait, redraw/reload, restore saved mode and TELEOP. |
 | Tool Touch Off | `TOOL_TOUCH_OFF {axis,value,system,units}` | LinuxCNC source requires `G10 L10/L11` plus `G43`, but the selected WASM interpreter does not expose canonical tool-offset storage. The control is therefore disabled with `blocked_by_abi_tool_offsets`; it never sends a fake fixed `G43`. |
 | Override limits | disabled | `SOURCE_BLOCKED`: widget enable requires `on_any_limit`; handler separately requires interpreter IDLE. If already overridden it ensures AUTO; otherwise it ensures MANUAL and calls `c.override_limits()`. The selected WASM ABI cannot represent this canonical path. |
@@ -400,15 +404,15 @@ history rows intentionally share the family ID `mdi-history-select`.
 | `toolbar-clear-live-plot` | `clear_live_plot` -> `positionlogger.clear()` | Worker `VISUAL_CLEAR`; always visual-only | Advances `live_path_epoch`, clears Live Plot only and retains static preview |
 | `workspace-case-select` | Web selection of the INI/configuration input | Local selection; selected catalog is restricted to supported XYZAC case | Does not load or change machine state until `toolbar-load-case` |
 | `workspace-load-3d-chips` | Web packaged-file equivalent of `open_file_guts` | Fetch published `3D_Chips.ngc`, then `PROGRAM_LOAD`; IDLE only | Same replacement path as Open; retains Live Plot, no automatic Run/Home |
-| `manual-home-all` | Machine Homing menu -> `home_all_joints` | `HOME {all:true}`; `manual_ok`, then MANUAL | Repeat asks source confirmation; Web Re-home label is non-authoritative presentation only |
+| `manual-home-all` | Machine Homing menu -> `home_all_joints` | `HOME {all:true}`; `manual_ok`, MANUAL, FREE/joint home, wait, canonical snapshot | Repeat asks source confirmation; Web Re-home label is non-authoritative presentation only; response records the mode phase and five-joint homed mask |
 | `switchkins-0`, `switchkins-1`, `switchkins-2` | `M429`, `M428`, `M430` remaps and `motion.switchkins-type` | `KINEMATICS_SELECT`; ON, homed, IDLE, empty TP | Identity/XYZAC/User K canonical type, or stable gate reason |
-| `tab-manual`, `tab-mdi` | AXIS notebook F3/F5 `ensure_manual`/`ensure_mdi` | `SET_MODE` adapter under `manual_ok` | Acknowledged MANUAL/MDI task mode. Explicit FREE/TELEOP/joint switching is an unimplemented ABI boundary; the selected panel uses its homed world-axis motion adapter. |
+| `tab-manual`, `tab-mdi` | AXIS notebook F3/F5 `ensure_manual`/`ensure_mdi` | `SET_MODE` adapter under `manual_ok` | Acknowledged MANUAL/MDI task mode. The Web does not expose a separate Joint/World toggle; Home transactions use an internal FREE/joint phase and restore the selected fixed XYZAC world-axis presentation mode after completion. |
 | `tab-diagnostics` | Web diagnostics boundary | Local tab only | Reads Worker state/gates; sends no command |
 | `tab-preview`, `tab-dro` | AXIS preview/DRO presentation | Local tab only | Changes visible projection; machine state unchanged |
 | `manual-axis-x`, `manual-axis-y`, `manual-axis-z`, `manual-axis-a`, `manual-axis-c` | AXIS axis radio group / `ja_rbutton` | Local axis selection; source manualgroup ON+IDLE | Supplies the selected axis to Jog/Home/Touch Off; sends no motion by itself |
 | `manual-jog-increment` | `jogincrement` combobox | Local choice: Continuous or configured increment | Determines `JOG_CONTINUOUS` versus `JOG_INCREMENT` payload only |
 | `manual-jog-negative`, `manual-jog-positive` | `jogminus`, `jogplus` -> `jog_on` | `JOG_START`; visible Manual tab and `manual_ok`; source chooses joint/teleop mode from kinematics+homing | Incremental submits once; Continuous remains active until one release/cancel `JOG_STOP` |
-| `manual-home-axis` | `home_joint` | UI ON+IDLE; `HOME {axis}` checks KINEMATICS_BOTH | World-axis letter rejected before confirmation/mode mutation; individual numeric joint input remains unavailable |
+| `manual-home-axis` | `home_joint` | UI ON+IDLE; `HOME {axis,joint}` validates the fixed XYZAC mapping, then follows the source MANUAL -> FREE/joint -> home transaction | Selected axis is homed through its mapped numeric joint; already-homed joint asks for explicit re-home confirmation; invalid mapping is rejected without mode/home mutation |
 | `manual-touch-off` | `touch_off_system` | `TOUCH_OFF`; exact Touch Off UI formula, `manual_ok`, valid axis/value/system, plus task-layer homing policy | MDI `G10 L20`, wait, reload and restore saved task/motion mode |
 | `manual-tool-touch-off` | `touch_off_tool` | Permanently disabled for selected ABI | `blocked_by_abi_tool_offsets`; never approximated with `G92`/fixed `G43` |
 | `manual-override-limits` | `toggle_override_limits` | Permanently disabled for selected ABI | No state mutation; explanatory ABI title |
@@ -445,7 +449,7 @@ React must derive its button gates from that state on the next snapshot.
 | `ESTOP(active=false)` | Source toggle requires current status ESTOP | IO E-stop clears; observed source task state becomes `ESTOP_RESET`; Web may display `STOPPED` only as an adapter label | Power is enabled; motion/manual/MDI remain disabled until ON |
 | `POWER(active=true)` | Source ON edge is valid only from `ESTOP_RESET`; it does not require interpreter IDLE | Trajectory enables and observed task state becomes ON | Manual group requires ON+IDLE; program Run still meets UI/taskfile adapter and task-layer homing rules |
 | `POWER(active=false)` | Source toolbar allows the toggle whenever status is not ESTOP, including active execution | Motion/task/IO abort, trajectory disables, volatile-home joints unhome, task plan synchronizes; taskfile retained | Observed state returns to ESTOP_RESET; nonvolatile homing is not falsely cleared by the UI |
-| `HOME(all/axis)` | AXIS homing UI: ON+IDLE; handler `manual_ok`, then MANUAL | Home authority updates `homed[]`; individual coordinate-axis home is rejected for non-identity/duplicate coordinates | AUTO's task layer may run only when all required joints are homed unless `NO_FORCE_HOMING=1` |
+| `HOME(all/axis)` | AXIS homing UI: ON+IDLE; handler `manual_ok`, then MANUAL; `go_home()` selects FREE/joint before `c.home()` | Home authority updates the canonical five-joint `homed[]`; Web axis selection is validated and mapped to one numeric joint for this fixed one-to-one XYZAC case | AUTO's task layer may run only when all required joints are homed unless `NO_FORCE_HOMING=1`; an invalid axis/joint pair never changes mode or home state |
 | `PROGRAM_LOAD` | Native Open/Reload requires interpreter IDLE; Web additionally excludes active TP/MDI queue and concurrent parse | Save mode, ensure MANUAL, restore mode, set line 0, synchronize, open/replace taskfile and canon, parse status-derived preview, then apply tab mode | New taskfile/preview replace the old selection. Static preview replacement is independent of Live Plot data. |
 | `KINEMATICS_SELECT` | Machine on, homed, idle, TP queue empty, valid type 0/1/2 | M429/M428/M430 selection updates canonical kinematics and the HAL switchkins type | KINEMATICS_BOTH remains unchanged; a non-empty queue blocks selection |
 | `SET_MODE(MANUAL)` | Source task rejects leaving active AUTO; tab handler also requires `manual_ok` | Task mode MANUAL acknowledged; explicit joint/teleop switching remains the stated boundary | Manual widgets are still controlled by ON+IDLE, not mode alone |
@@ -759,7 +763,7 @@ ESTOP(active=false)
 POWER(active=true)
  -> valid from ESTOP_RESET; trajectory enable; observed task_state ON
 HOME(all=true)
- -> manual_ok -> MANUAL -> joint mode -> c.home(-1) -> wait
+ -> manual_ok -> MANUAL -> joint/FREE -> c.home(-1) -> wait
 PROGRAM_RUN
  -> if the previous plan is completed/aborted: reopen current taskfile at line 0
  -> AUTO mode, interpreter READING; browser scheduler drives WASM samples
@@ -788,6 +792,39 @@ block whose target already equals the current canonical pose is a zero-motion
 block: it advances the interpreter line but must not enqueue an invalid
 zero-length TP segment.
 
+### Homing must execute through the WASM trajectory
+
+`sim_kinematics_home_limit_home()` and
+`sim_kinematics_home_limit_home_joint()` are home-state authorities. They
+calculate and commit the canonical homed mask, joint values and forward pose;
+they are not a substitute for the LinuxCNC `c.home()` motion command. The Web
+must therefore use a two-phase transaction whenever the current pose differs
+from the home target:
+
+```text
+HOME click
+ -> validate ON+IDLE/manual_ok and axis-to-joint mapping
+ -> ensure MANUAL -> select FREE/joint homing phase
+ -> WASM kinematics computes target pose without committing home state
+ -> enqueue one LinuxCNC TP homing move to that target
+ -> return HOME {homing.phase:"moving"}; keep current pose and homed state
+ -> browser scheduler sends SIM_STEP task/servo ticks
+ -> TP reaches target and queue becomes empty
+ -> commit sim_kinematics_home(_joint)
+ -> synchronize interpreter/TP canonical position
+ -> restore the prior Web presentation mode
+ -> publish HOME {homing.phase:"complete", wasm_home_limit, pose}
+```
+
+When the current pose already equals the target, the transaction may commit in
+the same command because there is no motion segment to execute. A Home request
+must never call `setPosition()` to jump the TP to zero, must never change the
+React pose locally, and must never advance `home_sequence` before the queued
+motion has completed. `HOME ALL` targets all five configured joint home values;
+`Home Axis` targets only the mapped joint and lets the selected XYZAC
+kinematics calculate the resulting world pose. A pending home blocks another
+Home until its queue has completed or an ESTOP/Power Off aborts it.
+
 ### Touch-off command encoding
 
 AXIS's `all_systems` list is `P0 Current`, `P1 G54` through `P9 G59.3`.
@@ -893,9 +930,13 @@ caller with its obsolete flag. Clear Live Plot is an explicit user operation.
 
 Focused evidence for this contract is kept in
 `web/worker/test_xyzac_touch_off_source_flow.mjs`,
+`web/worker/test_xyzac_home_source_flow.mjs`,
 `web/worker/test_xyzac_panel_buttons.mjs` and
 `scripts/test_xyzac_panel_buttons_browser.mjs`. The completed/aborted direct
 rerun contract is covered by `web/worker/test_xyzac_program_rerun.mjs` and the
+direct visible Jog -> Home Axis/Home All sequence at
+`scripts/test_xyzac_home_reset_browser.mjs` records the in-flight TP pose,
+queue depth and final zero pose on the local `:5175` panel.
 published-site execution sequence is covered by
 `scripts/test_xyzac_program_execution_browser_strict.mjs`.
 The source-surface audit is enforced by `scripts/test_axis_control_contract.mjs`.
@@ -907,8 +948,9 @@ OFF/ESTOP overrides and the source mode transitions against real WASM.
 `update_state` procedure across 576 combinations and compares 13 widget
 predicates (7488 assertions), rather than comparing two rewritten formulas.
 `web/worker/test_axis_source_execution.mjs` verifies repeated Step, queued
-motion Step, WAITING/MDI Pause-Resume, source OFF state, world-axis home rejection
-and spindle override 0-to-100 restoration using the actual WASM runtime.
+motion Step, WAITING/MDI Pause-Resume, source OFF state, fixed XYZAC
+axis-to-joint Home Axis mapping and spindle override 0-to-100 restoration using
+the actual WASM runtime.
 The exhaustive control-ID audit is enforced by
 `scripts/test_axis_control_inventory.mjs` and
 `scripts/test_axis_control_inventory_browser.mjs`; the latter rejects any