feat(stdlib): @pixi/ui binding (bindings #3) (#435)

## Summary

Adds an MVP `@pixi/ui` binding (`stdlib/PixiUI.affine` + Deno-ESM
codegen lowerings) so idaptik's HUD + menu layer
(`src/bindings/PixiUI.res`) can move off ReScript. Follows the pattern
proven by wasmCall (#422) / motion (#422 bundle) / Pixi (#429 open).

Row #3 in `docs/bindings-roadmap.adoc` moves `○` -> `◐` scaffold.

## Surface

- 5 opaque host types: `Button`, `FancyButton`, `Slider`, `Switch`,
`Container` (re-declared opaque so this module can be consumed without a
hard dependency on `stdlib/Pixi.affine`).
- 11 extern fns: ctor + primary event-callback registrar + zero-cost
`AsContainer` upcast for each component.
- 11 `__as_pixiUi*` runtime helpers + `deno_builtins` table entries in
`lib/codegen_deno.ml`.
- Consumer sets `globalThis.__as_pixi_ui = PixiUI` once at module-init.

## Deferred (follow-ups)

- `Input` (text-entry + focus + value)
- `ScrollBox` (scroll position + viewport)
- Full event surface (onHover / onOut / onDown / onUp)
- FancyButton textures-per-state, Slider min/max/step accessors

## Test plan

- [x] `dune build bin/main.exe` clean
- [x] `bash tools/run_codegen_deno_tests.sh` — 9/9 harnesses green (was
8/8; +pixiui_smoke with 17 assertions)
- [x] All new files MPL-2.0 SPDX; no `.as` / AGPL / PMPL
- [ ] Hypatia security scan: no new findings (delta-only — pre-existing
baselines ignored per repo CLAUDE.md)

Note: pre-existing flaky E2E Node-CJS Codegen tests #4/#5 unrelated.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

docs/bindings-roadmap.adoc

@@ -61,9 +61,9 @@ no further significant ReScript → AffineScript work is tractable.
 
 |3
 |*@pixi/ui* (Button, FancyButton, Switch, Slider, Input, ScrollBox)
-|`○`
-|`affinescript-pixijs` sub-module
-|idaptik `src/bindings/PixiUI.res`; all HUD / menu code.
+|`◐` scaffold
+|`stdlib/PixiUI.affine` (eventual home: `affinescript-pixijs` sub-module)
+|idaptik `src/bindings/PixiUI.res`; all HUD / menu code. MVP surface (Button / FancyButton / Slider / Switch — `new` + primary callback + `AsContainer` upcast) lives in `stdlib/` alongside Pixi / PixiSound; consumer provides `globalThis.__as_pixi_ui` at module-init time. Test fixture: `tests/codegen-deno/pixiui_smoke.{affine,harness.mjs}`. Deferred follow-ups: Input (text-entry + focus + value), ScrollBox (scroll position + viewport), full event surface (onHover / onOut / onDown / onUp), FancyButton textures-per-state accessors, Slider min/max/step accessors.
 
 |4
 |*motion* (animate, animateMini, tween, ease, spring)

lib/codegen_deno.ml

@@ -208,6 +208,28 @@ const __as_pixiTextAsContainer = (t) => t;
 const __as_pixiTickerAdd = (t, cb) => { t.add(cb); return 0; };
 const __as_pixiTickerStart = (t) => { t.start(); return 0; };
 const __as_pixiTickerStop = (t) => { t.stop(); return 0; };
+// ---- @pixi/ui (bindings #3): consumer-provided import ----
+// Host JS environment exposes globalThis.__as_pixi_ui (the namespace
+// from `import * as PixiUI from "@pixi/ui"`). Tests set it in the
+// harness before importing the generated module; production
+// consumers typically do once at module-init time. The
+// AffineScript-side externs (stdlib/PixiUI.affine) don't see this
+// indirection — they call __as_pixiUi* helpers directly.
+//
+// Upcasts to Container are identity — @pixi/ui's Button /
+// FancyButton / Slider / Switch are all real PIXI.Container
+// subclasses, so the JS object is the same.
+const __as_pixiUiButtonNew         = (options) => new globalThis.__as_pixi_ui.Button(options);
+const __as_pixiUiButtonOnPress     = (b, cb)   => { b.onPress.connect(cb); return 0; };
+const __as_pixiUiButtonAsContainer = (b)       => b;
+const __as_pixiUiFancyButtonNew         = (options) => new globalThis.__as_pixi_ui.FancyButton(options);
+const __as_pixiUiFancyButtonAsContainer = (b)       => b;
+const __as_pixiUiSliderNew         = (options) => new globalThis.__as_pixi_ui.Slider(options);
+const __as_pixiUiSliderOnUpdate    = (s, cb)   => { s.onUpdate.connect(cb); return 0; };
+const __as_pixiUiSliderAsContainer = (s)       => s;
+const __as_pixiUiSwitchNew         = (options) => new globalThis.__as_pixi_ui.Switch(options);
+const __as_pixiUiSwitchOnChange    = (sw, cb)  => { sw.onChange.connect(cb); return 0; };
+const __as_pixiUiSwitchAsContainer = (sw)      => sw;
 // `++` is overloaded (string concat / array concat); `a + b` would
 // stringify arrays. Dispatch on shape so stdlib/string.affine's
 // `result ++ [x]` and `a ++ b` are both correct.
@@ -383,6 +405,18 @@ let () =
   b "pixiTickerAdd"            (fun a -> Printf.sprintf "__as_pixiTickerAdd(%s, %s)" (arg 0 a) (arg 1 a));
   b "pixiTickerStart"          (fun a -> Printf.sprintf "__as_pixiTickerStart(%s)" (arg 0 a));
   b "pixiTickerStop"           (fun a -> Printf.sprintf "__as_pixiTickerStop(%s)" (arg 0 a));
+  (* ---- @pixi/ui (bindings #3) ---- *)
+  b "pixiUiButtonNew"              (fun a -> Printf.sprintf "__as_pixiUiButtonNew(%s)" (arg 0 a));
+  b "pixiUiButtonOnPress"          (fun a -> Printf.sprintf "__as_pixiUiButtonOnPress(%s, %s)" (arg 0 a) (arg 1 a));
+  b "pixiUiButtonAsContainer"      (fun a -> Printf.sprintf "__as_pixiUiButtonAsContainer(%s)" (arg 0 a));
+  b "pixiUiFancyButtonNew"         (fun a -> Printf.sprintf "__as_pixiUiFancyButtonNew(%s)" (arg 0 a));
+  b "pixiUiFancyButtonAsContainer" (fun a -> Printf.sprintf "__as_pixiUiFancyButtonAsContainer(%s)" (arg 0 a));
+  b "pixiUiSliderNew"              (fun a -> Printf.sprintf "__as_pixiUiSliderNew(%s)" (arg 0 a));
+  b "pixiUiSliderOnUpdate"         (fun a -> Printf.sprintf "__as_pixiUiSliderOnUpdate(%s, %s)" (arg 0 a) (arg 1 a));
+  b "pixiUiSliderAsContainer"      (fun a -> Printf.sprintf "__as_pixiUiSliderAsContainer(%s)" (arg 0 a));
+  b "pixiUiSwitchNew"              (fun a -> Printf.sprintf "__as_pixiUiSwitchNew(%s)" (arg 0 a));
+  b "pixiUiSwitchOnChange"         (fun a -> Printf.sprintf "__as_pixiUiSwitchOnChange(%s, %s)" (arg 0 a) (arg 1 a));
+  b "pixiUiSwitchAsContainer"      (fun a -> Printf.sprintf "__as_pixiUiSwitchAsContainer(%s)" (arg 0 a));
   (* Generic JS array push helper (returns the array, fluent). *)
   b "arrayPush" (fun a -> Printf.sprintf "(%s.push(%s), %s)" (arg 0 a) (arg 1 a) (arg 0 a));
   (* ---- honest string/number primitives underpinning the

stdlib/PixiUI.affine

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MPL-2.0
+// SPDX-FileCopyrightText: 2026 hyperpolymath
+//
+// PixiUI.affine — bindings for the `@pixi/ui` v2.x npm library
+// (bindings #3 in docs/bindings-roadmap.adoc).
+//
+// `@pixi/ui` provides interactive UI components built on top of
+// PixiJS — Button, FancyButton, Switch, Slider, Input, ScrollBox.
+// Reference consumer: idaptik's `src/bindings/PixiUI.res`, the
+// HUD + menu layer over the core PixiJS scene graph.
+//
+// MVP coverage (this version): Button, FancyButton, Slider, Switch
+// constructors + their typical event callback + the upcast to
+// `Container` (so a UI component can be added to the PixiJS scene
+// graph via `Pixi::pixiContainerAddChild`).
+//
+// Deferred (follow-ups):
+//   - Input  — text-entry, focus, blur, value accessor
+//   - ScrollBox — scroll position, content add/remove, viewport
+//   - Full event surface (onHover / onOut / onDown / onUp)
+//   - FancyButton style accessors (textures per state)
+//   - Slider min/max/step accessors
+//
+// Targets the Deno-ESM backend. Consumer (or its host wrapper) sets
+// `globalThis.__as_pixi_ui` to the `@pixi/ui` namespace at module-
+// init time:
+//
+//   import * as PixiUI from "@pixi/ui";
+//   globalThis.__as_pixi_ui = PixiUI;
+//
+// Tests mock the same shape — see `tests/codegen-deno/pixiui_smoke.*`.
+//
+// @pixi/ui type hierarchy: Button, FancyButton, Slider, Switch are
+// all `Container` subclasses (via PixiJS). AffineScript has no
+// subtype polymorphism, so the binding exposes explicit upcast
+// functions (`pixiUiButtonAsContainer`, etc.). These are zero-cost
+// identity lowerings; the underlying JS value is the same object.
+// The `Container` type is re-declared as an opaque extern here for
+// parity with `stdlib/Pixi.affine` — the JS-side handle for the two
+// is identical (a PIXI.Container instance).
+
+module PixiUI;
+
+use Deno::{Json};
+
+// ── Opaque host types ──────────────────────────────────────────────
+//
+// Each maps to its same-named `@pixi/ui` class. They're treated
+// opaquely at the AS boundary; the only consumer-visible operations
+// are construction, callback registration, and upcast to Container.
+
+pub extern type Button;
+pub extern type FancyButton;
+pub extern type Slider;
+pub extern type Switch;
+
+/// `PIXI.Container` — re-declared as opaque extern so this module can
+/// be consumed without a hard dependency on `stdlib/Pixi.affine`.
+/// When both modules are imported, the underlying JS values coincide
+/// (both resolve to the same `PIXI.Container` host class), so a
+/// container produced here can be added as a child of an
+/// `Application.stage` from `Pixi.affine` with no further marshalling.
+pub extern type Container;
+
+// ── Button ─────────────────────────────────────────────────────────
+
+/// `new PixiUI.Button(options)`.
+/// `options` is the @pixi/ui Button-options JSON (typically `{ view }`
+/// where `view` is a PIXI display object).
+pub extern fn pixiUiButtonNew(options: Json) -> Button;
+
+/// `button.onPress.connect(callback)` — register a press-event
+/// handler. `callback` crosses the boundary as opaque `Json` (the
+/// host-side JS function value). Returns 0.
+pub extern fn pixiUiButtonOnPress(b: Button, callback: Json) -> Int;
+
+/// Upcast a Button to its Container superclass. Zero-cost identity
+/// lowering — the underlying JS value is the same object.
+pub extern fn pixiUiButtonAsContainer(b: Button) -> Container;
+
+// ── FancyButton ────────────────────────────────────────────────────
+
+/// `new PixiUI.FancyButton(options)`. `options` is the @pixi/ui
+/// FancyButton-options JSON (text + textures-per-state + padding).
+pub extern fn pixiUiFancyButtonNew(options: Json) -> FancyButton;
+
+/// Upcast a FancyButton to its Container superclass. Zero-cost
+/// identity lowering.
+pub extern fn pixiUiFancyButtonAsContainer(b: FancyButton) -> Container;
+
+// ── Slider ─────────────────────────────────────────────────────────
+
+/// `new PixiUI.Slider(options)`. `options` is the @pixi/ui
+/// Slider-options JSON (min/max/value/bg/fill/slider textures).
+pub extern fn pixiUiSliderNew(options: Json) -> Slider;
+
+/// `slider.onUpdate.connect(callback)` — register a value-change
+/// handler. Callback receives the new value (number). Returns 0.
+pub extern fn pixiUiSliderOnUpdate(s: Slider, callback: Json) -> Int;
+
+/// Upcast a Slider to its Container superclass. Zero-cost identity
+/// lowering.
+pub extern fn pixiUiSliderAsContainer(s: Slider) -> Container;
+
+// ── Switch ─────────────────────────────────────────────────────────
+
+/// `new PixiUI.Switch(options)`. `options` is the @pixi/ui
+/// Switch-options JSON (textures + value).
+pub extern fn pixiUiSwitchNew(options: Json) -> Switch;
+
+/// `switch.onChange.connect(callback)` — register a state-change
+/// handler. Returns 0.
+pub extern fn pixiUiSwitchOnChange(sw: Switch, callback: Json) -> Int;
+
+/// Upcast a Switch to its Container superclass. Zero-cost identity
+/// lowering.
+pub extern fn pixiUiSwitchAsContainer(sw: Switch) -> Container;

tests/codegen-deno/pixiui_smoke.affine

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MPL-2.0
+// bindings #3 — @pixi/ui smoke test.
+//
+// The harness mocks globalThis.__as_pixi_ui before importing the
+// generated module; this fixture exercises construction, callback
+// registration, and upcast → Container for each MVP component.
+
+use Deno::{Json};
+use PixiUI::{Button, FancyButton, Slider, Switch, Container, pixiUiButtonNew, pixiUiButtonOnPress, pixiUiButtonAsContainer, pixiUiFancyButtonNew, pixiUiFancyButtonAsContainer, pixiUiSliderNew, pixiUiSliderOnUpdate, pixiUiSliderAsContainer, pixiUiSwitchNew, pixiUiSwitchOnChange, pixiUiSwitchAsContainer};
+
+pub fn smokeButton(options: Json, callback: Json) -> Container {
+  let b = pixiUiButtonNew(options);
+  pixiUiButtonOnPress(b, callback);
+  pixiUiButtonAsContainer(b)
+}
+
+pub fn smokeFancyButton(options: Json) -> Container {
+  let fb = pixiUiFancyButtonNew(options);
+  pixiUiFancyButtonAsContainer(fb)
+}
+
+pub fn smokeSlider(options: Json, callback: Json) -> Container {
+  let s = pixiUiSliderNew(options);
+  pixiUiSliderOnUpdate(s, callback);
+  pixiUiSliderAsContainer(s)
+}
+
+pub fn smokeSwitch(options: Json, callback: Json) -> Container {
+  let sw = pixiUiSwitchNew(options);
+  pixiUiSwitchOnChange(sw, callback);
+  pixiUiSwitchAsContainer(sw)
+}

tests/codegen-deno/pixiui_smoke.harness.mjs

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MPL-2.0
+// bindings #3 — Node ESM harness for the @pixi/ui binding.
+//
+// Installs a globalThis.__as_pixi_ui mock covering Button /
+// FancyButton / Slider / Switch, drives the smoke functions, and
+// asserts every constructor + callback registration + upcast was
+// observed. Upcasts are identity at the JS level (the @pixi/ui
+// classes are PIXI.Container subclasses); the harness mirrors that.
+
+import assert from "node:assert/strict";
+
+const ctorCalls = { Button: [], FancyButton: [], Slider: [], Switch: [] };
+const onPressRegs = [];
+const onUpdateRegs = [];
+const onChangeRegs = [];
+
+// `Signal`-ish stub matching the @pixi/ui event surface
+// (`button.onPress.connect(cb)`). Records every registered callback
+// into the sink array passed in at construction time.
+class MockSignal {
+  constructor(sink) { this._sink = sink; }
+  connect(cb) { this._sink.push(cb); }
+}
+
+class MockButton {
+  constructor(options) {
+    ctorCalls.Button.push(options);
+    this.onPress = new MockSignal(onPressRegs);
+  }
+}
+
+class MockFancyButton {
+  constructor(options) {
+    ctorCalls.FancyButton.push(options);
+  }
+}
+
+class MockSlider {
+  constructor(options) {
+    ctorCalls.Slider.push(options);
+    this.onUpdate = new MockSignal(onUpdateRegs);
+  }
+}
+
+class MockSwitch {
+  constructor(options) {
+    ctorCalls.Switch.push(options);
+    this.onChange = new MockSignal(onChangeRegs);
+  }
+}
+
+globalThis.__as_pixi_ui = {
+  Button: MockButton,
+  FancyButton: MockFancyButton,
+  Slider: MockSlider,
+  Switch: MockSwitch,
+};
+
+const { smokeButton, smokeFancyButton, smokeSlider, smokeSwitch } =
+  await import("./pixiui_smoke.deno.js");
+
+// ── Button: ctor + onPress + upcast ────────────────────────────────
+const buttonPressCb = () => "pressed";
+const buttonContainer = smokeButton({ text: "OK" }, buttonPressCb);
+assert.equal(ctorCalls.Button.length, 1, "Button ctor called once");
+assert.deepEqual(ctorCalls.Button[0], { text: "OK" }, "Button options reach host");
+assert.equal(onPressRegs.length, 1, "onPress.connect called once");
+assert.equal(onPressRegs[0], buttonPressCb, "onPress callback identity preserved");
+assert.ok(buttonContainer instanceof MockButton, "Button upcast is identity (still MockButton)");
+
+// ── FancyButton: ctor + upcast ─────────────────────────────────────
+const fancyContainer = smokeFancyButton({ text: "Start", padding: 8 });
+assert.equal(ctorCalls.FancyButton.length, 1, "FancyButton ctor called once");
+assert.deepEqual(ctorCalls.FancyButton[0], { text: "Start", padding: 8 }, "FancyButton options reach host");
+assert.ok(fancyContainer instanceof MockFancyButton, "FancyButton upcast is identity");
+
+// ── Slider: ctor + onUpdate + upcast ───────────────────────────────
+const sliderUpdateCb = (v) => v * 2;
+const sliderContainer = smokeSlider({ min: 0, max: 100, value: 50 }, sliderUpdateCb);
+assert.equal(ctorCalls.Slider.length, 1, "Slider ctor called once");
+assert.deepEqual(ctorCalls.Slider[0], { min: 0, max: 100, value: 50 }, "Slider options reach host");
+assert.equal(onUpdateRegs.length, 1, "onUpdate.connect called once");
+assert.equal(onUpdateRegs[0], sliderUpdateCb, "onUpdate callback identity preserved");
+assert.ok(sliderContainer instanceof MockSlider, "Slider upcast is identity");
+
+// ── Switch: ctor + onChange + upcast ───────────────────────────────
+const switchChangeCb = (state) => !state;
+const switchContainer = smokeSwitch({ value: false }, switchChangeCb);
+assert.equal(ctorCalls.Switch.length, 1, "Switch ctor called once");
+assert.deepEqual(ctorCalls.Switch[0], { value: false }, "Switch options reach host");
+assert.equal(onChangeRegs.length, 1, "onChange.connect called once");
+assert.equal(onChangeRegs[0], switchChangeCb, "onChange callback identity preserved");
+assert.ok(switchContainer instanceof MockSwitch, "Switch upcast is identity");
+
+console.log("pixiui_smoke.harness.mjs OK");