feat(stage3): TEA stdlib — counter + titlescreen running in interpreter

Stage 3 of the AffineScript TEA dogfood plan: The Elm Architecture
running in the AffineScript interpreter. Closes 3a–3d.

**Interpreter fixes (3b foundation):**
- `interp.ml` — `TopType TyEnum`: register enum constructors into the
  runtime env. Nullary → VVariant value; N-ary → VBuiltin constructor
  function. Previously all enum constructors were "Unbound variable" at
  runtime.
- `interp.ml` — `tea_run` builtin: reads stdin line-by-line, dispatches
  each line as a VVariant Msg to the user's `update` function, prints
  the result of `view`. Clean EOF exit. Full REPL-style TEA loop.
- `value.ml` — `binop_string`: add `OpConcat` (the `++` operator) so
  string concatenation works at runtime. Was falling through to "not
  supported on strings".
- `resolve.ml` — `create_context`: register ALL interpreter builtins
  (int_to_string, tea_run, float_to_string, read_line, etc.) so the
  resolver doesn't reject them as UndefinedVariable.
- `typecheck.ml` — `register_builtins`: add `tea_run` with flexible
  type `∀a. a → unit ! IO`.
- `bin/main.ml` — `eval_file` (both JSON and non-JSON paths): call
  `register_builtins` before type-checking declarations (the eval path
  was skipping this); auto-call `main()` after `eval_program` if main
  is defined in the env.

**Examples (3c + 3d):**
- `examples/counter.afs` — canonical TEA counter: Increment/Decrement/
  Reset messages, affine model, view renders "Count: N"
- `examples/titlescreen.afs` — IDApTIK title screen: TitleModel struct,
  TitleMsg enum (NewGame/LoadGame/Settings/Credits), view renders screen
  dimensions and selected option. Bridge target for Stage 4.

**Tests (5 new, 85 total):**
- counter compiles: frontend + eval_program succeeds
- counter init=0: apply_function counter_init [] returns VInt 0
- counter update transitions: Increment 0→1, Decrement 1→0
- titlescreen compiles: frontend + eval_program succeeds
- titlescreen NewGame→new_game: update sets selected field correctly

Stage 3 done when:
  ✓ counter.afs runs correctly (Increment/Decrement/Reset via stdin)
  ✓ ownership violations caught (Stage 1 QTT enforcement still live)
  ✓ titlescreen.afs compiles and interprets without errors

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

Author: hyperpolymath

bin/main.ml

@@ -240,6 +240,8 @@ let eval_file face json path =
         add (Affinescript.Json_output.of_resolve_error e span)
       | Ok (resolve_ctx, type_ctx) ->
         let type_ctx = { type_ctx with symbols = resolve_ctx.symbols } in
+        (* Register builtins (print, int_to_string, tea_run, etc.) before type-checking *)
+        Affinescript.Typecheck.register_builtins type_ctx;
         (match List.fold_left (fun acc decl ->
           match acc with
           | Error _ as e -> e
@@ -254,7 +256,14 @@ let eval_file face json path =
             add (Affinescript.Json_output.of_quantity_error (err, span))
           | Ok () ->
             (match Affinescript.Interp.eval_program prog with
-            | Ok _env -> ()
+            | Ok env ->
+              (* Auto-call main() if defined — entry point for TEA apps and scripts *)
+              (match Affinescript.Value.lookup_env "main" env with
+              | Ok main_fn ->
+                (match Affinescript.Interp.apply_function main_fn [] with
+                | Ok _ -> ()
+                | Error e -> add (Affinescript.Json_output.of_eval_error e))
+              | Error _ -> ())  (* no main — that's fine, just eval declarations *)
             | Error e ->
               add (Affinescript.Json_output.of_eval_error e)))))
     with
@@ -276,6 +285,8 @@ let eval_file face json path =
         `Error (false, "Resolution error")
       | Ok (resolve_ctx, type_ctx) ->
         let type_ctx = { type_ctx with symbols = resolve_ctx.symbols } in
+        (* Register builtins (print, int_to_string, tea_run, etc.) before type-checking *)
+        Affinescript.Typecheck.register_builtins type_ctx;
         (match List.fold_left (fun acc decl ->
           match acc with
           | Error _ as e -> e
@@ -294,9 +305,20 @@ let eval_file face json path =
             `Error (false, "Quantity error")
           | Ok () ->
             (match Affinescript.Interp.eval_program prog with
-            | Ok _env ->
-              Format.printf "Program executed successfully@.";
-              `Ok ()
+            | Ok env ->
+              (* Auto-call main() if defined — entry point for TEA apps and scripts *)
+              (match Affinescript.Value.lookup_env "main" env with
+              | Ok main_fn ->
+                (match Affinescript.Interp.apply_function main_fn [] with
+                | Ok _ -> `Ok ()
+                | Error e ->
+                  Format.eprintf "@[<v>Runtime error: %s@]@."
+                    (Affinescript.Value.show_eval_error e);
+                  `Error (false, "Runtime error"))
+              | Error _ ->
+                (* No main function — declarations evaluated, nothing to run *)
+                Format.printf "Program evaluated successfully@.";
+                `Ok ())
             | Error e ->
               Format.eprintf "@[<v>Runtime error: %s@]@."
                 (Affinescript.Value.show_eval_error e);

examples/counter.afs

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2025-2026 hyperpolymath
+//
+// AffineScript TEA counter — Stage 3c dogfood
+//
+// Demonstrates The Elm Architecture in AffineScript:
+//   - Model is an owned value: each update consumes the old model, produces a new one
+//   - Msg is linear: consumed by update, not reusable
+//   - Cmd carries obligations: None means no side-effects, Log carries a message to handle
+//
+// Run: affinescript eval examples/counter.afs
+//   At the stdin prompt, type one of: Increment  Decrement  Reset
+//   Ctrl-D (EOF) exits cleanly.
+
+// ── Msg ─────────────────────────────────────────────────────────────────────
+// Linear: each message is consumed exactly once by update.
+
+enum CounterMsg {
+  Increment,
+  Decrement,
+  Reset
+}
+
+// ── Cmd ─────────────────────────────────────────────────────────────────────
+// Linear obligation.  None → no effect.  Log(String) → something to handle.
+// Dropping a non-None Cmd at compile time is a quantity violation (Stage 1).
+
+enum CounterCmd {
+  None,
+  Log(String)
+}
+
+// ── init ─────────────────────────────────────────────────────────────────────
+// Produces the initial model.  No commands needed at start-up.
+
+fn counter_init() -> Int {
+  0
+}
+
+// ── update ───────────────────────────────────────────────────────────────────
+// Consumes Msg and old Model; produces new Model plus any commands.
+// The old model is gone after this call — AffineScript enforces this via QTT.
+
+fn counter_update(msg: CounterMsg, model: Int) -> Int {
+  match msg {
+    Increment => model + 1,
+    Decrement => model - 1,
+    Reset     => 0
+  }
+}
+
+// ── view ─────────────────────────────────────────────────────────────────────
+// Borrows the model (read-only), renders a string.
+// Rebuilding the view does not consume the model.
+
+fn counter_view(model: Int) -> String {
+  "Count: " ++ int_to_string(model)
+}
+
+// ── subscriptions ────────────────────────────────────────────────────────────
+// No real-time subscriptions at the interpreter level.
+
+fn counter_subs(model: Int) -> String {
+  "None"
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+// Wire up the TEA runtime and hand off to the interpreter loop.
+
+fn main() -> () {
+  tea_run({
+    init:          counter_init,
+    update:        counter_update,
+    view:          counter_view,
+    subscriptions: counter_subs
+  })
+}

examples/titlescreen.afs

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2025-2026 hyperpolymath
+//
+// AffineScript TEA TitleScreen — Stage 3d dogfood
+//
+// IDApTIK title screen in AffineScript TEA.
+// This is the bridge target for Stage 4: when the Wasm/JS bridge is done,
+// this exact file compiles to a .wasm that AffineTEA.js drives via PixiJS.
+//
+// Model: screen state (dimensions, music playing, selected option)
+// Msg:   navigation events from the title menu
+// Cmd:   side-effects (BGM, SFX, screen navigation)
+//
+// Run: affinescript eval examples/titlescreen.afs
+//   Type: NewGame  LoadGame  Settings  Credits  Ctrl-D to exit
+
+// ── Msg ──────────────────────────────────────────────────────────────────────
+
+enum TitleMsg {
+  NewGame,
+  LoadGame,
+  Settings,
+  Credits
+}
+
+// ── Cmd ──────────────────────────────────────────────────────────────────────
+
+enum TitleCmd {
+  None,
+  PlayBGM(String),
+  PlaySFX(String),
+  Navigate(String)
+}
+
+// ── Model ────────────────────────────────────────────────────────────────────
+
+struct TitleModel {
+  screen_w:   Int,
+  screen_h:   Int,
+  bgm_playing: Int,
+  selected:   String
+}
+
+// ── init ─────────────────────────────────────────────────────────────────────
+
+fn title_init() -> TitleModel {
+  {
+    screen_w:    1280,
+    screen_h:    720,
+    bgm_playing: 0,
+    selected:    "none"
+  }
+}
+
+// ── update ────────────────────────────────────────────────────────────────────
+// Consumes msg and model; returns updated model.
+// In Stage 4, this also emits Cmd(Navigate(...)) which the JS bridge handles.
+
+fn title_update(msg: TitleMsg, model: TitleModel) -> TitleModel {
+  match msg {
+    NewGame  => { screen_w: model.screen_w, screen_h: model.screen_h, bgm_playing: model.bgm_playing, selected: "new_game" },
+    LoadGame => { screen_w: model.screen_w, screen_h: model.screen_h, bgm_playing: model.bgm_playing, selected: "load_game" },
+    Settings => { screen_w: model.screen_w, screen_h: model.screen_h, bgm_playing: model.bgm_playing, selected: "settings" },
+    Credits  => { screen_w: model.screen_w, screen_h: model.screen_h, bgm_playing: model.bgm_playing, selected: "credits" }
+  }
+}
+
+// ── view ─────────────────────────────────────────────────────────────────────
+// Borrows model, renders the title screen state as a string.
+// In Stage 4, this returns Html that the JS bridge applies to the Pixi scene.
+
+fn title_view(model: TitleModel) -> String {
+  "=== IDApTIK ===" ++ "\n" ++
+  "Screen: " ++ int_to_string(model.screen_w) ++ "x" ++ int_to_string(model.screen_h) ++ "\n" ++
+  "Selected: " ++ model.selected
+}
+
+// ── subscriptions ─────────────────────────────────────────────────────────────
+
+fn title_subs(model: TitleModel) -> String {
+  "None"
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
+fn main() -> () {
+  tea_run({
+    init:          title_init,
+    update:        title_update,
+    view:          title_view,
+    subscriptions: title_subs
+  })
+}

lib/interp.ml

@@ -872,6 +872,70 @@ let create_initial_env () : env =
     ("time_now", VBuiltin ("time_now", fun _args ->
       Ok (VFloat (Sys.time ()))
     ));
+
+    (* -- TEA (The Elm Architecture) interpreter runtime -------------------- *)
+    ("tea_run", VBuiltin ("tea_run", fun args ->
+      (* tea_run expects a record with fields: init, update, view, subscriptions.
+         - init        : () -> (Model, [Cmd])
+         - update      : Msg -> Model -> (Model, [Cmd])
+         - view        : Model -> Html    (Html is rendered as a string or shown)
+         - subscriptions: Model -> [Sub]  (unused at interpreter level)
+
+         The interpreter loop:
+           1. Call init() to get the initial model.
+           2. Render and print the initial view.
+           3. Read lines from stdin; each line becomes a variant Msg.
+           4. Call update(msg, model) -> (new_model, cmds).
+           5. Print new view. Repeat until EOF. *)
+      match args with
+      | [VRecord fields] ->
+        let get f = match List.assoc_opt f fields with
+          | Some v -> Ok v
+          | None -> Error (RuntimeError (Printf.sprintf "tea_run: missing field '%s'" f))
+        in
+        let render_html v =
+          let s = match v with
+            | VString s -> s
+            | VVariant ("Text", Some (VString s)) -> s
+            | VVariant ("Node", _) -> "[Html node]"
+            | other -> show_value other
+          in
+          print_endline s
+        in
+        let* init_fn   = get "init"   in
+        let* update_fn = get "update" in
+        let* view_fn   = get "view"   in
+        (* Call init() -> (model, cmds) — 0-param function, no args *)
+        let* init_result = apply_function init_fn [] in
+        let model0 = match init_result with
+          | VTuple (m :: _) -> m
+          | m -> m
+        in
+        (* Render initial view *)
+        let* view0 = apply_function view_fn [model0] in
+        render_html view0;
+        (* Read-eval-print loop: stdin lines become variant Msgs until EOF *)
+        let rec loop model =
+          let input = try Some (read_line ()) with End_of_file -> None in
+          match input with
+          | None -> Ok VUnit  (* EOF — done, clean exit *)
+          | Some "" -> loop model  (* blank line — skip *)
+          | Some line ->
+            let msg = VVariant (String.trim line, None) in
+            let* upd_result = apply_function update_fn [msg; model] in
+            let new_model = match upd_result with
+              | VTuple (m :: _) -> m
+              | m -> m
+            in
+            let* new_view = apply_function view_fn [new_model] in
+            render_html new_view;
+            loop new_model
+        in
+        loop model0
+      | _ ->
+        Error (RuntimeError
+          "tea_run expects a record: {init, update, view, subscriptions}")
+    ));
   ] in
   builtins
 
@@ -892,8 +956,46 @@ let eval_decl (env : env) (decl : top_level) : env result =
     let* v = eval env tc.tc_value in
     Ok (extend_env tc.tc_name.name v env)
 
-  | TopType _ | TopTrait _ | TopImpl _ ->
-    (* Type/trait/impl declarations don't affect the runtime value environment *)
+  | TopType td ->
+    (* Register enum constructors so they can be used as values / constructor functions.
+       Nullary constructors become VVariant values.
+       N-ary constructors become VBuiltin constructor functions. *)
+    begin match td.td_body with
+      | TyEnum variants ->
+        let env' = List.fold_left (fun env (vd : variant_decl) ->
+          let name = vd.vd_name.name in
+          match vd.vd_fields with
+          | [] ->
+            (* Nullary constructor: bind directly as a VVariant value *)
+            extend_env name (VVariant (name, None)) env
+          | [_] ->
+            (* Single-payload constructor: wrap arg in VVariant *)
+            extend_env name
+              (VBuiltin (name, fun args ->
+                match args with
+                | [v] -> Ok (VVariant (name, Some v))
+                | _ -> Error (TypeMismatch (Printf.sprintf "%s expects 1 argument" name))))
+              env
+          | fields ->
+            (* Multi-payload constructor: pack args into a VTuple *)
+            let n = List.length fields in
+            extend_env name
+              (VBuiltin (name, fun args ->
+                if List.length args = n then
+                  Ok (VVariant (name, Some (VTuple args)))
+                else
+                  Error (TypeMismatch
+                    (Printf.sprintf "%s expects %d arguments" name n))))
+              env
+        ) env variants in
+        Ok env'
+      | _ ->
+        (* Struct, alias, and other type declarations don't create runtime bindings *)
+        Ok env
+    end
+
+  | TopTrait _ | TopImpl _ ->
+    (* Trait and impl declarations don't affect the runtime value environment *)
     Ok env
 
   | TopEffect ed ->

lib/resolve.ml

@@ -51,12 +51,32 @@ let create_context () : context =
     imports = [];
     references = [];
   } in
-  (* Register built-in functions *)
-  let _ = Symbol.define ctx.symbols "print" SKFunction Span.dummy Public in
-  let _ = Symbol.define ctx.symbols "println" SKFunction Span.dummy Public in
-  let _ = Symbol.define ctx.symbols "int" SKFunction Span.dummy Public in
-  let _ = Symbol.define ctx.symbols "float" SKFunction Span.dummy Public in
-  let _ = Symbol.define ctx.symbols "sqrt" SKFunction Span.dummy Public in
+  (* Register built-in functions — must match the interpreter's create_initial_env *)
+  let def name = let _ = Symbol.define ctx.symbols name SKFunction Span.dummy Public in () in
+  (* Console I/O *)
+  def "print"; def "println"; def "eprint"; def "eprintln";
+  (* String / char builtins *)
+  def "len"; def "string_get"; def "string_sub"; def "string_find";
+  def "char_to_int"; def "int_to_char"; def "show";
+  def "to_lowercase"; def "to_uppercase"; def "trim";
+  def "int_to_string"; def "float_to_string"; def "string_length";
+  def "parse_int"; def "parse_float";
+  (* Numeric coercions and math *)
+  def "int"; def "float";
+  def "sqrt"; def "cbrt"; def "pow_float"; def "floor"; def "ceil"; def "round";
+  def "abs"; def "max"; def "min";
+  def "sin"; def "cos"; def "tan"; def "atan"; def "atan2";
+  def "exp"; def "log"; def "log10"; def "log2";
+  (* I/O — files, process, environment *)
+  def "read_line"; def "read_file"; def "write_file"; def "append_file";
+  def "file_exists"; def "is_directory";
+  def "getenv"; def "setenv"; def "getcwd"; def "chdir";
+  def "list_dir"; def "create_dir"; def "remove_file"; def "remove_dir";
+  def "panic"; def "exit";
+  (* Time *)
+  def "time_now";
+  (* TEA runtime — The Elm Architecture interpreter loop *)
+  def "tea_run";
   ctx
 
 (** Record a use-site reference for a symbol (Phase C: find-references). *)