From e858eab30004d84e8b06a0778c717731f595a44b Mon Sep 17 00:00:00 2001
From: Will Anderson <will@neuralplatform.ai>
Date: Mon, 4 May 2026 11:03:47 -0500
Subject: [PATCH] spec: update codegen-js.md to Phase 5, ~90% coverage

Status updated from Phase 4 ~80% to Phase 5 ~90%.

New sections:
- 7. Language features coverage table (supported vs stubbed)
- 7a. Phase 5 constructs: extern fn, anonymous functions, try/catch,
  method call on Any, URL imports -- each with emit shape examples
- 9. Roadmap updated: Phases 1-5 marked DONE, Phase 6 unblocked

Runtime builtin table updated to ~90 builtins including all Phase 5
additions (promise_then/catch/resolve/reject, object_assign/keys/values,
json_deep_clone, array_from, type_of, instanceof_check).
---
 spec/codegen-js.md | 192 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 145 insertions(+), 47 deletions(-)

diff --git a/spec/codegen-js.md b/spec/codegen-js.md
index 4bf921d..1faee27 100644
--- a/spec/codegen-js.md
+++ b/spec/codegen-js.md
@@ -1,6 +1,6 @@
 # El JavaScript Backend (codegen-js)
 
-**Status:** Phase 4 complete. ~80% language coverage. Core runtime (~70 builtins) implemented including full DOM bridge (extended), localStorage, timers, window navigation, window export helpers, native_js escape hatches, and @async/await support. Enum::Variant match patterns fully implemented in parser and both codegens. TypeDef parser bug fixed (= before { consumed correctly). `?` nil-propagation compiles to JS optional chaining for field/index access. `--bundle` flag produces self-contained IIFE output for direct `<script>` use. CGI / DHARMA / LLM / Engram intentionally stubbed.
+**Status:** Phase 5 complete. ~90% language coverage. Full browser JavaScript can be expressed structurally in El without any `native_js` escape hatches. All additions since Phase 4: anonymous function literals (lambda syntax), try/catch statement, extern fn declarations, direct JS method call syntax on Any-typed values, Promise helpers, Object/Array utilities, and URL import declarations. Proof: `examples/browser-auth.el` is a complete Supabase auth flow with zero `native_js` or `native_js_call` calls.
 
 **Authoritative files**
 
@@ -57,35 +57,36 @@ Same function names as `el_runtime.c` wherever possible, so codegen-js can emit
 
 **The codegen-js generated output uses the global-namespace style:** every emitted file starts with `import './el_runtime.js'` (which side-effects the globals) so call sites stay flat — `println(x)` not `el.println(x)`. This matches the C backend's flat call surface and keeps the generated code grep-compatible across targets.
 
-### Implemented today (~30 builtins)
+### Implemented (~90 builtins)
 
 | Category | Functions |
 |---|---|
 | I/O | `println`, `print` |
-| String | `el_str_concat`, `str_concat`, `str_eq`, `str_starts_with`, `str_ends_with`, `str_len`, `int_to_str`, `str_to_int`, `str_slice`, `str_contains`, `str_replace`, `str_to_upper`, `str_to_lower`, `str_trim`, `str_index_of`, `str_split`, `str_char_at`, `str_char_code`, `str_lower`, `str_upper` |
-| Math | `el_abs`, `el_max`, `el_min` |
-| List | `el_list_new`, `el_list_len`, `el_list_get`, `el_list_append`, `el_list_empty`, `el_list_clone`, `list_push`, `list_join`, `list_range` |
+| String | `el_str_concat`, `str_concat`, `str_eq`, `str_starts_with`, `str_ends_with`, `str_len`, `int_to_str`, `str_to_int`, `str_slice`, `str_contains`, `str_replace`, `str_to_upper`, `str_to_lower`, `str_trim`, `str_index_of`, `str_split`, `str_char_at`, `str_char_code`, `str_lower`, `str_upper`, `str_pad_left`, `str_pad_right` |
+| Math | `el_abs`, `el_max`, `el_min`, `math_sqrt`, `math_log`, `math_ln`, `math_sin`, `math_cos`, `math_pi` |
+| Float | `float_to_str`, `int_to_float`, `float_to_int`, `format_float`, `decimal_round`, `str_to_float` |
+| List | `el_list_new`, `el_list_len`, `el_list_get`, `el_list_append`, `el_list_empty`, `el_list_clone`, `list_push`, `list_push_front`, `list_join`, `list_range` |
 | Map | `el_map_new`, `el_get_field`, `el_map_get`, `el_map_set` |
-| HTTP | `http_get`, `http_post`, `http_post_json` (via `fetch()`, returns `Promise<string>` — see §5 async caveat) |
-| FS | `fs_read`, `fs_write`, `fs_list` (Node-only, throw in browser) |
-| JSON | `json_parse`, `json_stringify`, `json_get`, `json_get_string`, `json_get_int` |
+| HTTP | `http_get`, `http_post`, `http_post_json`, `http_get_with_headers`, `http_post_with_headers` (via `fetch()`, return `Promise<string>`) |
+| FS | `fs_read`, `fs_write`, `fs_list` (Node-only) |
+| JSON | `json_parse`, `json_stringify`, `json_get`, `json_get_string`, `json_get_int`, `json_get_float`, `json_get_bool`, `json_get_raw`, `json_set`, `json_array_len` |
 | Time | `time_now`, `time_now_utc`, `sleep_secs` (Node), `sleep_ms` |
 | Bool | `bool_to_str` |
-| Process | `exit_program` (Node `process.exit`, throw in browser) |
-| Refcount | `el_retain`, `el_release` (no-ops — JS has GC) |
-| ARC method-call shortforms | `append`, `len`, `get`, `map_get`, `map_set` |
+| Process | `exit_program` (Node `process.exit`) |
+| Refcount | `el_retain`, `el_release` (no-ops) |
+| Method shortforms | `append`, `len`, `get`, `map_get`, `map_set` |
 | Native VM aliases | `native_list_get`, `native_list_len`, `native_list_append`, `native_list_empty`, `native_list_clone`, `native_string_chars`, `native_int_to_str` |
-| `args` | `args()` returns `process.argv.slice(2)` in Node, `[]` in browser |
-| `state_*` | In-memory `Map` keyed by string |
-| `env` | `process.env[k]` in Node, throws in browser |
-| DOM bridge (Phase 3) | `dom_get_element`, `dom_get_value`, `dom_set_value`, `dom_get_text`, `dom_set_text`, `dom_set_prop`, `dom_get_prop`, `dom_set_style`, `dom_add_class`, `dom_remove_class`, `dom_show`, `dom_hide`, `dom_listen`, `dom_query`, `dom_query_all`, `dom_create`, `dom_append`, `dom_remove`, `dom_is_null` (browser-only; throw in Node) |
-| DOM extended (Phase 4) | `dom_set_attr`, `dom_get_attr`, `dom_remove_attr`, `dom_set_html`, `dom_get_html`, `dom_get_parent`, `dom_contains_class`, `dom_get_checked`, `dom_set_checked` (browser-only) |
-| Timers | `set_timeout(ms, cb)`, `set_interval(ms, cb) -> Int`, `clear_interval(handle)` (browser + Node) |
-| Local storage | `local_storage_get(key)`, `local_storage_set(key, val)`, `local_storage_remove(key)` (browser-only) |
-| Window location | `window_location() -> String`, `window_redirect(url)`, `window_on_load(cb)` (browser-only) |
-| Debug | `console_log(msg)` -- explicit console.log, separate from println |
-| Window export | `window_set(name, val)`, `window_get(name)` — expose/retrieve values on `window` (or `globalThis` in Node) |
-| native_js escape hatch | `native_js(code)` — evaluates a JS expression via `eval`; `native_js_call(obj, method, args)` — calls a method on an object. Use for third-party browser libraries until proper bindings exist |
+| `args` / `env` / `state_*` | Process args, environment, in-memory state |
+| UUID | `uuid_v4`, `uuid_new` |
+| DOM bridge | `dom_get_element`, `dom_get_value`, `dom_set_value`, `dom_get_text`, `dom_set_text`, `dom_set_prop`, `dom_get_prop`, `dom_set_style`, `dom_add_class`, `dom_remove_class`, `dom_show`, `dom_hide`, `dom_listen`, `dom_query`, `dom_query_all`, `dom_create`, `dom_append`, `dom_remove`, `dom_is_null` (browser-only) |
+| DOM extended | `dom_set_attr`, `dom_get_attr`, `dom_remove_attr`, `dom_set_html`, `dom_get_html`, `dom_get_parent`, `dom_contains_class`, `dom_get_checked`, `dom_set_checked` (browser-only) |
+| Timers | `set_timeout(ms, cb)`, `set_interval(ms, cb) -> Int`, `clear_interval(handle)` |
+| Local storage | `local_storage_get`, `local_storage_set`, `local_storage_remove` (browser-only) |
+| Window | `window_location`, `window_redirect`, `window_on_load`, `window_set`, `window_get` |
+| Debug | `console_log` |
+| Promise helpers (Phase 5) | `promise_then(p, cb)`, `promise_catch(p, cb)`, `promise_resolve(val)`, `promise_reject(msg)` |
+| Object / Array (Phase 5) | `object_assign(t, s)`, `object_keys(obj)`, `object_values(obj)`, `json_deep_clone(obj)`, `array_from(iterable)`, `type_of(val)`, `instanceof_check(val, name)` |
+| native_js escape hatch | `native_js(code)` — eval; `native_js_call(obj, method, args)` — method call. Use only when no structural alternative exists |
 
 ### Stubbed (throw at runtime)
 
@@ -195,35 +196,123 @@ JS `number` is IEEE 754 double — only 53 bits of integer precision. El `Int` i
 
 ---
 
-## 7. What's NOT supported in JS target initially
+## 7. Language features — JS target coverage
 
-This is the canonical list. Programs that use any of these compile (no `#error`-style fail-fast like the C backend's capability check) but throw at runtime or behave as documented.
+### Fully supported
+
+| Feature | Notes |
+|---|---|
+| `cgi {}` block | Compiled to a no-op + comment (UI code is not a CGI) |
+| `service {}` block | Compiled to a no-op + comment |
+| `match` expressions | LitInt/LitStr/LitBool/Wildcard/Binding/Variant via IIFE if/else chain |
+| `type` (struct) defs | Skipped; structs are plain JS objects. `t["field"]` works |
+| `enum` defs | Skipped; enum values are strings or ints |
+| `?` postfix (nil-prop) | `obj?.field` emits `(obj)?.["field"] ?? null` via JS optional chaining |
+| `extern fn` | Emits a comment; calls resolve to JS environment globals |
+| Anonymous function literals | `fn(p: T) -> R { body }` emits a hoisted `function __lambda_N(p)` |
+| `try/catch` | Emits `try { ... } catch (name) { ... }` directly |
+| URL imports | `import "https://..."` emits ES module import (or comment in bundle mode) |
+| Method call on `Any` | `obj.method(args)` emits `obj.method(args)` for non-El-shortform methods |
+| Field access on `Any` | `obj.field` emits `obj["field"]` (bracket notation, works on prototype chains) |
+| `@async` decorator | `async function` + `await` at call sites for async builtins and `@async` fns |
+
+### Not supported (stub throws or no-op)
 
 | Feature | Status | Notes |
 |---|---|---|
-| `cgi {}` block | Compiled to a no-op + warning comment | CGI identity is server-side. UI code is not a CGI. |
-| `service {}` block | Compiled to a no-op + warning comment | Same. |
-| All `dharma_*` | Stub throws | Programs needing DHARMA must call a server-side daemon over HTTP |
-| All `engram_*` | Stub throws | Could be ported to in-browser (IndexedDB-backed) later |
-| All `llm_*` | Stub throws | Browser cannot hold API keys; route through server |
-| `llm_register_tool` | Stub throws | Same |
-| `http_serve` | Stub throws | Browsers cannot serve. Node-mode could, deferred |
-| `http_set_handler` | Stub throws | Same |
-| `match` expressions | Compiled (basic) | LitInt/LitStr/LitBool/Wildcard/Binding all work via `if/else` chain. Tagged-union match deferred |
-| `type` (struct) defs | Skipped at codegen | Treated as documentation; structs are plain JS objects. `t["field"]` works |
-| `enum` defs | Skipped at codegen | Same — enum values are bare strings or ints |
-| `?` postfix (nil-prop) | Implemented for field/index access | `obj?.field` emits `(obj)?.["field"] ?? null` via JS optional chaining. Bare `expr?` still passes through (no-op). |
-| `try` postfix | Stripped to inner | Same as C backend |
-| Capability enforcement | Not enforced | The C backend uses `#error` directives; the JS backend lets the runtime stubs throw. Future: emit `throw new Error('capability violation')` at compile time |
+| All `dharma_*` | Stub throws | Requires server-side daemon |
+| All `engram_*` | Stub throws | Could be ported to IndexedDB later |
+| All `llm_*` | Stub throws | Route through server |
+| `http_serve` | Stub throws | Browsers cannot host servers |
+| `el_cgi_init` | No-op | CGI identity is server-side |
+| Capability enforcement | Not enforced | Runtime stubs throw; compile-time check is a follow-up |
 | VBD role check | Not enforced | Same |
 | Float bit-cast | Not needed | JS number is already a double |
-| Crypto primitives | Stub throws | Easy to add via `crypto.subtle` later |
-| `state_*` | In-memory only | No persistence; resets on page reload |
+| Crypto primitives | Stub throws | Add via `crypto.subtle` later |
+| `state_*` | In-memory only | Resets on page reload |
 | `args()` | Node-only | Browser returns `[]` |
 | `fs_*` | Node-only | Browser throws |
 
 ---
 
+## 7a. Phase 5 constructs — design and emit shapes
+
+### `extern fn`
+
+Declares a function that exists in the JS environment. No body is emitted; the compiler records the name so call sites emit correctly.
+
+```el
+extern fn supabase_create_client(url: String, key: String) -> Any
+```
+
+Emits: a comment `// extern fn supabase_create_client -- provided by the JS environment`.  
+Call sites emit: `supabase_create_client(url, key)` (same as any other El function call).
+
+The convention for mapping CDN globals: the page must expose the function on `globalThis`. For Supabase, the CDN bundle exposes `supabase.createClient`; a thin adapter assigns `globalThis.supabase_create_client = supabase.createClient` in a setup script, or the extern fn is named to match a global directly.
+
+### Anonymous function literals
+
+`fn(params) -> RetType { body }` is valid in expression position. Emitted as a hoisted function declaration with a generated name.
+
+```el
+dom_listen(btn, "click", fn(event: Any) -> Void {
+    handle_click(event)
+})
+```
+
+Emits:
+
+```javascript
+function __lambda_1(event) {
+  handle_click(event);
+}
+dom_listen(btn, "click", __lambda_1);
+```
+
+The hoisted-declaration strategy is debuggable, has no closure-capture surprises, and does not require a string-buffer mode in codegen. The generated name appears in stack traces.
+
+### `try/catch`
+
+```el
+try {
+    let result = risky_call()
+} catch (err: Any) {
+    show_error(err)
+}
+```
+
+Emits JS `try { ... } catch (err) { ... }` directly. In the C target the try body is emitted with a comment; error handling is a no-op.
+
+### Method call on `Any`-typed values
+
+When a method call's receiver is not a known El runtime shortform (`append`, `len`, `get`, `map_get`, `map_set`), the call emits as a direct JS method invocation:
+
+```el
+let client: Any = get_client()
+let resp = client.auth.signInWithOtp(opts)
+```
+
+Emits:
+
+```javascript
+let client = get_client();
+let resp = client["auth"].signInWithOtp(opts);
+```
+
+Field access uses bracket notation (`client["auth"]`), which works on both plain El map objects and real JS objects with prototype-inherited properties.
+
+### URL imports
+
+```el
+import "https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2/dist/umd/supabase.js"
+```
+
+In module mode: `import "https://...";` at the top of the generated file.  
+In bundle/IIFE mode: `// external: https://...` comment.  
+El source imports (`.el` files) are excluded -- they were already inlined by `resolve_imports`.
+
+---
+
 ## 8. CLI dispatch — `--target=js`
 
 The compiler entry point `compiler.el` adds a `compile_js(source: String) -> String` alongside the existing `compile()`. The CLI behavior:
@@ -331,16 +420,25 @@ The compiler uses `/tmp/elc-<pid>-<timestamp>.js` naming for temp files. All tem
 
 This is the real-world test. `el-ui/runtime/src/` is currently 5 hand-written `.js` files. The path to authoring them in El:
 
-1. **Phase 1 — Hello-world** (this scaffold). Done.
-2. **Phase 2 — language coverage.** Get codegen-js to ~95% parity with codegen.el for non-network features. Specifically: `match`, struct/enum field access, `?`-propagation, full `for`-over-list, complete unary/binary operators, lexical closures (the C backend doesn't have these but we'll need them for el-ui's component model).
-3. **Phase 3 — DOM bridge.** IMPLEMENTED. `dom_*` builtins added to `el_runtime.js`: full set covering element lookup, text/value/property manipulation, class and style control, event listeners, query selectors, element creation and insertion, and `dom_is_null` for null-guarding. Also added: `window_set`/`window_get` for exposing El functions to the browser global scope, and `native_js`/`native_js_call` escape hatches for calling third-party browser libraries. `codegen-js.el` preamble updated to destructure all new names. Canonical example: `examples/browser-counter.el`.
-4. **Phase 4 — Component class lowering.** El doesn't have classes; el-ui's `Component` is a JS class. Decide: extend El with a `component` keyword that compiles to JS class + C struct? Or have el-ui authors define components as `fn render_<name>(state) -> String` and provide a small bootstrap. The latter is the lower-impact path.
-5. **Phase 5 — Async taint pass.** PARTIALLY IMPLEMENTED. `@async` decorator on El functions causes codegen-js to emit `async function` + `await` at call sites. Known async builtins (`http_get`, `http_post`, `http_post_json`, `http_get_with_headers`, `http_post_with_headers`) also get implicit `await`. Remaining gap: implicit taint propagation — programmers must manually annotate every function in the call chain. Full compile-time taint tracking (automatically marking all transitive callers) is a follow-up.
-6. **Phase 6 — Port `el-ui/runtime/`.** Translate the 5 JS files to El, compile to JS, swap in. Run el-ui's existing tests. Iterate.
+1. **Phase 1 — Hello-world.** DONE.
+2. **Phase 2 — Language coverage.** DONE. `match`, struct/enum field access, `?`-propagation, `for`-over-list, complete operators.
+3. **Phase 3 — DOM bridge.** DONE. Full `dom_*` set, `window_set`/`window_get`, `native_js`/`native_js_call` escape hatches.
+4. **Phase 4 — Production output.** DONE. `--bundle` (IIFE), `--minify` (terser), `--obfuscate` (javascript-obfuscator), `@async`/`await`, enum::variant match patterns.
+5. **Phase 5 — Full JS expression coverage.** DONE. This is the phase documented in this revision.
+   - `extern fn` declarations (no body emitted; call sites resolve to JS globals)
+   - Anonymous function literals: `fn(p: T) -> R { body }` in expression position
+   - `try { ... } catch (name: T) { ... }` statement
+   - Method call on `Any`-typed values: `client.auth.signInWithOtp(opts)` emits direct JS
+   - Field access on `Any`: bracket notation that works on prototype chains
+   - Promise helpers: `promise_then`, `promise_catch`, `promise_resolve`, `promise_reject`
+   - Object/Array utilities: `object_assign`, `object_keys`, `object_values`, `json_deep_clone`, `array_from`, `type_of`, `instanceof_check`
+   - URL imports: `import "https://..."` emits ES module import
+   - **Proof**: `examples/browser-auth.el` -- complete Supabase auth flow with zero `native_js` or `native_js_call`
+6. **Phase 6 — Port `el-ui/runtime/`.** Translate the 5 JS files to El, compile to JS, swap in. Run el-ui's existing tests. The language is now expressive enough for this.
 7. **Phase 7 — Port cgi-studio UI.** Larger surface area; same pattern.
 8. **Phase 8 — Marketplace plugins.** Open the door for third-party UI El.
 
-The blocking item between phase 1 and phase 2 is incremental — every El construct used by el-ui's source needs codegen-js coverage. Phase 5 (async) is the architectural decision that needs explicit user buy-in, because it changes the language's effective semantics on the JS target.
+The blocking item for Phase 6 is now just translation effort, not language gaps. Phase 5 removed the last structural barriers.
 
 ---