plainscript-lang 1.0.36 → 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 (84) hide show
  1. package/README.md +251 -19
  2. package/compiler/bundler.js +4 -4
  3. package/compiler/cli.js +18 -18
  4. package/compiler/dependency-detector.js +34 -22
  5. package/compiler/generator.js +286 -186
  6. package/compiler/lexer.js +49 -39
  7. package/compiler/parser.js +552 -181
  8. package/compiler/sourcemap.js +1 -1
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +2 -2
  11. package/docs/FB-PROMPT.md +524 -0
  12. package/docs/GAME-PROMPT.md +56 -55
  13. package/docs/PLAINSCRIPT-SPEC.md +16 -15
  14. package/docs/index.html +13 -6
  15. package/docs/website/script.js +1 -1
  16. package/docs/website/style.css +3 -3
  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 +3 -3
  25. package/examples/browser-interactive/src/interactive.pln +1 -1
  26. package/examples/cache-and-jobs.pln +1 -1
  27. package/examples/cache-schedule.pln +1 -1
  28. package/examples/canvas-game/README.md +4 -4
  29. package/examples/canvas-game/src/game.pln +1 -1
  30. package/examples/collections.pln +1 -1
  31. package/examples/concurrency.pln +1 -1
  32. package/examples/conditions.pln +1 -1
  33. package/examples/database.pln +1 -1
  34. package/examples/day2.pln +1 -1
  35. package/examples/day3.pln +1 -1
  36. package/examples/deployment.pln +1 -1
  37. package/examples/email-send.pln +1 -1
  38. package/examples/error-handling.pln +3 -2
  39. package/examples/expressions.pln +1 -1
  40. package/examples/file-uploads.pln +1 -1
  41. package/examples/files-and-config.pln +1 -1
  42. package/examples/files.pln +1 -1
  43. package/examples/football-backend/app.pln +1 -1
  44. package/examples/functions.pln +1 -1
  45. package/examples/hello.pln +1 -1
  46. package/examples/http-client.pln +1 -1
  47. package/examples/http.pln +1 -1
  48. package/examples/id-verification/app.pln +1 -1
  49. package/examples/javascript-library/README.md +6 -6
  50. package/examples/javascript-library/public/index.html +1 -1
  51. package/examples/javascript-library/src/interop.pln +1 -1
  52. package/examples/json.pln +1 -1
  53. package/examples/loops.pln +1 -1
  54. package/examples/modules/app.pln +1 -1
  55. package/examples/modules/main.pln +1 -1
  56. package/examples/modules/math.pln +1 -1
  57. package/examples/mongo.pln +1 -1
  58. package/examples/objects.pln +1 -1
  59. package/examples/ocr.pln +1 -1
  60. package/examples/packages.pln +1 -1
  61. package/examples/record-kinds.pln +1 -1
  62. package/examples/records.pln +1 -1
  63. package/examples/rest-api-fetch.pln +1 -1
  64. package/examples/rest-api.pln +1 -1
  65. package/examples/scheduled-tasks.pln +1 -1
  66. package/examples/search-and-filter.pln +1 -1
  67. package/examples/server.pln +1 -1
  68. package/examples/sessions-and-cookies.pln +1 -1
  69. package/examples/sqlite.pln +1 -1
  70. package/examples/start.pln +1 -1
  71. package/examples/stdlib.pln +1 -1
  72. package/examples/string-verbs.pln +1 -1
  73. package/examples/telegram-ai-bot.pln +1 -1
  74. package/examples/telegram-bot.pln +1 -1
  75. package/examples/testing.pln +1 -1
  76. package/examples/three-dimensional/README.md +2 -2
  77. package/examples/three-dimensional/src/scene.pln +1 -1
  78. package/examples/web-api.pln +1 -1
  79. package/examples/web-app.pln +1 -1
  80. package/examples/websocket-server.pln +1 -1
  81. package/examples/websocket.pln +1 -1
  82. package/examples/whatsapp-bot/pairing.pln +2 -2
  83. package/examples/whatsapp-bot/qr.pln +2 -2
  84. package/package.json +7 -9
@@ -1,4 +1,4 @@
1
- # PlainScript Game Development Prompt Guide (v1.0.36)
1
+ # PlainScript Game Development Prompt Guide (v1.0.361)
2
2
 
3
3
  The standing instruction sheet for AI agents asked to build games and
4
4
  interactive browser apps in PlainScript.
@@ -11,25 +11,25 @@ the compiler actually implements.
11
11
 
12
12
  - **Work in PlainScript.** Write `.pln`, compile it, ship the generated JS. Do
13
13
  not hand-rewrite the logic in JavaScript.
14
- - **Rule Zero — trust the compiler, nothing else.** Before you claim anything
14
+ - **Rule Zero - trust the compiler, nothing else.** Before you claim anything
15
15
  works, run `node compiler/cli.js check <file.pln>` (or `plainscript check`).
16
16
  If it does not compile, it does not work.
17
- - **You may import and CALL any JavaScript library** — canvas, Web Audio,
17
+ - **You may import and CALL any JavaScript library** - canvas, Web Audio,
18
18
  three.js, matter.js, npm packages, browser globals. `new Type(args)`, member
19
19
  chains, property assignment, promises, and callbacks all work.
20
20
  - **Never rewrite PlainScript project logic in JavaScript** just because the
21
21
  underlying API is JS. A library is *called* from PlainScript; game logic
22
22
  stays in `.pln`. JS is the guest library, not the host language.
23
23
 
24
- Every PlainScript block you show a user must compile — check it first.
24
+ Every PlainScript block you show a user must compile - check it first.
25
25
 
26
26
  ---
27
27
 
28
28
  ## 1. Philosophy: intent-first, never rewrite in JavaScript (cardinal rule)
29
29
 
30
30
  PlainScript is intent-oriented: you describe *what* the game should do and the
31
- compiler generates JavaScript. One hard rule — **game logic lives in
32
- PlainScript**. v1.0.36 reaches into any JS API from `.pln`, which makes
31
+ compiler generates JavaScript. One hard rule - **game logic lives in
32
+ PlainScript**. v1.0.361 reaches into any JS API from `.pln`, which makes
33
33
  dropping to JS tempting; do not. Every browser capability below stays
34
34
  reachable without leaving PlainScript.
35
35
 
@@ -58,13 +58,13 @@ my-game/
58
58
  web app that serves the page; `public/index.html` is a dumb shell owning the
59
59
  canvas and script tag; `public/game.js` is build output, never hand-edited;
60
60
  `src/*.pln` helpers are pulled in with `bring name from "./helpers.pln"`.
61
- Keep server and client logic in separate files — different runtimes.
61
+ Keep server and client logic in separate files - different runtimes.
62
62
 
63
63
  ---
64
64
 
65
65
  ## 3. Browser target / how a game is served
66
66
 
67
- A game is static files. `server.pln` — `serve folder "public"` exposes every
67
+ A game is static files. `server.pln` - `serve folder "public"` exposes every
68
68
  file under `public/` at `/`, and `reply file` sends the HTML shell for the
69
69
  root path:
70
70
 
@@ -94,14 +94,14 @@ node compiler/cli.js build src/game.pln -o public/game.js
94
94
  ```
95
95
 
96
96
  **Package-free JS is browser-`<script>`-safe.** Without an npm import the
97
- generated code has no `require()` — it is an async IIFE with a guarded
97
+ generated code has no `require()` - it is an async IIFE with a guarded
98
98
  `module.exports` tail, so it loads as a plain script.
99
99
 
100
100
  **When you need an npm library in the browser:**
101
101
 
102
102
  1. **CDN global (preferred, stays package-free).** Load the library in
103
103
  `index.html` *before* `game.js`; it becomes a browser global that
104
- PlainScript calls directly — no `use`, no bundler:
104
+ PlainScript calls directly - no `use`, no bundler:
105
105
 
106
106
  ```html
107
107
  <script src="https://unpkg.com/three@0.160.0/build/three.min.js"></script>
@@ -118,7 +118,7 @@ generated code has no `require()` — it is an async IIFE with a guarded
118
118
 
119
119
  ### 4.1 Canvas 2D
120
120
 
121
- Default for 2D games — get the element, its 2D context, draw each frame:
121
+ Default for 2D games - get the element, its 2D context, draw each frame:
122
122
 
123
123
  ```plainscript
124
124
  remember canvas as document.getElementById("game")
@@ -136,8 +136,8 @@ done
136
136
  requestAnimationFrame(step)
137
137
  ```
138
138
 
139
- Canvas state is property interop — `fillStyle becomes ...`, `strokeStyle
140
- becomes ...`, `font becomes ...` — then a draw call. Colors like `"#0d1117"`
139
+ Canvas state is property interop - `fillStyle becomes ...`, `strokeStyle
140
+ becomes ...`, `font becomes ...` - then a draw call. Colors like `"#0d1117"`
141
141
  are just strings. Match the canvas backing size to its display size so nothing
142
142
  drifts on resize:
143
143
 
@@ -180,7 +180,7 @@ remember prog as glProgram(gl, vs, fs)
180
180
  remember buf as glBuffer(gl, [0.0, 0.0, 1.0, 0.0, 0.0, 1.0])
181
181
  ```
182
182
 
183
- Per-frame render — keep setup out of the loop:
183
+ Per-frame render - keep setup out of the loop:
184
184
 
185
185
  ```plainscript
186
186
  make renderTriangle()
@@ -196,7 +196,7 @@ done
196
196
 
197
197
  ### 4.3 WebGPU
198
198
 
199
- No special syntax — plain member-chain interop like WebGL, guarded, with the
199
+ No special syntax - plain member-chain interop like WebGL, guarded, with the
200
200
  promise verbs for async parts. Do not over-promise; support depends on the
201
201
  browser/GPU:
202
202
 
@@ -237,8 +237,8 @@ done
237
237
  requestAnimationFrame(loop)
238
238
  ```
239
239
 
240
- v1.0.36 adds hex literals (`0xRRGGBB`): numeric colors use `0xffffff` instead
241
- of magic decimals, and a `"#ffffff"` string works too — THREE accepts all
240
+ v1.0.361 adds hex literals (`0xRRGGBB`): numeric colors use `0xffffff` instead
241
+ of magic decimals, and a `"#ffffff"` string works too - THREE accepts all
242
242
  three.
243
243
 
244
244
  ---
@@ -266,7 +266,7 @@ make step(dt)
266
266
  done
267
267
  ```
268
268
 
269
- - Never mutate world state inside an event handler — set a flag, let the loop
269
+ - Never mutate world state inside an event handler - set a flag, let the loop
270
270
  consume it.
271
271
  - `when <target> "<event>" happens` → `target.addEventListener(event, ...)`
272
272
  with the parameter named via `as name` (default `event`).
@@ -293,7 +293,7 @@ when window "wheel" happens as e
293
293
  done
294
294
  ```
295
295
 
296
- Touch reuses pointer events (`"touchmove"`) — call `e.preventDefault()` when
296
+ Touch reuses pointer events (`"touchmove"`) - call `e.preventDefault()` when
297
297
  you own the gesture; `"wheel"` gives `e.deltaY` for zoom; `gamepads()` returns
298
298
  connected pads to read inside the loop; drag-and-drop files arrive via
299
299
  `droppedFiles(event)` in a `drop` handler.
@@ -304,9 +304,9 @@ connected pads to read inside the loop; drag-and-drop files arrive via
304
304
 
305
305
  The browser runs a single-threaded event loop; the only good loop is
306
306
  `requestAnimationFrame` (rAF). A `while true` or long synchronous loop blocks
307
- rendering, input, and audio — the page freezes. Never write one.
307
+ rendering, input, and audio - the page freezes. Never write one.
308
308
 
309
- rAF passes a millisecond timestamp — difference, normalize to seconds, and
309
+ rAF passes a millisecond timestamp - difference, normalize to seconds, and
310
310
  movement is frame-rate independent:
311
311
 
312
312
  ```plainscript
@@ -324,14 +324,14 @@ requestAnimationFrame(loop)
324
324
 
325
325
  Cap `dt` (skip the step after a long stall) so a background-tab resume does not
326
326
  jump the sim forward by seconds. For loops that do not need delta time, the
327
- short form is `every frame ... done` (still rAF under the hood — see the
327
+ short form is `every frame ... done` (still rAF under the hood - see the
328
328
  Appendix); use rAF + `dt` when movement must be time-based.
329
329
 
330
330
  ---
331
331
 
332
332
  ## 7. Asset loading
333
333
 
334
- Built-in loaders return promises and **auto-await** — no `await` written:
334
+ Built-in loaders return promises and **auto-await** - no `await` written:
335
335
 
336
336
  ```plainscript
337
337
  remember bg as loadImage("img/background.png")
@@ -341,16 +341,16 @@ remember manifest as fetchJson("assets/manifest.json")
341
341
 
342
342
  - `loadImage(url)` → an `Image` ready for `ctx.drawImage(img, x, y)`.
343
343
  - `loadAudio(url)` → an `Audio` element; call `sound.play()`.
344
- - `fetchJson(url)` → `{ok, status, data, text, parseError}` — never throws on a
344
+ - `fetchJson(url)` → `{ok, status, data, text, parseError}` - never throws on a
345
345
  bad status; check `ok`.
346
346
  - `fetchBytes(url)` → `{ok, status, data: Uint8Array}` for binary payloads.
347
347
  - `readDataUrl(file)` → a `data:` URL string for a `File` (from
348
- `droppedFiles(event)` or a file input) — feed it straight to `loadImage`.
348
+ `droppedFiles(event)` or a file input) - feed it straight to `loadImage`.
349
349
 
350
350
  For an `Image` you own, use `new Image()` and `spriteSheet.src becomes "img.png"`.
351
351
 
352
352
  Start the scene **after** assets are ready, or the first frame draws a blank
353
- flash — gate scene start on a loaded flag. Sprite atlases are one image plus a
353
+ flash - gate scene start on a loaded flag. Sprite atlases are one image plus a
354
354
  `fetchJson` manifest of `{x, y, w, h}` frames, drawn with
355
355
  `drawImage(sheet, sx, sy, sw, sh, dx, dy, dw, dh)`.
356
356
 
@@ -366,7 +366,7 @@ remember sfx as loadAudio("boing.mp3")
366
366
 
367
367
  `audioContext()` lazily creates a singleton `AudioContext` (with a
368
368
  `webkitAudioContext` fallback); `playTone(freq, seconds, options)` plays a tone
369
- on it. **Browsers require a user gesture to start audio** — the context stays
369
+ on it. **Browsers require a user gesture to start audio** - the context stays
370
370
  `"suspended"` until a click/keypress/touch, so resume it from the first one:
371
371
 
372
372
  ```plainscript
@@ -376,7 +376,7 @@ done
376
376
  document.addEventListener("click", resumeAudio)
377
377
  ```
378
378
 
379
- The #1 "audio does not work" bug in browser games — always wire the resume.
379
+ The #1 "audio does not work" bug in browser games - always wire the resume.
380
380
 
381
381
  ---
382
382
 
@@ -415,7 +415,7 @@ one predictable place per frame.
415
415
 
416
416
  ## 10. Collision and physics
417
417
 
418
- Two workhorse tests. AABB — exact enough for rectangles and tiles:
418
+ Two workhorse tests. AABB - exact enough for rectangles and tiles:
419
419
 
420
420
  ```plainscript
421
421
  if enemy.x is at least player.x - 26 and enemy.x is at most player.x + 26 and enemy.y is at least player.y - 26 and enemy.y is at most player.y + 26
@@ -423,7 +423,7 @@ if enemy.x is at least player.x - 26 and enemy.x is at most player.x + 26 and en
423
423
  done
424
424
  ```
425
425
 
426
- Circle distance — compare squared distance against squared radius to skip a
426
+ Circle distance - compare squared distance against squared radius to skip a
427
427
  `Math.sqrt` per pair:
428
428
 
429
429
  ```plainscript
@@ -436,8 +436,8 @@ done
436
436
  ```
437
437
 
438
438
  With many entities, do a broad phase first (bounding boxes, tile-grid buckets)
439
- and run the precise test only on candidates. When you need real physics —
440
- impulses, joints, continuous collision — delegate to a physics library. That is
439
+ and run the precise test only on candidates. When you need real physics -
440
+ impulses, joints, continuous collision - delegate to a physics library. That is
441
441
  interop, not surrender:
442
442
 
443
443
  ```plainscript
@@ -465,7 +465,7 @@ library computes physics.
465
465
  ## 11. UI overlay via DOM
466
466
 
467
467
  Canvas = the world; DOM = the chrome. Score, lives, menus, and buttons live in
468
- HTML and update by property assignment — `innerHTML becomes`,
468
+ HTML and update by property assignment - `innerHTML becomes`,
469
469
  `textContent becomes`, `classList.add`. Do not build UI in canvas when a div
470
470
  will do:
471
471
 
@@ -529,7 +529,7 @@ compact tick/snapshot; clients render and correct.
529
529
 
530
530
  ## 13. Persistence
531
531
 
532
- `localStorage` is direct interop — strings only. Wrap state in JSON:
532
+ `localStorage` is direct interop - strings only. Wrap state in JSON:
533
533
 
534
534
  ```plainscript
535
535
  remember rawSave as localStorage.getItem("plainscript-save")
@@ -540,7 +540,7 @@ done
540
540
  localStorage.setItem("plainscript-save", jsonEncode(state))
541
541
  ```
542
542
 
543
- Save on meaningful changes or `beforeunload`, not every frame —
543
+ Save on meaningful changes or `beforeunload`, not every frame -
544
544
  `localStorage` is synchronous and small (~5MB). For structured or large data,
545
545
  wrap IndexedDB behind promises via the `idb` npm library (`use idb`).
546
546
 
@@ -551,9 +551,9 @@ wrap IndexedDB behind promises via the `idb` npm library (`use idb`).
551
551
  - **One rAF loop, one `step(dt)`.** No scattered timers drawing or simulating
552
552
  independently.
553
553
  - **No allocations in the loop.** Reuse typed arrays and mutating math
554
- (gl-matrix `mat4.rotateX(mat, mat, 0.5)`) — never fresh arrays per frame.
554
+ (gl-matrix `mat4.rotateX(mat, mat, 0.5)`) - never fresh arrays per frame.
555
555
  - **Cap dt** so a background-tab resume cannot run the sim forward for seconds.
556
- - **Canvas sizing discipline.** Match backing size to display size — oversized
556
+ - **Canvas sizing discipline.** Match backing size to display size - oversized
557
557
  canvases are the #1 silent frame-rate killer.
558
558
  - **Reuse sprites and draw calls**; redraw only what changed.
559
559
  - **No synchronous work in the loop.** No storage writes, no fetch, no heavy
@@ -584,14 +584,14 @@ bring axios from "axios"
584
584
  bring geometry from "./helpers.pln"
585
585
  ```
586
586
 
587
- **Call member chains** — no special syntax:
587
+ **Call member chains** - no special syntax:
588
588
 
589
589
  ```plainscript
590
590
  crypto.createHash("sha256").update("abc").digest("hex")
591
591
  mesh.scale.set(2, 2, 2)
592
592
  ```
593
593
 
594
- **Construct with `new Type(args)`** — statement start, `remember`, arguments,
594
+ **Construct with `new Type(args)`** - statement start, `remember`, arguments,
595
595
  member chains, or bare without parens:
596
596
 
597
597
  ```plainscript
@@ -613,9 +613,9 @@ window.addEventListener("resize", fitWindow)
613
613
  button.onclick becomes fitWindow
614
614
  ```
615
615
 
616
- **Promises** — browser builtins (`loadImage`, `fetchJson`, `loadAudio`)
616
+ **Promises** - browser builtins (`loadImage`, `fetchJson`, `loadAudio`)
617
617
  auto-await. Raw interop uses `await` / `wait for`; errors use the repository's
618
- `try/recover` idiom — never `.then`:
618
+ `try/recover` idiom - never `.then`:
619
619
 
620
620
  ```plainscript
621
621
  remember response as await fetch("/api/state")
@@ -629,9 +629,10 @@ recover as err
629
629
  show message of err
630
630
  finally
631
631
  show "done"
632
+ done
632
633
  ```
633
634
 
634
- **Typed arrays / binary** — `remember buffer as new Uint8Array(64)` and index
635
+ **Typed arrays / binary** - `remember buffer as new Uint8Array(64)` and index
635
636
  with `buffer[0] becomes 255`.
636
637
 
637
638
  **Arrays, objects, JSON:**
@@ -645,7 +646,7 @@ remember config as jsonDecode(rawJson)
645
646
  ```
646
647
 
647
648
  Rules: no `=>`, `.then`, `let/const`, braces, or semicolons in `.pln`. A
648
- library is *called* from PlainScript — symbol, flow, and state stay in
649
+ library is *called* from PlainScript - symbol, flow, and state stay in
649
650
  PlainScript. Need a stateful callback? Define a `make` function that reads the
650
651
  shared state you already have.
651
652
 
@@ -686,7 +687,7 @@ Debug by checking `game.js` for that shape (`addEventListener`,
686
687
  | Variable named for a keyword/builtin | Rename (`start`, `now`, `get`, `set`, `reply`, `from`, `as`, `of`, `in`, `json`, `bytes`, `update`, `status` are taken) |
687
688
  | Writing `is most` for `<=` | Use `is at most` (`is most` is not a comparison) |
688
689
  | Storing colors as opaque decimals (`4244579`) | Hex literal `0x40c463` is supported (or a `"#40c463"` string) |
689
- | `make update` / `make get` as function names | Rename — those are keywords |
690
+ | `make update` / `make get` as function names | Rename - those are keywords |
690
691
  | Bare `keys["ArrowLeft"]` in `if` | Compare: `if keys["ArrowLeft"] is true` |
691
692
  | Audio with no user gesture | `ctx.resume()` from a click/keydown handler |
692
693
  | Drawing before assets load | Gate scene start on a loaded flag |
@@ -833,7 +834,7 @@ requestAnimationFrame(loop)
833
834
  For games up to a few hundred lines, one `.pln` file is correct: one `state`
834
835
  record owned by the loop, one rAF loop (`every frame` or the dt form) that
835
836
  steps then draws, one input set (a `keys{}` map plus one pointer handler), and
836
- plain DOM updates for the HUD. File count should track surface area — a small
837
+ plain DOM updates for the HUD. File count should track surface area - a small
837
838
  game in five files is as wrong as a big game in one.
838
839
 
839
840
  ### 19.2 Large games
@@ -850,15 +851,15 @@ remember firstWave as spawnEnemy(320, 40)
850
851
 
851
852
  A proven structure:
852
853
 
853
- - **Entity factories** — `define a kind` plus a `make spawnThing()` returning a
854
+ - **Entity factories** - `define a kind` plus a `make spawnThing()` returning a
854
855
  new instance; one file per entity family.
855
- - **Systems as `make` functions** — one system (movement, collision, rendering,
856
+ - **Systems as `make` functions** - one system (movement, collision, rendering,
856
857
  scoring) per function, run in order by the loop.
857
- - **Scene/state table** — a state record or switch with explicit `attract`,
858
+ - **Scene/state table** - a state record or switch with explicit `attract`,
858
859
  `play`, and `gameover` states.
859
- - **Asset manifest** — one `assets` record of URLs loaded at boot; scenes look
860
+ - **Asset manifest** - one `assets` record of URLs loaded at boot; scenes look
860
861
  up paths instead of hardcoding.
861
- - **A server when networking** — own `server.pln` with `websocket server`,
862
+ - **A server when networking** - own `server.pln` with `websocket server`,
862
863
  authority checks, and snapshot broadcasts; the client is a pure renderer +
863
864
  input reporter.
864
865
 
@@ -887,7 +888,7 @@ APIs stay libraries you call.
887
888
 
888
889
  ## Appendix A: Canonical snippets quick reference
889
890
 
890
- Every line below is verified canonical form — copy it exactly:
891
+ Every line below is verified canonical form - copy it exactly:
891
892
 
892
893
  ```plainscript
893
894
  remember canvas as document.getElementById("game")
@@ -909,7 +910,7 @@ remember bg as loadImage("img.png")
909
910
 
910
911
  Runnable, maintained reference implementations live in:
911
912
 
912
- - `examples/canvas-game` — canvas 2D dodge game (keys map + `every frame` + delta time + kinds + restart).
913
- - `examples/browser-interactive` — DOM-first interactive app (`when ... happens`, `classList`, innerHTML/textContent).
914
- - `examples/three-dimensional` — WebGL 3D scene via the global `THREE` object.
915
- - `examples/javascript-library` — an npm library (`bring THREE from "three"`), callbacks, and `fetchJson`.
913
+ - `examples/canvas-game` - canvas 2D dodge game (keys map + `every frame` + delta time + kinds + restart).
914
+ - `examples/browser-interactive` - DOM-first interactive app (`when ... happens`, `classList`, innerHTML/textContent).
915
+ - `examples/three-dimensional` - WebGL 3D scene via the global `THREE` object.
916
+ - `examples/javascript-library` - an npm library (`bring THREE from "three"`), callbacks, and `fetchJson`.
@@ -1,4 +1,4 @@
1
- # PlainScript 1.0.36 language specification
1
+ # PlainScript 1.0.361 language specification
2
2
 
3
3
  This reference covers the syntax implemented by `compiler/lexer.js` and
4
4
  `compiler/parser.js`. The runtime it generates lives in
@@ -230,6 +230,7 @@ recover as error
230
230
  show message of error
231
231
  finally
232
232
  show "finished"
233
+ done
233
234
 
234
235
  retry 3 times every 1 second
235
236
  show "retry"
@@ -311,7 +312,7 @@ accepts the following clauses:
311
312
  | Clause | Purpose |
312
313
  |--------|---------|
313
314
  | `auth "<folder>"` | Path where session credentials persist across restarts. |
314
- | `use baileys "<pkg>"` | Optional. Override the Baileys package (default: `@qwerty-xcv/baileys`). |
315
+ | `use baileys "<pkg>"` | Optional. Override the Baileys package (default: `@whiskeysockets/baileys`). |
315
316
  | `login qr` | Authenticate by scanning a QR code in the terminal. |
316
317
  | `login pairing "<phone>"` | Authenticate by entering a phone number (digits only, no `+`). The argument may also be an expression such as `env("WHATSAPP_PHONE")`. |
317
318
  | `on message ... done` | Handler that fires for every incoming message. |
@@ -326,7 +327,7 @@ include `message.text`, `message.type`, `message.mtype`, `message.caption`,
326
327
  ```plainscript
327
328
  whatsapp bot
328
329
  auth "plain-script-whatsapp"
329
- use baileys "@qwerty-xcv/baileys"
330
+ use baileys "@whiskeysockets/baileys"
330
331
  login pairing "2348012345678"
331
332
  on message
332
333
  if message.text is "/start"
@@ -377,12 +378,12 @@ documents, buttons, lists, and more. The following helpers are available:
377
378
  `"reaction"`, `"contact"`, `"contacts"`, `"location"`, `"live-location"`,
378
379
  `"poll"`, `"group-invite"`, and `"other"`.
379
380
 
380
- **Full example — media, buttons, and list replies:**
381
+ **Full example - media, buttons, and list replies:**
381
382
 
382
383
  ```plainscript
383
384
  whatsapp bot
384
385
  auth "plain-script-whatsapp"
385
- use baileys "@qwerty-xcv/baileys"
386
+ use baileys "@whiskeysockets/baileys"
386
387
  login pairing env("WHATSAPP_PHONE")
387
388
  on message
388
389
  log message
@@ -448,7 +449,7 @@ PlainScript compiles to Plain JavaScript that runs in modern browsers. A
448
449
  `web app` can serve the page itself, or you compile a `.pln` to `game.js` and
449
450
  serve it with any static host. The tested workflows are:
450
451
 
451
- 1. **Static**, served by PlainScript — `web app` + `serve folder "public"` +
452
+ 1. **Static**, served by PlainScript - `web app` + `serve folder "public"` +
452
453
  a `reply file` route that returns `index.html`:
453
454
 
454
455
  ```plainscript
@@ -460,10 +461,10 @@ serve it with any static host. The tested workflows are:
460
461
  start 8000
461
462
  ```
462
463
 
463
- 2. **Static**, any host — `node compiler/cli.js build game.pln -o public/game.js`
464
+ 2. **Static**, any host - `node compiler/cli.js build game.pln -o public/game.js`
464
465
  and include `<script src="game.js">` after the canvas and any CDN globals.
465
466
 
466
- Canvas apps use the same value/property interop as everything else — canvas
467
+ Canvas apps use the same value/property interop as everything else - canvas
467
468
  state is assigned with `becomes`, then a draw call runs:
468
469
 
469
470
  ```plainscript
@@ -475,7 +476,7 @@ ctx.fillRect(0, 0, 320, 240)
475
476
 
476
477
  Animation is `requestAnimationFrame`. Two native loop forms: `every frame`
477
478
  (timing-agnostic) and an explicit rAF callback with delta seconds for
478
- frame-rate-independent movement — see `docs/GAME-PROMPT.md` for the canonical
479
+ frame-rate-independent movement - see `docs/GAME-PROMPT.md` for the canonical
479
480
  `dt` idiom. Input uses the DOM event form; `when <target> "<event>" happens`
480
481
  becomes `addEventListener`, and reading a key map uses a boolean comparison:
481
482
 
@@ -493,7 +494,7 @@ if keys["ArrowLeft"] is true
493
494
  done
494
495
  ```
495
496
 
496
- Browser builtins are either direct helpers or auto-awaited promises — no
497
+ Browser builtins are either direct helpers or auto-awaited promises - no
497
498
  `await` is written for the loaders:
498
499
 
499
500
  - `select("canvas")` / `selectAll(".card")` / `parseHTML("<div>...</div>")`
@@ -502,7 +503,7 @@ Browser builtins are either direct helpers or auto-awaited promises — no
502
503
  → `{ok, status, data: Uint8Array}`
503
504
  - `readDataUrl(file)` → a `data:` URL string for a `File` (from
504
505
  `droppedFiles(event)` or a file input)
505
- - `audioContext()` + `playTone(frequency, seconds, options)` — start from a
506
+ - `audioContext()` + `playTone(frequency, seconds, options)` - start from a
506
507
  user-gesture handler (`ctx.resume()`)
507
508
  - `localPoint(event, canvas)` maps client to canvas coordinates
508
509
  - `gamepads()` returns connected pads; `droppedFiles(event)` reads drag-drop
@@ -513,7 +514,7 @@ Browser builtins are either direct helpers or auto-awaited promises — no
513
514
  `setItem` plus `jsonEncode` / `jsonDecode` (JSON is a builtin data type)
514
515
 
515
516
  WebGL runs through the WebGL2 canvas API (`webglContext(canvas)`, `glShader`,
516
- `glProgram`, `glBuffer` — all protected by teaching errors) or a library such
517
+ `glProgram`, `glBuffer` - all protected by teaching errors) or a library such
517
518
  as Three.js constructed interop-style with `new`. WebGPU is available via its
518
519
  canvas API.
519
520
  A detailed, expanding guide for browser games lives in
@@ -531,7 +532,7 @@ remember engine as matter.Engine.create()
531
532
  remember scene as new THREE.Scene()
532
533
  ```
533
534
 
534
- Call anything — member chains need no special syntax, and there is no wrapper
535
+ Call anything - member chains need no special syntax, and there is no wrapper
535
536
  around values:
536
537
 
537
538
  ```plainscript
@@ -539,9 +540,9 @@ crypto.createHash("sha256").update("abc").digest("hex")
539
540
  mesh.scale.set(2, 2, 2)
540
541
  ```
541
542
 
542
- Construct with `new Type(args)` — as a statement, in `remember`, as an
543
+ Construct with `new Type(args)` - as a statement, in `remember`, as an
543
544
  argument, or bare without parens (`new Enemy`). A `make` function reference is
544
- a first-class value — pass it as a callback:
545
+ a first-class value - pass it as a callback:
545
546
 
546
547
  ```plainscript
547
548
  make fitWindow()
package/docs/index.html CHANGED
@@ -3,9 +3,9 @@
3
3
  <head>
4
4
  <meta charset="utf-8">
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
- <meta name="description" content="PlainScript 1.0.36 language reference and examples">
6
+ <meta name="description" content="PlainScript 1.0.361 language reference and examples">
7
7
  <meta name="theme-color" content="#070c16">
8
- <title>PlainScript 1.0.36</title>
8
+ <title>PlainScript 1.0.361</title>
9
9
 
10
10
  <link rel="preconnect" href="https://fonts.googleapis.com">
11
11
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
@@ -21,7 +21,7 @@
21
21
  <a class="nav-logo" href="#">
22
22
  <img class="nav-logo-image" src="logo-pln.jpg" alt="">
23
23
  <span>PlainScript</span>
24
- <span class="logo-ver">1.0.36</span>
24
+ <span class="logo-ver">1.0.361</span>
25
25
  </a>
26
26
  <button class="nav-toggle" id="nav-toggle" aria-label="Toggle navigation" aria-expanded="false" aria-controls="nav-links">
27
27
  <span class="nav-toggle-bar"></span>
@@ -44,7 +44,7 @@
44
44
  <div class="hero-headline-block">
45
45
  <p class="hero-badge" data-reveal>an intent-oriented language for node.js</p>
46
46
  <h1 class="hero-title"><span class="kw">remember</span> the sentence <span class="kw">as</span> the program.<br><span class="kw">show</span> the result <span class="kw">when</span> the meaning is clear.</h1>
47
- <p class="hero-lead">Write what you want in plain words. PlainScript checks it, then turns it into readable JavaScript — no boilerplate, no hidden steps.</p>
47
+ <p class="hero-lead">Write what you want in plain words. PlainScript checks it, then turns it into readable JavaScript - no boilerplate, no hidden steps.</p>
48
48
  <div class="hero-actions">
49
49
  <span class="hero-install-label">install</span>
50
50
  <a class="button" href="#quickstart">npx plainscript new hello</a>
@@ -82,14 +82,21 @@ npm start</code></pre>
82
82
  <div class="container">
83
83
  <p class="section-tag" data-reveal>Language</p>
84
84
  <h2 class="section-title" data-reveal>A small set of words you already know.</h2>
85
+ <p class="section-lead" data-reveal>Every construct is a sentence: a verb opens a block, <code>done</code> closes it, and values, functions, and collections nest freely - a comparison, a lambda, and a list all fit anywhere a value fits.</p>
85
86
  <div class="feature-grid">
86
87
  <article class="feature-card" data-reveal><h3>Variables</h3><p>Store values with <code>remember name as "Ada"</code> and change them with <code>becomes</code>.</p></article>
87
88
  <article class="feature-card" data-reveal><h3>Conditions</h3><p>Compare things with <code>is at least</code>, <code>contains</code>, <code>between</code>, and more.</p></article>
89
+ <article class="feature-card" data-reveal><h3>Choice</h3><p>Pick a value inline with <code>choosing ok is true then "online" otherwise "offline"</code>, or an <code>if / otherwise</code> block for steps.</p></article>
88
90
  <article class="feature-card" data-reveal><h3>Functions</h3><p>Create functions with <code>make</code>, return with <code>give</code>, and close with <code>done</code>.</p></article>
91
+ <article class="feature-card" data-reveal><h3>Lambdas</h3><p>Write snippets as values: <code>(n) -> n * 2</code>, or a block with <code>(n) do ... done</code>.</p></article>
92
+ <article class="feature-card" data-reveal><h3>Loops</h3><p>Iterate with <code>for each item in list</code>, <code>for index i from 0 to 9</code>, or <code>repeat N times</code>.</p></article>
89
93
  <article class="feature-card" data-reveal><h3>Records</h3><p>Model your data with record kinds and easy constructors.</p></article>
90
94
  <article class="feature-card" data-reveal><h3>Modules</h3><p>Import code with <code>bring ... from</code>, <code>@/</code> aliases, and re-exports.</p></article>
91
95
  <article class="feature-card" data-reveal><h3>Compound Types</h3><p>Use dictionaries, sets, and tuples with unpacking.</p></article>
96
+ <article class="feature-card" data-reveal><h3>Errors</h3><p>Guard against failure with <code>try / recover as err / finally</code> and <code>raise</code>.</p></article>
97
+ <article class="feature-card" data-reveal><h3>Async and events</h3><p>Await promises with <code>wait for</code>, and bind events with <code>when element "click" happens</code>.</p></article>
92
98
  <article class="feature-card" data-reveal><h3>Web apps</h3><p>Set up routes, JSON responses, sessions, cookies, uploads, and auth.</p></article>
99
+ <article class="feature-card" data-reveal><h3>HTTP client</h3><p>Call APIs with <code>get url</code> / <code>post url with body</code> and read <code>status of response</code>.</p></article>
93
100
  <article class="feature-card" data-reveal><h3>Data and async</h3><p>Work with SQLite, HTTP, files, schedules, concurrency, and WebSockets.</p></article>
94
101
  <article class="feature-card" data-reveal><h3>AI providers</h3><p>Call Groq and other OpenAI-compatible providers using your own keys.</p></article>
95
102
  </div>
@@ -110,7 +117,7 @@ npm start</code></pre>
110
117
  <div class="container">
111
118
  <p class="section-tag" data-reveal>Feature library</p>
112
119
  <h2 class="section-title" data-reveal>Examples you can try today.</h2>
113
- <p class="section-lead">These snippets use the PlainScript 1.0.36 grammar.</p>
120
+ <p class="section-lead">These snippets use the PlainScript 1.0.361 grammar.</p>
114
121
  <div class="library-toolbar" data-reveal>
115
122
  <label class="sr-only" for="lib-search">Search examples</label>
116
123
  <input id="lib-search" class="lib-search-input" type="search" placeholder="Search examples">
@@ -139,7 +146,7 @@ npm start</code></pre>
139
146
  </main>
140
147
 
141
148
  <footer class="site-footer">
142
- <div class="container footer-bottom"><span>PlainScript</span><span>1.0.36</span></div>
149
+ <div class="container footer-bottom"><span>PlainScript</span><span>1.0.361</span></div>
143
150
  </footer>
144
151
 
145
152
  <script src="https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js"></script>
@@ -288,7 +288,7 @@
288
288
  { category: "web", name: "Web routes", description: "Build an HTTP app with JSON routes.", source: 'web app\nroute get "/health"\n reply json\n ok is true\n done\ndone\nstart 3000' },
289
289
  { category: "web", name: "HTTP client", description: "Fetch data from a URL.", source: 'remember response as get "https://example.com/data" timeout 5000\nshow response.status' },
290
290
  { category: "web", name: "Auth and sessions", description: "Protect routes and track visitors.", source: 'web app\nenable sessions "session-secret"\nrequire api key from env("API_KEY")\nroute get "/me"\n reply json\n user is user of session of request\n done\ndone' },
291
- { category: "runtime", name: "Async errors", description: "Handle errors gracefully.", source: 'try\n remember result as get "https://example.com" timeout 5000\nrecover as error\n show message of error\nfinally\n show "finished"' },
291
+ { category: "runtime", name: "Async errors", description: "Handle errors gracefully.", source: 'try\n remember result as get "https://example.com" timeout 5000\nrecover as error\n show message of error\nfinally\n show "finished"\ndone' },
292
292
  { category: "runtime", name: "Concurrency", description: "Run several tasks at once.", source: 'remember results as allOf(list with firstJob(), secondJob())\nremember quick as withTimeout(firstJob(), 1000)\nshow results' },
293
293
  { category: "runtime", name: "WebSockets", description: "Chat and push updates live.", source: 'websocket server on 8080\n when socket connects\n send socket "connected"\n done\n when socket sends message\n broadcast message\n done\ndone' },
294
294
  { category: "runtime", name: "Cache", description: "Keep values ready with a TTL.", source: 'cache env("REDIS_URL")\ncacheSet("status", "ready", 60)\nremember status as cacheGet("status")' },
@@ -26,7 +26,7 @@ code { font-size: .92em; color: #b9e6c7; }
26
26
 
27
27
  .container { width: min(1120px, calc(100% - 40px)); margin: 0 auto; }
28
28
 
29
- /* Full-bleed animated background — flat, no glow */
29
+ /* Full-bleed animated background - flat, no glow */
30
30
  .bg-scrim, #bg-canvas {
31
31
  position: fixed;
32
32
  inset: 0;
@@ -84,7 +84,7 @@ code { font-size: .92em; color: #b9e6c7; }
84
84
  .nav-toggle[aria-expanded="true"] .nav-toggle-bar:nth-child(2) { opacity: 0; }
85
85
  .nav-toggle[aria-expanded="true"] .nav-toggle-bar:nth-child(3) { transform: translateY(-7px) rotate(-45deg); }
86
86
 
87
- /* Hero — asymmetric, the headline is the demo */
87
+ /* Hero - asymmetric, the headline is the demo */
88
88
  .hero { position: relative; border-bottom: 1px solid var(--line); }
89
89
  .hero-content { position: relative; z-index: 1; padding: 0; }
90
90
  .hero-grid {
@@ -226,7 +226,7 @@ pre code {
226
226
  .section-lead { color: var(--muted); }
227
227
  .three-column, .feature-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1px; background: var(--line); border: 1px solid var(--line); }
228
228
 
229
- /* Cards — flat, hairline-separated, no shadow */
229
+ /* Cards - flat, hairline-separated, no shadow */
230
230
  .info-card, .feature-card, .library-card {
231
231
  padding: 24px;
232
232
  border: none;
@@ -1,4 +1,4 @@
1
- // PlainScript 1.0.36: provider-backed AI works in ordinary programs.
1
+ // PlainScript 1.0.361: provider-backed AI works in ordinary programs.
2
2
 
3
3
  remember answer as chatWith("groq", "llama-3.3-70b-versatile", "Explain PlainScript in one sentence")
4
4
  show answer
@@ -1,4 +1,4 @@
1
- // PlainScript 1.0.36: array literals and indexing.
1
+ // PlainScript 1.0.361: array literals and indexing.
2
2
  remember values as [1, 2, 3]
3
3
  show values[0]
4
4
  show length(values)
@@ -1,4 +1,4 @@
1
- // PlainScript 1.0.36: asynchronous work and error recovery.
1
+ // PlainScript 1.0.361: asynchronous work and error recovery.
2
2
 
3
3
  make loadProfile(id)
4
4
  wait for sleep(10)
@@ -12,6 +12,7 @@ recover as err
12
12
  show message of err
13
13
  finally
14
14
  show "request complete"
15
+ done
15
16
 
16
17
  retry 3 times every 2 seconds
17
18
  show "retrying"
@@ -1,4 +1,4 @@
1
- // PlainScript 1.0.36: protected API route.
1
+ // PlainScript 1.0.361: protected API route.
2
2
  web app
3
3
  require api key from env("API_KEY")
4
4
  route get "/private"
@@ -1,4 +1,4 @@
1
- // PlainScript 1.0.36: API keys, sessions, cookies, and auth helpers.
1
+ // PlainScript 1.0.361: API keys, sessions, cookies, and auth helpers.
2
2
 
3
3
  web app
4
4
  enable sessions "development-only-session-secret"