{"record":{"id":"ea9c0f228dc22d0c","repo":"deepseek-ai/deepseek-harness","slug":"web-boot-window-moduleloader-bootstrap-facade","errorCode":null,"errorMessage":"web boot: window.__ModuleLoader__ bootstrap facade is missing","messagePattern":"web boot: window\\.__ModuleLoader__ bootstrap facade is missing","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/client/web/src/boot.ts","lineNumber":51,"sourceCode":"   * @param seams - Optional module transport replacement.\n   */\n  constructor(container: HTMLElement, seams?: BootSeams) {\n    this.container = container\n    this.seams = seams\n    this.page = new BootPage(container)\n  }\n\n  /**\n   * Load and activate every client entry, then hand the mount point to the\n   * UI renderer. Plugin failures remain visible on the boot page.\n   * @returns Resolves after application mount or failure rendering.\n   */\n  async run(): Promise<void> {\n    try {\n      const win = globalThis as DshWindow\n      const moduleLoader = win.__ModuleLoader__\n      if (moduleLoader === undefined) {\n        throw new Error('web boot: window.__ModuleLoader__ bootstrap facade is missing')\n      }\n      // A pre-injected transport (the worker preview page) owns bundle bytes;\n      // its loadBundle is the default and explicit seams still win. The global\n      // is `ClientTransportHooks`, owned by @deepseek-ai/dsh-client-connection;\n      // this structural slice reads one optional member without adding a\n      // package edge.\n      const transport = (globalThis as {\n        __DSH_TRANSPORT__?: { loadBundle?: ClientModuleCreateOptions['loadBundle'] }\n      }).__DSH_TRANSPORT__\n      this.modules = moduleLoader.create({\n        boot: win.__DSH_BOOT__,\n        staticModules: getStaticModules(),\n        ...transport?.loadBundle === undefined ? {} : { loadBundle: transport.loadBundle },\n        ...this.seams,\n      })\n      this.manifest = this.modules.manifest\n\n      const prefetching = this.prefetchImmediateTier()","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/client/web/src/boot.ts#L33-L69","documentation":"AppWebEntry.run — the browser boot kernel of @deepseek-ai/dsh-client-web — requires the host page to install window.__ModuleLoader__ (the bootstrap facade that owns module creation and the boot manifest) before boot starts. If the global is undefined the kernel cannot even build the module system, so it aborts boot with this error and renders the failure on the boot page.","triggerScenarios":"Loading the web client bundle in a page where the script that defines window.__ModuleLoader__ never ran: omitted from the host HTML, loaded after the boot bundle, 404 or blocked by CSP. Also hit in jsdom tests that run AppWebEntry without seeding the global (the expectBootFailure helper exercises exactly this path).","commonSituations":"Custom host page assembled without the loader script tag; bundler/CDN misroute drops the bootstrap chunk; a refactor renames or removes the global; test setup forgets to seed window.__ModuleLoader__ before calling run().","solutions":["Ensure the script that defines window.__ModuleLoader__ executes before the web boot bundle in the host page.","Check the browser console/network tab for a failed load of that script (404, wrong MIME type, CSP block) and fix the serving path or policy.","In jsdom tests, seed the global (or pass seams) in setup before invoking AppWebEntry.run.","If the shell was refactored, grep the built shell output for __ModuleLoader__ to confirm the facade is still assigned early."],"exampleFix":"<!-- before — boot kernel runs before the loader facade exists -->\n<script src=\"/assets/boot.js\"></script>\n<script src=\"/assets/loader.js\"></script>\n\n<!-- after — loader facade first, boot kernel second -->\n<script src=\"/assets/loader.js\"></script>\n<script src=\"/assets/boot.js\"></script>","handlingStrategy":"validation","validationCode":"const win = globalThis as DshWindow\nif (win.__ModuleLoader__ === undefined) {\n  // surface a setup error or seed the facade before boot; run() would abort\n  throw new Error('host page did not install the __ModuleLoader__ facade')\n}","typeGuard":"function hasModuleLoader(w: unknown): w is DshWindow {\n  return typeof (w as DshWindow).__ModuleLoader__ !== 'undefined'\n}","tryCatchPattern":"run() already catches every boot error and renders it on the boot page; callers awaiting run() should log the failure instead of rethrowing. In tests, assert the rendered failure text rather than wrapping run() in another try/catch.","preventionTips":["Keep the facade-defining script first in the host page; add a CI check that the emitted HTML contains it.","Seed window.__ModuleLoader__ in jsdom setup when testing AppWebEntry.","Treat renaming __ModuleLoader__ as a breaking host-page change and update the shell template in the same commit."],"tags":["web-boot","bootstrap","browser-globals","module-loader"],"backgroundTag":"undefined-global-variable","analyzedSha":"b150a551b8d465e31e418e1b2eaf5e79bbb7d28e","analyzedAt":"2026-08-24T18:12:29.105Z","schemaVersion":2},"datasetVersion":"2026-08-24T22:17:12.610Z"}