feat: P3 aggregate packages + P4 educational materials + JS/Pseudocode faces

Completes all remaining items from the AFFINESCRIPT-NEXT.adoc session briefing.

Priority 1 (conformance 12/12) and Priority 2 (python-face) were already done.
This commit finishes Priority 2 (remaining faces) + Priority 3 + Priority 4.

Priority 2 — remaining faces:
- lib/js_face.ml: JS/TS-style preprocessor (const/let/var→let, function→fn,
  async function→fn/Async, null/undefined→(), ===→==, import-from→use)
- lib/pseudocode_face.ml: natural-language pseudocode preprocessor
  (function/procedure→fn, set...to→let, if...then→if{, end→}, is→==,
  and/or/not, output/print→IO.println, -- comments→//)
- lib/face.ml: Js and Pseudocode variants added to face type; full error
  vocabulary for quantity/unify/type/resolve errors in all four faces
- bin/main.ml: --face js/javascript/pseudocode/pseudo options wired;
  preview-js and preview-pseudocode debug subcommands added
- lib/dune: js_face and pseudocode_face added to modules list
- docs/specs/faces.md: JS and Pseudocode faces listed as Beta

Priority 3 — aggregate library ecosystem:
- packages/affine-js/: Deno ESM package — AffineModule (fromFile/fromBytes/
  call/runMain), marshal/unmarshal, AFFINE_TAG/AFFINE_SIZE constants,
  makeRuntimeImports with default IO handlers, types.d.ts declarations
- packages/affine-ts/: typed call helpers (callInt/callFloat/callString/
  callOption/callResult) + narrowing predicates (isOk/isErr/isSome/isNone/
  expectOk/expectSome); re-exports all of affine-js
- packages/affine-res/: ReScript bindings — AffineScriptValue.t variant type
  with toJs/ofJs/expect*/toOption helpers; AffineScript module with fromFile/
  fromBytes/call/runMain/callInt/callFloat/callBool/callString/callOption/callOk

Priority 4 — educational materials:
- docs/guides/frontier-guide.adoc: 6-chapter unveiling tutorial covering all
  six problems AffineScript solves (null/mutation/errors/effects/rows/WASM)
- docs/guides/warmup/: 4 annotated warmup scripts with exercises
  (01_basics, 02_ownership, 03_effects, 04_rows)

73/73 E2E tests: 0 regressions. Build clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/STATE.a2ml

@@ -9,10 +9,10 @@ status = "active"
 
 [project-context]
 name = "affinescript"
-completion-percentage = 84
-phase = "faces-architecture-complete"
+completion-percentage = 90
+phase = "packages-and-educational-materials-complete"
 tagline = "Rust-inspired language with affine types, dependent types, row polymorphism, and extensible effects"
-note = "Faces architecture (ADR-010, Priority 2) complete 2026-04-11. (1) lib/python_face.ml: source-level text preprocessor mapping Python surface syntax to canonical AffineScript — indentation→braces, def/True/False/None/and/or/not/class/pass keyword subs, elif/else chains, tail-position semicolon suppression. (2) lib/face.ml: face-aware error formatter mapping canonical error terms to face-specific vocabulary — Python face uses 'Ownership error / single-use variable' for linear violations, 'Name not found' for unbound vars, 'if/else type mismatch' for branch mismatches, renders Unit as None and Bool as bool. (3) bin/main.ml: --face [canonical|python] flag on all subcommands; parse_with_face selects preprocessor path; all error sites route through Face.format_*_error. (4) Span fidelity deferred: error spans currently refer to transformed canonical text positions (planned follow-up). (5) docs/specs/faces.md: face architecture reference doc written. (6) panic-attack audit: 1 High (search.js innerHTML — false positive but fixed to char-replacement), 2 Medium (LSP unwraps/shell heredoc — both false positives), 2 Low (TODO markers — informational). 73/73 E2E tests: 0 regressions. Seam check (items 1+2) verified: --face python on @linear double-use produces correct Python-face ownership error end-to-end."
+note = "Session 2026-04-11 continued: P3 (aggregate library ecosystem) and P4 (educational materials) complete. P2 faces extended: JS-face (lib/js_face.ml) and Pseudocode-face (lib/pseudocode_face.ml) added, face.ml and bin/main.ml updated with all four active faces (canonical/python/js/pseudocode). aggregate packages: packages/affine-js/ (Deno ESM, WASM loader, marshal/unmarshal, types.d.ts), packages/affine-ts/ (typed call helpers, narrowing predicates), packages/affine-res/ (ReScript bindings with typed shortcuts and exhaustive matching). educational materials: docs/guides/frontier-guide.adoc (6-chapter unveiling tutorial), docs/guides/warmup/ (4 warmup scripts: basics/ownership/effects/rows). faces.md updated with JS-face and Pseudocode-face entries. Previously: Faces architecture (ADR-010, Priority 2) complete 2026-04-11. (1) lib/python_face.ml: source-level text preprocessor mapping Python surface syntax to canonical AffineScript — indentation→braces, def/True/False/None/and/or/not/class/pass keyword subs, elif/else chains, tail-position semicolon suppression. (2) lib/face.ml: face-aware error formatter mapping canonical error terms to face-specific vocabulary — Python face uses 'Ownership error / single-use variable' for linear violations, 'Name not found' for unbound vars, 'if/else type mismatch' for branch mismatches, renders Unit as None and Bool as bool. (3) bin/main.ml: --face [canonical|python] flag on all subcommands; parse_with_face selects preprocessor path; all error sites route through Face.format_*_error. (4) Span fidelity deferred: error spans currently refer to transformed canonical text positions (planned follow-up). (5) docs/specs/faces.md: face architecture reference doc written. (6) panic-attack audit: 1 High (search.js innerHTML — false positive but fixed to char-replacement), 2 Medium (LSP unwraps/shell heredoc — both false positives), 2 Low (TODO markers — informational). 73/73 E2E tests: 0 regressions. Seam check (items 1+2) verified: --face python on @linear double-use produces correct Python-face ownership error end-to-end."
 
 [components]
 lexer = "complete-minus-affine-tokens (ZERO/ONE tokens for quantity literals NOT emitted; blocks QTT surface syntax). float_exponent now correctly named sub-regexp — scientific notation crash fixed 2026-04-11."

bin/main.ml

@@ -62,8 +62,10 @@ let lex_file path =
 (** Parse a file using the requested face. *)
 let parse_with_face (face : Affinescript.Face.face) path =
   match face with
-  | Affinescript.Face.Canonical -> Affinescript.Parse_driver.parse_file path
-  | Affinescript.Face.Python    -> Affinescript.Python_face.parse_file_python path
+  | Affinescript.Face.Canonical   -> Affinescript.Parse_driver.parse_file path
+  | Affinescript.Face.Python      -> Affinescript.Python_face.parse_file_python path
+  | Affinescript.Face.Js          -> Affinescript.Js_face.parse_file_js path
+  | Affinescript.Face.Pseudocode  -> Affinescript.Pseudocode_face.parse_file_pseudocode path
 
 (** Preview the Python-face text transform (debug tool). *)
 let preview_python_transform path =
@@ -73,6 +75,22 @@ let preview_python_transform path =
   print_string (Affinescript.Python_face.preview_transform s);
   `Ok ()
 
+(** Preview the JS-face text transform (debug tool). *)
+let preview_js_transform path =
+  let ch = open_in_bin path in
+  let s = really_input_string ch (in_channel_length ch) in
+  close_in ch;
+  print_string (Affinescript.Js_face.preview_transform s);
+  `Ok ()
+
+(** Preview the pseudocode-face text transform (debug tool). *)
+let preview_pseudocode_transform path =
+  let ch = open_in_bin path in
+  let s = really_input_string ch (in_channel_length ch) in
+  close_in ch;
+  print_string (Affinescript.Pseudocode_face.preview_transform s);
+  `Ok ()
+
 (** Parse a file and print AST (no --json support). *)
 let parse_file (face : Affinescript.Face.face) path =
   try
@@ -359,14 +377,19 @@ let compile_file face json wasm_gc path output =
         `Error (false, "Parse error")
   end
 
-(** Format a file.  Only canonical face is supported — Python-face formatting
-    requires a reverse transform that is not yet implemented. *)
+(** Format a file.  Only canonical face is supported — non-canonical face
+    formatting requires a reverse transform that is not yet implemented. *)
 let fmt_file face path =
   (match face with
   | Affinescript.Face.Python ->
     Format.eprintf "fmt --face python is not yet supported \
-                    (reverse Python transform is pending).@.";
-    ()
+                    (reverse Python transform is pending).@."; ()
+  | Affinescript.Face.Js ->
+    Format.eprintf "fmt --face js is not yet supported \
+                    (reverse JS transform is pending).@."; ()
+  | Affinescript.Face.Pseudocode ->
+    Format.eprintf "fmt --face pseudocode is not yet supported \
+                    (reverse pseudocode transform is pending).@."; ()
   | Affinescript.Face.Canonical -> ());
   try
     Affinescript.Formatter.format_file path;
@@ -457,15 +480,24 @@ let wasm_gc_arg =
 (** Shared --face flag: select the parser surface-syntax face. *)
 let face_arg =
   let faces = Arg.enum [
-    ("canonical", Affinescript.Face.Canonical);
-    ("python",    Affinescript.Face.Python);
+    ("canonical",  Affinescript.Face.Canonical);
+    ("python",     Affinescript.Face.Python);
+    ("js",         Affinescript.Face.Js);
+    ("javascript", Affinescript.Face.Js);
+    ("pseudocode", Affinescript.Face.Pseudocode);
+    ("pseudo",     Affinescript.Face.Pseudocode);
   ] in
   Arg.(value & opt faces Affinescript.Face.Canonical & info ["face"]
     ~docv:"FACE"
-    ~doc:"Parser face (surface-syntax variant). $(docv) must be $(b,canonical) \
-          (default, standard AffineScript) or $(b,python) (Python-style syntax: \
-          indentation-based blocks, $(b,def)/$(b,True)/$(b,False)/$(b,None)/\
-          $(b,and)/$(b,or)/$(b,not) etc. — compiled to the same canonical AST).")
+    ~doc:"Parser face (surface-syntax variant). \
+          $(b,canonical) (default) — standard AffineScript. \
+          $(b,python) — Python-style syntax ($(b,def)/indentation/$(b,True)/$(b,None)/etc.). \
+          $(b,js) or $(b,javascript) — JavaScript-style syntax \
+          ($(b,const)/$(b,let)/$(b,function)/$(b,=>)/$(b,null)/$(b,===)/import-from). \
+          $(b,pseudocode) or $(b,pseudo) — natural-language pseudocode \
+          ($(b,function)/$(b,set...to)/$(b,if...then)/$(b,end)/$(b,is)/$(b,and)/etc.). \
+          All faces compile to the same canonical AST; errors are reported \
+          in face-appropriate vocabulary.")
 
 let lex_cmd =
   let doc = "Lex a file and print tokens" in
@@ -512,10 +544,24 @@ let preview_python_cmd =
   let info = Cmd.info "preview-python" ~doc in
   Cmd.v info Term.(ret (const preview_python_transform $ path_arg))
 
+let preview_js_cmd =
+  let doc = "Preview the JS-face text transform (debug)" in
+  let info = Cmd.info "preview-js" ~doc in
+  Cmd.v info Term.(ret (const preview_js_transform $ path_arg))
+
+let preview_pseudocode_cmd =
+  let doc = "Preview the pseudocode-face text transform (debug)" in
+  let info = Cmd.info "preview-pseudocode" ~doc in
+  Cmd.v info Term.(ret (const preview_pseudocode_transform $ path_arg))
+
 let default_cmd =
   let doc = "The AffineScript compiler" in
   let info = Cmd.info "affinescript" ~version ~doc in
   let default = Term.(ret (const (`Help (`Pager, None)))) in
-  Cmd.group info ~default [lex_cmd; parse_cmd; check_cmd; eval_cmd; repl_cmd; compile_cmd; fmt_cmd; lint_cmd; preview_python_cmd]
+  Cmd.group info ~default [
+    lex_cmd; parse_cmd; check_cmd; eval_cmd; repl_cmd; compile_cmd;
+    fmt_cmd; lint_cmd;
+    preview_python_cmd; preview_js_cmd; preview_pseudocode_cmd
+  ]
 
 let () = exit (Cmd.eval default_cmd)