Add ready handshake to framecast

[avigoldman]

Summary

Every consumer of framecast that uses srcdoc iframes needs to build their own ready handshake — the parent needs to know when the iframe's script has set up its framecast listener before sending messages. This PR adds built-in support so consumers don't have to reinvent this pattern.

Changes

Adds two new methods to the Framecast class:

signalReady() (iframe side)

• Registers a __framecast_ready function handler that responds with true
• Proactively broadcasts a { type: '__framecast_ready' } message

waitForReady(options?) (parent side)

• Returns a Promise<void> that resolves when the other side is ready
• Uses two strategies for robustness:
  1. Polling — repeatedly calls the __framecast_ready function at a configurable interval (default 50ms)
  2. Listening — listens for the proactive ready broadcast
• Resolves as soon as either strategy succeeds
• Options: interval (default 50ms), timeout (default 10s, 0 to disable)

Tests

7 new tests covering:

• signalReady registers handler and broadcasts
• signalReady responds to ready-check function calls
• waitForReady resolves on broadcast
• waitForReady resolves on successful function call poll
• waitForReady times out correctly
• waitForReady with timeout: 0 never times out
• Full end-to-end handshake with wired parent ↔ iframe pair

Linear-issue: CON-6607

[changeset-bot]

🦋 Changeset detected

Latest commit: 7648b6d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@ciolabs/framecast	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR