docs(util): clarify safeJs trust boundary and unsupported value types

1 files changed, 10 insertions, 3 deletions

diff --git a/src/util/js-template.ts b/src/util/js-template.ts
index e536b3d..392dbc0 100644
--- a/src/util/js-template.ts
+++ b/src/util/js-template.ts
@@ -3,9 +3,16 @@
  * 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,