fix(core): invoke structured Signal listeners with runtime args before bound args

[cptbtptpbcptdtptp]

Summary

• Flip structured-binding listener invocation order from method(...boundArgs, ...signalArgs) to method(...signalArgs, ...boundArgs), so the event object always sits at index 0.
• Aligns with DOM / Cocos (event, customData) convention — migrated Cocos scripts work without rewriting parameter order.

Background

Cherry-picked from b16d8b5d7 on fix/shaderlab.

Test plan

• 3 new Signal.test.ts cases: arg ordering, event index 0 invariant, once() parity
• All 29 Signal tests pass
• CI green

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Corrected Signal structured binding behavior: runtime arguments now properly precede bound arguments during method invocation. The event object remains at index 0, restoring expected argument ordering for handlers using bound arguments.

• Tests

  • Added comprehensive test coverage for Signal structured binding, validating correct argument ordering with bound arguments and ensuring single-use listeners maintain expected behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 60db261f-4ddc-4720-a312-4330dbfebe95

📥 Commits

Reviewing files that changed from the base of the PR and between 1bc2b10 and eb8ac58.

📒 Files selected for processing (2)

• packages/core/src/Signal.ts
• tests/src/core/Signal.test.ts

---

Walkthrough

Signal's structured binding listener changes argument order: runtime signal arguments now precede pre-resolved bound arguments when invoking target methods. Implementation, documentation, and test coverage are updated to reflect and validate this new invocation contract.

Changes

Signal Argument Ordering for Structured Binding

Layer / File(s)	Summary
Core Implementation packages/core/src/Signal.ts	Listener wrapper for structured binding now calls target method as target[methodName](...signalArgs, ...args) instead of target[methodName](...args, ...signalArgs).
Documentation packages/core/src/Signal.ts	JSDoc for both on and once structured binding overloads now document that runtime signal arguments are passed first and bound arguments are appended.
Test Infrastructure tests/src/core/Signal.test.ts	TestHandler gains lastArgs field to record received arguments and handleWithArgs(...args) method to support argument ordering validation.
Test Validation tests/src/core/Signal.test.ts	New test cases verify runtime args precede bound args, event object stays at index 0 regardless of bound-arg count, and once preserves argument order for both invocation count and captured arguments.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 Arguments dancing in a line,
Runtime first, then bound ones shine!
Signal whispers, listeners hear,
Order matters, crystal clear! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing structured Signal listeners to invoke with runtime arguments before bound arguments, which aligns with the documentation and code changes in both Signal.ts and the test file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[GuoLei1990]

总结

将 Signal 结构化绑定监听器的调用顺序从 method(...boundArgs, ...signalArgs) 修正为 method(...signalArgs, ...boundArgs)，确保 event 对象始终在 index 0，与 DOM addEventListener / Cocos (event, customData) 约定对齐。

一行改动，三个新测试覆盖 arg ordering、event at index 0 不变量、once() 行为一致性。

无新问题，LGTM。

[GuoLei1990]

总结

将 Signal 结构化绑定监听器的调用顺序从 method(...boundArgs, ...signalArgs) 修正为 method(...signalArgs, ...boundArgs)，使事件对象始终在参数列表第 0 位，与 DOM/Cocos 约定对齐。测试覆盖了顺序验证、事件对象位置不变性、once() 对等性。

修复方向正确，实现最小化。无新问题，可以合并。

[GuoLei1990]

总结

将 structured binding 的参数顺序从 (...args, ...signalArgs) 改为 (...signalArgs, ...args)，与 DOM/Cocos (event, customData) 惯例对齐。修复正确，3 个新测试验证了参数顺序不变量。

问题

[P2] Signal.ts:175 — 更改前代码把 bound args 放前面，这意味着已有用 structured binding 并依赖旧顺序的代码（method(boundArg, event)）会 silently break。PR 描述里没有 migration guide。建议在 CHANGELOG 或 Breaking Changes 里明确标注旧语义。

无阻塞问题，LGTM。

[GuoLei1990]

总结

逻辑修复正确，与 DOM addEventListener 和 Cocos EventTarget 的 (event, customData) 惯例对齐，测试覆盖完整（arg ordering + event index 0 invariant + once parity）。

问题

[P1] Breaking change 需在 CHANGELOG 中标注

使用 structured binding 且传了 bound args 的现有代码（signal.on(component, 'handler', boundArg1)），升级后 handler 收到的参数顺序从 (boundArg1, ...signalArgs) 变为 (...signalArgs, boundArg1)。dev/2.0 允许 breaking changes，但需在 changelog 或 PR 描述中明确标注：旧顺序 (bound, ...runtime) → 新顺序 (...runtime, bound)，以便用户迁移。