{"record":{"id":"2692c453f31acd41","repo":"halo-dev/halo","slug":"root-snapshot-runtime-descriptor-is-invalid","errorCode":null,"errorMessage":"${root} snapshot runtime descriptor is invalid.","messagePattern":"(.+?) snapshot runtime descriptor is invalid\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"ui/packages/ui-plugin-bundler-kit/src/runtime-snapshot.ts","lineNumber":208,"sourceCode":"    value.exports.length === 0 ||\n    value.exports.some(\n      (exportName) =>\n        typeof exportName !== \"string\" || !/^[$A-Z_a-z][$\\w]*$/.test(exportName)\n    ) ||\n    new Set(value.exports).size !== value.exports.length\n  ) {\n    throw new Error(`${root} snapshot exports must be unique identifiers.`);\n  }\n  if (\n    !isRecord(value.runtime) ||\n    typeof value.runtime.bridge !== \"string\" ||\n    !/^[a-z0-9-]+$/.test(value.runtime.bridge) ||\n    typeof value.runtime.global !== \"string\" ||\n    !/^[$A-Z_a-z][$\\w]*$/.test(value.runtime.global) ||\n    (value.runtime.identity !== \"singleton\" &&\n      value.runtime.identity !== \"shared\")\n  ) {\n    throw new Error(`${root} snapshot runtime descriptor is invalid.`);\n  }\n  return {\n    version: value.version,\n    exports: [...value.exports].sort(),\n    runtime: {\n      bridge: value.runtime.bridge,\n      global: value.runtime.global,\n      identity: value.runtime.identity,\n    },\n  };\n}\n\nfunction getPackageResolutionBase(providerRoot: string, sourceId?: string) {\n  const cleanSourceId = sourceId?.split(/[?#]/, 1)[0];\n  if (cleanSourceId && path.isAbsolute(cleanSourceId)) {\n    return path.dirname(cleanSourceId);\n  }\n  return providerRoot;","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/halo-dev/halo/blob/d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8/ui/packages/ui-plugin-bundler-kit/src/runtime-snapshot.ts#L190-L226","documentation":"Thrown by validateSnapshotEntry when the snapshot entry's 'runtime' descriptor is malformed: runtime is not an object, bridge is not a lowercase kebab string (/^[a-z0-9-]+$/), global is not a valid JS identifier, or identity is neither 'singleton' nor 'shared'. The descriptor tells the ESM externalizer how the host exposes the package (the window/global name and the bridge module id), so an invalid descriptor would produce a broken import map at runtime.","triggerScenarios":"Fires at module load when constructing HALO_HOST_RUNTIME_SNAPSHOTS if a snapshot entry.runtime is absent, has bridge 'Vue' (uppercase), global 'vue-router' (hyphen), or identity 'global'.","commonSituations":"A forked snapshot data file uses the wrong global var name or a camelCase bridge; a maintainer adds a new shared root but forgets the runtime descriptor; identity typo like 'singletons'.","solutions":["Set runtime.bridge to a lowercase kebab string (e.g. 'halo-vue'), runtime.global to a valid identifier (e.g. 'Vue'), and runtime.identity to 'singleton' or 'shared'.","Cross-check the descriptor against how the host actually assigns window[global] in the console bundle.","Restore upstream snapshot data and upgrade the bundler kit."],"exampleFix":"// before\nruntime: { bridge: \"Vue\", global: \"vue-router\", identity: \"global\" }\n\n// after\nruntime: { bridge: \"halo-vue\", global: \"Vue\", identity: \"singleton\" }","handlingStrategy":"validation","validationCode":"function validateRuntimeDescriptor(root: string, runtime: unknown) {\n  const r = runtime as Record<string, unknown> | null;\n  if (!r || typeof r.bridge !== \"string\" || !/^[a-z0-9-]+$/.test(r.bridge) ||\n      typeof r.global !== \"string\" || !/^[$A-Z_a-z][$\\w]*$/.test(r.global) ||\n      (r.identity !== \"singleton\" && r.identity !== \"shared\")) {\n    throw new Error(`${root} snapshot runtime descriptor is invalid.`);\n  }\n}","typeGuard":"function isValidRuntimeDescriptor(value: unknown): value is { bridge: string; global: string; identity: \"singleton\" | \"shared\" } {\n  if (typeof value !== \"object\" || value === null) return false;\n  const r = value as Record<string, unknown>;\n  return typeof r.bridge === \"string\" && /^[a-z0-9-]+$/.test(r.bridge) &&\n    typeof r.global === \"string\" && /^[$A-Z_a-z][$\\w]*$/.test(r.global) &&\n    (r.identity === \"singleton\" || r.identity === \"shared\");\n}","tryCatchPattern":null,"preventionTips":["Derive bridge/global/identity from the host bundle, not by guesswork.","Add a test that asserts every snapshot entry passes isValidRuntimeDescriptor.","Keep bridge lowercase-kebab and global a valid identifier."],"tags":["build","esm","snapshot","runtime-descriptor","bundler-kit"],"backgroundTag":null,"analyzedSha":"d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8","analyzedAt":"2026-08-14T00:18:38.915Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}