M src/util/js-template.ts → src/util/js-template.ts

@@ -3,9 +3,16 @@ * Build a JavaScript source string with safely-interpolated values.
  * Every interpolated value is JSON.stringify'd, so strings, numbers,
  * objects, and special characters all become valid JS literals.
  *
- * This is the ONLY supported way to build evaluation source in the
- * codebase — never use raw template literals for JS that crosses the
- * CDP boundary.
+ * This is the ONLY supported way to interpolate untrusted values into
+ * evaluation source — never use raw template literals for JS that
+ * crosses the CDP boundary. The static parts of the template (the
+ * `strings` array) must remain hard-coded; only the `${...}` slots
+ * are sanitized.
+ *
+ * Values must be JSON-serializable: BigInt and Symbol throw at runtime;
+ * functions and undefined serialize to `undefined`/omitted, which yields
+ * a ReferenceError when evaluated. Pass strings, numbers, booleans,
+ * plain objects, or arrays.
  */
 export const safeJs = (
   strings: TemplateStringsArray,