Save named machine documents and restore editor configuration from GLB or local library

docs/glb-machine-manager/01-项目功能内容.md

@@ -58,3 +58,5 @@
 18. MGR-19：对话框第一步独立选择设计机床类型 XYZAC/XYZBC；控制面板切换不覆盖设计草稿。机型限制轴绑定、运动验证和标定。保存完整机床 GLB，供控制面板“导入机床模型”自动识别机型并使用。
 
 19. MGR-20：导入/应用跨机型模型时同步加载目标机型默认 G 代码，程序路径、源码、预览与运行机型保持一致；同机型标定保留兼容程序。不兼容轴程序在加载及执行入口拒绝。
+
+20. MGR-21 文档管理：新建、打开已保存机床、编辑控制面板机床；模型名称/说明；保存 GLB 同时提供浏览器下载和本地机床库副本；刷新后从库恢复，多部件文件分组、节点路径、层级覆盖、显隐、关节和标定完整回填。

docs/glb-machine-manager/02-项目程序开发详细步骤.md

@@ -23,3 +23,5 @@
 16. `MGR-19`：把机型纳入草稿/撤销历史；添加首步机型选择；切换清理不适用倾转绑定；完整模型打开恢复机型；下载前调用控制面板读取器校验；验证从 AC 工作区导入 BC GLB 自动切换及 MILL700 两机型保存/运动闭环。
 
 17. `MGR-20`：修正 applyGeometry 跨机型程序选择；加载前读取并验证目标程序；添加 Worker 轴兼容门控；测试双向模型导入、管理器应用、自定义程序保留、文件/编辑器拒绝和旧程序运行门控。
+
+18. `MGR-21`：定义机床编辑文档元数据；重建原部件树再应用覆盖防止双重偏移；实现 IndexedDB 元数据/文件原子保存；文件页提供保存位置解释与恢复；测试刷新、再次保存等价、标准导入、旧版兼容、存储失败下载和 AC/BC 五轴回归。

docs/glb-machine-manager/03-推进台账.md

@@ -119,3 +119,11 @@
 - 新增共享 `programMachineMismatch`：检查文件机型标识和有效块中的不支持 A/B 轴字，忽略注释、命名参数、O 标签及表达式内部。通用三轴程序继续可用，不改写 A/B 指令。
 - Worker 在 PROGRAM_LOAD 以及 RUN/STEP/RESUME 检查源程序与展开子程序；覆盖绕过 UI 和旧恢复程序。门控缓存源文本/机型/路径，避免每帧重复扫描大程序。
 - E16 本地验证通过：AC→BC、BC→AC、管理器应用、错轴文件/编辑器拒绝、同机型保留、自定义程序与正确 BC 运行。11 个可加载 RTCP 目录程序、程序替换和单步回归通过。
+
+## R15 / 2026-09-21 / 保存位置与机床文档恢复
+
+- 原“保存”只有浏览器下载，无法从网页看到保存位置；新增明确下载说明和本浏览器机床库（IndexedDB），显示名称、机型、时间、大小、部件/关节数和校验摘要。
+- 增加文件与恢复页、新建机床、打开已保存机床、编辑控制面板机床、模型名称与设计说明、保存版本打开/再下载/删除。新建/打开仍可撤销。
+- 增加 `linuxcnc.machine-editor/1` GLB 元数据：原部件配置与源节点零姿态拓扑，打开时根据持久节点 ID 重建原始部件树，再应用编辑覆盖，避免合并分组与双重变换。校验恢复结果与运动 JSON 一致。
+- 文件和元数据在 IndexedDB 一次事务提交；写入失败仍允许下载并明确提示。库打开校验 SHA256；库副本独立于磁盘文件，清站点数据会删除库记录。
+- 8 部件文件往返测试已通过：刷新后逐项回填、再次保存元数据完全等价、控制面板导入再送回编辑、旧 GLB 兼容、存储失败反馈。MILL700 AC/BC 完整回归通过，各 8 个五轴动态 tick，浏览器错误 0。工作台布局与八部件生产回归通过。MGR-21 verified。

docs/glb-machine-manager/04-任务矩阵.md

@@ -23,3 +23,4 @@
 |MGR-18 工程化工作台体验|verified|MGR-17|层级搜索与定位、绑定总览、撤销/重做、输入校验、步骤页签、视图预设、单轴步进、实时跟随锁定、响应式布局和失败导入保护通过|
 |MGR-19 对话框机型与保存整机|verified|MGR-18|先在对话框选择设计机型；绑定/标定受机型约束；草稿独立/可撤销；保存完整 GLB 可由控制面板导入并自动切换机型|
 |MGR-20 机型程序一致性|verified|MGR-19|导入/应用跨机型时加载目标默认程序；同机型保留；错轴程序加载/运行/单步/继续拒绝；AC↔BC 浏览器及 Worker 验收通过|
+|MGR-21 保存位置与完整文档恢复|verified|MGR-20|命名 GLB 下载与本地机床库；显式打开/刷新恢复；多部件配置精确回填；二次保存等价；标准导入、旧版兼容、存储失败和 AC/BC 回归|

docs/glb-machine-manager/05-验收证据.md

@@ -176,3 +176,17 @@
 - `node web/worker/test_boat_trt_programs.mjs`：AC/BC 船形程序均完整运行至 completed；报告 `program-compatibility/boats.report.json`。
 
 - E16 已发布 `0de96bb`，线上资源 `index-VAG1dzJ6.js`。线上重复 AC↔BC 模型导入/管理器应用、错误轴加载拒绝、同机型保留和 BC 运行，全部 verified、浏览器错误 0；`program-compatibility/cloud.report.json`、`deployment.report.json`。
+
+## E17 / R15 / 文件保存与编辑文档恢复
+
+- `node scripts/test_machine_document_browser.mjs`：GLB-MGR-E17 verified。测试命名保存、浏览器库原子保存、刷新再打开八个部件、层级覆盖/轴反向/显隐/原点辅助/标定/说明逐项恢复；二次保存的三个元数据对象完全等价。
+- 显式磁盘打开、库再次下载字节一致、删除仅影响副本、损坏编辑数据拒绝且保持现有草稿、控制面板标准导入再回到编辑器、旧文件兼容、存储故障时继续下载并显示失败信息全部通过；浏览器错误 0。
+- `JOINT_TEST_OUTPUT=.../coverage/glb-machine-manager/document/mill700 node scripts/test_machine_joint_dof_browser.mjs`：MILL700 AC/BC 各 8 个动态 tick；导出/打开/标准导入及实时映射 verified。
+- `test_machine_manager_workbench.mjs` 和生产 `test_machine_manager_browser.mjs` 通过；静态类型、构建、历史、数学、134→146 控件清单、双画布/XYZAC 契约通过。
+
+|文件（相对 document）|SHA-256|
+|---|---|
+|`browser.report.json`|`5f45884a75acf14d7a3ecff6a9a50b306842216cb2c26f91d44a781aff3f0073`|
+|`files-and-recovery.png`|`ae48e693668a8e100b81fa2cbfe1a6d4dbc21600a230994f73f2d85d2876e389`|
+|`saved-eight-parts.glb`|`f155f46e6d5566e407a2f708a66ba61332366fb2ba5007b01ac99ed04494769e`|
+|`mill700/browser.report.json`|`7f5c87b1a2d5491242aa87248d0cb4085e5d849065520ad56e4e64c6453216b2`|

docs/glb-machine-manager/06-决策记录.md

@@ -71,3 +71,7 @@ GLB 树节点 ID 使用导入时的子节点索引路径，不使用可能重复
 ## D18 / 跨机型加载匹配程序，不转换旋转轴
 
 工作区切换会改变解释器轴语义，不能继续加载旧机型的 G 代码。跨机型导入/应用自动使用目标机型 catalog 指定的默认程序，目标资源在提交配置前读取和校验；同机型标定保留兼容源程序。禁止通过把 A 文本替换为 B 冒充程序适配。加载和执行门控由 Worker 再次校验，注释和参数名不算轴指令。校验范围是 AC/BC 机型隔离，完整 G 代码解析仍由 LinuxCNC WASM 负责。
+
+## D19 / 可移植 GLB 与浏览器副本
+
+完整机床文档以 GLB 为交付文件；普通网页不能读取浏览器下载文件的绝对磁盘路径，因此界面明确告知查看下载记录。保存时另存完整 GLB 到当前站点 IndexedDB，并提供列表恢复，不暗示上传云端或跨设备同步。每次保存为独立副本，删除库记录不删除磁盘文件或当前草稿。原始编辑拓扑/零姿态保存为 `linuxcnc.machine-editor/1`，与运行关节 JSON 并存；精确恢复原始多文件装配后再施加覆盖，不重复叠加。旧文件缺少编辑元数据时按兼容装配恢复并保留轴/标定。临时关节试动不保存，未完成绑定的会话草稿目前不做跨刷新自动恢复。

docs/glb-machine-manager/08-保存与重新打开机床.md

@@ -0,0 +1,38 @@
+# 保存与重新打开机床
+
+## 保存在哪里
+
+“保存机床模型 GLB”会生成包含几何、层级、机型、单自由度轴绑定、正负方向、零姿态和标定的完整文件：
+
+- **磁盘文件**：发起浏览器下载。通常在系统“下载”目录；如果浏览器开启“每次询问保存位置”，则在用户选择的位置。浏览器下载记录可定位文件，网页不能获取其绝对路径，也不能验证用户是否取消了下载。
+- **本浏览器机床库**：保存成功时还会把相同 GLB 存入本网站的 IndexedDB。刷新页面后进入“文件与恢复”，可直接打开配置、重新下载或删除副本。列表显示保存时间、机型、大小及 SHA256 摘要，每次保存生成一个独立版本。
+
+本地机床库不会自动上传云端；它只存在于同一浏览器、同一站点地址（包括协议和端口）。清理站点数据、隐私窗口退出或换设备会失去这些本地副本。因此磁盘 GLB 是重要的可移植保存方式。库保存失败时仍会下载 GLB，并显示失败信息。
+
+## 再次打开和回填
+
+1. 在“三维机床管理”点击“打开已保存机床”，选择之前下载的 GLB；或在“文件与恢复”的机床库点击“打开配置”。
+2. 新版保存文件恢复为原来的多个部件，回填原始部件名、父级关系、源节点路径、层级拖放覆盖、平移/姿态零位、节点结构角色、轴绑定、方向、正负向和显隐/坐标原点显示。
+3. 顶部自动恢复 XYZAC/XYZBC，标定页恢复 C 原点、A/B 偏置、物理零点；文件页恢复模型名称、设计说明。轴总览可定位相应节点。
+4. 打开操作替换当前草稿，原草稿可通过撤销恢复。关节试动值归零，不作为机床设计零姿态保存。
+5. “编辑控制面板机床”将控制面板已加载的受支持配置回填到管理器，不需要再次找磁盘文件；后续编辑不会自动改变正在运行的机床，仍需显式应用。
+6. 名称和说明在“文件与恢复”中修改；保存后生成新的 GLB 和本地版本。默认下载名为 `managed-xyzac.glb` 或 `managed-xyzbc.glb`，命名后为 `名称-xyzac.glb` 或 `名称-xyzbc.glb`。
+
+旧版本机床 GLB 若缺少完整编辑数据，仍恢复已有装配层级、轴配置和标定；无法凭空恢复已丢失的原始多文件分组。普通几何 GLB 使用“导入 GLB 部件”，完整机床使用“打开已保存机床”。
+
+## 提供给控制面板
+
+控制面板关机且程序空闲 → “导入机床模型” → 选择保存的 GLB。文件内的机型会决定控制配置；跨 AC/BC 会加载对应机型默认程序。完成后重新回零再执行程序。
+
+## 元数据
+
+- `userData.linuxcncMachine`：原 URDF 控制框架。
+- `userData.linuxcncMachineGeometry`：C 原点、偏置、物理零点与部件配置。
+- `userData.linuxcncJointModel`：运行关节 ID、父链与轴映射。
+- `userData.linuxcncMachineEditor`：`linuxcnc.machine-editor/1`，包含 `info.name/description`、每个部件的 `settings`、原始 `sourceNodes`。源节点记录稳定路径、原点位置（米）、四元数、比例、名称和可见性。GLB 节点的 `linuxcncNodeId` 负责匹配实际几何。
+
+加载新版文件时会重建源节点拓扑，再复用原装配逻辑应用设置，并对比恢复后的关节 JSON，防止错绑或双重偏移。源 GLB 文件不原地修改。
+
+## 当前边界
+
+本轮提供完整机床的保存/打开/本地版本恢复。尚未绑定完整五轴的会话草稿、撤销历史、相机视角和临时试动值不会跨刷新自动保存；关闭对话框但不刷新页面仍保留草稿。云端共享、权限审批、碰撞检查及其他机型运动学不属于本轮实现。

docs/glb-machine-manager/README.md

@@ -11,7 +11,7 @@
 
 现有整机 GLB + 内嵌 URDF 导入能力继续保留。新管理器生成与现有 `linuxcnc.machine/1` 相同的严格结构，再通过已有配置、Worker、WASM 和 Three.js 投影链运行。
 
-当前状态：MGR-20 机型程序一致性 verified；MGR-19 对话框选择机型/整机保存已 verified；MGR-17、MGR-18 已 verified；MGR-01 至 MGR-16 已完成历史验收，MILL700 实测覆盖照明、Z-up、132 节点树、拖放、节点原点、关节局部坐标系、节点相对父级平移旋转、模型删除、轴绑定、XYZ/AC 层级运动和 WebGL 资源降级。最新台账 R14，证据 `GLB-MGR-E01/E02/E05/E07/E08/E09/E10/E12/E13/E14/E15/E16` 位于 `coverage/glb-machine-manager/`。
+当前状态：MGR-21 文件管理与恢复 verified；MGR-20 机型程序一致性 verified；MGR-19 对话框选择机型/整机保存已 verified；MGR-17、MGR-18 已 verified；MGR-01 至 MGR-16 已完成历史验收，MILL700 实测覆盖照明、Z-up、132 节点树、拖放、节点原点、关节局部坐标系、节点相对父级平移旋转、模型删除、轴绑定、XYZ/AC 层级运动和 WebGL 资源降级。最新台账 R15，证据 `GLB-MGR-E01/E02/E05/E07/E08/E09/E10/E12/E13/E14/E15/E16/E17` 位于 `coverage/glb-machine-manager/`。
 
 文档：
 
@@ -26,3 +26,5 @@
 
 - [07-单自由度JSON与实时驱动](07-单自由度JSON与实时驱动.md)
 - [关节 JSON Schema](joint-model.schema.json)
+
+- [08-保存与重新打开机床](08-保存与重新打开机床.md)

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

@@ -1083,3 +1083,7 @@ silently reproduced in the browser.
 ### MGR-19 document machine type
 
 `machine-manager-type`, `machine-manager-type-note`: select XYZAC/XYZBC inside the design dialog before configuring structure. Design type belongs to undoable draft state and is independent of the live controller. Saving validates the GLB through the standard importer; loading a full machine restores type, bindings and calibration, and the control panel switches workspace to match the imported model.
+
+### MGR-21 document save and recovery
+
+`machine-document-new`, `machine-document-open`, `machine-document-open-file`, `machine-document-from-controller`, `machine-document-name`, `machine-document-description`, `machine-document-location`, `machine-library-search`, `machine-library-open`, `machine-library-download`, `machine-library-delete`, `machine-manager-tab-files`: named GLB document, complete multi-part editor recovery, explicit file opening, immutable saved copies in browser IndexedDB, location/status information, download and delete. Controller model editing reads current effective calibration. GLB remains compatible with the standard importer.