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
@@ -1,5 +1,5 @@
1
1
  // SourceMap: V3 Source Map generator for PlainScript compiler.
2
- // Zero external dependencies — implements VLQ Base64 encoding.
2
+ // Zero external dependencies - implements VLQ Base64 encoding.
3
3
 
4
4
  const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
5
5
 
@@ -1,6 +1,6 @@
1
1
  // Single source of truth for the compiler version.
2
2
  // Consumed by cli.js help/version output.
3
3
 
4
- const VERSION = '1.0.35';
4
+ const VERSION = '1.0.361';
5
5
 
6
6
  module.exports = { VERSION };
@@ -1,4 +1,4 @@
1
- # PlainScript 1.0.35 Capability Audit
1
+ # PlainScript 1.0.361 Capability Audit
2
2
 
3
3
  This audit is based on what the compiler actually supports right now.
4
4
  If `plainscript check` validates it, it's listed here.
@@ -66,6 +66,23 @@ If `plainscript check` validates it, it's listed here.
66
66
  | WhatsApp bots | Implemented | `whatsapp bot` (pairing/QR, message types, media download, custom Baileys) |
67
67
  | OCR | Implemented | `ocr path of file as text` |
68
68
 
69
+ ## Browser and Games
70
+
71
+ | Capability | Status | Current source form |
72
+ | --- | --- | --- |
73
+ | Static serving | Implemented | `web app`, `serve folder "public"`, `reply file "public/index.html"` |
74
+ | Browser compile target | Implemented | `build game.pln -o public/game.js` (package-free `<script>` output) |
75
+ | Canvas 2D | Implemented | `canvas.getContext("2d")`, `fillStyle becomes ...`, `fillRect(...)` |
76
+ | DOM events | Implemented | `when <target> "<event>" happens as name` → `addEventListener` |
77
+ | Frame loops | Implemented | `every frame ... done`, rAF + delta time |
78
+ | Browser builtins | Implemented | `select`, `selectAll`, `parseHTML`, `localPoint`, `gamepads`, `droppedFiles` |
79
+ | Promise builtins | Implemented | `loadImage`, `loadAudio`, `fetchJson`, `fetchBytes`, `readDataUrl` (auto-awaited) |
80
+ | Audio | Implemented | `audioContext()`, `playTone(freq, seconds, options)` (user-gesture resume) |
81
+ | WebSocket client | Implemented | `new WebSocket(url)`, `when ws "message" happens`, `webSocketSend(ws, value)` |
82
+ | Persistence | Implemented | `localStorage.getItem/setItem`, `jsonEncode`, `jsonDecode` |
83
+ | JS library interop | Implemented | `use <pkg>`, `bring name from "pkg"`, `new Type(...)`, callbacks, `try/recover` |
84
+ | WebGL/WebGPU and libraries | Implemented | `webglContext`/`glShader`/`glProgram`/`glBuffer`, `new THREE.Scene()` etc. |
85
+
69
86
  ## Canonical Examples
70
87
 
71
88
  Here are the example files that exercise each capability:
@@ -91,6 +108,10 @@ examples/cache-schedule.pln
91
108
  examples/bots.pln
92
109
  examples/ocr.pln
93
110
  examples/testing.pln
111
+ examples/canvas-game/
112
+ examples/browser-interactive/
113
+ examples/three-dimensional/
114
+ examples/javascript-library/
94
115
  examples/modules/
95
116
  examples/football-backend/
96
117
  examples/id-verification/
@@ -105,6 +126,6 @@ find examples -name '*.pln' -exec node compiler/cli.js check {} \;
105
126
 
106
127
  ## Version Info
107
128
 
108
- The release label for this repo is `1.0.35`. It covers the compiler,
109
- package metadata, website, and editor tooling. Third-party dependency
110
- versions are not tied to this label.
129
+ The release label for this repo is `1.0.361`. It covers the compiler,
130
+ package metadata, website, editor tooling, and browser/game documentation.
131
+ Third-party dependency versions are not tied to this label.
@@ -0,0 +1,524 @@
1
+ # PlainScript General-Purpose Build Prompt
2
+
3
+ This document is the standing guide for an AI coding agent or programmer
4
+ building a serious project with PlainScript. It describes the compiler and
5
+ runtime that are present in this repository. Treat the compiler and the
6
+ checked examples as the source of truth: if a snippet does not pass
7
+ `node compiler/cli.js check <file.pln>`, it is not a PlainScript program yet.
8
+
9
+ ## 1. What PlainScript is
10
+
11
+ PlainScript is a line-oriented, intent-oriented language that compiles to
12
+ readable JavaScript. It is designed to express application logic clearly
13
+ while retaining access to the Node.js, browser, and npm ecosystems.
14
+
15
+ PlainScript is not a replacement for every JavaScript library. Its strongest
16
+ general-purpose pattern is:
17
+
18
+ 1. keep application intent, state, control flow, and data transformations in
19
+ `.pln` files;
20
+ 2. use PlainScript's built-ins for common application concerns;
21
+ 3. call JavaScript APIs and npm packages when the platform or ecosystem
22
+ already provides the right implementation;
23
+ 4. compile before running or shipping.
24
+
25
+ The compiler does not use an AI model to generate code. Compilation is
26
+ deterministic and produces ordinary JavaScript.
27
+
28
+ ## 2. Project shape
29
+
30
+ For a small program, one file is enough:
31
+
32
+ ```text
33
+ hello/
34
+ app.pln
35
+ ```
36
+
37
+ For a larger application, keep the source and generated output separate:
38
+
39
+ ```text
40
+ my-app/
41
+ src/
42
+ app.pln
43
+ domain.pln
44
+ http.pln
45
+ public/
46
+ index.html
47
+ package.json
48
+ plainscript.config.json
49
+ ```
50
+
51
+ `plainscript build` discovers `.pln` files under `src/` and writes matching
52
+ `.js` files under `dist/`. With no `src/` directory, the project root is
53
+ scanned. `plainscript.config.json` may set `rootDir`, `outDir`, and `exclude`.
54
+ Generated JavaScript is build output; do not hand-edit it.
55
+
56
+ Use separate source files for browser and server code. Browser code can be
57
+ compiled as a package-free script; server code can use Node built-ins and
58
+ server packages.
59
+
60
+ ## 3. Build and run loop
61
+
62
+ The CLI commands are:
63
+
64
+ ```text
65
+ node compiler/cli.js check src/app.pln
66
+ node compiler/cli.js build src/app.pln
67
+ node compiler/cli.js build src/app.pln -o public/app.js
68
+ node compiler/cli.js run src/app.pln
69
+ node compiler/cli.js start
70
+ node compiler/cli.js fmt src/app.pln
71
+ node compiler/cli.js doctor
72
+ node compiler/cli.js install
73
+ ```
74
+
75
+ Use `check` early and often. It parses imports, generates JavaScript, and
76
+ validates the generated syntax without writing build output. Use `build` for
77
+ artifacts and `run` for a one-file Node program. `start` builds the project's
78
+ entry file and runs the generated output.
79
+
80
+ When a project uses npm packages, keep them in `package.json`. The compiler's
81
+ dependency detector reports packages used by `use`, imports, and built-in
82
+ integration statements. The CLI can install detected dependencies, but
83
+ package installation still depends on the Node version, package availability,
84
+ native modules, and the local environment.
85
+
86
+ ## 4. Core syntax
87
+
88
+ ### Values and assignment
89
+
90
+ PlainScript supports strings, template strings, numbers, booleans, `null`,
91
+ `undefined`, BigInt, arrays, objects, function values, and JavaScript objects
92
+ returned by libraries.
93
+
94
+ ```plainscript
95
+ remember name as "Ada"
96
+ let age be 36
97
+ remember tags as ["compiler", "language"]
98
+ remember user as { name: name, active: true }
99
+ name becomes "Grace"
100
+ show `Hello, ${name}`
101
+ show user.name
102
+ show tags[0]
103
+ ```
104
+
105
+ Use `remember` or `let` for a local binding and `becomes`, `is now`, `set`,
106
+ or `change` for assignment. Destructuring is available for arrays and
107
+ objects:
108
+
109
+ ```plainscript
110
+ remember pair as [10, 20]
111
+ remember [first, second] as pair
112
+ show first
113
+ show second
114
+ ```
115
+
116
+ ### Expressions and conditions
117
+
118
+ Arithmetic uses `+`, `-`, `*`, `/`, `%`, and `**`. Word forms such as `plus`,
119
+ `minus`, `times`, and `divided by` are also supported. Member calls, indexed
120
+ access, optional chaining, nullish coalescing, `new`, `typeof`, `void`, and
121
+ `delete` are available.
122
+
123
+ ```plainscript
124
+ remember score as 7 * 6
125
+ if score is at least 40 and name contains "A"
126
+ show "accepted"
127
+ otherwise
128
+ show "review"
129
+ done
130
+ ```
131
+
132
+ Conditions support equality, ordering, string predicates, `between`,
133
+ `instanceof`, property checks, and `and`, `or`, and `not`. Inline conditional
134
+ expressions use `choosing ... then ... otherwise ...`.
135
+
136
+ ### Functions, closures, and generators
137
+
138
+ ```plainscript
139
+ make add(a, b)
140
+ give a + b
141
+ done
142
+
143
+ make greet(name as "friend")
144
+ give `Hello, ${name}`
145
+ done
146
+
147
+ show add(2, 3)
148
+ show greet()
149
+ ```
150
+
151
+ Functions may capture values from their surrounding scope, accept rest
152
+ parameters, and destructure parameters. `yield` turns a function into a
153
+ JavaScript generator:
154
+
155
+ ```plainscript
156
+ make countUp(limit)
157
+ remember i as 0
158
+ while i is less than limit
159
+ i becomes i + 1
160
+ yield i
161
+ done
162
+ done
163
+
164
+ remember values as countUp(3)
165
+ show values.next().value
166
+ ```
167
+
168
+ ### Control flow and collections
169
+
170
+ ```plainscript
171
+ for each item in ["a", "b", "c"]
172
+ show item
173
+ done
174
+
175
+ remember count as 0
176
+ while count is less than 3
177
+ count becomes count + 1
178
+ done
179
+
180
+ for index i from 0 to 3
181
+ show i
182
+ done
183
+ ```
184
+
185
+ `break` and `continue` work inside loops. The standard library includes
186
+ collection and text helpers such as `length`, `first`, `last`, `range`,
187
+ `sort`, `reverse`, `unique`, `sum`, `flatten`, `groupBy`, `paginate`, `split`,
188
+ `join`, `trim`, `replace`, `startsWith`, and `endsWith`. These helpers return
189
+ ordinary JavaScript values.
190
+
191
+ Record kinds are useful when a domain object has declared fields:
192
+
193
+ ```plainscript
194
+ define a kind called "Player" with
195
+ name is ""
196
+ score is 0
197
+ done
198
+
199
+ remember player as create a Player with name "Ada" and score 4
200
+ show player.name
201
+ ```
202
+
203
+ ## 5. Modules and npm interoperability
204
+
205
+ Local PlainScript modules are bundled in dependency order:
206
+
207
+ ```plainscript
208
+ import "./domain.pln"
209
+ import { add } from "./math.pln"
210
+ show add(2, 3)
211
+ ```
212
+
213
+ Use explicit exports when a module's public surface matters:
214
+
215
+ ```plainscript
216
+ make add(a, b)
217
+ give a + b
218
+ done
219
+ export add
220
+ ```
221
+
222
+ Circular local imports are rejected. Relative imports may omit the `.pln`
223
+ extension and may resolve an `index.pln` or `app.pln` entry in a directory.
224
+
225
+ Use an npm package directly:
226
+
227
+ ```plainscript
228
+ use path
229
+ remember file as path.join("data", "items.json")
230
+ show path.basename(file)
231
+ ```
232
+
233
+ Packages with JavaScript identifiers can be bound automatically. Packages
234
+ whose names are not valid identifiers should use an alias or a named import:
235
+
236
+ ```plainscript
237
+ use node-fetch as fetcher
238
+ remember result as fetcher("https://example.com")
239
+ ```
240
+
241
+ The exact package name and export shape remain the npm package's contract.
242
+ PlainScript passes values into JavaScript and receives values back; it does
243
+ not normalize every library API.
244
+
245
+ The `bring`/`import` forms can import a namespace, default export, or named
246
+ exports from a non-local package. Use `new Type(...)` for JavaScript
247
+ constructors, member chains for objects, and callbacks in the same places
248
+ the JavaScript API expects them.
249
+
250
+ ## 6. Async and event-driven programming
251
+
252
+ PlainScript propagates asynchronous requirements through functions and
253
+ handlers. Use `wait for` or `await` around a promise:
254
+
255
+ ```plainscript
256
+ make loadProfile(id)
257
+ wait for sleep(10)
258
+ give { id: id, ready: true }
259
+ done
260
+
261
+ remember profile as wait for loadProfile(7)
262
+ show profile.ready
263
+ ```
264
+
265
+ Async built-ins include promise-aware HTTP requests, database operations,
266
+ mail, OCR, AI helpers, browser asset loading, and `sleep`. Promise
267
+ combinators are available as `all of`, `any of`, `settled of`, and
268
+ `withTimeout`. `run background` schedules work without blocking the current
269
+ path.
270
+
271
+ ```plainscript
272
+ make fetchItem(name)
273
+ wait for sleep(5)
274
+ give name
275
+ done
276
+
277
+ remember results as all of [fetchItem("one"), fetchItem("two")]
278
+ show results[0]
279
+ show results[1]
280
+ ```
281
+
282
+ Timers and scheduled work use `after`, `every`, `schedule`, and
283
+ `run background`. Event-driven features use `when`, `emit`, WebSocket
284
+ handlers, browser event listeners, and the event APIs supplied by imported
285
+ JavaScript libraries.
286
+
287
+ Errors are ordinary JavaScript exceptions. Handle them explicitly:
288
+
289
+ ```plainscript
290
+ try
291
+ remember response as get "https://example.com" timeout 5000
292
+ show response.status
293
+ recover as err
294
+ show message of err
295
+ finally
296
+ show "request complete"
297
+ done
298
+ ```
299
+
300
+ `retry ... done` provides bounded retry behavior. Errors thrown inside a
301
+ PlainScript callback or imported JavaScript callback remain part of the same
302
+ exception path, so validate error boundaries in tests.
303
+
304
+ ## 7. Files, data, and system integration
305
+
306
+ PlainScript provides synchronous file helpers for simple scripts and data
307
+ pipelines:
308
+
309
+ ```plainscript
310
+ remember input as readFile("input.json")
311
+ remember data as jsonDecode(input)
312
+ remember names as data
313
+ gather each item in names giving item.name
314
+ writeFile("names.json", jsonEncode(names))
315
+ ```
316
+
317
+ There are helpers for bytes, append/copy/move/delete, folders, file existence,
318
+ JSON encoding/decoding, environment variables, UUIDs, hashing, and dates.
319
+ For more specialized Node APIs, use `use fs`, `use path`, `use crypto`,
320
+ `use child_process`, streams, buffers, typed arrays, or another npm package.
321
+
322
+ Process execution, exit codes, stdin/stdout/stderr, and OS-specific behavior
323
+ belong to the Node API used by the program. Keep those calls behind a small
324
+ PlainScript module so the rest of the application stays portable.
325
+
326
+ ## 8. HTTP and backend applications
327
+
328
+ An Express-backed application can be expressed directly:
329
+
330
+ ```plainscript
331
+ web app
332
+ allow cors
333
+
334
+ route get "/health"
335
+ reply json
336
+ ok is true
337
+ done
338
+ done
339
+
340
+ route post "/items"
341
+ remember missing as validate("name")
342
+ if length(missing) is greater than 0
343
+ status 400
344
+ reply json
345
+ errors is missing
346
+ done
347
+ otherwise
348
+ reply json
349
+ name is body("name")
350
+ done
351
+ done
352
+ done
353
+
354
+ start 3000
355
+ ```
356
+
357
+ Supported route methods are `get`, `post`, `put`, `patch`, and `delete`.
358
+ Request data can be read with `body`, `param`, `query`, `header`, upload
359
+ helpers, and the route-specific request forms documented in
360
+ `docs/PLAINSCRIPT-SPEC.md`. Responses can be text, JSON, files, redirects,
361
+ or explicit status responses.
362
+
363
+ The backend surface also includes static folders, sessions, cookies, API key
364
+ checks, rate limiting, CORS, validation, and fallback routes. These are
365
+ convenience generators over Express middleware; for middleware or server
366
+ features not covered by the friendly syntax, use Express/npm directly.
367
+
368
+ The HTTP client supports `get`, `post`, `put`, `patch`, and `delete` with
369
+ options such as headers, JSON bodies, and timeouts. Check status and error
370
+ behavior at the application boundary; network failures are not silently
371
+ converted into successful responses.
372
+
373
+ ## 9. Databases and external services
374
+
375
+ SQLite supports a native driver and a WebAssembly fallback:
376
+
377
+ ```plainscript
378
+ database "app.db" using "wasm"
379
+ execute
380
+ CREATE TABLE items (name TEXT)
381
+ done
382
+ insert
383
+ INSERT INTO items (name) VALUES ({name})
384
+ done
385
+ remember name as "Ada"
386
+ remember items as query
387
+ SELECT name FROM items
388
+ done
389
+ show items
390
+ ```
391
+
392
+ SQL block placeholders are bound parameters, not string interpolation. Use
393
+ transactions for related writes. PostgreSQL and MongoDB are generated through
394
+ their JavaScript drivers, and asynchronous query behavior remains visible in
395
+ the generated program.
396
+
397
+ Email, Redis/in-memory cache, OCR, Telegram, WhatsApp, AI provider helpers,
398
+ and scheduled jobs are available as integration layers. They require the
399
+ corresponding package and service configuration. Credentials belong in
400
+ environment variables or the deployment's secret store, never in source.
401
+
402
+ For an unsupported provider, prefer `fetch`, the provider's npm SDK, or a
403
+ small external service instead of adding project-specific compiler syntax.
404
+
405
+ ## 10. Browser, graphics, and multimedia
406
+
407
+ Package-free generated output can run from a normal browser script. A static
408
+ HTML shell can load the compiled file:
409
+
410
+ ```html
411
+ <canvas id="game" width="640" height="480"></canvas>
412
+ <script src="game.js"></script>
413
+ ```
414
+
415
+ PlainScript can call browser globals and libraries:
416
+
417
+ ```plainscript
418
+ remember canvas as document.getElementById("game")
419
+ remember ctx as canvas.getContext("2d")
420
+ ctx.fillStyle becomes "black"
421
+ ctx.fillRect(0, 0, 640, 480)
422
+
423
+ when document "keydown" happens as event
424
+ show event.key
425
+ done
426
+
427
+ every frame
428
+ ctx.clearRect(0, 0, 640, 480)
429
+ done
430
+ ```
431
+
432
+ Browser helpers cover DOM selection, HTML parsing, pointer coordinates,
433
+ gamepads, dropped files, image/audio loading, JSON/byte fetches, data URLs,
434
+ Web Audio, and WebGL shader/program/buffer helpers. WebSocket clients can use
435
+ the browser's `WebSocket` object.
436
+
437
+ Three.js, canvas libraries, WebGL/WebGPU libraries, audio/video APIs, image
438
+ processors, and rendering engines should remain JavaScript dependencies.
439
+ Load a browser-global library before the compiled script or use a browser
440
+ bundler for npm imports. PlainScript does not provide a complete graphics or
441
+ game engine.
442
+
443
+ ## 11. Testing and verification
444
+
445
+ Start with compiler validation:
446
+
447
+ ```text
448
+ node compiler/cli.js check src/app.pln
449
+ npm test
450
+ ```
451
+
452
+ PlainScript also has a native test DSL:
453
+
454
+ ```plainscript
455
+ test "addition"
456
+ check 2 + 2 equals 4
457
+ done
458
+ ```
459
+
460
+ Use regular Node tests for integration boundaries such as real HTTP servers,
461
+ browser harnesses, database drivers, network services, package exports, and
462
+ process behavior. Add a representative example when a capability crosses
463
+ multiple layers; an isolated generator assertion is not enough.
464
+
465
+ For every new feature, check:
466
+
467
+ - synchronous and asynchronous callers;
468
+ - errors inside callbacks and across module boundaries;
469
+ - promise ordering and timeouts;
470
+ - generated JavaScript syntax;
471
+ - browser versus Node globals;
472
+ - missing environment configuration;
473
+ - package detection and installation;
474
+ - malformed source and useful diagnostics;
475
+ - backwards compatibility with existing examples.
476
+
477
+ ## 12. Common mistakes
478
+
479
+ - Do not claim a snippet works without running `plainscript check`.
480
+ - Do not put `require()` in a browser bundle unless a bundler is handling it.
481
+ - Do not assume an npm package's default export is callable; verify its API.
482
+ - Do not use SQL string concatenation when a bound placeholder is available.
483
+ - Do not put API keys, database URLs, or session secrets in `.pln` files.
484
+ - Do not use server-only globals such as `process` or `fs` in browser code.
485
+ - Do not treat an async function as synchronous just because its source reads
486
+ naturally; await its result at the boundary.
487
+ - Do not create circular local imports.
488
+ - Do not edit generated files instead of the `.pln` source.
489
+ - Do not add compiler syntax for a capability already exposed cleanly by an
490
+ npm package or browser API.
491
+
492
+ ## 13. What PlainScript should own
493
+
494
+ PlainScript is a good home for application flow, domain rules, validation,
495
+ data shaping, orchestration, route handlers, error handling, and the glue
496
+ between services. Its line-oriented syntax is especially useful for readable
497
+ business logic and small-to-medium service modules.
498
+
499
+ Delegate mature platform implementations to JavaScript/npm: database drivers,
500
+ HTTP clients, graphics engines, codecs, cloud SDKs, model runtimes, and
501
+ specialized algorithms. PlainScript should make those systems usable without
502
+ turning each one into a proprietary language feature.
503
+
504
+ ## 14. Current limitations
505
+
506
+ - The compiler targets JavaScript; runtime behavior follows the Node or
507
+ browser version executing the generated code.
508
+ - Package installation can be blocked by the environment or by a package's
509
+ native-module and Node-version requirements.
510
+ - Browser npm imports need a bundler; package-free output is the simplest
511
+ browser deployment path.
512
+ - External services still require their own credentials, network access,
513
+ quotas, and operational handling.
514
+ - PostgreSQL, MongoDB, Redis, mail, AI, OCR, Telegram, WhatsApp, and similar
515
+ integrations are adapters around third-party packages, not local emulators.
516
+ - The language does not provide static type checking or a separate memory
517
+ safety model; use JavaScript tooling and runtime validation where needed.
518
+ - Cancellation, distributed coordination, and streaming semantics depend on
519
+ the underlying JavaScript API. Design those boundaries explicitly.
520
+
521
+ When a proposed feature falls outside this guide, first test whether existing
522
+ PlainScript syntax plus a JavaScript or npm API is enough. Only add a language
523
+ feature when the gap is real, broadly reusable, and worth its compatibility
524
+ cost.