feat(stdlib): motion library binding — animate / await / cancel (bindings #4)

Lands the first tranche of the bindings-roadmap #4 (motion) item:
animate, awaitable handle, and cancel. Surface mirrors the Http /
Sqlite / Crypto stdlib pattern.

Also bundles bindings #5 (wasmCall) which has been waiting on CI in
PR #419 — same codegen_deno.ml runtime helper + lowering, plus the
test fixture under tests/codegen-deno/wasm_call.* (already merged via
#410 era; not duplicated here). Superseding PR #419 keeps the
codegen_deno.ml history linear and avoids a parallel-edit merge knot.

Files:
- stdlib/Motion.affine — extern type AnimationControls + 3 extern fns
- lib/codegen_deno.ml — __as_motion* runtime helpers + lowering
  entries; __as_wasmCall helper restored
- tests/codegen-deno/motion_smoke.{affine,harness.mjs} — round-trip
  fixture with a mocked globalThis.__as_motion
- docs/bindings-roadmap.adoc — row #4 status ○ → ◐ scaffold

Test plan: all 7 codegen-deno harnesses green, incl. the new
motion_smoke (4 assertions: target/keyframes/options pass-through,
cancel side-effect, no-op cancel on bare object).

Consumer responsibility: production code must set
globalThis.__as_motion = motionLibrary (or compatible mock) at module
init. Documented in stdlib/Motion.affine's preamble.

Follow-ups (deferred, tracked in row #4 rationale):
- animateMini, tween, ease, spring
- typed keyframe shapes (currently opaque Json)
- migrate to dedicated affinescript-motion package (additive, source-
  compatible)

Refs #414 (closes via the wasmCall bundle), bindings #4 in
docs/bindings-roadmap.adoc.

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

Author: hyperpolymath

docs/bindings-roadmap.adoc

@@ -67,9 +67,9 @@ no further significant ReScript → AffineScript work is tractable.
 
 |4
 |*motion* (animate, animateMini, tween, ease, spring)
-|`○`
-|`affinescript-motion`
-|idaptik `src/bindings/Motion.res`; player + UI transitions.
+|`◐` scaffold (animate / await / cancel landed)
+|`stdlib/Motion.affine` (eventual home: `affinescript-motion`)
+|idaptik `src/bindings/Motion.res`; player + UI transitions. Initial surface (`motionAnimate` / `motionAwait` / `motionCancel`) lands in `stdlib/` parallel to Http / Sqlite / Crypto; consumer provides `globalThis.__as_motion` at module-init time. Test fixture: `tests/codegen-deno/motion_smoke.{affine,harness.mjs}`. Follow-ups: `animateMini`, `tween`, `ease`, `spring`, typed keyframe shapes.
 
 |5
 |*WASM-exports calling pattern* — invoke individual `exports.fn_name(args)` from a `WasmExports` value

lib/codegen_deno.ml

@@ -157,6 +157,22 @@ const __as_readDirNames = (p) => {
 const __as_isNotFound = (e) => (e instanceof Deno.errors.NotFound);
 const __as_wasmInstance = (bytes) =>
   new WebAssembly.Instance(new WebAssembly.Module(bytes)).exports;
+const __as_wasmCall = (exports, name, args) => Number(exports[name](...(args || [])));
+// ---- motion (bindings #4): consumer-provided import ----
+// Host JS environment must expose globalThis.__as_motion (the motion
+// library or a compatible mock). Tests set it in the harness before
+// importing the generated module; production consumers typically do
+// `import * as m from "motion"; globalThis.__as_motion = m;` once at
+// module-init time. The AffineScript-side externs (stdlib/Motion.affine)
+// don't see this indirection — they call __as_motion* helpers directly.
+const __as_motionAnimate = (target, keyframes, options) =>
+  globalThis.__as_motion.animate(target, keyframes, options);
+const __as_motionAwait = (controls) =>
+  Promise.resolve(controls).then(() => 0);
+const __as_motionCancel = (controls) => {
+  if (controls && typeof controls.cancel === "function") controls.cancel();
+  return 0;
+};
 // `++` 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.
@@ -250,6 +266,11 @@ let () =
   (* ---- misc host ---- *)
   b "dateNow"     (fun _ -> "Date.now()");
   b "wasmInstance" (fun a -> Printf.sprintf "__as_wasmInstance(%s)" (arg 0 a));
+  b "wasmCall"     (fun a -> Printf.sprintf "__as_wasmCall(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a));
+  (* ---- motion (bindings #4) ---- *)
+  b "motionAnimate" (fun a -> Printf.sprintf "__as_motionAnimate(%s, %s, %s)" (arg 0 a) (arg 1 a) (arg 2 a));
+  b "motionAwait"   (fun a -> Printf.sprintf "(await __as_motionAwait(%s))" (arg 0 a));
+  b "motionCancel"  (fun a -> Printf.sprintf "__as_motionCancel(%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/Motion.affine

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MPL-2.0
+// SPDX-FileCopyrightText: 2026 hyperpolymath
+//
+// Motion.affine — bindings for the `motion` npm library (bindings #4
+// in docs/bindings-roadmap.adoc).
+//
+// Provides a typed surface over motion's `animate()` for tween / spring
+// animations. Targets the Deno-ESM backend; the consumer (or its host
+// wrapper) is responsible for putting the motion library at
+// `globalThis.__as_motion` before any generated module that uses these
+// externs runs. The test harness pattern is in
+// `tests/codegen-deno/motion_smoke.harness.mjs`.
+//
+// This file lives in `stdlib/` for parity with Http / Sqlite / Crypto.
+// The dedicated `affinescript-motion` package home flagged in the
+// bindings roadmap is the long-term destination; the migration from
+// here to there is additive and source-compatible.
+//
+// Surface coverage in this version: `animate` (with await + cancel).
+// Follow-ups (deferred): `animateMini`, `tween`, `ease`, `spring`,
+// keyframe-typing, transform-property typing. Status row in
+// `docs/bindings-roadmap.adoc` (#4) updates with each coverage tranche.
+
+module Motion;
+
+// `Json` from stdlib/Deno.affine is the estate's opaque-host-value
+// type. We reuse it rather than declaring a parallel hierarchy of
+// Element / Keyframes / AnimationOptions — typed shapes for those
+// are tracked separately under the `affinescript-motion` follow-up.
+use Deno::{Json};
+
+// Opaque handle to an in-flight motion animation. Underlying value is
+// a motion `AnimationPlaybackControls` — thenable + `.cancel()`.
+// Treated opaquely at the AS boundary.
+pub extern type AnimationControls;
+
+/// `motion.animate(target, keyframes, options) -> AnimationPlaybackControls`.
+///
+/// `target`, `keyframes`, and `options` cross the boundary as opaque
+/// `Json`. The runtime helper forwards them unchanged to the
+/// host-provided motion library.
+pub extern fn motionAnimate(
+  target: Json,
+  keyframes: Json,
+  options: Json
+) -> AnimationControls;
+
+/// Wait for an animation to finish (or be cancelled). Returns 0 on
+/// completion. Lowers to `await Promise.resolve(controls).then(...)`,
+/// so a controls value whose underlying promise rejects will surface
+/// here as a JS exception — consumers wanting Result semantics should
+/// wrap in `try`/`catch` at the call site.
+pub extern fn motionAwait(controls: AnimationControls) -> Int / { Async };
+
+/// `controls.cancel()` — force-cancel an in-flight animation.
+/// Returns 0. A controls value without a `.cancel` method (e.g. a
+/// mock) is treated as already-cancelled; this is a no-op return 0.
+pub extern fn motionCancel(controls: AnimationControls) -> Int;

tests/codegen-deno/motion_smoke.affine

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MPL-2.0
+// bindings #4 — Motion library smoke test.
+//
+// The harness installs a mock at globalThis.__as_motion before
+// importing the generated module; we re-export thin wrappers so the
+// harness can drive `motionAnimate` / `motionCancel` via stable names.
+
+use Deno::{Json};
+use Motion::{AnimationControls, motionAnimate, motionCancel};
+
+pub fn smokeAnimate(target: Json, keyframes: Json, options: Json) -> AnimationControls =
+  motionAnimate(target, keyframes, options);
+
+pub fn smokeCancel(controls: AnimationControls) -> Int =
+  motionCancel(controls);

tests/codegen-deno/motion_smoke.harness.mjs

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MPL-2.0
+// bindings #4 — Node ESM harness for the motion library binding.
+//
+// Installs a globalThis.__as_motion mock before importing the
+// generated module, drives smokeAnimate / smokeCancel, and asserts
+// the arguments + cancel side-effect were observed.
+
+import assert from "node:assert/strict";
+
+let lastAnimateCall = null;
+let cancelCount = 0;
+
+globalThis.__as_motion = {
+  animate(target, keyframes, options) {
+    lastAnimateCall = { target, keyframes, options };
+    return {
+      then(cb) { if (cb) cb(); return this; },
+      cancel() { cancelCount += 1; },
+    };
+  },
+};
+
+const { smokeAnimate, smokeCancel } = await import("./motion_smoke.deno.js");
+
+const controls = smokeAnimate("#player", { x: 100, opacity: 0.5 }, { duration: 1.0 });
+assert.equal(lastAnimateCall.target, "#player", "target reaches host");
+assert.deepEqual(lastAnimateCall.keyframes, { x: 100, opacity: 0.5 }, "keyframes reach host");
+assert.deepEqual(lastAnimateCall.options, { duration: 1.0 }, "options reach host");
+
+assert.equal(smokeCancel(controls), 0, "cancel returns 0");
+assert.equal(cancelCount, 1, "cancel invoked exactly once");
+
+// Cancel a null-controls value is a no-op (mock controls without .cancel)
+assert.equal(smokeCancel({}), 0, "cancel on bare object returns 0");
+assert.equal(cancelCount, 1, "cancel count unchanged for bare object");
+
+console.log("motion_smoke.harness.mjs OK");