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
package/README.md CHANGED
@@ -32,11 +32,15 @@ Describe *what* you want. The compiler decides *how* to implement it in JavaScri
32
32
  - [Variables](#variables)
33
33
  - [String Templates](#string-templates)
34
34
  - [Conditions](#conditions)
35
+ - [Conditional expressions](#conditional-expressions)
35
36
  - [Functions](#functions)
37
+ - [Lambdas](#lambdas)
36
38
  - [Arrays & Objects](#arrays--objects)
39
+ - [Dictionaries, Sets & Tuples](#dictionaries-sets--tuples)
37
40
  - [Loops](#loops)
38
41
  - [Natural-Language Expressions](#natural-language-expressions)
39
42
  - [Logical Assignment](#logical-assignment)
43
+ - [Error handling, async, and events](#error-handling-async-and-events)
40
44
  - [Record Kinds, Concurrency & More](#record-kinds-concurrency--more)
41
45
  - [Backend Services](#backend-services)
42
46
  - [Databases](#databases)
@@ -72,7 +76,7 @@ Describe *what* you want. The compiler decides *how* to implement it in JavaScri
72
76
 
73
77
  ## Why PlainScript
74
78
 
75
- Most languages ask you to describe *how* a computation happens: loop constructs, control flow, boilerplate. PlainScript inverts that. You write source that reads like an instruction to a competent engineer, and a deterministic compiler — no rules engine, no AI, no hidden codegen — turns it into JavaScript.
79
+ Most languages ask you to describe *how* a computation happens: loop constructs, control flow, boilerplate. PlainScript inverts that. You write source that reads like an instruction to a competent engineer, and a deterministic compiler - no rules engine, no AI, no hidden codegen - turns it into JavaScript.
76
80
 
77
81
  | | |
78
82
  |---|---|
@@ -118,7 +122,7 @@ done
118
122
  </tr>
119
123
  </table>
120
124
 
121
- **Current version:** `v1.0.36` — the `plainscript-lang` npm package, with a TypeScript-style production build (`plainscript build` → `dist/`, source names and structure preserved).
125
+ **Current version:** `v1.0.361` - the `plainscript-lang` npm package, with a TypeScript-style production build (`plainscript build` → `dist/`, source names and structure preserved).
122
126
 
123
127
  ---
124
128
 
@@ -127,7 +131,7 @@ done
127
131
  ```bash
128
132
  npx plainscript new myapp # scaffolds src/app.pln and package.json
129
133
  cd myapp
130
- npm install # installs plainscript as a devDependency, plus runtime packages
134
+ npm install # installs the compiler and runtime packages
131
135
  npm run build # compiles src/ -> dist/ (plainscript build)
132
136
  node dist/app.js # or: npm start
133
137
  ```
@@ -136,18 +140,53 @@ Adding PlainScript to an existing project:
136
140
 
137
141
  ```bash
138
142
  npm install --save-dev plainscript-lang
139
- # start writing src/*.pln files — plainscript build auto-discovers them
143
+ # start writing src/*.pln files - plainscript build auto-discovers them
140
144
  ```
141
145
 
142
146
  No global install is required. Everything runs through `npm` scripts and `npx`.
143
147
 
148
+ ### Supported Node.js and dependency policy
149
+
150
+ The compiler and its checked-in dependency tree support **Node.js 18 or newer**.
151
+ Use the lockfile for reproducible installs:
152
+
153
+ ```bash
154
+ npm ci
155
+ ```
156
+
157
+ The compiler package intentionally does not install the optional WhatsApp
158
+ adapter. This keeps a normal `npm ci` independent of Baileys' native/GitHub
159
+ transitives and lets projects that do not use WhatsApp install cleanly on the
160
+ Node 18 floor. The SQLite, MongoDB, and Redis versions in `package.json` are
161
+ the last compatible major lines for that floor.
162
+
163
+ WhatsApp projects have a separate adapter requirement. `plainscript install`
164
+ uses the pinned default `@whiskeysockets/baileys@6.7.24` (Node.js 20 or newer)
165
+ and `qrcode-terminal`. If a package firewall or registry cannot provide that
166
+ adapter, install a Baileys-compatible package or local fork yourself and select
167
+ it in the bot block:
168
+
169
+ ```plainscript
170
+ whatsapp bot
171
+ use baileys "./vendor/baileys"
172
+ auth "session"
173
+ login qr
174
+ done
175
+ ```
176
+
177
+ For a local adapter, install it from the project directory (for example,
178
+ `npm install ./vendor/baileys`) and ensure it exposes the Baileys default
179
+ socket export plus `useMultiFileAuthState`, `makeCacheableSignalKeyStore`, and
180
+ `DisconnectReason`. Local adapter paths are not passed to `npm install` by
181
+ `plainscript install`.
182
+
144
183
  ---
145
184
 
146
185
  ## CLI Reference
147
186
 
148
187
  | Command | Description |
149
188
  |---|---|
150
- | `plainscript run <file.pln>` | Installs missing dependencies, compiles, and executes. Runs from a scratch directory — nothing is written into your project. |
189
+ | `plainscript run <file.pln>` | Installs missing dependencies, compiles, and executes. Runs from a scratch directory - nothing is written into your project. |
151
190
  | `plainscript build [file.pln]` | Compiles to `dist/`. With no argument, builds every `.pln` file under the source root, preserving names and folder structure. |
152
191
  | `plainscript check <file.pln>` | Checks syntax only. No output, no execution. |
153
192
  | `plainscript fmt <file.pln>` | Formats a PlainScript file in place. |
@@ -165,7 +204,7 @@ No global install is required. Everything runs through `npm` scripts and `npx`.
165
204
 
166
205
  ## Building &amp; Configuration
167
206
 
168
- `plainscript build` is a deterministic production build — TypeScript-style, but for `.pln` sources — with zero configuration required.
207
+ `plainscript build` is a deterministic production build - TypeScript-style, but for `.pln` sources - with zero configuration required.
169
208
 
170
209
  - Run with no argument and it discovers every `.pln` file under `src/`, compiling each to `dist/` while **preserving source file names and folder structure**: `src/messi.pln` → `dist/messi.js`, `src/helpers/math.pln` → `dist/helpers/math.js`.
171
210
  - `plainscript build <file.pln>` compiles a single file into `dist/`.
@@ -198,16 +237,23 @@ For projects that need custom output or source directories, add a `plainscript.c
198
237
  "build": "plainscript build",
199
238
  "prepare": "plainscript build"
200
239
  },
201
- "devDependencies": { "plainscript-lang": "^1.0.36" }
240
+ "devDependencies": { "plainscript-lang": "^1.0.361" }
202
241
  }
203
242
  ```
204
243
 
205
- `src/index.pln` builds to `dist/index.js`; consumers install and `require()` it like any Node package. There is no PlainScript-specific registry or format — standard `package.json` semantics apply.
244
+ `src/index.pln` builds to `dist/index.js`; consumers install and `require()` it like any Node package. There is no PlainScript-specific registry or format - standard `package.json` semantics apply.
206
245
 
207
246
  ---
208
247
 
209
248
  ## Language Tour
210
249
 
250
+ PlainScript is a fixed vocabulary of English verbs compiled to JavaScript. Every
251
+ construct follows the same rhythm: a word opens a block, `done` closes it, and
252
+ `give` returns a value - a sentence you could say to a colleague ("if the score
253
+ is at least 80, show accepted, otherwise review") is valid source. The sections
254
+ below keep the code first, with a short note on what each construct is *for* and
255
+ the constraint that matters when you use it.
256
+
211
257
  ### Variables
212
258
 
213
259
  ```
@@ -216,6 +262,12 @@ let age be 16
216
262
  set age to 17
217
263
  ```
218
264
 
265
+ `remember name as "Ada"` and `let name be "Ada"` are two spellings of the same
266
+ declaration; `set name to ...`, `name becomes ...`, and `name is now ...` all
267
+ reassign it. Numbers, strings, and booleans behave like JavaScript primitives;
268
+ lists, records, dictionaries, and sets are *references*, so pointing two names
269
+ at the same list means they see the same data.
270
+
219
271
  ### String Templates
220
272
 
221
273
  Backtick-delimited strings preserve whitespace and support `${expression}` interpolation:
@@ -233,10 +285,17 @@ Best regards,
233
285
  The Team`
234
286
  ```
235
287
 
236
- Interpolation compiles directly to JavaScript template literals — it is not evaluated at compile time. Literal dollar signs without `{` are preserved as-is.
288
+ Interpolation compiles directly to JavaScript template literals - it is not evaluated at compile time. Literal dollar signs without `{` are preserved as-is.
237
289
 
238
290
  ### Conditions
239
291
 
292
+ `if <condition> ... done` runs its block when the condition is true, and the
293
+ optional `otherwise` block runs when it is false (`when ... done` is the same
294
+ statement used in web and event contexts). Conditions read like English, and a
295
+ comparison is itself a value: `score is at least 80` is `true` or `false`, so it
296
+ can be stored, printed, passed to a function, or joined with `and` / `or` /
297
+ `not`. When you need a *value* rather than a block, use `choosing` (below).
298
+
240
299
  ```
241
300
  when age is at least 18
242
301
  show "Adult"
@@ -277,6 +336,19 @@ All comparison operators:
277
336
  | `has field "x"` | `"x" in obj` |
278
337
  | `at position key` | `obj[key]` |
279
338
 
339
+ ### Conditional expressions
340
+
341
+ `choosing` is the value form of `if`: pick between two expressions and keep the
342
+ whole thing inline - in an argument, a `give`, or a list element.
343
+
344
+ ```
345
+ remember verdict as choosing score is at least 90 then "A" otherwise "B"
346
+ show choosing score is below 60 then "low" otherwise "ok"
347
+ ```
348
+
349
+ `choosing <condition> then <a> otherwise <b>` evaluates to `<a>` when the
350
+ condition is true and `<b>` otherwise.
351
+
280
352
  ### Functions
281
353
 
282
354
  ```
@@ -290,8 +362,46 @@ to multiply x and y together
290
362
  done
291
363
  ```
292
364
 
365
+ `make name(args)` and its `to ... together` spelling define a function; `done`
366
+ closes it - the PlainScript form of JavaScript's `function`. `give <value>` (or
367
+ `give back <value>`) returns; `give` alone simply ends the function. A `make`
368
+ function is a value like any other, so it can be stored with `remember`, passed
369
+ as an argument, or returned from another function. Arguments are optional with
370
+ defaults: `make label(name as "guest")`.
371
+
372
+ ### Lambdas
373
+
374
+ A lambda is a function without a name, written where a value is expected -
375
+ `(a, b) -> a + b` is JavaScript's `(a, b) => a + b`. Use the arrow form for a
376
+ one-expression body and the `do ... done` form when the body has several
377
+ statements:
378
+
379
+ ```
380
+ remember add as (a, b) -> a + b
381
+ show add(2, 3)
382
+
383
+ remember grade as (score) do
384
+ if score is at least 90
385
+ give "excellent"
386
+ otherwise
387
+ give "keep practicing"
388
+ done
389
+ done
390
+
391
+ remember doubled as numbers.map((n) -> n * 2)
392
+ ```
393
+
394
+ Lambdas are ordinary values: store them, put them in lists and records, pass
395
+ them to `.map` / `.filter` / `.find` / `.forEach`, and return or chain them
396
+ (`mul(2)(3)(5)`) to build factories and curried helpers.
397
+
293
398
  ### Arrays &amp; Objects
294
399
 
400
+ `list with ...` is PlainScript's spelling of an array; `record with ... done`
401
+ is a plain object. Both are ordinary values, so lists hold records, records
402
+ hold lists, and lambdas can live anywhere a value can. Read and write them with
403
+ `.name`, `[index]`, or the natural-language forms later in this tour.
404
+
295
405
  ```
296
406
  let players be list with "Haaland", "Foden", "Rodri"
297
407
  show players[0]
@@ -304,8 +414,47 @@ done
304
414
  show user.name
305
415
  ```
306
416
 
417
+ ### Dictionaries, Sets & Tuples
418
+
419
+ JavaScript's `Map` and `Set` have direct spellings, and tuples are fixed-size
420
+ arrays you usually unpack all at once:
421
+
422
+ ```
423
+ remember lookup as dictionary with "alpha" is 1 and "beta" is 2 done
424
+ show lookup.get("beta") // 2
425
+
426
+ remember tags as set with "admin", "editor", "admin" done // duplicates collapse
427
+
428
+ remember point as tuple with 10, 20 and 30 done
429
+ unpack point into x, y and z // x=10, y=20, z=30
430
+ show x + y + z
431
+ ```
432
+
433
+ Dictionary and set entries are joined with `and`; a tuple separates its members
434
+ with commas and `and` before the final member. `show <value>` accepts any value,
435
+ and JSON data arrives as nested lists and records.
436
+
307
437
  ### Loops
308
438
 
439
+ `for each item in <collection> ... done` visits every element, and `while
440
+ <condition> ... done` repeats until the condition is false. Counted loops come
441
+ in sentence form too:
442
+
443
+ ```
444
+ repeat 5 times
445
+ show "tick"
446
+ done
447
+
448
+ remember energy as 9
449
+ repeat while energy is above 0
450
+ energy becomes energy - 1
451
+ done
452
+ ```
453
+
454
+ `for every item in basket` is an alias for `for each`, `repeat until <condition>`
455
+ flips the `while` sense, and `for index i from 0 to 9` gives a zero-based
456
+ counter when you need positions.
457
+
309
458
  ```
310
459
  for each player in players
311
460
  show player
@@ -335,7 +484,7 @@ show player two from players // players[1]
335
484
  first player from players is now "Haaland" // players[0] = "Haaland"
336
485
  ```
337
486
 
338
- Number words from `one` to `twenty` map to one-based positions — `player one` is the first item.
487
+ Number words from `one` to `twenty` map to one-based positions - `player one` is the first item.
339
488
 
340
489
  **Collections**
341
490
 
@@ -370,6 +519,10 @@ The older `readFile()` / `writeFile()` forms still work and are unchanged.
370
519
 
371
520
  ### Logical Assignment
372
521
 
522
+ The word-style assignment operators keep the common "fill the empty value"
523
+ pattern on one line - PlainScript for `flag = flag || true` and
524
+ `val = val ?? "default"`:
525
+
373
526
  ```
374
527
  let flag be false
375
528
  flag or is now true
@@ -380,8 +533,53 @@ val nullish is now "default"
380
533
  show val
381
534
  ```
382
535
 
536
+ ### Error handling, async, and events
537
+
538
+ Programs that fail should say so. `raise <value>` throws an error, `try` /
539
+ `recover as err` / `finally` catch it, and `retry N times every Mms` re-runs a
540
+ block that may fail transiently:
541
+
542
+ ```
543
+ raise "not implemented"
544
+
545
+ try
546
+ remember data as jsonDecode(raw)
547
+ recover as err
548
+ show "bad json: " + message of err
549
+ finally
550
+ show "request complete"
551
+ done
552
+
553
+ retry 3 times every 2 seconds
554
+ show "fetching..."
555
+ done
556
+ ```
557
+
558
+ Asynchronous work uses `wait for <promise>` (or `await <promise>`). A `make`
559
+ function or lambda that `wait for`s a promise becomes async automatically, and
560
+ `all of [...]`, `any of [...]`, and `settled of [...]` run several promises at
561
+ once. Events bind with `when <target> "<event>" happens [as <name>] ... done` -
562
+ the DOM equivalent of `addEventListener` - and server/websocket forms follow
563
+ the same `when ... done` pattern.
564
+
383
565
  ### Record Kinds, Concurrency &amp; More
384
566
 
567
+ For the shapes that repeat in a program - a user, a message, an order - declare
568
+ a **record kind** and construct instances with `create`. Kinds behave like
569
+ plain objects with a known field list: setting an unknown field throws, which
570
+ catches typos early.
571
+
572
+ ```
573
+ define a kind called "Player" with
574
+ name is ""
575
+ goals is 0
576
+ done
577
+
578
+ remember player as create a Player with name "Ada" and goals 4
579
+ player.goals becomes player.goals + 1
580
+ show player.goals
581
+ ```
582
+
385
583
  PlainScript 1.0.2 closes most of the gap with TypeScript-class languages using its own grammar. The full audit lives in [`docs/CAPABILITY_GAP_AUDIT.md`](./docs/CAPABILITY_GAP_AUDIT.md).
386
584
 
387
585
  <details>
@@ -405,11 +603,22 @@ PlainScript 1.0.2 closes most of the gap with TypeScript-class languages using i
405
603
 
406
604
  </details>
407
605
 
606
+ **How the pieces fit together.** PlainScript is deliberately small: a handful
607
+ of verbs (`remember`, `give`, `if` / `otherwise`, `done`) plus the collections
608
+ and functions you just met. Everything is a value - numbers and strings,
609
+ comparisons, collections, lambdas, whole functions - so pieces nest instead of
610
+ needing new syntax: a lambda inside a list, a comparison handed to a filter, a
611
+ `make` function stored in a record. When a pattern repeats, extract it into a
612
+ `make` function (or a lambda), group related names into a module, and call the
613
+ abstraction the same way you call `show` or `jsonDecode`. The standard library
614
+ and the backend capabilities that follow are exactly this: vocabulary built on
615
+ the primitives above, available to every program.
616
+
408
617
  ---
409
618
 
410
619
  ## Backend Services
411
620
 
412
- Everything in this section is compiled by the deterministic compiler — no rules, no AI, no hidden codegen.
621
+ Everything in this section is compiled by the deterministic compiler - no rules, no AI, no hidden codegen.
413
622
 
414
623
  ### Databases
415
624
 
@@ -419,7 +628,7 @@ Portable databases (SQLite native or WebAssembly):
419
628
  database "app.db" // probes better-sqlite3, falls back to sql.js
420
629
  ```
421
630
 
422
- `plainscript install` verifies that `better-sqlite3` actually loads. If the native module cannot be used, PlainScript warns and continues on the pure-JavaScript WebAssembly engine (`sql.js`) — the same program runs unchanged. An engine can be forced explicitly:
631
+ `plainscript install` verifies that `better-sqlite3` actually loads. If the native module cannot be used, PlainScript warns and continues on the pure-JavaScript WebAssembly engine (`sql.js`) - the same program runs unchanged. An engine can be forced explicitly:
423
632
 
424
633
  ```
425
634
  database "app.db" using "native" // hard requirement: better-sqlite3
@@ -550,7 +759,9 @@ done
550
759
 
551
760
  ## Runtime Standard Library
552
761
 
553
- No imports needed — these functions are built into the compiler:
762
+ No imports needed - these functions are built into the compiler. They are the
763
+ standard vocabulary of everyday work - JSON, files, time, strings - so the
764
+ first version of a program usually needs no dependency at all:
554
765
 
555
766
  | PlainScript | Description |
556
767
  |---|---|
@@ -577,6 +788,12 @@ No imports needed — these functions are built into the compiler:
577
788
 
578
789
  ## Web Applications
579
790
 
791
+ `web app` starts the HTTP stack available to every program. `route <method>
792
+ "<path>" ... done` registers an endpoint; `reply` (or `show`) sends a response,
793
+ `reply json ... done` sends JSON with `is`-style fields, and `start <port>`
794
+ serves it. `status <n>` sets the response code and `when nothing matches`
795
+ handles otherwise-unmatched requests.
796
+
580
797
  ```
581
798
  web app
582
799
 
@@ -601,7 +818,7 @@ start 3000
601
818
  The same `.pln` you run on Node compiles to a browser script. Drive a canvas,
602
819
  handle keyboard, pointer, touch, and gamepad input, run `requestAnimationFrame`
603
820
  loops with delta time, load images and audio, and call any JavaScript library
604
- (Three.js, WebGL, WebGPU, Matter.js) through plain interop — no bundler needed:
821
+ (Three.js, WebGL, WebGPU, Matter.js) through plain interop - no bundler needed:
605
822
 
606
823
  ```plainscript
607
824
  web app
@@ -633,8 +850,8 @@ done
633
850
  `gamepads`, `droppedFiles`, `webSocketSend`, and the WebGL helpers
634
851
  `webglContext`/`glShader`/`glProgram`/`glBuffer`) make canvas apps, games, and
635
852
  DOM UI direct. The full browser
636
- and game development guide — input, loops, assets, audio, state, collision,
637
- networking, persistence, and interop — is [docs/GAME-PROMPT.md](docs/GAME-PROMPT.md).
853
+ and game development guide - input, loops, assets, audio, state, collision,
854
+ networking, persistence, and interop - is [docs/GAME-PROMPT.md](docs/GAME-PROMPT.md).
638
855
 
639
856
  ## Additional Backend Capabilities
640
857
 
@@ -776,16 +993,31 @@ show page.hasNext # true if another page exists
776
993
 
777
994
  ## Multi-File Projects
778
995
 
996
+ Programs grow into files. `import "./math.pln"` pulls a whole file into the
997
+ current one, `import { circleArea } from "./math.pln"` and `bring circleArea
998
+ from "./math.pln"` import specific names, and `export <name>` (or
999
+ `export <name> and <name>`) makes names available to other files:
1000
+
779
1001
  ```
780
1002
  import "./math.pln"
781
1003
  import "./utils.pln"
1004
+ import { circleArea } from "./math.pln"
1005
+ bring circleArea from "./math.pln"
782
1006
 
783
1007
  show PI
784
1008
 
785
1009
  show double(5)
786
1010
  ```
787
1011
 
788
- Imports are bundled per entry: `plainscript build` gives every source file its own standalone output under `dist/`, with imported code inlined.
1012
+ ```
1013
+ remember PI as 3.14159
1014
+ make circleArea(r)
1015
+ give PI * r * r
1016
+ done
1017
+ export circleArea
1018
+ ```
1019
+
1020
+ Imports are bundled per entry: `plainscript build` gives every source file its own standalone output under `dist/`, with imported code inlined. Functions, lambdas, records, and modules together are how you build your own vocabulary on top of the core verbs - a new reader puzzle (`validate(body, fields)`) is a one-line call, not a loop.
789
1021
 
790
1022
  ---
791
1023
 
@@ -818,7 +1050,7 @@ done
818
1050
 
819
1051
  ## WhatsApp Bots
820
1052
 
821
- Full WhatsApp connectivity through Baileys — the implementation package is installed automatically and never appears in source:
1053
+ Full WhatsApp connectivity through Baileys - the implementation package is installed automatically and never appears in source:
822
1054
 
823
1055
  ```
824
1056
  whatsapp bot
@@ -842,7 +1074,7 @@ done
842
1074
  ```
843
1075
 
844
1076
  - `login qr` prints a scannable QR code; `login pairing "<number>"` prints an enter-on-phone code instead. Pairing numbers are validated at compile time (digits only after normalization, 8–15 characters).
845
- - `login pairing` also accepts a variable — prompt for the number at runtime instead of hard-coding it:
1077
+ - `login pairing` also accepts a variable - prompt for the number at runtime instead of hard-coding it:
846
1078
 
847
1079
  ```
848
1080
  ask "WhatsApp number: " as phone
@@ -67,7 +67,7 @@ function resolveDependencies(entryPath) {
67
67
  const order = []; // final compile order
68
68
 
69
69
  function visit(absPath, stack) {
70
- // Already fully processed — skip (handles duplicate imports)
70
+ // Already fully processed - skip (handles duplicate imports)
71
71
  if (visited.has(absPath)) return;
72
72
 
73
73
  // File is in the current DFS stack → circular dependency
@@ -90,7 +90,7 @@ function resolveDependencies(entryPath) {
90
90
 
91
91
  // Parse the file to discover its own imports.
92
92
  // Annotate any tokenise/parse error with the filename so callers see
93
- // "file.pln — Line N, Column N: …" rather than a bare positional message.
93
+ // "file.pln - Line N, Column N: …" rather than a bare positional message.
94
94
  const source = fs.readFileSync(absPath, 'utf8');
95
95
  let tokens, ast;
96
96
  try {
@@ -98,7 +98,7 @@ function resolveDependencies(entryPath) {
98
98
  ast = parse(tokens);
99
99
  } catch (err) {
100
100
  const relPath = path.relative(process.cwd(), absPath) || path.basename(absPath);
101
- throw new Error(`${relPath} — ${err.message}`);
101
+ throw new Error(`${relPath} - ${err.message}`);
102
102
  }
103
103
 
104
104
  // Recurse into each import before processing this file (DFS)
@@ -109,7 +109,7 @@ function resolveDependencies(entryPath) {
109
109
  visit(resolvedAbs, newStack);
110
110
  }
111
111
 
112
- // All dependencies are done — add this file to the order
112
+ // All dependencies are done - add this file to the order
113
113
  visited.add(absPath);
114
114
  order.push({ absPath, ast });
115
115
  }
package/compiler/cli.js CHANGED
@@ -287,7 +287,7 @@ function ensurePackageJson(cwd = process.cwd()) {
287
287
  }, null, 2) + '\n', 'utf8');
288
288
  }
289
289
 
290
- // v2.1.1 — verify that a freshly installed package actually LOADS on this
290
+ // v2.1.1 - verify that a freshly installed package actually LOADS on this
291
291
  // machine. "better-sqlite3 present in node_modules" does not imply usable:
292
292
  // its native binding may be missing for this platform or Node ABI (the
293
293
  // Termux failure mode). The check runs in a child process so a hard crash
@@ -321,7 +321,7 @@ function installPackages(packages, cwd = process.cwd()) {
321
321
  stdio: 'ignore',
322
322
  });
323
323
  dependencyCache.set(`${cwd}\0${bareName}`, true);
324
- // v2.1.1 — "downloaded" and "usable" are different facts. Report both.
324
+ // v2.1.1 - "downloaded" and "usable" are different facts. Report both.
325
325
  if (verifyPackageUsable(bareName, cwd)) {
326
326
  console.log(`${clrGreen('✓')} ${pkg} installed`);
327
327
  } else {
@@ -332,7 +332,7 @@ function installPackages(packages, cwd = process.cwd()) {
332
332
  );
333
333
  }
334
334
  } catch (_) {
335
- // v2.1.1 — better-sqlite3 is optional at install time: programs opened
335
+ // v2.1.1 - better-sqlite3 is optional at install time: programs opened
336
336
  // through the portable engine chain fall back to sql.js, so a native
337
337
  // build failure must not abort setup.
338
338
  if (bareName === 'better-sqlite3') {
@@ -366,7 +366,7 @@ function ensureDependencies(files, install = true) {
366
366
  //
367
367
  // Deterministic only: the lexer/parser/generator pipeline is the single
368
368
  // authoritative compiler. Unsupported syntax produces a precise compiler
369
- // error — there is no second compilation path (v2.1.1).
369
+ // error - there is no second compilation path (v2.1.1).
370
370
  function compile(filePath, options = {}) {
371
371
  const absPath = path.resolve(filePath);
372
372
  if (!fs.existsSync(absPath)) {
@@ -421,7 +421,7 @@ function compile(filePath, options = {}) {
421
421
  // file in the OS temp dir could never see the project's node_modules. Passing
422
422
  // every node_modules directory between the entry file and the filesystem root
423
423
  // through NODE_PATH gives the child the exact same resolution the old
424
- // project-local temp file had — without ever writing into the project.
424
+ // project-local temp file had - without ever writing into the project.
425
425
  function nodeModulesSearchPaths(entryDir) {
426
426
  const paths = [];
427
427
  let dir = path.resolve(entryDir);
@@ -504,9 +504,9 @@ function buildOne(filePath, srcDir, outDir, options = {}) {
504
504
  return path.relative(process.cwd(), outPath) || outPath;
505
505
  }
506
506
 
507
- // `plainscript build <file.pln> -o <out.js>` — compile one entry to an explicit
507
+ // `plainscript build <file.pln> -o <out.js>` - compile one entry to an explicit
508
508
  // output path (same compilation pipeline as buildOne, including source maps
509
- // when requested). Valuable for browser payloads such as the v1.0.36
509
+ // when requested). Valuable for browser payloads such as the v1.0.361
510
510
  // requestAnimationFrame / addEventListener helpers, which are meant to run as
511
511
  // a single script tag.
512
512
  function writeOneFile(filePath, outputFile) {
@@ -536,7 +536,7 @@ function writeOneFile(filePath, outputFile) {
536
536
  return path.relative(process.cwd(), outPath) || outPath;
537
537
  }
538
538
 
539
- // `plainscript build` — TypeScript-style production build:
539
+ // `plainscript build` - TypeScript-style production build:
540
540
  //
541
541
  // Zero config (default):
542
542
  // messi.pln → dist/messi.js (project-root sources)
@@ -619,7 +619,7 @@ function cmdNew(projectName) {
619
619
  fs.mkdirSync(path.join(dir, 'public'));
620
620
  fs.mkdirSync(path.join(dir, 'src'));
621
621
 
622
- // src/app.pln — starter web app
622
+ // src/app.pln - starter web app
623
623
  fs.writeFileSync(path.join(dir, 'src', 'app.pln'), `web app
624
624
 
625
625
  serve folder "public"
@@ -631,14 +631,14 @@ done
631
631
  route get "/api/status"
632
632
  reply json
633
633
  status is "ok"
634
- version is "1.0.36"
634
+ version is "1.0.361"
635
635
  done
636
636
  done
637
637
 
638
638
  start 3000
639
639
  `);
640
640
 
641
- // package.json — plain Node semantics; PlainScript itself is a devDependency and
641
+ // package.json - plain Node semantics; PlainScript itself is a devDependency and
642
642
  // deployment only needs the generated dist/ output.
643
643
  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
644
644
  name,
@@ -746,7 +746,7 @@ function cmdInstall() {
746
746
  function cmdDoctor() {
747
747
  console.log('PlainScript doctor\n');
748
748
  const check = (label, ok, detail = '') => {
749
- const suffix = detail ? ` — ${detail}` : '';
749
+ const suffix = detail ? ` - ${detail}` : '';
750
750
  console.log(`${ok ? clrGreen('✓') : clrRed('✗')} ${label}${suffix}`);
751
751
  };
752
752
  check('Node.js', Boolean(process.version));
@@ -843,14 +843,14 @@ function cmdUpdate() {
843
843
  // Check syntax of a PlainScript file without generating JavaScript or executing.
844
844
  // Full validation of a single .pln entry: resolve imports, parse+generate every
845
845
  // file in dependency order, and verify the emitted JavaScript is syntactically
846
- // valid — all without writing anything to disk. Returns a deterministic
846
+ // valid - all without writing anything to disk. Returns a deterministic
847
847
  // result record; `deps` are the npm packages the sources require.
848
848
  function validateSource(absPath) {
849
849
  const rel = path.relative(process.cwd(), absPath) || absPath;
850
850
  const t0 = Date.now();
851
851
  try {
852
852
  // resolveDependencies parses each file too, so a parse error anywhere in
853
- // the import graph surfaces here with a "file.pln — Line:Col" prefix.
853
+ // the import graph surfaces here with a "file.pln - Line:Col" prefix.
854
854
  const files = resolveDependencies(absPath);
855
855
  const context = createGenerationContext();
856
856
  let js = files.map(({ ast }) => generate(ast, context)).filter(s => s.trim()).join('\n');
@@ -948,7 +948,7 @@ function cmdCheck(target, json) {
948
948
 
949
949
  for (const r of results) {
950
950
  if (r.ok) {
951
- console.log(`${clrGreen('✓')} ${r.file} — ok${clrDim(` (${r.ms}ms)`)}`);
951
+ console.log(`${clrGreen('✓')} ${r.file} - ok${clrDim(` (${r.ms}ms)`)}`);
952
952
  } else {
953
953
  console.log(`${clrRed('✗')} ${r.file}`);
954
954
  console.error(r.error);
@@ -978,7 +978,7 @@ function cmdFmt(filePath) {
978
978
  const source = fs.readFileSync(absPath, 'utf8');
979
979
  const formatted = format(source);
980
980
  if (source === formatted) {
981
- console.log(`${clrDim('–')} ${filePath} — already formatted.`);
981
+ console.log(`${clrDim('–')} ${filePath} - already formatted.`);
982
982
  } else {
983
983
  fs.writeFileSync(absPath, formatted, 'utf8');
984
984
  console.log(`${clrGreen('✓')} Formatted ${filePath}`);
@@ -998,7 +998,7 @@ function cmdHelp() {
998
998
  async function main() {
999
999
  const args = process.argv.slice(2);
1000
1000
 
1001
- // Global flags — recognized anywhere in the argument list.
1001
+ // Global flags - recognized anywhere in the argument list.
1002
1002
  const quiet = args.includes('--quiet');
1003
1003
  const verbose = args.includes('--verbose');
1004
1004
  const json = args.includes('--json');
@@ -1014,7 +1014,7 @@ async function main() {
1014
1014
  switch (command) {
1015
1015
  case 'run': await cmdRun(fileArg, positional.slice(2)); break;
1016
1016
  case 'build': {
1017
- // v1.0.36 — optional -o/--output <path>. "-o" is a single-dash flag, so
1017
+ // v1.0.361 - optional -o/--output <path>. "-o" is a single-dash flag, so
1018
1018
  // it survives the "--filtered" positional list; pull it out here before
1019
1019
  // building the positional file argument for cmdBuild.
1020
1020
  let outputPath = null;