fix(director): recover temporary entry loading failures

data/index.json

@@ -2,9 +2,9 @@
   "version": "1.0",
   "schemaVersion": "1.2",
   "release": {
-    "displayVersion": "5.21.7",
-    "appSemver": "5.21.7",
-    "gitRef": "f7459408edecc7ef0b744dd9c5aaa3620a4ebd51",
+    "displayVersion": "5.21.8",
+    "appSemver": "5.21.8",
+    "gitRef": "25eea922cead3e38006780d55859f76c5f050010",
     "schemaVersion": "1.2",
     "historyUrl": "/data/version-history.json",
     "updatedAt": "2026-10-09"

data/version-history.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": "1.1",
   "cutoffGitRef": "c613a87",
-  "documentedThrough": "f7459408edecc7ef0b744dd9c5aaa3620a4ebd51",
+  "documentedThrough": "25eea922cead3e38006780d55859f76c5f050010",
   "defaultResourceVersion": "1.0a",
   "current": {
-    "displayVersion": "5.21.7",
-    "appSemver": "5.21.7",
+    "displayVersion": "5.21.8",
+    "appSemver": "5.21.8",
     "indexSchemaVersion": "1.2",
     "date": "2026-10-09",
-    "gitRef": "f7459408edecc7ef0b744dd9c5aaa3620a4ebd51",
+    "gitRef": "25eea922cead3e38006780d55859f76c5f050010",
     "historyUrl": "/data/version-history.json",
     "upstream": {
       "repository": "playcanvas/supersplat-viewer",
@@ -296,6 +296,16 @@
       "gitRef": "2ed2ae21280d4115a78dedce2d316994b847379f",
       "date": "2026-10-09",
       "summary": "MF-106 5.21.7 original optical and interaction source checkpoint, preserved by viewer-v5.21.7-rc1; final product is PR 131 squash."
+    },
+    {
+      "gitRef": "b6250e41720009b92f9a530508da543af01a069a",
+      "date": "2026-10-09",
+      "summary": "MF-106 5.21.8 candidate version mirrors and 5.21.7 production evidence; original behavior source 25eea922c."
+    },
+    {
+      "gitRef": "00d3e56285bb1f3816853ebb532e76af2688dd7c",
+      "date": "2026-10-09",
+      "summary": "MF-106 bootstrap isolation assertion adapts to bounded importer, preserving routing semantics; browser fault and failed CI evidence."
     }
   ],
   "entries": [
@@ -1798,6 +1808,24 @@
         "releaseTag": "viewer-v5.21.7",
         "pullRequest": "https://github.com/Shuang-su/Metaflow/pull/131"
       }
+    },
+    {
+      "displayVersion": "5.21.8",
+      "appSemver": "5.21.8",
+      "type": "fix",
+      "scope": "viewer",
+      "date": "2026-10-09",
+      "gitRef": "25eea922cead3e38006780d55859f76c5f050010",
+      "summary": "摄影入口临时获取失败自动有限重试，耗尽后提供重试与原资源Viewer返回入口；不改变摄影成像或普通Viewer",
+      "trace": {
+        "changeId": "MF-106",
+        "issue": "https://github.com/Shuang-su/Metaflow/issues/106",
+        "spec": "docs/changes/106-acg-director/spec.md",
+        "plan": "docs/changes/106-acg-director/plan.md",
+        "evidence": "docs/changes/106-acg-director/verification.md",
+        "releaseTag": "viewer-v5.21.8",
+        "pullRequest": "https://github.com/Shuang-su/Metaflow/pull/133"
+      }
     }
   ]
 }

docs/changes/106-acg-director/plan.md

@@ -64,3 +64,7 @@
 ## 2026-10-09 持续完成
 
 沿用隔离工作区，在`codex/acg-director-final-parity`从远端main `d724479f9b73f05d41ffdf391f3e7b7a78408622`继续。先保留近同深度与大场景的修改前图像/实际GPU顺序，再改用摄影浮点深度键并检查十次重复、同深度稳定性、四个固定场景、拾取和输出。随后逐控件记录参考来源、开始/途中/结束/反向/中断，修正具体差异；受控薄透镜、Spark、GPU与CPU对照分别说明判断边界。检查通过后按既有上线授权追加PATCH、PR、预览和生产回读；历史失败及源文件保持原状。
+
+## 2026-10-09 生产启动复查修正
+
+5.21.7上线后的单次动态入口获取失败作为5.21.8兼容修复：从实际发布记录42b3e172隔离分支实现有限网络重试和明确失败控制。先以四项行为测试及实际浏览器503故障注入验证，再运行Viewer检查、构建版本故障复验及正式部署回读。沿用PR/精确HEAD CI/正式tag/15分钟观察，不混入光学或公共契约变化，不将原始未知网络原因误称已定位。

docs/changes/106-acg-director/spec.md

@@ -33,6 +33,10 @@ Fast不混入孔径累积、不保存为已收敛缓存、不进入照片或视
 
 光学检查分别登记排序、尾部覆盖、孔径积分、颜色和资产自身缺陷；受控平面使用独立薄透镜光线参照。不得将扫描数据中本来缺失的面、发丝或残影列成可以通过增加采样恢复的实现项。逐状态验收限定于公开实际保留的控件及现有浏览器，已排除功能和未运行设备不充作已完成。
 
+## 2026-10-09 启动恢复
+
+生产复查中一次动态摄影入口获取失败，普通刷新后恢复；原始网络原因未证实。限定兼容修正：仅对网络类动态导入错误采用100/300/900ms退避和新模块URL，最多四次，不重试语法、执行或GPU能力错误。预算耗尽后显示可操作的重试和对应资源Viewer返回入口。Viewer及SDK独立启动不改变；摄影模型、采样、素材和相机交接不改变。使用实际浏览器的首次503及持续503验证，不以单元测试或刷新成功替代恢复验收。
+
 ## 2026-10-05 输入反馈与上线修正
 
 沿用候选摄影组件；修复透明 header 阻断 Operator/Compose 命中。AF/MF 点击对焦提示及渐进/收敛反馈在取景框外，比例菜单在数字前显示真实宽高形状；手动距离和 ƒ 图标对齐已固定来源尺寸。原图对比使用自有分栏符号，仅切换预览，不改变摄影参数/历史。

docs/changes/106-acg-director/verification.md

@@ -350,6 +350,12 @@
 ## 5.21.7 合并及发布准备
 
 - [PR #131](https://github.com/Shuang-su/Metaflow/pull/131)常规squash合并产品 `f7459408edecc7ef0b744dd9c5aaa3620a4ebd51`，精确候选 `8194cdb3a4c8d0eb0f57c116c952d549b2207855` 的[CI 37884934299](https://github.com/Shuang-su/Metaflow/actions/runs/37884934299)所选Viewer/Director/Viewer开发及构建E2E、数据、治理、文档、CodeQL及summary成功。未选中的组件skipped。`viewer-v5.21.7-rc1`保留所有本轮来源，5.21.7尚未生产发布的candidate记录回填实际产品SHA，旧正式版本条目不改写。
+
+## 5.21.8 启动恢复来源验证
+
+- 5.21.7生产浏览器在2026-10-09T05:01:23.076Z记录一次`Failed to fetch dynamically imported module: /director/entry.js`；普通刷新后入口、字体、WASM均200，主模型/环境512收敛。获取失败前未启用网络录制，不能推断具体网络或浏览器原因。单次失败历史不从观察记录删除。
+- 主动503故障注入：首次入口失败后使用`?mf_retry=1`自动恢复，无人工刷新，实际场景128收敛；持续失败按每轮四次退出，显示重试按钮及对应Viewer链接。按钮再次启动累计八次，未无限循环。故障服务器直接调用宿主转换函数，非正式构建；构建版本和正常Viewer返回继续复查。
+- 四项新增行为测试、Viewer完整148/148通过；语法/运行/GPU错误不重试、预算及最终错误保留、SDK模板不改变。JSON与当前Viewer交接的生产误差均小于1e-6，参数/焦点核对见本地`production-handoff-actual.json`。实际源码、构建、CI与部署另行回填。
 - 完整预览8个文件字节/300路线及引用、79主模型/51环境、8redirect/9header通过。当前预览真实缇宝/环境128收敛，Operator展开、390亮色PHOTO Capture64×42、VIDEO REC64×42、教程关闭不出现Show、border=0、无横向溢出及console error为0。只读布局脚本初次使用不存在的.stage选择器失败，修正为实际.view-frame后核对；非产品错误。
 - 7张中文对照图与2个过程视频已通过GitHub原生附件发布于[MF-106正文](https://github.com/Shuang-su/Metaflow/issues/106#issuecomment-6074383785)及[MF-62分析](https://github.com/Shuang-su/Metaflow/issues/62#issuecomment-6074392326)。匿名GET全部200、字节和SHA256与本地一致，正文video controls播放器实际存在。此前原生附件失败的历史记录保留，本轮通路已完成。
 - 四场景960×540、五类输入各五轮、每轮5秒，共100轮产品调度测试，耗时537.4秒：全有新画面、最终状态必达、无错误；最终各场景恢复128。通过程序化摄影状态输入，非原生DOM/真机手势，也未称GPU时间。原始输入/呈现时间、哈希、相机和逐轮统计在four-scene-input-current/summary.json。首轮取证脚本未重置样本计数而中断，修正后完整重跑；首轮不充作验收。
@@ -378,3 +384,17 @@
 |interior|aperture|245|104.9/120.8|305.3|
 
 正式tag/build/生产部署与15分钟观察仍在执行，回退仍为5.21.6 `6ac7ec0fa8239794c0ab5d12`。
+
+## 5.21.7 正式回读及5.21.8准备
+
+- 正式tag/build `42b3e172324c4f03a4c63a2b3df0552df8999fd8`，产品 `f7459408edecc7ef0b744dd9c5aaa3620a4ebd51`；Netlify `6ac873b8382d690120124c07`于2026-10-09T04:58:24.432Z发布。8文件与300路由/引用、79符合入口/51环境、8redirect/9header回读匹配。16轮HTTP观察900.009秒无回读错误。浏览器单次模块获取错误及刷新恢复另列，不能以HTTP观察覆盖。
+- 已承接实际Viewer机位：最大位置误差4.44e-16，target/focusPoint误差0；实际865623点含环境，512收敛。原光圈标定保持0.2493011431231506。
+- 5.21.8准备脚本初次使用错误元数据键`releases`，未写任何文件；更正现有`entries`后版本契约/MCL通过。Viewer148项、类型/lint/fmt通过；全部100资源对象与上次正式数据一致。只追加本版本，旧历史未改写。
+
+## 5.21.8 构建及首次CI核查
+
+- 实际完整构建5.21.8再次注入首次503自动恢复，场景128收敛；持续503四次后返回入口实际导航到原资源Viewer，正常呈现动画控制。独立预览正常完整加载，控制台无错误。
+- 精确head b6250e417的[CI 37887980827](https://github.com/Shuang-su/Metaflow/actions/runs/37887980827)因Director旧测试硬编码直接`await import`字符串失败；实际行为已替换为有限重试函数。断言改为保留摄影/Viewer分支和初始化顺序检查，新增四项网络重试行为检查仍保留，不削弱隔离要求；本地Director36项及类型通过，修订head重跑CI。
+- 第一个CLI预览6ac87940的版本历史文件出现immutable缓存头，未提升生产；重新使用已验证的部署工作目录，继续检查8redirect/9header及实际HTTP，失败候选保留。
+
+- CI 37888362657的Director36项、构建及两种Viewer E2E已通过；Viewer版本历史检查指出00d3e5628测试维护来源缺少maintenance记录。追加实际来源，不改测试/检查规则；精确最终head重跑。初次本地输入`typecheck`脚本名不存在，更正既有`type:check`后正常通过，保留命令修正记录。配置工作目录预览6ac87a38已ready，8文件/300路由引用及版本文件非immutable缓存头回读匹配，失败候选未生产。

docs/metaflow-viewer-change-ledger.md

@@ -578,3 +578,18 @@ The 2026-08-15 Viewer 5.19.2 release-record commit updated package/version/index
 - [PR #131](https://github.com/Shuang-su/Metaflow/pull/131)已合并；精确候选[CI 37884934299](https://github.com/Shuang-su/Metaflow/actions/runs/37884934299)所选检查通过，不绕过分支规则。不可变rc1固定8194cdb3a并保留源码`2ed2ae21280d4115a78dedce2d316994b847379f`及既有维护记录。
 - 四场景100轮输入全部有呈现、最终状态与128收敛；24本地+24来源DPR2状态、原生控件及缓存、三档真实动态4K、四转场取消重试见[验证记录](changes/106-acg-director/verification.md)。完整站点预览、79/51资源、8redirect/9header通过。
 - [原生正文附件](https://github.com/Shuang-su/Metaflow/issues/106#issuecomment-6074383785)7图2视频已匿名GET/哈希验证；Fast方差及Float32深度稳定排序两项因果修复与扫描/材料边界分开说明。正式tag/build/部署随后记录，未将候选称为生产。
+
+
+### `5.21.8` · `25eea922cead3e38006780d55859f76c5f050010` · startup recovery candidate
+
+- [PR #133](https://github.com/Shuang-su/Metaflow/pull/133)修复生产一次入口获取失败后的人工刷新依赖。网络类动态导入最多四次、新URL及100/300/900ms退避；运行、语法、GPU错误不重试，耗尽提供明确重试/原资源返回入口。
+- Viewer148/148、四项行为验证和实际首次/持续503注入通过；构建版本、精确HEAD CI、正式部署及观察另行追加。5.21.7连续16轮900.009秒HTTP观察通过，但单次浏览器获取错误保留，不能称全部零故障。摄影算法、资源及原Viewer/SDK启动不改变。
+
+
+### `5.21.7` · `f7459408edecc7ef0b744dd9c5aaa3620a4ebd51` · production verification
+
+- 正式tag/build `42b3e172324c4f03a4c63a2b3df0552df8999fd8`，Netlify `6ac873b8382d690120124c07`于2026-10-09T04:58:24.432Z发布。8文件/300路由引用、79/51资源、8redirect/9header及900.009秒16轮HTTP观察通过。真实Viewer交接误差≤4.44e-16、含环境512收敛。
+- 单次浏览器动态模块获取失败后刷新恢复，原因未证实，作为5.21.8有限重试修复继续登记。HTTP检查不代表没有此浏览器故障。实际光学、输出和原生GitHub正文媒体见MF-106验证记录，源资产缺陷与材料模型边界独立说明。
+
+
+- 5.21.8候选维护来源`b6250e41720009b92f9a530508da543af01a069a`记录版本镜像及5.21.7生产证据；`00d3e56285bb1f3816853ebb532e76af2688dd7c`更新宿主隔离测试以验证新重试入口，并保留首次CI/预览失败，不改变摄影运行时。最终精确HEAD与实际产品SHA另行回填。

metadata/version-history.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": "1.1",
   "cutoffGitRef": "c613a87",
-  "documentedThrough": "f7459408edecc7ef0b744dd9c5aaa3620a4ebd51",
+  "documentedThrough": "25eea922cead3e38006780d55859f76c5f050010",
   "defaultResourceVersion": "1.0a",
   "current": {
-    "displayVersion": "5.21.7",
-    "appSemver": "5.21.7",
+    "displayVersion": "5.21.8",
+    "appSemver": "5.21.8",
     "indexSchemaVersion": "1.2",
     "date": "2026-10-09",
-    "gitRef": "f7459408edecc7ef0b744dd9c5aaa3620a4ebd51",
+    "gitRef": "25eea922cead3e38006780d55859f76c5f050010",
     "historyUrl": "/data/version-history.json",
     "upstream": {
       "repository": "playcanvas/supersplat-viewer",
@@ -296,6 +296,16 @@
       "gitRef": "2ed2ae21280d4115a78dedce2d316994b847379f",
       "date": "2026-10-09",
       "summary": "MF-106 5.21.7 original optical and interaction source checkpoint, preserved by viewer-v5.21.7-rc1; final product is PR 131 squash."
+    },
+    {
+      "gitRef": "b6250e41720009b92f9a530508da543af01a069a",
+      "date": "2026-10-09",
+      "summary": "MF-106 5.21.8 candidate version mirrors and 5.21.7 production evidence; original behavior source 25eea922c."
+    },
+    {
+      "gitRef": "00d3e56285bb1f3816853ebb532e76af2688dd7c",
+      "date": "2026-10-09",
+      "summary": "MF-106 bootstrap isolation assertion adapts to bounded importer, preserving routing semantics; browser fault and failed CI evidence."
     }
   ],
   "entries": [
@@ -1798,6 +1808,24 @@
         "releaseTag": "viewer-v5.21.7",
         "pullRequest": "https://github.com/Shuang-su/Metaflow/pull/131"
       }
+    },
+    {
+      "displayVersion": "5.21.8",
+      "appSemver": "5.21.8",
+      "type": "fix",
+      "scope": "viewer",
+      "date": "2026-10-09",
+      "gitRef": "25eea922cead3e38006780d55859f76c5f050010",
+      "summary": "摄影入口临时获取失败自动有限重试，耗尽后提供重试与原资源Viewer返回入口；不改变摄影成像或普通Viewer",
+      "trace": {
+        "changeId": "MF-106",
+        "issue": "https://github.com/Shuang-su/Metaflow/issues/106",
+        "spec": "docs/changes/106-acg-director/spec.md",
+        "plan": "docs/changes/106-acg-director/plan.md",
+        "evidence": "docs/changes/106-acg-director/verification.md",
+        "releaseTag": "viewer-v5.21.8",
+        "pullRequest": "https://github.com/Shuang-su/Metaflow/pull/133"
+      }
     }
   ]
 }

metaflow-director/tests/routes.test.mjs

@@ -111,9 +111,10 @@ test("Viewer bootstrap never imports the engine on the Director branch", async (
     await readFile("../metaflow-viewer/src/index.html", "utf8"),
   );
   assert(!html.includes("import { createViewer } from './index.js'"));
-  assert(html.includes("await import('/director/entry.js')"));
+  assert(html.includes("await (async function loadDirectorEntry("));
+  assert(html.includes("await importer(`/director/entry.js${attempt"));
   assert.match(
     html,
-    /metaflowDirectorPath[\s\S]*await import\('\/director\/entry.js'\)[\s\S]*else[\s\S]*await import\('\.\/index.js'\)/,
+    /if \(window\.metaflowDirectorPath\)[\s\S]*await \(async function loadDirectorEntry\([\s\S]*\}\)\(\);\s*\} else \{\s*const \{ createViewer \} = await import\('\.\/index.js'\)/,
   );
 });

metaflow-viewer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metaflow-viewer",
-  "version": "5.21.7",
+  "version": "5.21.8",
   "description": "Gaussian Splatting Viewer for metaflow.shuang-su.com",
   "license": "MIT",
   "type": "module",

metaflow-viewer/site-html.mjs

@@ -1,4 +1,24 @@
 /** Only the hosted site dispatches resource /director routes. SDK exports keep their standalone bootstrap. */
+export async function loadDirectorEntry(
+    importer = (url) => import(url),
+    delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+) {
+    const backoff = [100, 300, 900];
+    for (let attempt = 0; ; attempt++) {
+        try {
+            await importer(`/director/entry.js${attempt ? `?mf_retry=${attempt}` : ''}`);
+            return;
+        } catch (error) {
+            // Failed imports remain rejected in the document's module map. A fresh URL
+            // retries the request; runtime and syntax errors must retain their cause.
+            const transient = error instanceof TypeError &&
+                /failed to fetch dynamically imported module|failed to load module script|importing a module script failed|error loading dynamically imported module/i.test(error.message);
+            if (!transient || attempt >= backoff.length) throw error;
+            await delay(backoff[attempt]);
+        }
+    }
+}
+
 export function siteHtml(template) {
     const replace = (from, to) => {
         if (!template.includes(from)) throw Error(`Site bootstrap seam missing: ${from}`);
@@ -22,15 +42,25 @@ export function siteHtml(template) {
                     const css = document.createElement('link');
                     css.rel = 'stylesheet'; css.href = '/director/style.css';
                     document.head.appendChild(css);
-                    await import('/director/entry.js');
+                    await (${loadDirectorEntry.toString()})();
                 } else {
                 const { createViewer } = await import('./index.js');
                 const { config, settings } = await window.sseReady;`
     );
     replace('exposeGlobals: true\n                });', 'exposeGlobals: true\n                });\n                }');
     replace(
         "message.textContent = 'Viewer failed to load. Please check the resource and retry.';",
-        "message.textContent = window.metaflowDirectorPath ? 'Director 实验版加载失败，请刷新重试或返回资源 Viewer。' : 'Viewer failed to load. Please check the resource and retry.';"
+        `message.textContent = window.metaflowDirectorPath ? '摄影页面加载失败。可以重试，或返回 Viewer。' : 'Viewer failed to load. Please check the resource and retry.';
+                if (window.metaflowDirectorPath) {
+                    message.setAttribute('role', 'alert');
+                    const retry = document.createElement('button');
+                    retry.type = 'button'; retry.textContent = '重试摄影页面';
+                    retry.addEventListener('click', () => location.reload());
+                    const back = document.createElement('a');
+                    back.textContent = '返回 Viewer';
+                    back.href = location.pathname.replace(/\\/director\\/*$/, '') || '/';
+                    message.append(' ', retry, ' ', back);
+                }`
     );
     return template;
 }