plainscript-lang 1.0.35 → 1.0.361

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +1052 -201
  2. package/compiler/bundler.js +4 -4
  3. package/compiler/cli.js +82 -18
  4. package/compiler/dependency-detector.js +34 -22
  5. package/compiler/generator.js +587 -172
  6. package/compiler/lexer.js +61 -39
  7. package/compiler/parser.js +685 -182
  8. package/compiler/sourcemap.js +1 -1
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +25 -4
  11. package/docs/FB-PROMPT.md +524 -0
  12. package/docs/GAME-PROMPT.md +916 -0
  13. package/docs/PLAINSCRIPT-SPEC.md +135 -5
  14. package/docs/index.html +28 -14
  15. package/docs/website/script.js +1 -1
  16. package/docs/website/style.css +162 -195
  17. package/examples/ai-providers.pln +1 -1
  18. package/examples/arrays.pln +1 -1
  19. package/examples/async-errors.pln +2 -1
  20. package/examples/auth-api.pln +1 -1
  21. package/examples/auth-sessions.pln +1 -1
  22. package/examples/basics.pln +1 -1
  23. package/examples/bots.pln +1 -1
  24. package/examples/browser-interactive/README.md +29 -0
  25. package/examples/browser-interactive/public/index.html +83 -0
  26. package/examples/browser-interactive/public/interactive.js +27 -0
  27. package/examples/browser-interactive/src/interactive.pln +34 -0
  28. package/examples/cache-and-jobs.pln +1 -1
  29. package/examples/cache-schedule.pln +1 -1
  30. package/examples/canvas-game/README.md +34 -0
  31. package/examples/canvas-game/public/game.js +131 -0
  32. package/examples/canvas-game/public/index.html +48 -0
  33. package/examples/canvas-game/src/game.pln +139 -0
  34. package/examples/collections.pln +1 -1
  35. package/examples/concurrency.pln +1 -1
  36. package/examples/conditions.pln +1 -1
  37. package/examples/database.pln +1 -1
  38. package/examples/day2.pln +1 -1
  39. package/examples/day3.pln +1 -1
  40. package/examples/deployment.pln +1 -1
  41. package/examples/email-send.pln +1 -1
  42. package/examples/error-handling.pln +3 -2
  43. package/examples/expressions.pln +1 -1
  44. package/examples/file-uploads.pln +1 -1
  45. package/examples/files-and-config.pln +1 -1
  46. package/examples/files.pln +1 -1
  47. package/examples/football-backend/app.pln +1 -1
  48. package/examples/functions.pln +1 -1
  49. package/examples/hello.pln +1 -1
  50. package/examples/http-client.pln +1 -1
  51. package/examples/http.pln +1 -1
  52. package/examples/id-verification/app.pln +1 -1
  53. package/examples/javascript-library/README.md +54 -0
  54. package/examples/javascript-library/package-lock.json +21 -0
  55. package/examples/javascript-library/package.json +8 -0
  56. package/examples/javascript-library/public/config.json +4 -0
  57. package/examples/javascript-library/public/index.html +40 -0
  58. package/examples/javascript-library/src/interop.pln +53 -0
  59. package/examples/json.pln +1 -1
  60. package/examples/loops.pln +1 -1
  61. package/examples/modules/app.pln +1 -1
  62. package/examples/modules/main.pln +1 -1
  63. package/examples/modules/math.pln +1 -1
  64. package/examples/mongo.pln +1 -1
  65. package/examples/objects.pln +1 -1
  66. package/examples/ocr.pln +1 -1
  67. package/examples/packages.pln +1 -1
  68. package/examples/record-kinds.pln +1 -1
  69. package/examples/records.pln +1 -1
  70. package/examples/rest-api-fetch.pln +1 -1
  71. package/examples/rest-api.pln +1 -1
  72. package/examples/scheduled-tasks.pln +1 -1
  73. package/examples/search-and-filter.pln +1 -1
  74. package/examples/server.pln +1 -1
  75. package/examples/sessions-and-cookies.pln +1 -1
  76. package/examples/sqlite.pln +1 -1
  77. package/examples/start.pln +1 -1
  78. package/examples/stdlib.pln +1 -1
  79. package/examples/string-verbs.pln +1 -1
  80. package/examples/telegram-ai-bot.pln +1 -1
  81. package/examples/telegram-bot.pln +1 -1
  82. package/examples/testing.pln +1 -1
  83. package/examples/three-dimensional/README.md +51 -0
  84. package/examples/three-dimensional/public/index.html +33 -0
  85. package/examples/three-dimensional/src/scene.pln +34 -0
  86. package/examples/web-api.pln +1 -1
  87. package/examples/web-app.pln +1 -1
  88. package/examples/websocket-server.pln +1 -1
  89. package/examples/websocket.pln +1 -1
  90. package/examples/whatsapp-bot/pairing.pln +2 -2
  91. package/examples/whatsapp-bot/qr.pln +2 -2
  92. package/package.json +9 -10
@@ -11,9 +11,9 @@ const KNOWN_PACKAGES = {
11
11
  path: `const path = require('path');`,
12
12
  axios: `const axios = require('axios');`,
13
13
  chalk: `const chalk = require('chalk');`,
14
- // v2.1.0 — PostgreSQL driver behind the friendly "postgres" name.
14
+ // v2.1.0 - PostgreSQL driver behind the friendly "postgres" name.
15
15
  postgres: `const { Pool } = require('pg');`,
16
- // v2.2.0 — MongoDB driver.
16
+ // v2.2.0 - MongoDB driver.
17
17
  mongodb: `const { MongoClient } = require('mongodb');`,
18
18
  };
19
19
 
@@ -22,7 +22,7 @@ const KNOWN_PACKAGES = {
22
22
  const NPM_NAME = {
23
23
  sqlite: 'better-sqlite3',
24
24
  postgres: 'pg',
25
- // v2.1.1 — portable WebAssembly SQLite engine used by the "database"
25
+ // v2.1.1 - portable WebAssembly SQLite engine used by the "database"
26
26
  // statement as an automatic fallback (or explicit choice) when
27
27
  // better-sqlite3's native binding is unavailable.
28
28
  'wasm-sqlite': 'sql.js',
@@ -42,7 +42,7 @@ const BUILTIN_DECLARATIONS = {
42
42
  fs: `const fs = require('fs');`,
43
43
  path: `const path = require('path');`,
44
44
  crypto: `const crypto = require('crypto');`,
45
- // v1.0.1 — env-file runtime. Applies KEY=VALUE pairs from a .env file to
45
+ // v1.0.1 - env-file runtime. Applies KEY=VALUE pairs from a .env file to
46
46
  // process.env. Blank lines and `#` comment lines are skipped.
47
47
  dotenv: [
48
48
  `function __loadEnvFile(path) {`,
@@ -61,7 +61,7 @@ const BUILTIN_DECLARATIONS = {
61
61
  ` }`,
62
62
  `}`,
63
63
  ].join('\n'),
64
- // v1.1.1 — ask runtime (RFC-0011 §14)
64
+ // v1.1.1 - ask runtime (RFC-0011 §14)
65
65
  ask: [
66
66
  `const readline = require('readline');`,
67
67
  `async function __ask(prompt = '') {`,
@@ -73,7 +73,7 @@ const BUILTIN_DECLARATIONS = {
73
73
  ` }`,
74
74
  `}`,
75
75
  ].join('\n'),
76
- // v2.0.1 — OCR runtime (tesseract.js). Extracts text from an image file.
76
+ // v2.0.1 - OCR runtime (tesseract.js). Extracts text from an image file.
77
77
  // The worker is created per call and always terminated, so repeated ocr
78
78
  // statements do not leak workers.
79
79
  ocr: [
@@ -88,7 +88,165 @@ const BUILTIN_DECLARATIONS = {
88
88
  ` }`,
89
89
  `}`,
90
90
  ].join('\n'),
91
- // v1.0.1 — shared runtime helpers for reflection, binary-size, YAML subset
91
+ // v1.0.361 - DOM browser runtime (select/selectAll/parseHTML). Browser
92
+ // globals are guarded so the generated JS explains the problem when it is
93
+ // run under Node instead of failing with a ReferenceError midpoint.
94
+ dom: [
95
+ `function __select(sel) {`,
96
+ ` if (typeof document === 'undefined') throw new Error('select(...) needs a browser (document is not defined in Node).');`,
97
+ ` return document.querySelector(sel);`,
98
+ `}`,
99
+ `function __selectAll(sel) {`,
100
+ ` if (typeof document === 'undefined') throw new Error('selectAll(...) needs a browser (document is not defined in Node).');`,
101
+ ` return [...document.querySelectorAll(sel)];`,
102
+ `}`,
103
+ `function __parseHTML(html) {`,
104
+ ` if (typeof document === 'undefined') throw new Error('parseHTML(...) needs a browser (document is not defined in Node).');`,
105
+ ` const template = document.createElement('template');`,
106
+ ` template.innerHTML = String(html);`,
107
+ ` return template.content;`,
108
+ `}`,
109
+ ].join('\n'),
110
+ // v1.0.361 - input runtime: pointer coordinates, gamepads, dropped files.
111
+ input: [
112
+ `function __localPoint(e, canvas) {`,
113
+ ` if (typeof document === 'undefined') throw new Error('localPoint(...) needs a browser (document is not defined in Node).');`,
114
+ ` const rect = canvas.getBoundingClientRect();`,
115
+ ` return {`,
116
+ ` x: (e.clientX - rect.left) * (canvas.width / rect.width),`,
117
+ ` y: (e.clientY - rect.top) * (canvas.height / rect.height),`,
118
+ ` };`,
119
+ `}`,
120
+ `function __gamepads() {`,
121
+ ` if (typeof navigator === 'undefined' || typeof navigator.getGamepads !== 'function') throw new Error('gamepads() needs a browser with the Gamepad API (navigator.getGamepads).');`,
122
+ ` return navigator.getGamepads().filter(Boolean);`,
123
+ `}`,
124
+ `function __droppedFiles(event) {`,
125
+ ` return [...(event && event.dataTransfer ? event.dataTransfer.files : [])];`,
126
+ `}`,
127
+ ].join('\n'),
128
+ // v1.0.361 - asset-loading runtime (images, JSON, bytes, data URLs). All
129
+ // helpers return promises; the STDLIB entries await them.
130
+ assets: [
131
+ `function __loadImage(url) {`,
132
+ ` if (typeof Image === 'undefined') throw new Error('loadImage(...) needs a browser (global Image is not defined in Node).');`,
133
+ ` return new Promise((resolve, reject) => {`,
134
+ ` const img = new Image();`,
135
+ ` img.onload = () => resolve(img);`,
136
+ ` img.onerror = () => reject(new Error('Could not load image: ' + url));`,
137
+ ` img.src = String(url);`,
138
+ ` });`,
139
+ `}`,
140
+ `async function __fetchJson(url) {`,
141
+ ` if (typeof fetch === 'undefined') throw new Error('fetchJson(...) needs a browser or Node 18+ with global fetch.');`,
142
+ ` const response = await fetch(url);`,
143
+ ` const text = await response.text();`,
144
+ ` let data = null;`,
145
+ ` let parseError = null;`,
146
+ ` try { data = JSON.parse(text); } catch (e) { parseError = e.message; }`,
147
+ ` return { ok: response.ok, status: response.status, data, text, parseError };`,
148
+ `}`,
149
+ `async function __fetchBytes(url) {`,
150
+ ` if (typeof fetch === 'undefined') throw new Error('fetchBytes(...) needs a browser or Node 18+ with global fetch.');`,
151
+ ` const response = await fetch(url);`,
152
+ ` const buffer = await response.arrayBuffer();`,
153
+ ` return { ok: response.ok, status: response.status, data: new Uint8Array(buffer) };`,
154
+ `}`,
155
+ `function __readDataUrl(file) {`,
156
+ ` if (typeof FileReader === 'undefined') throw new Error('readDataUrl(...) needs a browser (FileReader is not defined in Node).');`,
157
+ ` return new Promise((resolve, reject) => {`,
158
+ ` const reader = new FileReader();`,
159
+ ` reader.onload = () => resolve(reader.result);`,
160
+ ` reader.onerror = () => reject(new Error('Could not read the file as a data URL.'));`,
161
+ ` reader.readAsDataURL(file);`,
162
+ ` });`,
163
+ `}`,
164
+ ].join('\n'),
165
+ // v1.0.361 - Web Audio runtime. The AudioContext is created once and shared
166
+ // (browsers cap the number), and resumed on demand because autoplay policies
167
+ // start it suspended.
168
+ audio: [
169
+ `let __plainAudioCtx = null;`,
170
+ `function __audioContext() {`,
171
+ ` if (typeof window === 'undefined' && typeof self === 'undefined') throw new Error('audioContext() / playTone(...) need a browser (Web Audio is not available in Node).');`,
172
+ ` if (!__plainAudioCtx) {`,
173
+ ` const Ctx = window.AudioContext || window.webkitAudioContext;`,
174
+ ` if (!Ctx) throw new Error('Web Audio is not supported in this browser.');`,
175
+ ` __plainAudioCtx = new Ctx();`,
176
+ ` }`,
177
+ ` if (__plainAudioCtx.state === 'suspended') __plainAudioCtx.resume();`,
178
+ ` return __plainAudioCtx;`,
179
+ `}`,
180
+ `function __audioTone(freq, seconds, opts) {`,
181
+ ` const ctx = __audioContext();`,
182
+ ` const o = opts || {};`,
183
+ ` const oscillator = ctx.createOscillator();`,
184
+ ` const gain = ctx.createGain();`,
185
+ ` const duration = seconds || 0.5;`,
186
+ ` oscillator.type = o.type || 'sine';`,
187
+ ` oscillator.frequency.value = freq;`,
188
+ ` gain.gain.value = o.gain || 0.2;`,
189
+ ` oscillator.connect(gain);`,
190
+ ` gain.connect(ctx.destination);`,
191
+ ` const t = ctx.currentTime;`,
192
+ ` if (o.when) oscillator.start(t + o.when); else oscillator.start(t);`,
193
+ ` gain.gain.setValueAtTime(o.gain || 0.2, t);`,
194
+ ` gain.gain.exponentialRampToValueAtTime(0.0001, t + duration);`,
195
+ ` oscillator.stop(t + duration);`,
196
+ `}`,
197
+ `function __loadAudio(url) {`,
198
+ ` if (typeof Audio === 'undefined') throw new Error('loadAudio(...) needs a browser (global Audio is not defined in Node).');`,
199
+ ` return new Promise((resolve, reject) => {`,
200
+ ` const audio = new Audio();`,
201
+ ` audio.oncanplaythrough = () => resolve(audio);`,
202
+ ` audio.onerror = () => reject(new Error('Could not load audio: ' + url));`,
203
+ ` audio.src = String(url);`,
204
+ ` audio.load();`,
205
+ ` });`,
206
+ `}`,
207
+ ].join('\n'),
208
+ // v1.0.361 - WebGL runtime: context selection plus the three compile/link/
209
+ // buffer helpers behind the gl* stdlib entries.
210
+ gl: [
211
+ `function __glContext(canvas) {`,
212
+ ` if (typeof document === 'undefined') throw new Error('webglContext(...) needs a browser (document is not defined in Node).');`,
213
+ ` const gl = canvas.getContext('webgl2') || canvas.getContext('webgl') || canvas.getContext('experimental-webgl');`,
214
+ ` if (!gl) throw new Error('WebGL is not supported in this browser.');`,
215
+ ` return gl;`,
216
+ `}`,
217
+ `function __glShader(gl, type, source) {`,
218
+ ` // Accept both the friendly names ("vertex"/"fragment") and the DOM`,
219
+ ` // constant names ("VERTEX_SHADER"/"FRAGMENT_SHADER").`,
220
+ ` const kind = type === 'vertex' || type === 'VERTEX_SHADER' ? gl.VERTEX_SHADER : gl.FRAGMENT_SHADER;`,
221
+ ` const shader = gl.createShader(kind);`,
222
+ ` gl.shaderSource(shader, source);`,
223
+ ` gl.compileShader(shader);`,
224
+ ` if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {`,
225
+ ` const info = gl.getShaderInfoLog(shader);`,
226
+ ` gl.deleteShader(shader);`,
227
+ ` throw new Error('Shader compile error: ' + (info || 'unknown'));`,
228
+ ` }`,
229
+ ` return shader;`,
230
+ `}`,
231
+ `function __glProgram(gl, vertexShader, fragmentShader) {`,
232
+ ` const program = gl.createProgram();`,
233
+ ` gl.attachShader(program, vertexShader);`,
234
+ ` gl.attachShader(program, fragmentShader);`,
235
+ ` gl.linkProgram(program);`,
236
+ ` if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {`,
237
+ ` const info = gl.getProgramInfoLog(program);`,
238
+ ` throw new Error('Program link error: ' + (info || 'unknown'));`,
239
+ ` }`,
240
+ ` return program;`,
241
+ `}`,
242
+ `function __glBuffer(gl, data) {`,
243
+ ` const buffer = gl.createBuffer();`,
244
+ ` gl.bindBuffer(gl.ARRAY_BUFFER, buffer);`,
245
+ ` gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);`,
246
+ ` return buffer;`,
247
+ `}`,
248
+ ].join('\n'),
249
+ // v1.0.1 - shared runtime helpers for reflection, binary-size, YAML subset
92
250
  // parsing/emitting, spread of timeouts, and set/map helpers. Injected lazily
93
251
  // when any feature that needs them is used.
94
252
  core: [
@@ -221,11 +379,12 @@ const BUILTIN_DECLARATIONS = {
221
379
  ` });`,
222
380
  `}`,
223
381
  ].join('\n'),
224
- // v1.0.35 — dependency-free SVG images and visualizations.
382
+ // v1.0.35 - dependency-free SVG images and visualizations.
225
383
  // The image value is an SVG string, so it can be saved, embedded, or returned
226
384
  // from a web route without a native graphics dependency.
227
385
  visualization: [
228
386
  `const __vizFs = require('fs');`,
387
+ `const __vizPath = require('path');`,
229
388
  `function __svgEscape(value) {`,
230
389
  ` return String(value == null ? '' : value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');`,
231
390
  `}`,
@@ -304,6 +463,7 @@ const BUILTIN_DECLARATIONS = {
304
463
  `}`,
305
464
  `function __saveImage(file, image) {`,
306
465
  ` const target = String(file);`,
466
+ ` __vizFs.mkdirSync(__vizPath.dirname(target), { recursive: true });`,
307
467
  ` __vizFs.writeFileSync(target, String(image == null ? '' : image), 'utf8');`,
308
468
  ` return target;`,
309
469
  `}`,
@@ -311,7 +471,7 @@ const BUILTIN_DECLARATIONS = {
311
471
  ` return 'data:image/svg+xml;base64,' + Buffer.from(String(image == null ? '' : image), 'utf8').toString('base64');`,
312
472
  `}`,
313
473
  ].join('\n'),
314
- // v1.0.1 — process execution (child processes).
474
+ // v1.0.1 - process execution (child processes).
315
475
  process: [
316
476
  `const { execFile } = require('child_process');`,
317
477
  `function __runCommand(command, args) {`,
@@ -322,11 +482,11 @@ const BUILTIN_DECLARATIONS = {
322
482
  ` });`,
323
483
  `}`,
324
484
  ].join('\n'),
325
- // v1.0.1 — Map helpers.
485
+ // v1.0.1 - Map helpers.
326
486
  mapset: [
327
487
  `function __mapSet(map, key, value) { map.set(key, value); return map; }`,
328
488
  ].join('\n'),
329
- // v2.2.0 — collection primitives (flatten / pick / omit / groupBy).
489
+ // v2.2.0 - collection primitives (flatten / pick / omit / groupBy).
330
490
  coll: [
331
491
  `function __flatten(list) {`,
332
492
  ` const out = [];`,
@@ -369,7 +529,7 @@ const BUILTIN_DECLARATIONS = {
369
529
  ` return { items: slice, count: total, page, pages, perPage, hasNext: page < pages, hasPrev: page > 1 };`,
370
530
  `}`,
371
531
  ].join('\n'),
372
- // v1.0.1 — dynamic module loader.
532
+ // v1.0.1 - dynamic module loader.
373
533
  loadmodule: [
374
534
  `function __loadModule(spec) {`,
375
535
  ` const path = require('path');`,
@@ -378,7 +538,7 @@ const BUILTIN_DECLARATIONS = {
378
538
  ` catch (e) { if (spec[0] !== '.') return require(spec); throw e; }`,
379
539
  `}`,
380
540
  ].join('\n'),
381
- // v1.0.1 — recursive directory walker (returns full paths, files first).
541
+ // v1.0.1 - recursive directory walker (returns full paths, files first).
382
542
  walk: [
383
543
  `function __walkFolder(dir) {`,
384
544
  ` const fs = require('fs');`,
@@ -396,7 +556,7 @@ const BUILTIN_DECLARATIONS = {
396
556
  ` return out;`,
397
557
  `}`,
398
558
  ].join('\n'),
399
- // v2.1.0 — request validation runtime. Returns the names of required
559
+ // v2.1.0 - request validation runtime. Returns the names of required
400
560
  // fields whose value is missing (undefined/null/empty string) in data.
401
561
  validation: [
402
562
  `function __validate(data, fields) {`,
@@ -406,7 +566,7 @@ const BUILTIN_DECLARATIONS = {
406
566
  ` });`,
407
567
  `}`,
408
568
  ].join('\n'),
409
- // v2.1.0 — email runtime (nodemailer). One transport per program; sending
569
+ // v2.1.0 - email runtime (nodemailer). One transport per program; sending
410
570
  // fails with a teaching error when no transport was configured.
411
571
  mailer: [
412
572
  `const nodemailer = require('nodemailer');`,
@@ -417,12 +577,12 @@ const BUILTIN_DECLARATIONS = {
417
577
  ` return __mailTransport.sendMail(options);`,
418
578
  `}`,
419
579
  ].join('\n'),
420
- // v2.1.0 — cron scheduling runtime (croner). Zero dependencies, validates
580
+ // v2.1.0 - cron scheduling runtime (croner). Zero dependencies, validates
421
581
  // expressions at registration time.
422
582
  scheduler: [
423
583
  `const cron = require('croner');`,
424
584
  ].join('\n'),
425
- // v2.1.0 — WebSocket runtime (ws). Standalone server bound to its own port.
585
+ // v2.1.0 - WebSocket runtime (ws). Standalone server bound to its own port.
426
586
  websocket: [
427
587
  `const { WebSocketServer } = require('ws');`,
428
588
  `function __wsServerCreate(port, handlers) {`,
@@ -446,7 +606,7 @@ const BUILTIN_DECLARATIONS = {
446
606
  ` }`,
447
607
  `}`,
448
608
  ].join('\n'),
449
- // v2.1.0 — cache runtime (Redis via the redis package). The client is
609
+ // v2.1.0 - cache runtime (Redis via the redis package). The client is
450
610
  // created by the "cache" statement; accessors fail with a teaching error
451
611
  // when no cache was configured.
452
612
  cache: [
@@ -473,7 +633,7 @@ const BUILTIN_DECLARATIONS = {
473
633
  ` return __memCache.delete(key) ? 1 : 0;`,
474
634
  `}`,
475
635
  ].join('\n'),
476
- // v2.1.1 — WhatsApp runtime (@whiskeysockets/baileys behind the
636
+ // v2.1.1 - WhatsApp runtime (@whiskeysockets/baileys behind the
477
637
  // "whatsapp bot" block). Everything Baileys-shaped stays in here: socket
478
638
  // creation, auth-state files, QR rendering, pairing codes, connection
479
639
  // lifecycle and messages.upsert normalization. PlainScript programs only ever
@@ -481,7 +641,7 @@ const BUILTIN_DECLARATIONS = {
481
641
  whatsapp: [
482
642
  `const { __whatsappStart, __whatsappPair, __whatsappOnMessage, __whatsappReply, __whatsappSend, __whatsappDownload } = (() => {`,
483
643
  ` let sock = null;`,
484
- ` let __waBaileysPkg = '@qwerty-xcv/baileys';`,
644
+ ` let __waBaileysPkg = '@whiskeysockets/baileys';`,
485
645
  ` const handlers = [];`,
486
646
  ` const __waSilentLogger = (() => {`,
487
647
  ` const noop = () => {};`,
@@ -591,7 +751,7 @@ const BUILTIN_DECLARATIONS = {
591
751
  ` }`,
592
752
  ` function __whatsappOnMessage(handler) { handlers.push(handler); }`,
593
753
  ` async function __whatsappStart(options) {`,
594
- ` __waBaileysPkg = options.baileys || '@qwerty-xcv/baileys';`,
754
+ ` __waBaileysPkg = options.baileys || '@whiskeysockets/baileys';`,
595
755
  ` const baileys = require(__waBaileysPkg);`,
596
756
  ` const makeWASocket = baileys.default;`,
597
757
  ` const { useMultiFileAuthState, makeCacheableSignalKeyStore, DisconnectReason } = baileys;`,
@@ -606,7 +766,7 @@ const BUILTIN_DECLARATIONS = {
606
766
  // Auth/session persistence: useMultiFileAuthState stores credentials in
607
767
  // the folder from `auth "<name>"`; saveCreds writes every update back.
608
768
  ` const { state, saveCreds } = await useMultiFileAuthState(folder);`,
609
- // v2.14 — adopt the proven pairing-safe socket settings used by the
769
+ // v2.14 - adopt the proven pairing-safe socket settings used by the
610
770
  // reference Dual-Crasher build on the qwerty fork: a fixed Baileys protocol
611
771
  // version and the exact browser fingerprint that survives WhatsApp's
612
772
  // handshake without a 428 connection close.
@@ -623,7 +783,7 @@ const BUILTIN_DECLARATIONS = {
623
783
  ` auth: { creds: state.creds, keys: makeCacheableSignalKeyStore(state.keys, __waSilentLogger) },`,
624
784
  ` });`,
625
785
  ` sock.ev.on('creds.update', saveCreds);`,
626
- // Pairing codes are requested two seconds after socket creation — asking
786
+ // Pairing codes are requested two seconds after socket creation - asking
627
787
  // earlier aborts the link attempt. PlainScript retries a few times (spam)
628
788
  // so a dropped request never blocks linking. The number was validated at
629
789
  // compile time; no custom suffix is applied.
@@ -823,7 +983,7 @@ const BUILTIN_DECLARATIONS = {
823
983
  ` return { __whatsappStart, __whatsappPair, __whatsappOnMessage, __whatsappReply, __whatsappSend, __whatsappDownload };`,
824
984
  `})();`,
825
985
  ].join('\n'),
826
- // v2.1.1 — HTTP client runtime on the global fetch API (Node.js 18+).
986
+ // v2.1.1 - HTTP client runtime on the global fetch API (Node.js 18+).
827
987
  // Every response becomes a PlainScript-friendly record: { ok, status, headers,
828
988
  // data }, where data holds parsed JSON when the content type says JSON.
829
989
  http: [
@@ -860,7 +1020,7 @@ const BUILTIN_DECLARATIONS = {
860
1020
  ` return { ok: response.ok, status: response.status, headers: Object.fromEntries(response.headers.entries()), data };`,
861
1021
  `}`,
862
1022
  ].join('\n'),
863
- // v2.2.0 — provider-neutral AI runtime. `chat` and `embedText` speak
1023
+ // v2.2.0 - provider-neutral AI runtime. `chat` and `embedText` speak
864
1024
  // OpenAI-compatible APIs, including Groq, OpenRouter, Together, Fireworks,
865
1025
  // and DeepSeek. A custom `base` and `key` can be supplied per call.
866
1026
  ai: [
@@ -920,7 +1080,7 @@ const BUILTIN_DECLARATIONS = {
920
1080
  ` return dot / (Math.sqrt(na) * Math.sqrt(nb));`,
921
1081
  `}`,
922
1082
  ].join('\n'),
923
- // v2.1.1 — file upload runtime (multer behind "accept uploads"). Files are
1083
+ // v2.1.1 - file upload runtime (multer behind "accept uploads"). Files are
924
1084
  // held in memory by default or written to disk when a folder is given.
925
1085
  // Normalised records expose: name, type, size, data (buffer) and path.
926
1086
  uploads: [
@@ -964,7 +1124,7 @@ const BUILTIN_DECLARATIONS = {
964
1124
  ` return (req.files || []).filter((f) => f.fieldname === field).map(__normalizeUpload);`,
965
1125
  `}`,
966
1126
  ].join('\n'),
967
- // v2.1.1 — cookie helpers shared by the cookie() accessor and the session
1127
+ // v2.1.1 - cookie helpers shared by the cookie() accessor and the session
968
1128
  // runtime.
969
1129
  cookies: [
970
1130
  `function __parseCookies(header) {`,
@@ -985,7 +1145,7 @@ const BUILTIN_DECLARATIONS = {
985
1145
  ` return value === undefined ? null : value;`,
986
1146
  `}`,
987
1147
  ].join('\n'),
988
- // v2.1.1 — session runtime. Cookie-signed session ids backed by an
1148
+ // v2.1.1 - session runtime. Cookie-signed session ids backed by an
989
1149
  // in-memory store (sessions reset when the server restarts).
990
1150
  sessions: [
991
1151
  `const __sessionStore = new Map();`,
@@ -1028,7 +1188,7 @@ const BUILTIN_DECLARATIONS = {
1028
1188
  ` response.setHeader('Set-Cookie', 'plainscript.sid=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0');`,
1029
1189
  `}`,
1030
1190
  ].join('\n'),
1031
- // v2.1.1 — authentication runtime: scrypt password hashing and signed
1191
+ // v2.1.1 - authentication runtime: scrypt password hashing and signed
1032
1192
  // tokens (HS256 format), both zero-dependency.
1033
1193
  auth: [
1034
1194
  `const __authCrypto = require('crypto');`,
@@ -1073,7 +1233,7 @@ const BUILTIN_DECLARATIONS = {
1073
1233
  ` }`,
1074
1234
  `}`,
1075
1235
  ].join('\n'),
1076
- // v2.1.1 — Google sign-in (OAuth 2.0 authorization code flow). Registers
1236
+ // v2.1.1 - Google sign-in (OAuth 2.0 authorization code flow). Registers
1077
1237
  // two endpoints: /auth/google (redirect) and the configured callback URL
1078
1238
  // (token exchange + profile fetch), then redirects to the landing page.
1079
1239
  oauth: [
@@ -1128,7 +1288,7 @@ const BUILTIN_DECLARATIONS = {
1128
1288
  ` });`,
1129
1289
  `}`,
1130
1290
  ].join('\n'),
1131
- // v2.1.1 — per-IP request rate limiting with an in-memory sliding window.
1291
+ // v2.1.1 - per-IP request rate limiting with an in-memory sliding window.
1132
1292
  ratelimit: [
1133
1293
  `function __rateLimit(options) {`,
1134
1294
  ` const hits = new Map();`,
@@ -1153,13 +1313,13 @@ const BUILTIN_DECLARATIONS = {
1153
1313
  ` };`,
1154
1314
  `}`,
1155
1315
  ].join('\n'),
1156
- // v2.1.1 — pause helper for "retry N times every N seconds".
1316
+ // v2.1.1 - pause helper for "retry N times every N seconds".
1157
1317
  retry: [
1158
1318
  `const __retrySleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));`,
1159
1319
  ].join('\n'),
1160
- // IOPL-native — event emitter runtime.
1320
+ // IOPL-native - event emitter runtime.
1161
1321
  __emitter: 'const __emitter = new (require("events").EventEmitter)();',
1162
- // IOPL-native — line-by-line file streaming runtime.
1322
+ // IOPL-native - line-by-line file streaming runtime.
1163
1323
  __streamFile: [
1164
1324
  `async function __streamFile(path, fn) {`,
1165
1325
  ` const fs = require('fs');`,
@@ -1167,7 +1327,7 @@ const BUILTIN_DECLARATIONS = {
1167
1327
  ` for await (const line of rl) await fn(line);`,
1168
1328
  `}`,
1169
1329
  ].join('\n'),
1170
- // v2.1.1 — SQLite runtime with a portable engine chain. Default order:
1330
+ // v2.1.1 - SQLite runtime with a portable engine chain. Default order:
1171
1331
  // better-sqlite3 (native binding) first, sql.js (WebAssembly) as fallback.
1172
1332
  // Both engines are wrapped in the same tiny synchronous surface that PlainScript
1173
1333
  // generates (prepare().all()/.run(), exec(), transaction()), so compiled
@@ -1385,7 +1545,7 @@ const BUILTIN_DECLARATIONS = {
1385
1545
  ` inline_keyboard: [rows.map(([text, data]) => ({ text, callback_data: data }))],`,
1386
1546
  ` },`,
1387
1547
  ` });`,
1388
- // v2.0.1 — createTelegramBot is defined inside this module so its handler
1548
+ // v2.0.1 - createTelegramBot is defined inside this module so its handler
1389
1549
  // registry (`handlers`) and API transport (`call`, `sleep`) are in scope.
1390
1550
  // Defining it outside made every BOT.onCommand/onPattern/onCallback call
1391
1551
  // throw "ReferenceError: handlers is not defined", so no rendered inline
@@ -1504,11 +1664,11 @@ const BUILTIN_DECLARATIONS = {
1504
1664
  symbolSpecies: (_args) => `Symbol.species`,
1505
1665
  // Runtime constructors
1506
1666
  sqlite: (args, context) => `new Database(${args.map(arg => generateExpr(arg, context)).join(', ')})`,
1507
- // v0.6 — runtime standard library
1667
+ // v0.6 - runtime standard library
1508
1668
  print: (args, context) => `console.log(${args.map(arg => generateExpr(arg, context)).join(', ')})`,
1509
1669
  readFile: (args, context) => `fs.readFileSync(${generateExpr(args[0], context)}, 'utf8')`,
1510
1670
  writeFile: (args, context) => `fs.writeFileSync(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)}, 'utf8')`,
1511
- // v2.4.0 — dependency-free SVG image and visualization helpers.
1671
+ // v2.4.0 - dependency-free SVG image and visualization helpers.
1512
1672
  svgImage: (args, context) => {
1513
1673
  ensureBuiltin(context, 'visualization');
1514
1674
  return `__svgImage(${args.map(arg => generateExpr(arg, context)).join(', ')})`;
@@ -1539,7 +1699,7 @@ const BUILTIN_DECLARATIONS = {
1539
1699
  env: (args, context) => `process.env[${generateExpr(args[0], context)}]`,
1540
1700
  exit: (args, context) => `process.exit(${args.length ? generateExpr(args[0], context) : '0'})`,
1541
1701
  uuid: (_args, context) => `crypto.randomUUID()`,
1542
- // v1.2 — Telegram runtime helpers
1702
+ // v1.2 - Telegram runtime helpers
1543
1703
  bot: (args, context) => {
1544
1704
  ensureBuiltin(context, 'telegram');
1545
1705
  markAsync(context);
@@ -1581,7 +1741,7 @@ const BUILTIN_DECLARATIONS = {
1581
1741
  const params = args.length > 1 ? generateExpr(args[1], context) : '{}';
1582
1742
  return `await Telegram.call(${method}, ${params})`;
1583
1743
  },
1584
- // v2.1.0 — HTTP request accessors. Only meaningful inside a route handler,
1744
+ // v2.1.0 - HTTP request accessors. Only meaningful inside a route handler,
1585
1745
  // where Express provides req/res.
1586
1746
  param: (args, context) => routeAccessor('param', 'params', args, context),
1587
1747
  query: (args, context) => routeAccessor('query', 'query', args, context),
@@ -1598,13 +1758,13 @@ const BUILTIN_DECLARATIONS = {
1598
1758
  if (!args || args.length === 0) return base;
1599
1759
  return `${base}[${generateExpr(args[0], context)}]`;
1600
1760
  },
1601
- // v2.1.0 — request validation. Returns the list of missing required fields.
1761
+ // v2.1.0 - request validation. Returns the list of missing required fields.
1602
1762
  validate: (args, context) => {
1603
1763
  ensureBuiltin(context, 'validation');
1604
1764
  return `__validate(${args.map(arg => generateExpr(arg, context)).join(', ')})`;
1605
1765
  },
1606
1766
 
1607
- // ── v2.1.0 — filesystem helpers (sync, matching readFile/writeFile style)
1767
+ // ── v2.1.0 - filesystem helpers (sync, matching readFile/writeFile style)
1608
1768
 
1609
1769
  copyFile: (args, context) => { ensureBuiltin(context, 'fs'); return `fs.copyFileSync(${args.map(a => generateExpr(a, context)).join(', ')})`; },
1610
1770
  moveFile: (args, context) => { ensureBuiltin(context, 'fs'); return `fs.renameSync(${args.map(a => generateExpr(a, context)).join(', ')})`; },
@@ -1622,7 +1782,7 @@ const BUILTIN_DECLARATIONS = {
1622
1782
  return `fs.writeFileSync(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`;
1623
1783
  },
1624
1784
 
1625
- // ── v2.1.0 — text, number and collection helpers
1785
+ // ── v2.1.0 - text, number and collection helpers
1626
1786
 
1627
1787
  trim: (args, context) => `String(${generateExpr(args[0], context)}).trim()`,
1628
1788
  replace: (args, context) => {
@@ -1653,7 +1813,7 @@ const BUILTIN_DECLARATIONS = {
1653
1813
  hasKey: (args, context) => `Object.prototype.hasOwnProperty.call(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
1654
1814
  merge: (args, context) => `{ ...${generateExpr(args[0], context)}, ...${generateExpr(args[1], context)} }`,
1655
1815
 
1656
- // ── v2.2.0 — collection & string primitives (IOPL-native, dependency-free).
1816
+ // ── v2.2.0 - collection & string primitives (IOPL-native, dependency-free).
1657
1817
  // A numeric range [start..end], stepping by 1 (or `step` when given).
1658
1818
  range: (args, context) => {
1659
1819
  const start = generateExpr(args[0], context);
@@ -1670,7 +1830,11 @@ const BUILTIN_DECLARATIONS = {
1670
1830
  ensureBuiltin(context, 'coll');
1671
1831
  return `__flatten(${generateExpr(args[0], context)})`;
1672
1832
  },
1673
- includes: (args, context) => `(${generateExpr(args[0], context)}).includes(${generateExpr(args[1], context)})`,
1833
+ includes: (args, context) => {
1834
+ const coll = generateExpr(args[0], context);
1835
+ const val = generateExpr(args[1], context);
1836
+ return `(${coll} instanceof Set ? ${coll}.has(${val}) : (${coll}).includes(${val}))`;
1837
+ },
1674
1838
  paginate: (args, context) => {
1675
1839
  ensureBuiltin(context, 'coll');
1676
1840
  return `__paginate(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)}, ${args.length > 2 ? generateExpr(args[2], context) : '10'})`;
@@ -1698,7 +1862,7 @@ const BUILTIN_DECLARATIONS = {
1698
1862
  padStart: (args, context) => `String(${generateExpr(args[0], context)}).padStart(${generateExpr(args[1], context)}, String(${args.length > 2 ? generateExpr(args[2], context) : '" "'}))`,
1699
1863
  padEnd: (args, context) => `String(${generateExpr(args[0], context)}).padEnd(${generateExpr(args[1], context)}, String(${args.length > 2 ? generateExpr(args[2], context) : '" "'}))`,
1700
1864
 
1701
- // ── v2.3.0 — Proxy and Reflect (IOPL-native).
1865
+ // ── v2.3.0 - Proxy and Reflect (IOPL-native).
1702
1866
  // Proxy creation: proxy(target, handler)
1703
1867
  proxy: (args, context) => `new Proxy(${args.map(a => generateExpr(a, context)).join(', ')})`,
1704
1868
  // Proxy revocable: proxyRevocable(target, handler) -> { proxy, revoke }
@@ -1718,8 +1882,8 @@ const BUILTIN_DECLARATIONS = {
1718
1882
  reflectSet: (args, context) => `Reflect.set(${args.map(a => generateExpr(a, context)).join(', ')})`,
1719
1883
  reflectSetPrototypeOf: (args, context) => `Reflect.setPrototypeOf(${args.map(a => generateExpr(a, context)).join(', ')})`,
1720
1884
 
1721
- // ── v1.0.1 — nullable / regex / date helpers (IOPL-native).
1722
- // first non-null, non-undefined argument — IOPL null-coalescing.
1885
+ // ── v1.0.1 - nullable / regex / date helpers (IOPL-native).
1886
+ // first non-null, non-undefined argument - IOPL null-coalescing.
1723
1887
  coalesce: (args, context) =>
1724
1888
  `(() => { const __vals = [${args.map(a => generateExpr(a, context)).join(', ')}]; for (const __v of __vals) if (__v !== null && __v !== undefined) return __v; return undefined; })()`,
1725
1889
  // regex-aware replace (replace() is literal-only).
@@ -1735,7 +1899,7 @@ const BUILTIN_DECLARATIONS = {
1735
1899
  return `__formatDate(${value}, ${pattern})`;
1736
1900
  },
1737
1901
 
1738
- // ── v1.0.2 — Native Date/DateTime/Regex support (IOPL-native, no JS gateway needed).
1902
+ // ── v1.0.2 - Native Date/DateTime/Regex support (IOPL-native, no JS gateway needed).
1739
1903
  // Create a new Date object. With no args: now. With 1 arg: parse ISO string or timestamp.
1740
1904
  // With multiple args: year, month (1-12), day, hour, min, sec, ms.
1741
1905
  newDate: (args, context) => {
@@ -1873,7 +2037,7 @@ const BUILTIN_DECLARATIONS = {
1873
2037
  return `${text}.split(new RegExp(${pattern}, ${flags}))`;
1874
2038
  },
1875
2039
 
1876
- // ── v2.1.0 — cache (Redis) accessors. All async.
2040
+ // ── v2.1.0 - cache (Redis) accessors. All async.
1877
2041
 
1878
2042
  cacheGet: (args, context) => {
1879
2043
  ensureBuiltin(context, 'cache');
@@ -1896,14 +2060,14 @@ const BUILTIN_DECLARATIONS = {
1896
2060
  return `await __cacheDelete(String(${generateExpr(args[0], context)}))`;
1897
2061
  },
1898
2062
 
1899
- // v2.1.0 — email sending helper (statement form uses this too).
2063
+ // v2.1.0 - email sending helper (statement form uses this too).
1900
2064
  sendMail: (args, context) => {
1901
2065
  ensureBuiltin(context, 'mailer');
1902
2066
  markAsync(context);
1903
2067
  return `__mailSend(${args.map(arg => generateExpr(arg, context)).join(', ')})`;
1904
2068
  },
1905
2069
 
1906
- // ── v2.1.1 — uploads, cookies, passwords and tokens
2070
+ // ── v2.1.1 - uploads, cookies, passwords and tokens
1907
2071
 
1908
2072
  // upload("field") / uploads("field") read files registered by
1909
2073
  // "accept uploads". Single file → record or null; plural → array.
@@ -1946,7 +2110,7 @@ const BUILTIN_DECLARATIONS = {
1946
2110
  return `readToken(${args.map(arg => generateExpr(arg, context)).join(', ')})`;
1947
2111
  },
1948
2112
 
1949
- // ── v1.0.1 — capability-gap stdlib (reflection, binary, concurrency, ...) ──
2113
+ // ── v1.0.1 - capability-gap stdlib (reflection, binary, concurrency, ...) ──
1950
2114
 
1951
2115
  // Reflection
1952
2116
  typeOf: (args, context) => { ensureBuiltin(context, 'core'); return `__typeOf(${generateExpr(args[0], context)})`; },
@@ -1977,7 +2141,7 @@ const BUILTIN_DECLARATIONS = {
1977
2141
  return `crypto.createHash('md5').update(String(${generateExpr(args[0], context)})).digest('hex')`;
1978
2142
  },
1979
2143
 
1980
- // Serialization — minimal dependency-free YAML subset (see __yamlParse).
2144
+ // Serialization - minimal dependency-free YAML subset (see __yamlParse).
1981
2145
  yamlDecode: (args, context) => { ensureBuiltin(context, 'core'); return `__yamlParse(${generateExpr(args[0], context)})`; },
1982
2146
  yamlEncode: (args, context) => { ensureBuiltin(context, 'core'); return `__yamlStringify(${generateExpr(args[0], context)})`; },
1983
2147
 
@@ -2007,7 +2171,7 @@ const BUILTIN_DECLARATIONS = {
2007
2171
  // Generators / iterables
2008
2172
  spread: (args, context) => `[...${generateExpr(args[0], context)}]`,
2009
2173
 
2010
- // v1.0.1 — dynamic module loading (the runtime companion to `import "./x.pt"`).
2174
+ // v1.0.1 - dynamic module loading (the runtime companion to `import "./x.pt"`).
2011
2175
  // Resolves relative to the bundler's CWD so `loadModule("./m")` behaves like
2012
2176
  // `require.resolve` from the program root.
2013
2177
  loadModule: (args, context) => {
@@ -2015,7 +2179,7 @@ const BUILTIN_DECLARATIONS = {
2015
2179
  return `__loadModule(${generateExpr(args[0], context)})`;
2016
2180
  },
2017
2181
 
2018
- // ── v2.2.0 — AI/ML. `chat`/`embedText` call an OpenAI-compatible endpoint
2182
+ // ── v2.2.0 - AI/ML. `chat`/`embedText` call an OpenAI-compatible endpoint
2019
2183
  // (key from OPENAI_API_KEY, base from OPENAI_BASE_URL); `similarity` runs
2020
2184
  // offline cosine similarity over any two equal-length numeric vectors.
2021
2185
  chat: (args, context) => {
@@ -2116,7 +2280,7 @@ const BUILTIN_DECLARATIONS = {
2116
2280
  return `fs.appendFileSync(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)} + '\\n', 'utf8')`;
2117
2281
  },
2118
2282
 
2119
- // ── v1.0.2 — Extended Math functions (IOPL-native).
2283
+ // ── v1.0.2 - Extended Math functions (IOPL-native).
2120
2284
  abs: (args, context) => `Math.abs(${generateExpr(args[0], context)})`,
2121
2285
  min: (args, context) => `Math.min(${args.map(a => generateExpr(a, context)).join(', ')})`,
2122
2286
  max: (args, context) => `Math.max(${args.map(a => generateExpr(a, context)).join(', ')})`,
@@ -2156,7 +2320,7 @@ const BUILTIN_DECLARATIONS = {
2156
2320
  hypot: (args, context) => `Math.hypot(${args.map(a => generateExpr(a, context)).join(', ')})`,
2157
2321
  cbrt: (args, context) => `Math.cbrt(${generateExpr(args[0], context)})`,
2158
2322
 
2159
- // ── v1.0.2 — Extended String functions (IOPL-native).
2323
+ // ── v1.0.2 - Extended String functions (IOPL-native).
2160
2324
  trim: (args, context) => `String(${generateExpr(args[0], context)}).trim()`,
2161
2325
  trimStart: (args, context) => `String(${generateExpr(args[0], context)}).trimStart()`,
2162
2326
  trimEnd: (args, context) => `String(${generateExpr(args[0], context)}).trimEnd()`,
@@ -2188,7 +2352,7 @@ const BUILTIN_DECLARATIONS = {
2188
2352
  toString: (args, context) => `String(${generateExpr(args[0], context)}).toString()`,
2189
2353
  stringValueOf: (args, context) => `String(${generateExpr(args[0], context)}).valueOf()`,
2190
2354
 
2191
- // ── v1.0.2 — Extended Array/Collection functions (IOPL-native).
2355
+ // ── v1.0.2 - Extended Array/Collection functions (IOPL-native).
2192
2356
  push: (args, context) => `(${generateExpr(args[0], context)}).push(${args.slice(1).map(a => generateExpr(a, context)).join(', ')})`,
2193
2357
  pop: (args, context) => `(${generateExpr(args[0], context)}).pop()`,
2194
2358
  shift: (args, context) => `(${generateExpr(args[0], context)}).shift()`,
@@ -2204,7 +2368,12 @@ const BUILTIN_DECLARATIONS = {
2204
2368
  findLastIndex: (args, context) => `(${generateExpr(args[0], context)}).findLastIndex(${generateExpr(args[1], context)})`,
2205
2369
  indexOf: (args, context) => `(${generateExpr(args[0], context)}).indexOf(${generateExpr(args[1], context)}${args.length > 2 ? ', ' + generateExpr(args[2], context) : ''})`,
2206
2370
  lastIndexOf: (args, context) => `(${generateExpr(args[0], context)}).lastIndexOf(${generateExpr(args[1], context)}${args.length > 2 ? ', ' + generateExpr(args[2], context) : ''})`,
2207
- includes: (args, context) => `(${generateExpr(args[0], context)}).includes(${generateExpr(args[1], context)}${args.length > 2 ? ', ' + generateExpr(args[2], context) : ''})`,
2371
+ includes: (args, context) => {
2372
+ const coll = generateExpr(args[0], context);
2373
+ const val = generateExpr(args[1], context);
2374
+ const fromIndex = args.length > 2 ? ', ' + generateExpr(args[2], context) : '';
2375
+ return `(${coll} instanceof Set ? ${coll}.has(${val}) : (${coll}).includes(${val}${fromIndex}))`;
2376
+ },
2208
2377
  join: (args, context) => `(${generateExpr(args[0], context)}).join(${args.length > 1 ? generateExpr(args[1], context) : '","'})`,
2209
2378
  reverse: (args, context) => `[...${generateExpr(args[0], context)}].reverse()`,
2210
2379
  sort: (args, context) => `[...${generateExpr(args[0], context)}].sort(${args.length > 1 ? generateExpr(args[1], context) : '(a, b) => (a < b ? -1 : a > b ? 1 : 0)'})`,
@@ -2226,7 +2395,7 @@ const BUILTIN_DECLARATIONS = {
2226
2395
  values: (args, context) => `Object.values(${generateExpr(args[0], context)})`,
2227
2396
  entries: (args, context) => `Object.entries(${generateExpr(args[0], context)})`,
2228
2397
 
2229
- // ── v1.0.2 — Extended Object functions (IOPL-native).
2398
+ // ── v1.0.2 - Extended Object functions (IOPL-native).
2230
2399
  assign: (args, context) => `Object.assign(${args.map(a => generateExpr(a, context)).join(', ')})`,
2231
2400
  create: (args, context) => `Object.create(${generateExpr(args[0], context)}${args.length > 1 ? ', ' + generateExpr(args[1], context) : ''})`,
2232
2401
  defineProperty: (args, context) => `Object.defineProperty(${args.map(a => generateExpr(a, context)).join(', ')})`,
@@ -2246,7 +2415,7 @@ const BUILTIN_DECLARATIONS = {
2246
2415
  seal: (args, context) => `Object.seal(${generateExpr(args[0], context)})`,
2247
2416
  hasOwn: (args, context) => `Object.hasOwn(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2248
2417
 
2249
- // ── v1.0.2 — Promise/Async utilities (IOPL-native).
2418
+ // ── v1.0.2 - Promise/Async utilities (IOPL-native).
2250
2419
  Promise: {
2251
2420
  resolve: (args, context) => `Promise.resolve(${generateExpr(args[0], context)})`,
2252
2421
  reject: (args, context) => `Promise.reject(${generateExpr(args[0], context)})`,
@@ -2280,11 +2449,11 @@ const BUILTIN_DECLARATIONS = {
2280
2449
  return `Promise.race([${generateExpr(args[0], context)}, new Promise((_, r) => setTimeout(() => r(new Error('Timed out')), ${ms}))])`;
2281
2450
  },
2282
2451
 
2283
- // ── v1.0.2 — JSON utilities (IOPL-native).
2452
+ // ── v1.0.2 - JSON utilities (IOPL-native).
2284
2453
  jsonParse: (args, context) => `JSON.parse(${generateExpr(args[0], context)})`,
2285
2454
  stringify: (args, context) => `JSON.stringify(${generateExpr(args[0], context)}${args.length > 1 ? ', ' + generateExpr(args[1], context) : ''}${args.length > 2 ? ', ' + generateExpr(args[2], context) : ''})`,
2286
2455
 
2287
- // ── v1.0.2 — Type checking utilities (IOPL-native).
2456
+ // ── v1.0.2 - Type checking utilities (IOPL-native).
2288
2457
  isArray: (args, context) => `Array.isArray(${generateExpr(args[0], context)})`,
2289
2458
  isInteger: (args, context) => `Number.isInteger(${generateExpr(args[0], context)})`,
2290
2459
  isNaN: (args, context) => `Number.isNaN(${generateExpr(args[0], context)})`,
@@ -2293,12 +2462,12 @@ const BUILTIN_DECLARATIONS = {
2293
2462
  parseInt: (args, context) => `parseInt(${generateExpr(args[0], context)}${args.length > 1 ? ', ' + generateExpr(args[1], context) : ''})`,
2294
2463
  parseFloat: (args, context) => `parseFloat(${generateExpr(args[0], context)})`,
2295
2464
 
2296
- // ── v1.0.2 — Array static methods (IOPL-native).
2465
+ // ── v1.0.2 - Array static methods (IOPL-native).
2297
2466
  arrayFrom: (args, context) => `Array.from(${generateExpr(args[0], context)}${args.length > 1 ? ', ' + generateExpr(args[1], context) : ''})`,
2298
2467
  arrayOf: (args, context) => `Array.of(${args.map(a => generateExpr(a, context)).join(', ')})`,
2299
2468
  arrayIsArray: (args, context) => `Array.isArray(${generateExpr(args[0], context)})`,
2300
2469
 
2301
- // ── v1.0.2 — Object static methods (IOPL-native).
2470
+ // ── v1.0.2 - Object static methods (IOPL-native).
2302
2471
  objectFromEntries: (args, context) => `Object.fromEntries(${generateExpr(args[0], context)})`,
2303
2472
  objectGetOwnPropertySymbols: (args, context) => `Object.getOwnPropertySymbols(${generateExpr(args[0], context)})`,
2304
2473
  objectGetOwnPropertyDescriptors: (args, context) => `Object.getOwnPropertyDescriptors(${generateExpr(args[0], context)})`,
@@ -2322,7 +2491,7 @@ const BUILTIN_DECLARATIONS = {
2322
2491
  objectFreeze: (args, context) => `Object.freeze(${generateExpr(args[0], context)})`,
2323
2492
  objectSeal: (args, context) => `Object.seal(${generateExpr(args[0], context)})`,
2324
2493
 
2325
- // ── v1.0.2 — Symbol support (IOPL-native).
2494
+ // ── v1.0.2 - Symbol support (IOPL-native).
2326
2495
  symbol: (args, context) => `Symbol(${args.length > 0 ? generateExpr(args[0], context) : 'undefined'})`,
2327
2496
  symbolFor: (args, context) => `Symbol.for(${generateExpr(args[0], context)})`,
2328
2497
  symbolKeyFor: (args, context) => `Symbol.keyFor(${generateExpr(args[0], context)})`,
@@ -2339,7 +2508,7 @@ const BUILTIN_DECLARATIONS = {
2339
2508
  symbolToPrimitive: (_args) => `Symbol.toPrimitive`,
2340
2509
  symbolUnscopables: (_args) => `Symbol.unscopables`,
2341
2510
 
2342
- // ── v1.0.2 — Math static methods (IOPL-native).
2511
+ // ── v1.0.2 - Math static methods (IOPL-native).
2343
2512
  mathAbs: (args, context) => `Math.abs(${generateExpr(args[0], context)})`,
2344
2513
  mathMin: (args, context) => `Math.min(${args.map(a => generateExpr(a, context)).join(', ')})`,
2345
2514
  mathMax: (args, context) => `Math.max(${args.map(a => generateExpr(a, context)).join(', ')})`,
@@ -2377,7 +2546,7 @@ const BUILTIN_DECLARATIONS = {
2377
2546
  mathHypot: (args, context) => `Math.hypot(${args.map(a => generateExpr(a, context)).join(', ')})`,
2378
2547
  mathCbrt: (args, context) => `Math.cbrt(${generateExpr(args[0], context)})`,
2379
2548
 
2380
- // ── v1.0.2 — TypedArray support (IOPL-native).
2549
+ // ── v1.0.2 - TypedArray support (IOPL-native).
2381
2550
  int8Array: (args, context) => `new Int8Array(${args.map(a => generateExpr(a, context)).join(', ')})`,
2382
2551
  uint8Array: (args, context) => `new Uint8Array(${args.map(a => generateExpr(a, context)).join(', ')})`,
2383
2552
  uint8ClampedArray: (args, context) => `new Uint8ClampedArray(${args.map(a => generateExpr(a, context)).join(', ')})`,
@@ -2392,25 +2561,25 @@ const BUILTIN_DECLARATIONS = {
2392
2561
  dataView: (args, context) => `new DataView(${args.map(a => generateExpr(a, context)).join(', ')})`,
2393
2562
  arrayBuffer: (args, context) => `new ArrayBuffer(${args.map(a => generateExpr(a, context)).join(', ')})`,
2394
2563
 
2395
- // ── v1.0.2 — Global objects access (IOPL-native).
2564
+ // ── v1.0.2 - Global objects access (IOPL-native).
2396
2565
  globalThis: (_args) => `globalThis`,
2397
2566
  console: (_args) => `console`,
2398
2567
  process: (_args) => `process`,
2399
2568
  Buffer: (_args) => `Buffer`,
2400
2569
 
2401
- // ── v2.3.0 — EventSource / Server-Sent Events (IOPL-native).
2570
+ // ── v2.3.0 - EventSource / Server-Sent Events (IOPL-native).
2402
2571
  eventSource: (args, context) => `new EventSource(${args.map(a => generateExpr(a, context)).join(', ')})`,
2403
2572
 
2404
- // ── v2.2.0 — URL and URLSearchParams (IOPL-native).
2573
+ // ── v2.2.0 - URL and URLSearchParams (IOPL-native).
2405
2574
  url: (args, context) => `new URL(${generateExpr(args[0], context)}${args[1] ? `, ${generateExpr(args[1], context)}` : ''})`,
2406
2575
  urlSearchParams: (args, context) => `new URLSearchParams(${args.length ? generateExpr(args[0], context) : ''})`,
2407
2576
 
2408
- // ── v2.2.0 — Intl / Internationalization (IOPL-native).
2577
+ // ── v2.2.0 - Intl / Internationalization (IOPL-native).
2409
2578
  dateTimeFormat: (args, context) => `new Intl.DateTimeFormat(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2410
2579
  numberFormat: (args, context) => `new Intl.NumberFormat(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2411
2580
  collator: (args, context) => `new Intl.Collator(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2412
2581
 
2413
- // ── v2.2.0 — Crypto / Web Crypto API (IOPL-native).
2582
+ // ── v2.2.0 - Crypto / Web Crypto API (IOPL-native).
2414
2583
  cryptoRandomUUID: (_args) => `crypto.randomUUID()`,
2415
2584
  cryptoGetRandomValues: (args, context) => `crypto.getRandomValues(${generateExpr(args[0], context)})`,
2416
2585
  cryptoSubtleDigest: (args, context) => `crypto.subtle.digest(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
@@ -2425,13 +2594,13 @@ const BUILTIN_DECLARATIONS = {
2425
2594
  cryptoSubtleWrapKey: (args, context) => `crypto.subtle.wrapKey(${args.map(a => generateExpr(a, context)).join(', ')})`,
2426
2595
  cryptoSubtleUnwrapKey: (args, context) => `crypto.subtle.unwrapKey(${args.map(a => generateExpr(a, context)).join(', ')})`,
2427
2596
 
2428
- // ── v2.2.0 — WeakMap / WeakSet / WeakRef / FinalizationRegistry (IOPL-native).
2597
+ // ── v2.2.0 - WeakMap / WeakSet / WeakRef / FinalizationRegistry (IOPL-native).
2429
2598
  weakMap: (_args) => `new WeakMap()`,
2430
2599
  weakSet: (_args) => `new WeakSet()`,
2431
2600
  weakRef: (args, context) => `new WeakRef(${generateExpr(args[0], context)})`,
2432
2601
  finalizationRegistry: (args, context) => `new FinalizationRegistry(${generateExpr(args[0], context)})`,
2433
2602
 
2434
- // ── v2.2.0 — Proxy / Reflect (IOPL-native).
2603
+ // ── v2.2.0 - Proxy / Reflect (IOPL-native).
2435
2604
  proxy: (args, context) => `new Proxy(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2436
2605
  reflectGet: (args, context) => `Reflect.get(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2437
2606
  reflectSet: (args, context) => `Reflect.set(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)}, ${generateExpr(args[2], context)})`,
@@ -2443,7 +2612,7 @@ const BUILTIN_DECLARATIONS = {
2443
2612
  reflectDefineProperty: (args, context) => `Reflect.defineProperty(${args.map(a => generateExpr(a, context)).join(', ')})`,
2444
2613
  reflectGetOwnPropertyDescriptor: (args, context) => `Reflect.getOwnPropertyDescriptor(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2445
2614
 
2446
- // ── v2.2.0 — Symbol (IOPL-native).
2615
+ // ── v2.2.0 - Symbol (IOPL-native).
2447
2616
  symbol: (args, context) => `Symbol(${args.length ? generateExpr(args[0], context) : 'undefined'})`,
2448
2617
  symbolFor: (args, context) => `Symbol.for(${generateExpr(args[0], context)})`,
2449
2618
  symbolKeyFor: (args, context) => `Symbol.keyFor(${generateExpr(args[0], context)})`,
@@ -2460,12 +2629,12 @@ const BUILTIN_DECLARATIONS = {
2460
2629
  symbolToPrimitive: (_args) => `Symbol.toPrimitive`,
2461
2630
  symbolUnscopables: (_args) => `Symbol.unscopables`,
2462
2631
 
2463
- // ── v2.2.0 — BigInt (IOPL-native).
2632
+ // ── v2.2.0 - BigInt (IOPL-native).
2464
2633
  bigInt: (args, context) => `BigInt(${generateExpr(args[0], context)})`,
2465
2634
  bigIntAsIntN: (args, context) => `BigInt.asIntN(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2466
2635
  bigIntAsUintN: (args, context) => `BigInt.asUintN(${generateExpr(args[0], context)}, ${generateExpr(args[1], context)})`,
2467
2636
 
2468
- // ── v2.2.0 — Atomics / SharedArrayBuffer (IOPL-native).
2637
+ // ── v2.2.0 - Atomics / SharedArrayBuffer (IOPL-native).
2469
2638
  atomicsAdd: (args, context) => `Atomics.add(${args.map(a => generateExpr(a, context)).join(', ')})`,
2470
2639
  atomicsSub: (args, context) => `Atomics.sub(${args.map(a => generateExpr(a, context)).join(', ')})`,
2471
2640
  atomicsAnd: (args, context) => `Atomics.and(${args.map(a => generateExpr(a, context)).join(', ')})`,
@@ -2480,7 +2649,7 @@ const BUILTIN_DECLARATIONS = {
2480
2649
  atomicsIsLockFree: (args, context) => `Atomics.isLockFree(${generateExpr(args[0], context)})`,
2481
2650
  sharedArrayBuffer: (args, context) => `new SharedArrayBuffer(${generateExpr(args[0], context)})`,
2482
2651
 
2483
- // ── v2.2.0 — Error subclasses (IOPL-native).
2652
+ // ── v2.2.0 - Error subclasses (IOPL-native).
2484
2653
  error: (args, context) => `new Error(${args.length ? generateExpr(args[0], context) : ''})`,
2485
2654
  typeError: (args, context) => `new TypeError(${args.length ? generateExpr(args[0], context) : ''})`,
2486
2655
  rangeError: (args, context) => `new RangeError(${args.length ? generateExpr(args[0], context) : ''})`,
@@ -2490,17 +2659,126 @@ const BUILTIN_DECLARATIONS = {
2490
2659
  uriError: (args, context) => `new URIError(${args.length ? generateExpr(args[0], context) : ''})`,
2491
2660
  aggregateError: (args, context) => `new AggregateError(${args.map(a => generateExpr(a, context)).join(', ')})`,
2492
2661
 
2493
- // ── v2.2.0 — Blob / File / FormData (IOPL-native, browser-compatible).
2662
+ // ── v2.2.0 - Blob / File / FormData (IOPL-native, browser-compatible).
2494
2663
  blob: (args, context) => `new Blob(${args.map(a => generateExpr(a, context)).join(', ')})`,
2495
2664
  file: (args, context) => `new File(${args.map(a => generateExpr(a, context)).join(', ')})`,
2496
2665
  formData: (_args) => `new FormData()`,
2666
+
2667
+ // ── v1.0.361 - browser DOM (IOPL-native). All helpers guard their browser
2668
+ // global, so the generated output throws a clear teaching error under Node.
2669
+ select: (args, context) => {
2670
+ ensureBuiltin(context, 'dom');
2671
+ requireOneArg('select', args);
2672
+ return `__select(${generateExpr(args[0], context)})`;
2673
+ },
2674
+ selectAll: (args, context) => {
2675
+ ensureBuiltin(context, 'dom');
2676
+ requireOneArg('selectAll', args);
2677
+ return `__selectAll(${generateExpr(args[0], context)})`;
2678
+ },
2679
+ parseHTML: (args, context) => {
2680
+ ensureBuiltin(context, 'dom');
2681
+ requireOneArg('parseHTML', args);
2682
+ return `__parseHTML(${generateExpr(args[0], context)})`;
2683
+ },
2684
+
2685
+ // ── v1.0.361 - browser input (IOPL-native).
2686
+ localPoint: (args, context) => {
2687
+ ensureBuiltin(context, 'input');
2688
+ requireArgs('localPoint', args, 2, 'localPoint(event, canvas)');
2689
+ return `__localPoint(${args.map(a => generateExpr(a, context)).join(', ')})`;
2690
+ },
2691
+ gamepads: (_args, context) => {
2692
+ ensureBuiltin(context, 'input');
2693
+ return `__gamepads()`;
2694
+ },
2695
+ droppedFiles: (args, context) => {
2696
+ ensureBuiltin(context, 'input');
2697
+ requireOneArg('droppedFiles', args);
2698
+ return `__droppedFiles(${generateExpr(args[0], context)})`;
2699
+ },
2700
+
2701
+ // ── v1.0.361 - browser assets (IOPL-native). Each awaitable helper is
2702
+ // awaited here, so the surrounding function/handler is marked async.
2703
+ loadImage: (args, context) => {
2704
+ ensureBuiltin(context, 'assets');
2705
+ requireOneArg('loadImage', args);
2706
+ markAsync(context);
2707
+ return `(await __loadImage(${generateExpr(args[0], context)}))`;
2708
+ },
2709
+ loadAudio: (args, context) => {
2710
+ ensureBuiltin(context, 'assets');
2711
+ requireOneArg('loadAudio', args);
2712
+ markAsync(context);
2713
+ return `(await __loadAudio(${generateExpr(args[0], context)}))`;
2714
+ },
2715
+ fetchJson: (args, context) => {
2716
+ ensureBuiltin(context, 'assets');
2717
+ requireOneArg('fetchJson', args);
2718
+ markAsync(context);
2719
+ return `(await __fetchJson(${generateExpr(args[0], context)}))`;
2720
+ },
2721
+ fetchBytes: (args, context) => {
2722
+ ensureBuiltin(context, 'assets');
2723
+ requireOneArg('fetchBytes', args);
2724
+ markAsync(context);
2725
+ return `(await __fetchBytes(${generateExpr(args[0], context)}))`;
2726
+ },
2727
+ readDataUrl: (args, context) => {
2728
+ ensureBuiltin(context, 'assets');
2729
+ requireOneArg('readDataUrl', args);
2730
+ markAsync(context);
2731
+ return `(await __readDataUrl(${generateExpr(args[0], context)}))`;
2732
+ },
2733
+
2734
+ // ── v1.0.361 - Web Audio (IOPL-native).
2735
+ audioContext: (_args, context) => {
2736
+ ensureBuiltin(context, 'audio');
2737
+ return `__audioContext()`;
2738
+ },
2739
+ playTone: (args, context) => {
2740
+ ensureBuiltin(context, 'audio');
2741
+ requireArgs('playTone', args, 1, 'playTone(440)');
2742
+ return `__audioTone(${args.map(a => generateExpr(a, context)).join(', ')})`;
2743
+ },
2744
+
2745
+ // ── v1.0.361 - WebSocket send helper (works with any WebSocket-like object,
2746
+ // browser or Node): strings go through verbatim, everything else is JSON.
2747
+ webSocketSend: (args, context) => {
2748
+ requireArgs('webSocketSend', args, 2, 'webSocketSend(socket, { type: "move", x: 10 })');
2749
+ const ws = generateExpr(args[0], context);
2750
+ const value = generateExpr(args[1], context);
2751
+ return `${ws}.send(typeof (${value}) === 'string' ? (${value}) : JSON.stringify(${value}))`;
2752
+ },
2753
+
2754
+ // ── v1.0.361 - WebGL (IOPL-native).
2755
+ webglContext: (args, context) => {
2756
+ ensureBuiltin(context, 'gl');
2757
+ requireOneArg('webglContext', args);
2758
+ return `__glContext(${generateExpr(args[0], context)})`;
2759
+ },
2760
+ glShader: (args, context) => {
2761
+ ensureBuiltin(context, 'gl');
2762
+ requireArgs('glShader', args, 3, 'glShader(gl, "vertex", "void main() {}")');
2763
+ return `__glShader(${args.map(a => generateExpr(a, context)).join(', ')})`;
2764
+ },
2765
+ glProgram: (args, context) => {
2766
+ ensureBuiltin(context, 'gl');
2767
+ requireArgs('glProgram', args, 3, 'glProgram(gl, vertexShader, fragmentShader)');
2768
+ return `__glProgram(${args.map(a => generateExpr(a, context)).join(', ')})`;
2769
+ },
2770
+ glBuffer: (args, context) => {
2771
+ ensureBuiltin(context, 'gl');
2772
+ requireArgs('glBuffer', args, 2, 'glBuffer(gl, new Float32Array([0, 0, 1, 0, 0, 1]))');
2773
+ return `__glBuffer(${args.map(a => generateExpr(a, context)).join(', ')})`;
2774
+ },
2497
2775
  };
2498
2776
 
2499
2777
  // Mark the enclosing program async when a call awaits at the top level, and
2500
2778
  // record that this scope emitted an `await` so handler and function bodies can
2501
2779
  // decide their own async-ness at generation time (see generateBlock). Routing
2502
2780
  // every await-emitting construct through this single function removes the need
2503
- // for a separate hand-maintained registry of async statement types — so a new
2781
+ // for a separate hand-maintained registry of async statement types - so a new
2504
2782
  // async keyword can never silently break when used inside a route, listener, or
2505
2783
  // function.
2506
2784
  function markAsync(context) {
@@ -2508,7 +2786,7 @@ function markAsync(context) {
2508
2786
  // Only a construct that awaits at the true top level needs the program
2509
2787
  // wrapped in an async IIFE. Awaits emitted inside a user function (inFunction)
2510
2788
  // or inside a route/listener/404 handler (inHandler) are handled by marking
2511
- // that function/handler async instead — they must not drag the whole program
2789
+ // that function/handler async instead - they must not drag the whole program
2512
2790
  // into an async wrapper, or "top-level use wraps the whole program" would be
2513
2791
  // the only safe nesting level for a new async keyword.
2514
2792
  if (!context.inFunction && !context.inHandler) context.needsAsync = true;
@@ -2519,7 +2797,7 @@ function markAsync(context) {
2519
2797
  // This is the single source of truth for whether a route handler, listener,
2520
2798
  // 404 handler, or user function must be declared `async`. Previously this was
2521
2799
  // decided by a separate AST walker (containsAsyncBlock) that had to be kept in
2522
- // sync by hand with every construct that compiles down to `await` — the exact
2800
+ // sync by hand with every construct that compiles down to `await` - the exact
2523
2801
  // fragility that made "top-level use wraps the whole program" the only place
2524
2802
  // certain keywords (like ocr) were guaranteed to work. By observing the output
2525
2803
  // of generation instead, whatever a body contains is handled correctly, even if
@@ -2533,7 +2811,7 @@ function generateBlock(statements, indent, context) {
2533
2811
  return { out, emitted };
2534
2812
  }
2535
2813
 
2536
- // v2.1.0 — generate a request accessor (param/query/header). These compile to
2814
+ // v2.1.0 - generate a request accessor (param/query/header). These compile to
2537
2815
  // direct Express req.<bucket>[key] reads and are rejected outside routes so
2538
2816
  // mistakes surface at compile time with a teaching error.
2539
2817
  function routeAccessor(name, bucket, args, context) {
@@ -2548,7 +2826,7 @@ function routeAccessor(name, bucket, args, context) {
2548
2826
  return `req.${bucket}[${generateExpr(args[0], context)}]`;
2549
2827
  }
2550
2828
 
2551
- // v2.1.1 — compile-time guard shared by request-scoped accessors that do not
2829
+ // v2.1.1 - compile-time guard shared by request-scoped accessors that do not
2552
2830
  // follow the req.<bucket> shape (upload/uploads/cookie).
2553
2831
  function routeOnly(name, example) {
2554
2832
  if (!_inRoute) {
@@ -2578,15 +2856,15 @@ let _inRoute = false;
2578
2856
  // True while generating inside a Telegram handler body. Remaps PlainScript's
2579
2857
  // "reply" statement to send a chat message instead of an HTTP response.
2580
2858
  let _inTelegram = false;
2581
- // v2.1.1 — true while generating inside a WhatsApp "on message" handler.
2859
+ // v2.1.1 - true while generating inside a WhatsApp "on message" handler.
2582
2860
  // Remaps PlainScript's "reply" to a WhatsApp chat message and PlainScript's "message"
2583
2861
  // identifier to the normalized message record of the current delivery.
2584
2862
  let _inWhatsApp = false;
2585
- // v2.1.0 — active "group" prefixes. Route paths are prefixed with the
2863
+ // v2.1.0 - active "group" prefixes. Route paths are prefixed with the
2586
2864
  // concatenation of every enclosing group, innermost last.
2587
2865
  const _routePrefixes = [];
2588
2866
 
2589
- // v2.1.0 — active SQL driver. "sqlite" (default) targets better-sqlite3's
2867
+ // v2.1.0 - active SQL driver. "sqlite" (default) targets better-sqlite3's
2590
2868
  // synchronous prepare/run/exec API; "pg" targets node-postgres pools and
2591
2869
  // makes every SQL statement async. Set by database/postgres declarations.
2592
2870
  let _sqlDriver = 'sqlite';
@@ -2599,7 +2877,7 @@ function routePath(path) {
2599
2877
  return _routePrefixes.join('') + path;
2600
2878
  }
2601
2879
 
2602
- // v2.1.0 — render the JavaScript expression that executes one SQL statement
2880
+ // v2.1.0 - render the JavaScript expression that executes one SQL statement
2603
2881
  // under the active driver. kind: query | write | execute.
2604
2882
  function emitSqlCall(kind, sql, params, indent, context) {
2605
2883
  const args = params.join(', ');
@@ -2666,7 +2944,7 @@ function npmPackageName(moduleName) {
2666
2944
 
2667
2945
  function emitRequire(context, moduleName, alias) {
2668
2946
  // A specifier may carry a version range ("left-pad@^1.3.0"). require() takes
2669
- // the bare name only — the range is the installer's business (plain install).
2947
+ // the bare name only - the range is the installer's business (plain install).
2670
2948
  const { name: bareName } = splitPackageSpec(moduleName);
2671
2949
  const npmName = npmPackageName(bareName);
2672
2950
 
@@ -2696,7 +2974,7 @@ function emitRequire(context, moduleName, alias) {
2696
2974
 
2697
2975
  if (KNOWN_PACKAGES[bareName]) return KNOWN_PACKAGES[bareName];
2698
2976
 
2699
- // RFC-0011 §5.1 — arbitrary npm packages. A name that is not a valid JS
2977
+ // RFC-0011 §5.1 - arbitrary npm packages. A name that is not a valid JS
2700
2978
  // identifier (e.g. node-fetch) is required for its side effect only.
2701
2979
  if (isValidIdentifier(bareName)) {
2702
2980
  return `const ${bareName} = require('${npmName}');`;
@@ -2753,7 +3031,7 @@ function generate(ast, contextOrOptions = createGenerationContext(), options = {
2753
3031
  context = createGenerationContext(opts);
2754
3032
  }
2755
3033
 
2756
- // v1.0.1 — reset per-program test bookkeeping so repeated generate() calls
3034
+ // v1.0.1 - reset per-program test bookkeeping so repeated generate() calls
2757
3035
  // (build pipeline) start clean.
2758
3036
  __testCount = 0;
2759
3037
  __testCatchers = [];
@@ -2794,7 +3072,7 @@ function generate(ast, contextOrOptions = createGenerationContext(), options = {
2794
3072
  lines.push(`if (typeof module !== 'undefined') { module.exports = { ${exported.join(', ')} }; }`);
2795
3073
  }
2796
3074
 
2797
- // v1.0.1 — native test runner. When any "test ... done" block exists, emit
3075
+ // v1.0.1 - native test runner. When any "test ... done" block exists, emit
2798
3076
  // the runner helper, register each test after its function declaration, and
2799
3077
  // execute them. Each failure prints a message and sets process.exitCode = 1.
2800
3078
  if (__testCatchers.length > 0) {
@@ -2802,7 +3080,7 @@ function generate(ast, contextOrOptions = createGenerationContext(), options = {
2802
3080
  `const __tests = [];`,
2803
3081
  `function __check(op, a, b) {`,
2804
3082
  ` const ok = op === 'contains'`,
2805
- ` ? String(a).includes(String(b))`,
3083
+ ` ? (a instanceof Set ? a.has(b) : String(a).includes(String(b)))`,
2806
3084
  ` : op === 'is'`,
2807
3085
  ` ? a === b`,
2808
3086
  ` : op === 'raises'`,
@@ -2838,7 +3116,7 @@ function generate(ast, contextOrOptions = createGenerationContext(), options = {
2838
3116
  return jsCode;
2839
3117
  }
2840
3118
 
2841
- // ── v1.0.1 — test DSL bookkeeping ───────────────────────────────────────────
3119
+ // ── v1.0.1 - test DSL bookkeeping ───────────────────────────────────────────
2842
3120
  let __testCount = 0;
2843
3121
  let __testCatchers = [];
2844
3122
  let __inTest = false;
@@ -2851,8 +3129,14 @@ function generateCondition(cond, context) {
2851
3129
  return `${generateExpr(cond.left, context)} ${cond.op} ${generateExpr(cond.right, context)}`;
2852
3130
 
2853
3131
  case 'UnaryCondition':
2854
- if (cond.op === 'isEmpty') return `(${generateExpr(cond.left, context)}).length === 0`;
2855
- if (cond.op === 'isNotEmpty') return `(${generateExpr(cond.left, context)}).length > 0`;
3132
+ if (cond.op === 'isEmpty') {
3133
+ const expr = generateExpr(cond.left, context);
3134
+ return `(${expr} instanceof Map || ${expr} instanceof Set ? ${expr}.size === 0 : (typeof ${expr} === 'object' && ${expr} !== null ? Object.keys(${expr}).length === 0 : (${expr}).length === 0))`;
3135
+ }
3136
+ if (cond.op === 'isNotEmpty') {
3137
+ const expr = generateExpr(cond.left, context);
3138
+ return `(${expr} instanceof Map || ${expr} instanceof Set ? ${expr}.size > 0 : (typeof ${expr} === 'object' && ${expr} !== null ? Object.keys(${expr}).length > 0 : (${expr}).length > 0))`;
3139
+ }
2856
3140
  throw new Error(`Unknown unary condition op "${cond.op}".`);
2857
3141
 
2858
3142
  case 'BetweenCondition': {
@@ -2860,14 +3144,49 @@ function generateCondition(cond, context) {
2860
3144
  return `${expr} >= ${generateExpr(cond.low, context)} && ${expr} <= ${generateExpr(cond.high, context)}`;
2861
3145
  }
2862
3146
 
2863
- case 'StringCondition':
2864
- return `(${generateExpr(cond.left, context)}).${cond.method}(${generateExpr(cond.right, context)})`;
3147
+ case 'InCondition': {
3148
+ const right = generateExpr(cond.right, context);
3149
+ const left = generateExpr(cond.left, context);
3150
+ return `(${right} instanceof Set ? ${right}.has(${left}) : (${right}).includes(${left}))`;
3151
+ }
3152
+
3153
+ case 'NotInCondition': {
3154
+ const right = generateExpr(cond.right, context);
3155
+ const left = generateExpr(cond.left, context);
3156
+ return `!(${right} instanceof Set ? ${right}.has(${left}) : (${right}).includes(${left}))`;
3157
+ }
3158
+
3159
+ case 'StringCondition': {
3160
+ const left = generateExpr(cond.left, context);
3161
+ const right = generateExpr(cond.right, context);
3162
+ if (cond.method === 'includes') {
3163
+ return `(${left} instanceof Set ? ${left}.has(${right}) : (${left}).includes(${right}))`;
3164
+ }
3165
+ return `(${left}).${cond.method}(${right})`;
3166
+ }
2865
3167
 
2866
- // v2.1.1 — and / or / not combinators.
3168
+ // v2.1.1 - and / or / not combinators. The Boolean combinators operate on
3169
+ // the same LogicalCondition nodes at both the condition level and the
3170
+ // expression level, so an operand may be either a pure condition node
3171
+ // (comparison) or an arbitrary value expression (`f()`, a collection, a
3172
+ // number, a `set with ...` literal). Pure conditions recurse through the
3173
+ // condition generator; everything else is emitted as a general expression.
2867
3174
  case 'LogicalCondition': {
2868
- if (cond.op === 'not') return `!(${generateCondition(cond.operand, context)})`;
3175
+ const CONDITION_TYPES = [
3176
+ 'BinaryCondition',
3177
+ 'UnaryCondition',
3178
+ 'BetweenCondition',
3179
+ 'StringCondition',
3180
+ 'InCondition',
3181
+ 'NotInCondition',
3182
+ 'LogicalCondition',
3183
+ ];
3184
+ const emit = (n) => CONDITION_TYPES.includes(n.type)
3185
+ ? generateCondition(n, context)
3186
+ : generateExpr(n, context);
3187
+ if (cond.op === 'not') return `!(${emit(cond.operand)})`;
2869
3188
  const jsOp = cond.op === 'and' ? '&&' : '||';
2870
- return `${generateCondition(cond.left, context)} ${jsOp} ${generateCondition(cond.right, context)}`;
3189
+ return `${emit(cond.left)} ${jsOp} ${emit(cond.right)}`;
2871
3190
  }
2872
3191
 
2873
3192
  default:
@@ -2894,7 +3213,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
2894
3213
  return `${indent}console.log(${generateExpr(node.value, context)});`;
2895
3214
 
2896
3215
  case 'GiveStatement':
2897
- return `${indent}return ${generateExpr(node.value, context)};`;
3216
+ return `${indent}return${node.value ? ' ' + generateExpr(node.value, context) : ''};`;
2898
3217
 
2899
3218
  case 'BecomeStatement': {
2900
3219
  // Handle destructuring: [a, b] = arr / {x, y} = obj
@@ -2921,11 +3240,11 @@ function generateStatement(node, indent = '', context = createGenerationContext(
2921
3240
  return `${indent}${target} ${op} ${value};`;
2922
3241
  }
2923
3242
 
2924
- // v1.0.1 — record kinds: `define a kind called "Person" with ... done`.
3243
+ // v1.0.1 - record kinds: `define a kind called "Person" with ... done`.
2925
3244
  // Names are emitted as a JS factory that returns a fresh plain object with
2926
3245
  // declared defaults. Constructors prompt for required fields at compile
2927
3246
  // time via `create a Person with ...` (see GenerateExpr CreateKind).
2928
- // v1.0.2 — supports `extends` for inheritance.
3247
+ // v1.0.2 - supports `extends` for inheritance.
2929
3248
  case 'DefineKindStatement': {
2930
3249
  let defaults = '';
2931
3250
  if (node.extends) {
@@ -2954,14 +3273,14 @@ function generateStatement(node, indent = '', context = createGenerationContext(
2954
3273
  ].join('\n');
2955
3274
  }
2956
3275
 
2957
- // v1.0.1 — load env file "<path>": apply KEY=VALUE pairs to process.env.
3276
+ // v1.0.1 - load env file "<path>": apply KEY=VALUE pairs to process.env.
2958
3277
  // Blank lines and `#` comments are skipped; values keep their text.
2959
3278
  case 'LoadEnvFileStatement': {
2960
3279
  ensureBuiltin(context, 'dotenv');
2961
3280
  return `${indent}__loadEnvFile(${JSON.stringify(node.path)});`;
2962
3281
  }
2963
3282
 
2964
- // v1.0.1 — native test DSL. `test "<name>" ... done` registers a runnable
3283
+ // v1.0.1 - native test DSL. `test "<name>" ... done` registers a runnable
2965
3284
  // unit; all tests are executed after the program body with a tiny runner.
2966
3285
  case 'TestStatement': {
2967
3286
  __testCount++;
@@ -2974,7 +3293,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
2974
3293
  return `${indent}function ${fnName}() {\n${body}\n${indent}}`;
2975
3294
  }
2976
3295
 
2977
- // v1.0.1 — assertion `check <a> (equals|is|contains|raises) <b>`.
3296
+ // v1.0.1 - assertion `check <a> (equals|is|contains|raises) <b>`.
2978
3297
  // For `raises`, `a` is wrapped in a thunk so the expression is evaluated
2979
3298
  // inside the runner's try/catch (its thrown error is the subject).
2980
3299
  case 'CheckStatement': {
@@ -3002,7 +3321,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3002
3321
  return exports.map(e => `${indent}${e}`).join('\n');
3003
3322
  }
3004
3323
 
3005
- // v1.0.1 — generators: `yield <expr>` (or bare `yield`).
3324
+ // v1.0.1 - generators: `yield <expr>` (or bare `yield`).
3006
3325
  case 'YieldStatement': {
3007
3326
  if (!context.inFunction) {
3008
3327
  throw new Error('"yield" can only be used inside a function created with "make".\n\nExample:\n make countUp(n)\n let i = 0\n while i less than n\n i = i + 1\n yield i\n done\n done');
@@ -3073,7 +3392,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3073
3392
  return `${indent}let ${node.variable} = await __ask(${prompt});`;
3074
3393
  }
3075
3394
 
3076
- // v2.0.1 — ocr "<image>" as <variable> [using "<lang>"]
3395
+ // v2.0.1 - ocr "<image>" as <variable> [using "<lang>"]
3077
3396
  case 'OcrStatement': {
3078
3397
  ensureBuiltin(context, 'ocr');
3079
3398
  markAsync(context);
@@ -3125,6 +3444,15 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3125
3444
  return out;
3126
3445
  }
3127
3446
 
3447
+ case 'RepeatTimesStatement': {
3448
+ context.loopDepth++;
3449
+ const body = node.body.map(s => generateStatement(s, indent + ' ', context)).join('\n');
3450
+ context.loopDepth--;
3451
+ const count = generateExpr(node.count, context);
3452
+ const idxVar = `__repeat_i_${context.loopDepth + 1}`;
3453
+ return `${indent}for (let ${idxVar} = 0; ${idxVar} < ${count}; ${idxVar}++) {\n${body}\n${indent}}`;
3454
+ }
3455
+
3128
3456
  case 'ForEachStatement': {
3129
3457
  context.loopDepth++;
3130
3458
  const body = node.body.map(s => generateStatement(s, indent + ' ', context)).join('\n');
@@ -3136,7 +3464,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3136
3464
  context.loopDepth++;
3137
3465
  const body = node.body.map(s => generateStatement(s, indent + ' ', context)).join('\n');
3138
3466
  context.loopDepth--;
3139
- // for index <name> in <collection> — zero-based index over a list.
3467
+ // for index <name> in <collection> - zero-based index over a list.
3140
3468
  if (node.over != null) {
3141
3469
  const coll = generateExpr(node.over, context);
3142
3470
  return `${indent}for (let ${node.name} = 0; ${node.name} < ${coll}.length; ${node.name}++) {\n${body}\n${indent}}`;
@@ -3220,7 +3548,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3220
3548
  return `${indent}class ${node.name}${superClass} {\n${body}\n${indent}}`;
3221
3549
  }
3222
3550
 
3223
- // v0.3 — Express runtime
3551
+ // v0.3 - Express runtime
3224
3552
 
3225
3553
  case 'ListenStatement': {
3226
3554
  const prevInHandler = context.inHandler;
@@ -3277,7 +3605,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3277
3605
  return `${indent}res.json({ ${props} });`;
3278
3606
  }
3279
3607
 
3280
- // v1.2 — reply <value> with buttons … done (Telegram inline keyboard).
3608
+ // v1.2 - reply <value> with buttons … done (Telegram inline keyboard).
3281
3609
  // The AST stores rows of { text, data } objects (parser.js). The Telegram
3282
3610
  // runtime's keyboard() expects a flat list of [text, data] pairs, so each
3283
3611
  // button is rendered as [text, data] and rows are merged into that list.
@@ -3291,13 +3619,13 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3291
3619
  case 'ServeFolderStatement':
3292
3620
  return `${indent}app.use(express.static(${JSON.stringify(node.folder)}));`;
3293
3621
 
3294
- // v0.6 — Express DX
3622
+ // v0.6 - Express DX
3295
3623
 
3296
3624
  case 'WebAppStatement':
3297
3625
  return [
3298
3626
  emitRequire(context, 'express'),
3299
3627
  `${indent}const app = express();`,
3300
- // v2.1.0 — parse JSON request bodies so POST/PUT handlers can read
3628
+ // v2.1.0 - parse JSON request bodies so POST/PUT handlers can read
3301
3629
  // "body of request". Harmless for GET-only v2.0.1 programs.
3302
3630
  `${indent}app.use(express.json());`,
3303
3631
  ]
@@ -3314,7 +3642,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3314
3642
  return `${indent}app.${node.method}(${JSON.stringify(routePath(node.path))}, ${handlerAsync}(req, res) => {\n${block.out}\n${indent}});`;
3315
3643
  }
3316
3644
 
3317
- // v2.1.0 — group "<prefix>" ... done: composes routes under a shared
3645
+ // v2.1.0 - group "<prefix>" ... done: composes routes under a shared
3318
3646
  // prefix. Groups nest; every enclosed route (either form) gets the
3319
3647
  // concatenated prefix. Non-route statements run in program order.
3320
3648
  case 'GroupStatement': {
@@ -3324,7 +3652,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3324
3652
  return body;
3325
3653
  }
3326
3654
 
3327
- // v2.1.0 — status <expr>: sets the HTTP response status code. Only valid
3655
+ // v2.1.0 - status <expr>: sets the HTTP response status code. Only valid
3328
3656
  // inside a route handler (res is in scope there).
3329
3657
  case 'StatusStatement':
3330
3658
  if (!_inRoute) {
@@ -3332,14 +3660,14 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3332
3660
  }
3333
3661
  return `${indent}res.status(${generateExpr(node.value, context)});`;
3334
3662
 
3335
- // v2.2.0 — redirect to "<url>": sends an HTTP redirect from a route.
3663
+ // v2.2.0 - redirect to "<url>": sends an HTTP redirect from a route.
3336
3664
  case 'RedirectStatement':
3337
3665
  if (!_inRoute) {
3338
3666
  throw new Error('"redirect to" can only be used inside a route handler.\n\nExample:\n route get "/old"\n redirect to "/new"\n done');
3339
3667
  }
3340
3668
  return `${indent}res.redirect(${generateExpr(node.url, context)});`;
3341
3669
 
3342
- // v2.1.0 — allow cors: enables cross-origin requests on the current app.
3670
+ // v2.1.0 - allow cors: enables cross-origin requests on the current app.
3343
3671
  // Applies to routes registered after this statement.
3344
3672
  case 'AllowCorsStatement':
3345
3673
  return [
@@ -3352,7 +3680,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3352
3680
  `${indent}});`,
3353
3681
  ].join('\n');
3354
3682
 
3355
- // ── v2.1.1 — uploads, auth middleware, rate limiting, OAuth ────────────
3683
+ // ── v2.1.1 - uploads, auth middleware, rate limiting, OAuth ────────────
3356
3684
  // These register Express middleware in program order; routes declared
3357
3685
  // after them are protected / wired accordingly.
3358
3686
 
@@ -3365,7 +3693,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3365
3693
  return `${indent}app.use(__uploads({ ${options.join(', ')} }));`;
3366
3694
  }
3367
3695
 
3368
- // require api key from <expr> — rejects requests whose x-api-key header
3696
+ // require api key from <expr> - rejects requests whose x-api-key header
3369
3697
  // does not match. The expected key may come from env("...") or anywhere.
3370
3698
  case 'RequireApiKeyStatement':
3371
3699
  return [
@@ -3407,7 +3735,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3407
3735
  return `${indent}__googleOAuth(app, { ${parts} });`;
3408
3736
  }
3409
3737
 
3410
- // ── v2.1.1 — route-scoped state: cookies and sessions
3738
+ // ── v2.1.1 - route-scoped state: cookies and sessions
3411
3739
 
3412
3740
  case 'DestroySessionStatement':
3413
3741
  if (!_inRoute) {
@@ -3433,7 +3761,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3433
3761
  }
3434
3762
  return `${indent}res.clearCookie(${JSON.stringify(node.name)}, { path: '/' });`;
3435
3763
 
3436
- // when nothing matches … done — the 404 catch-all. Registered in source
3764
+ // when nothing matches … done - the 404 catch-all. Registered in source
3437
3765
  // position, so it must come after every route (Express matches handlers
3438
3766
  // in registration order).
3439
3767
  case 'NotFoundStatement': {
@@ -3447,7 +3775,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3447
3775
  return `${indent}app.use((${handlerAsync}req, res) => {\n${block.out}\n${indent}});`;
3448
3776
  }
3449
3777
 
3450
- // ── v2.1.1 — error handling and retries
3778
+ // ── v2.1.1 - error handling and retries
3451
3779
 
3452
3780
  case 'TryStatement': {
3453
3781
  const tryBody = (node.tryBody || node.body || []).map(s => generateStatement(s, indent + ' ', context)).join('\n');
@@ -3519,11 +3847,11 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3519
3847
  case 'StartStatement':
3520
3848
  return `${indent}app.listen(${generateExpr(node.port, context)});`;
3521
3849
 
3522
- // v0.6 — SQLite DX. v2.1.0 adds parameterized SQL, captured results and
3850
+ // v0.6 - SQLite DX. v2.1.0 adds parameterized SQL, captured results and
3523
3851
  // transactions; the driver switches to PostgreSQL when a "postgres"
3524
3852
  // declaration is active.
3525
3853
 
3526
- // database "<file>" [using "<driver>"] — v2.1.1 opens through the
3854
+ // database "<file>" [using "<driver>"] - v2.1.1 opens through the
3527
3855
  // portable engine chain: better-sqlite3 when its native binding works on
3528
3856
  // this machine, sql.js otherwise ("using" forces one engine). The opened
3529
3857
  // handle exposes the same prepare/exec/transaction surface either way,
@@ -3537,7 +3865,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3537
3865
  return `${indent}const db = await __dbOpen(${JSON.stringify(node.file)}, ${driverArg});`;
3538
3866
  }
3539
3867
 
3540
- // v2.1.0 — postgres "<connection>": node-postgres pool bound to "db".
3868
+ // v2.1.0 - postgres "<connection>": node-postgres pool bound to "db".
3541
3869
  // Every SQL statement afterwards compiles to async pool queries.
3542
3870
  case 'PostgresStatement': {
3543
3871
  _sqlDriver = 'pg';
@@ -3549,7 +3877,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3549
3877
  ].filter(Boolean).map(line => line.startsWith('const ') ? `${indent}${line}` : line).join('\n');
3550
3878
  }
3551
3879
 
3552
- // v2.2.0 — mongo "<connection>" [db "<name>"]: MongoDB client bound to "db".
3880
+ // v2.2.0 - mongo "<connection>" [db "<name>"]: MongoDB client bound to "db".
3553
3881
  // Uses the mongodb driver; subsequent query/insert/update/delete/execute
3554
3882
  // statements compile to MongoDB collection operations.
3555
3883
  case 'MongoStatement': {
@@ -3577,7 +3905,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3577
3905
  case 'ExecuteStatement':
3578
3906
  return `${indent}${emitSqlCall('execute', node.sql, node.params, indent, context)};`;
3579
3907
 
3580
- // v2.1.0 — remember <name> as query|insert|update|delete … done
3908
+ // v2.1.0 - remember <name> as query|insert|update|delete … done
3581
3909
  case 'RememberSqlStatement': {
3582
3910
  const kind = node.kind === 'query' ? 'query'
3583
3911
  : node.kind === 'execute' ? 'execute'
@@ -3587,7 +3915,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3587
3915
  return `${indent}let ${node.name} = ${emitSqlCall(kind, node.sql, node.params, indent, context)};`;
3588
3916
  }
3589
3917
 
3590
- // v2.1.0 — transaction … done: all enclosed database statements run
3918
+ // v2.1.0 - transaction … done: all enclosed database statements run
3591
3919
  // atomically (all succeed or none are applied).
3592
3920
  case 'TransactionStatement': {
3593
3921
  if (_sqlDriver === 'pg') {
@@ -3622,7 +3950,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3622
3950
  ].join('\n');
3623
3951
  }
3624
3952
 
3625
- // v1.2 — Telegram statements
3953
+ // v1.2 - Telegram statements
3626
3954
 
3627
3955
  case 'TelegramCommandStatement': {
3628
3956
  ensureBuiltin(context, 'telegram');
@@ -3651,18 +3979,18 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3651
3979
  return `${indent}await BOT.start();`;
3652
3980
  }
3653
3981
 
3654
- // ── v2.1.1 — WhatsApp statements ────────────────────────────────────────
3982
+ // ── v2.1.1 - WhatsApp statements ────────────────────────────────────────
3655
3983
 
3656
- // whatsapp bot … done — starts the Baileys runtime with the declared
3984
+ // whatsapp bot … done - starts the Baileys runtime with the declared
3657
3985
  // auth folder and login mode, then registers every "on message" handler.
3658
3986
  // When no login line is present (login is null), only registers handlers
3659
- // without auto-starting — used by hybrid bots that pair on-demand.
3987
+ // without auto-starting - used by hybrid bots that pair on-demand.
3660
3988
  case 'WhatsAppBotStatement': {
3661
3989
  ensureBuiltin(context, 'whatsapp');
3662
3990
  markAsync(context);
3663
3991
  const lines = [];
3664
3992
  if (node.login) {
3665
- // v2.1.2 — the pairing phone may be a compile-time literal or any
3993
+ // v2.1.2 - the pairing phone may be a compile-time literal or any
3666
3994
  // PlainScript expression (e.g. a variable filled by `ask`). Runtime values
3667
3995
  // are normalized/validated by __waNormalizePhone at startup.
3668
3996
  let loginArg;
@@ -3688,7 +4016,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3688
4016
  return lines.join('\n');
3689
4017
  }
3690
4018
 
3691
- // pair whatsapp "<phone>" — on-demand WhatsApp pairing session.
4019
+ // pair whatsapp "<phone>" - on-demand WhatsApp pairing session.
3692
4020
  // When _inTelegram is true, relays the pairing code and connection status
3693
4021
  // to the Telegram chat via ctx.chatId.
3694
4022
  case 'WhatsAppPairStatement': {
@@ -3705,7 +4033,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3705
4033
  return `${indent}await __whatsappPair(${phoneArg}, null, null);`;
3706
4034
  }
3707
4035
 
3708
- // on message … done — registers the handler that receives each incoming
4036
+ // on message … done - registers the handler that receives each incoming
3709
4037
  // WhatsApp message as a normalized PlainScript record on `message`.
3710
4038
  case 'WhatsAppOnMessageStatement': {
3711
4039
  ensureBuiltin(context, 'whatsapp');
@@ -3721,7 +4049,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3721
4049
  ].join('\n');
3722
4050
  }
3723
4051
 
3724
- // log message — prints the current message record. Handler-only by
4052
+ // log message - prints the current message record. Handler-only by
3725
4053
  // design: outside "on message" there is no message to log.
3726
4054
  case 'WhatsAppLogStatement':
3727
4055
  if (!_inWhatsApp) {
@@ -3730,7 +4058,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3730
4058
  ensureBuiltin(context, 'whatsapp');
3731
4059
  return `${indent}console.log(__waCtx.message);`;
3732
4060
 
3733
- // v2.14 — download "<path>" — saves the current message's media to a file.
4061
+ // v2.14 - download "<path>" - saves the current message's media to a file.
3734
4062
  // Handler-only by design: outside "on message" there is no message media.
3735
4063
  case 'WhatsAppDownloadStatement':
3736
4064
  if (!_inWhatsApp) {
@@ -3740,7 +4068,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3740
4068
  markAsync(context);
3741
4069
  return `${indent}await __whatsappDownload(__waCtx.message, ${JSON.stringify(node.filePath)});`;
3742
4070
 
3743
- // v2.1.0 — mail, cache, scheduling, background jobs, websocket
4071
+ // v2.1.0 - mail, cache, scheduling, background jobs, websocket
3744
4072
 
3745
4073
  case 'MailTransportStatement': {
3746
4074
  ensureBuiltin(context, 'mailer');
@@ -3774,7 +4102,7 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3774
4102
  return `${indent}await __mailSend({ ${fields} });`;
3775
4103
  }
3776
4104
 
3777
- // cache "<redis-url>" — connects the shared Redis client. At the top
4105
+ // cache "<redis-url>" - connects the shared Redis client. At the top
3778
4106
  // level the connect is awaited in program order; inside functions it is
3779
4107
  // connected fire-and-forget.
3780
4108
  case 'CacheStatement': {
@@ -3808,6 +4136,39 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3808
4136
  ].join('\n');
3809
4137
  }
3810
4138
 
4139
+ // v1.0.361 - every frame … done: one requestAnimationFrame loop. The next
4140
+ // frame is scheduled after the body so the body always runs once per
4141
+ // frame; an awaiting body makes the callback async automatically.
4142
+ case 'EveryFrameStatement': {
4143
+ const prevInHandler = context.inHandler;
4144
+ context.inHandler = true;
4145
+ const block = generateBlock(node.body, indent + ' ', context);
4146
+ context.inHandler = prevInHandler;
4147
+ const handlerAsync = block.emitted ? 'async ' : '';
4148
+ return [
4149
+ `${indent}requestAnimationFrame(${handlerAsync}function __frame(__frameTime) {`,
4150
+ block.out,
4151
+ `${indent} requestAnimationFrame(__frame);`,
4152
+ `${indent}});`,
4153
+ ].join('\n');
4154
+ }
4155
+
4156
+ // v1.0.361 - after <n> <unit> … done: one-shot setTimeout. The delay is an
4157
+ // expression scaled by the unit; an awaiting body makes the callback async.
4158
+ case 'AfterStatement': {
4159
+ const delay = generateExpr(node.delay, context);
4160
+ const prevInHandler = context.inHandler;
4161
+ context.inHandler = true;
4162
+ const block = generateBlock(node.body, indent + ' ', context);
4163
+ context.inHandler = prevInHandler;
4164
+ const handlerAsync = block.emitted ? 'async ' : '';
4165
+ return [
4166
+ `${indent}setTimeout(${handlerAsync}() => {`,
4167
+ block.out,
4168
+ `${indent}}, ${delay} * ${node.unit});`,
4169
+ ].join('\n');
4170
+ }
4171
+
3811
4172
  case 'ScheduleStatement': {
3812
4173
  ensureBuiltin(context, 'scheduler');
3813
4174
  const body = node.body.map(s => generateStatement(s, indent + ' ', context)).join('\n');
@@ -3929,6 +4290,19 @@ function generateStatement(node, indent = '', context = createGenerationContext(
3929
4290
  return `${indent}__emitter.on(${event}, (${node.paramName}) => {\n${body}\n${indent}});`;
3930
4291
  }
3931
4292
 
4293
+ // v1.0.361 - when <target> "<event>" happens [as <name>] … done: DOM event
4294
+ // listener. The handler param defaults to "event"; an awaiting body makes
4295
+ // the callback async automatically.
4296
+ case 'WhenTargetedStatement': {
4297
+ const prevInHandler = context.inHandler;
4298
+ context.inHandler = true;
4299
+ const block = generateBlock(node.body, indent + ' ', context);
4300
+ context.inHandler = prevInHandler;
4301
+ const handlerAsync = block.emitted ? 'async ' : '';
4302
+ const param = node.paramName || 'event';
4303
+ return `${indent}${generateExpr(node.target, context)}.addEventListener(${JSON.stringify(node.event)}, ${handlerAsync}function (${param}) {\n${block.out}\n${indent}});`;
4304
+ }
4305
+
3932
4306
  case 'StreamStatement': {
3933
4307
  ensureBuiltin(context, '__streamFile');
3934
4308
  markAsync(context);
@@ -3966,6 +4340,16 @@ function generateLValue(node, context) {
3966
4340
 
3967
4341
  function generateExpr(node, context = createGenerationContext()) {
3968
4342
  switch (node.type) {
4343
+ case 'BinaryCondition':
4344
+ case 'UnaryCondition':
4345
+ case 'BetweenCondition':
4346
+ case 'InCondition':
4347
+ case 'NotInCondition':
4348
+ case 'StringCondition':
4349
+ case 'LogicalCondition':
4350
+ // Comparisons are first-class expressions (e.g. `(x) -> x is above 3`),
4351
+ // so emit the same code the condition level produces.
4352
+ return generateCondition(node, context);
3969
4353
  case 'DictionaryLiteral': {
3970
4354
  if (!node.pairs || node.pairs.length === 0) return 'new Map()';
3971
4355
  const pairs = node.pairs.map(p => `[${generateExpr(p.key, context)}, ${generateExpr(p.value, context)}]`);
@@ -4000,13 +4384,13 @@ function generateExpr(node, context = createGenerationContext()) {
4000
4384
  case 'CollectionReflectExpression': {
4001
4385
  const target = generateExpr(node.target, context);
4002
4386
  if (node.accessor === 'keys') {
4003
- return `Array.from(${target}.keys())`;
4387
+ return `(${target} instanceof Map || ${target} instanceof Set ? Array.from(${target}.keys()) : Object.keys(${target}))`;
4004
4388
  }
4005
4389
  if (node.accessor === 'values') {
4006
- return `Array.from(${target}.values())`;
4390
+ return `(${target} instanceof Map || ${target} instanceof Set ? Array.from(${target}.values()) : Object.values(${target}))`;
4007
4391
  }
4008
4392
  if (node.accessor === 'entries') {
4009
- return `Array.from(${target}.entries())`;
4393
+ return `(${target} instanceof Map || ${target} instanceof Set ? Array.from(${target}.entries()) : Object.entries(${target}))`;
4010
4394
  }
4011
4395
  if (node.accessor === 'size') {
4012
4396
  return `(${target} instanceof Map || ${target} instanceof Set ? ${target}.size : (${target} && ${target}.size !== undefined ? ${target}.size : ${target}?.length))`;
@@ -4015,23 +4399,11 @@ function generateExpr(node, context = createGenerationContext()) {
4015
4399
  }
4016
4400
  case 'StringLiteral': return JSON.stringify(node.value);
4017
4401
  case 'NumberLiteral': return String(node.value);
4018
- // v2.1.1 — boolean and null literals are PlainScript keywords.
4402
+ // v2.1.1 - boolean and null literals are PlainScript keywords.
4019
4403
  case 'BooleanLiteral': return String(node.value);
4020
4404
  case 'NullLiteral': return 'null';
4021
- // v2.1.1 — arithmetic: unary minus (binary + - * / % reuse
4022
- // BinaryExpression). Binary operands need parentheses so that
4023
- // -(2 + 3) does not flatten to -2 + 3.
4024
- case 'UnaryExpression':
4025
- return `${node.operator}${node.operand.type === 'BinaryExpression'
4026
- ? `(${generateExpr(node.operand, context)})`
4027
- : generateExpr(node.operand, context)}`;
4028
- // v2.1.1 — wait for <expr>: awaits an async value (fetch promises,
4029
- // async functions called from PlainScript, etc.).
4030
- case 'AwaitExpression': {
4031
- markAsync(context);
4032
- return `(await ${generateExpr(node.value, context)})`;
4033
- }
4034
- // v2.1.1 — HTTP client: get/post/put/patch/delete "<url>" with clauses.
4405
+
4406
+ // v2.1.1 - HTTP client: get/post/put/patch/delete "<url>" with clauses.
4035
4407
  case 'HttpCall': {
4036
4408
  ensureBuiltin(context, 'http');
4037
4409
  markAsync(context);
@@ -4094,7 +4466,7 @@ function generateExpr(node, context = createGenerationContext()) {
4094
4466
  return `{ ${props} }`;
4095
4467
  }
4096
4468
 
4097
- // v1.2 — Inline object literal: { key: value, ... }
4469
+ // v1.2 - Inline object literal: { key: value, ... }
4098
4470
  case 'InlineObjectLiteral': {
4099
4471
  const props = node.properties
4100
4472
  .map(p => `${JSON.stringify(p.key)}: ${generateExpr(p.value, context)}`)
@@ -4120,12 +4492,47 @@ function generateExpr(node, context = createGenerationContext()) {
4120
4492
  case 'OptionalCallExpression':
4121
4493
  return `${generateExpr(node.callee.object, context)}?.${node.callee.property}(${node.args.map(arg => generateExpr(arg, context)).join(', ')})`;
4122
4494
 
4495
+ // Function expression: (params) -> expression → (params) => expression.
4496
+ // Block-bodied form: (params) do ... done → (params) => { ... } - reuses
4497
+ // generateBlock, the same body emitter as `make` functions, so closures,
4498
+ // effects, loops, conditionals, early returns, and async/await behave
4499
+ // exactly like ordinary functions.
4500
+ case 'ArrowFunctionExpression': {
4501
+ const prevInFunction = context.inFunction;
4502
+ context.inFunction = true;
4503
+ const prevAwait = context.emittedAwait;
4504
+ context.emittedAwait = false;
4505
+ const paramStr = node.params.map(p => typeof p === 'object' && p ? p.name : p).join(', ');
4506
+ if (node.block) {
4507
+ const block = generateBlock(node.body, ' ', context);
4508
+ const isAsync = block.emitted ? 'async ' : '';
4509
+ context.emittedAwait = prevAwait;
4510
+ context.inFunction = prevInFunction;
4511
+ return `${isAsync}(${paramStr}) => {\n${block.out}\n}`;
4512
+ }
4513
+ const body = generateExpr(node.body, context);
4514
+ const emitted = context.emittedAwait;
4515
+ context.emittedAwait = prevAwait;
4516
+ context.inFunction = prevInFunction;
4517
+ const isAsync = emitted ? 'async ' : '';
4518
+ return `${isAsync}(${paramStr}) => ${body}`;
4519
+ }
4520
+
4123
4521
  case 'CallExpression': {
4124
- // Method call: receiver.method(args). Member access invoked with parens —
4522
+ // Method call: receiver.method(args). Member access invoked with parens -
4125
4523
  // e.g. path.join("a", "b"), mrz.parse(line), fs.existsSync(("x")).
4524
+ // Postfix calls f()(), arr[0](1), mul(6)(7) also bind here; any composite
4525
+ // callee (arrow, binary, comparison/logical condition) is parenthesised so
4526
+ // the call still applies to the whole value, not its last operand.
4126
4527
  if (node.callee) {
4127
4528
  const args = node.args.map(arg => generateExpr(arg, context)).join(', ');
4128
- return `${generateExpr(node.callee, context)}(${args})`;
4529
+ const callee = generateExpr(node.callee, context);
4530
+ const composite = node.callee.type === 'ArrowFunctionExpression' ||
4531
+ node.callee.type === 'BinaryExpression' ||
4532
+ node.callee.type === 'LogicalCondition' ||
4533
+ node.callee.type === 'ComparisonCondition' ||
4534
+ node.callee.type === 'UnaryExpression';
4535
+ return `${composite ? `(${callee})` : callee}(${args})`;
4129
4536
  }
4130
4537
  if (STDLIB[node.name]) {
4131
4538
  if (node.name === 'readFile' || node.name === 'writeFile' ||
@@ -4139,7 +4546,7 @@ function generateExpr(node, context = createGenerationContext()) {
4139
4546
  return `${node.name}(${node.args.map(arg => generateExpr(arg, context)).join(', ')})`;
4140
4547
  }
4141
4548
 
4142
- // v1.1 — Item expressions
4549
+ // v1.1 - Item expressions
4143
4550
  case 'FirstItem':
4144
4551
  return `${generateExpr(node.collection, context)}[0]`;
4145
4552
 
@@ -4152,9 +4559,14 @@ function generateExpr(node, context = createGenerationContext()) {
4152
4559
  case 'LengthExpression':
4153
4560
  return `${generateExpr(node.object, context)}.length`;
4154
4561
 
4155
- // v1.1 — Property access
4562
+ case 'CountOfExpression': {
4563
+ const obj = generateExpr(node.object, context);
4564
+ return `((${obj} && ${obj}.count !== undefined) ? ${obj}.count : ((${obj} && ${obj}.length !== undefined) ? ${obj}.length : ((${obj} && ${obj}.size !== undefined) ? ${obj}.size : 0)))`;
4565
+ }
4566
+
4567
+ // v1.1 - Property access
4156
4568
  case 'OfExpression': {
4157
- // v2.1.1 — "session of request" / "user of request" read server-side
4569
+ // v2.1.1 - "session of request" / "user of request" read server-side
4158
4570
  // state managed by the session and OAuth runtimes.
4159
4571
  if (node.object.type === 'Identifier' && node.object.name === 'request' &&
4160
4572
  node.property.type === 'Identifier') {
@@ -4172,18 +4584,21 @@ function generateExpr(node, context = createGenerationContext()) {
4172
4584
  return `${generateExpr(node.object, context)}.${generateExpr(node.property, context)}`;
4173
4585
  }
4174
4586
 
4175
- // v1.1 — Collection operations
4587
+ // v1.1 - Collection operations
4176
4588
  case 'AddCall':
4177
4589
  return `${generateExpr(node.collection, context)}.push(${generateExpr(node.value, context)})`;
4178
4590
 
4179
- case 'RemoveCall':
4180
- return `${generateExpr(node.collection, context)}.splice(${generateExpr(node.collection, context)}.indexOf(${generateExpr(node.value, context)}), 1)`;
4591
+ case 'RemoveCall': {
4592
+ const coll = generateExpr(node.collection, context);
4593
+ const val = generateExpr(node.value, context);
4594
+ return `${coll} instanceof Map || ${coll} instanceof Set ? ${coll}.delete(${val}) : ${coll}.splice(${coll}.indexOf(${val}), 1)`;
4595
+ }
4181
4596
 
4182
4597
  case 'WriteCall':
4183
4598
  ensureBuiltin(context, 'fs');
4184
4599
  return `fs.writeFileSync(${generateExpr(node.data, context)}, ${generateExpr(node.file, context)}, 'utf8')`;
4185
4600
 
4186
- // v1.0.1 — record constructor: `create a Person with name "Ada" and age 17`
4601
+ // v1.0.1 - record constructor: `create a Person with name "Ada" and age 17`
4187
4602
  // calls the kind factory that `define a kind called "Person"` registered.
4188
4603
  case 'CreateKindExpression': {
4189
4604
  const fields = node.pairs
@@ -4192,7 +4607,7 @@ function generateExpr(node, context = createGenerationContext()) {
4192
4607
  return `${node.kind}({ ${fields} })`;
4193
4608
  }
4194
4609
 
4195
- // v1.0.1 — concurrency combinators: `all of [...]` / `any of [...]` /
4610
+ // v1.0.1 - concurrency combinators: `all of [...]` / `any of [...]` /
4196
4611
  // `settled of [...]`. All are awaited; `settled` returns status records.
4197
4612
  case 'ConcurrencyExpression': {
4198
4613
  markAsync(context);
@@ -4202,7 +4617,7 @@ function generateExpr(node, context = createGenerationContext()) {
4202
4617
  return `(await Promise.all(${rhs}))`;
4203
4618
  }
4204
4619
 
4205
- // v1.0.1 — `spread of <collection>` → a fresh array from an iterable.
4620
+ // v1.0.1 - `spread of <collection>` → a fresh array from an iterable.
4206
4621
  case 'SpreadExpression':
4207
4622
  return `[...${generateExpr(node.collection, context)}]`;
4208
4623