docs: add QuickJS limitation JSDoc to polyfilled APIs

packages/bedrock-url/src/bedrock-url.ts

@@ -3,6 +3,13 @@ import { URLSearchParams } from './url-search-params'
 const SCHEME = 'bedrock'
 const SCHEME_PREFIX = 'bedrock://'
 
+/**
+ * Minimal URL implementation for the bedrock:// scheme.
+ *
+ * QuickJS polyfill: Minecraft Bedrock Script API does not provide the
+ * standard URL class. This implementation supports the bedrock:// scheme
+ * used for addon-to-addon communication via script events.
+ */
 export class BedrockURL {
   #host = ''
   #hostname = ''

packages/bedrock-url/src/url-search-params.ts

@@ -1,3 +1,10 @@
+/**
+ * Minimal URLSearchParams implementation.
+ *
+ * QuickJS polyfill: Minecraft Bedrock Script API does not provide the
+ * standard URLSearchParams class. This implements the subset needed for
+ * the bedrock:// URL scheme used in addon-to-addon communication.
+ */
 export class URLSearchParams {
   readonly #entries: [string, string][] = []
 

packages/crypto/src/cipher.ts

@@ -7,6 +7,14 @@ import { sha256 } from '@noble/hashes/sha2.js'
 
 const KEY_LENGTH = 32
 
+/**
+ * Fallback random byte generator.
+ *
+ * QuickJS limitation: Minecraft Bedrock Script API does not expose
+ * crypto.getRandomValues or any other CSPRNG. Math.random() (Mersenne Twister)
+ * is used as fallback — NOT cryptographically secure. Users in environments
+ * with CSPRNG access should inject it via CipherOptions.randomBytes.
+ */
 function defaultRandomBytes(bytesLength: number): Uint8Array {
   const out = new Uint8Array(bytesLength)
   for (let i = 0; i < bytesLength; i++) {
@@ -31,6 +39,16 @@ export class Cipher {
     return defaultRandomBytes(length)
   }
 
+  /**
+   * Create a Cipher from a password using HKDF-SHA256 key derivation.
+   *
+   * QuickJS limitation: PBKDF2/scrypt are preferred for password-based KDFs
+   * but their iteration count causes script timeouts in Minecraft Bedrock
+   * Script API. HKDF is used as a lightweight alternative — suitable here
+   * because communication is confined to the local game instance (no remote
+   * brute-force exposure). The salt parameter is REQUIRED for security;
+   * when omitted, a fixed default salt is used (NOT recommended).
+   */
   static fromPassword(password: string, salt?: string | Uint8Array, options?: CipherOptions): Cipher {
     const ikm = utf8Encode(password)
     const saltBytes = salt !== undefined

packages/ipc/src/chunk.ts

@@ -9,6 +9,11 @@ interface PendingPacket {
 /**
  * Splits large serialized payloads into smaller chunks and reassembles them on the receiving end.
  * Used internally by {@link IPC} — you typically don't need to interact with this class directly.
+ *
+ * Note on sizing: String.slice() operates on UTF-16 code units, not bytes.
+ * TextEncoder is unavailable in Minecraft Bedrock Script API (QuickJS),
+ * so chunkSize is expressed in characters (UTF-16 code units). Consumers
+ * handling non-ASCII content should pre-encode to a byte-safe format.
  */
 export class Chunker {
   readonly #chunkSize: number

packages/utils/src/base64.ts

@@ -1,5 +1,11 @@
 import { utf8Decode, utf8Encode } from './textCodec'
 
+/**
+ * Base64 encoding/decoding.
+ *
+ * QuickJS polyfill: atob/btoa are unavailable in Minecraft Bedrock Script API,
+ * so we implement the RFC 4648 algorithm directly.
+ */
 export class Base64 {
   static #CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
 

packages/utils/src/getRandomProbability.ts

@@ -1,5 +1,8 @@
 /**
  * Random Probability
+ *
+ * Note: Uses Math.random() rather than crypto.getRandomValues because
+ * QuickJS in Minecraft Bedrock Script API does not expose a Web Crypto API.
  * @param {number} probability Probability percentage 0.01-100
  * @returns {boolean} The hit probability returns true, and vice versa false
  */

packages/utils/src/getRandomRangeValue.ts

@@ -1,5 +1,8 @@
 /**
  * Random Range Value
+ *
+ * Note: Uses Math.random() rather than crypto.getRandomValues because
+ * QuickJS in Minecraft Bedrock Script API does not expose a Web Crypto API.
  * @param {number} min A random minimum
  * @param {number} max A random maximum
  * @returns {number} A random integer between min and max

packages/utils/src/textCodec.ts

@@ -1,3 +1,7 @@
+/**
+ * QuickJS polyfill: TextEncoder is unavailable in Minecraft Bedrock Script API,
+ * so we use encodeURIComponent to build UTF-8 byte arrays.
+ */
 export function utf8Encode(s: string): Uint8Array {
   const encoded = encodeURIComponent(s)
   const bytes: number[] = []
@@ -13,6 +17,11 @@ export function utf8Encode(s: string): Uint8Array {
   return new Uint8Array(bytes)
 }
 
+/**
+ * QuickJS polyfill: TextDecoder is unavailable, so we use decodeURIComponent
+ * to decode UTF-8 byte arrays back to strings.
+ * @throws {URIError} If the byte sequence is not valid UTF-8
+ */
 export function utf8Decode(bytes: Uint8Array): string {
   let s = ''
   for (const b of bytes) {

packages/utils/src/unique.ts

@@ -1,6 +1,10 @@
 /**
  * Forked from simple-unique (https://github.com/lete114/Simple-Unique)
  * Completely random generation of unique strings
+ *
+ * Note: Uses Math.random() rather than crypto.getRandomValues because
+ * QuickJS in Minecraft Bedrock Script API does not provide a Web Crypto API.
+ * Not suitable for security-sensitive uniqueness (e.g. session tokens).
  * @param size - Length of the random string (default 10)
  */
 export function unique(size: number = 10): string {