feat(qr-modal): add preventIframe option + improve fallback behaviour

[harshajain6114]

Description

Adds support for a new preventIframe modal option that disables opening the QR modal when the SDK is running inside an iframe.
This improves SDK behavior for embedded apps, dashboards, widgets, and hosted integrations.

Changes included:

• Added preventIframe to ModalOptions type
• Added iframe detection + conditional modal block in modalUtils.ts
• Updated README documentation with usage example and explanation

---

Testing (ignore for documentation update)

• Tested iframe detection using a local HTML iframe wrapper
• When preventIframe: true, the modal no longer renders
• When unset or false, normal modal behavior continues
• Verified no regression in QR flow, extension flow, or mobile redirects
• Verified TypeScript builds successfully

---

Type of change

• [ ] Bug fix
• [x] New feature
• [ ] Breaking change
• [x] Documentation update

---

Checklist:

• [x] I have read and agree to the Code of Conduct.
• [x] I have signed the Contributor License Agreement (CLA).
• [x] I have considered the Security Policy.
• [x] I have self-reviewed and tested my code.
• [x] I have updated documentation as needed.
• [x] I agree to the project's custom license.

---

Additional Notes:

This enhancement ensures developers embedding the SDK inside external platforms have better control over modal behavior in restricted iframe environments.

---

[!NOTE] Adds a preventIframe modal option and iframe detection to block the QR modal inside iframes, plus safer modal lifecycle; updates README with usage.

• SDK / Modal:
  • Add preventIframe to ModalOptions in src/utils/types.ts.
  • In QRCodeModal.show() (src/utils/modalUtils.ts):
    • Always close any existing modal before rendering.
    • Detect iframe context; if preventIframe is true, log, invoke onClose, and skip rendering.
• Docs:
  • Update README.md with a new preventIframe section and usage example.

^{Written by Cursor Bugbot for commit 74902a07cb1afedeba7df50c3a6e6dedac19ed12. This will update automatically on new commits. Configure here.}

Summary by CodeRabbit

• New Features

  • Added an optional preventIframe modal option to stop the QR modal from opening when running inside an iframe.

• Improvements

  • Modal now reliably closes any existing modal before opening, reorders initialization steps, and includes safer iframe checks.
  • Enhanced error handling and more predictable auto-close behavior.

• Documentation

  • README updated with an example showing how to use the preventIframe option.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[CLAassistant]

All committers have signed the CLA.

[coderabbitai[bot]]

[!NOTE]

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Adds an optional preventIframe boolean to modal options and updates the modal show flow to close any existing modal, check iframe/security when preventIframe is set (log and call onClose then return on detection/error), then proceed to insert DOM, generate QR, register listeners, and start the auto-close timer.

Changes

Cohort / File(s)	Summary
Documentation README.md	Documented new preventIframe option for ReclaimProofRequest.setModalOptions with a TypeScript example showing preventIframe: true.
Modal Type Definitions src/utils/types.ts	Added optional property preventIframe?: boolean to ModalOptions.
Modal UI Logic src/utils/modalUtils.ts	Always closes existing modal first; if preventIframe is true, checks for iframe or security error, logs and calls onClose (if provided) then returns early; otherwise inserts modal HTML, generates QR, adds listeners, starts auto-close timer; core flow wrapped in try-catch with logging.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant Modal as QRCodeModal
    participant DOM
    participant QR as QRGenerator

    Caller->>Modal: show(requestUrl)

    Modal->>DOM: Close existing modal (if any)

    alt preventIframe enabled
        Modal->>Modal: Check "in iframe" (may throw SecurityError)
        alt inside iframe or error
            Modal->>Modal: Log info
            Modal->>Caller: invoke onClose (optional)
            Modal-->>Caller: return early
        end
    end

    Modal->>DOM: Insert modal HTML
    Modal->>QR: Generate QR into modal
    QR-->>DOM: Render QR
    Modal->>DOM: Add event listeners
    Modal->>Modal: Start auto-close timer
    Modal-->>Caller: resolve show()

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Pay attention to iframe detection/security error handling in src/utils/modalUtils.ts.
• Verify try-catch logging doesn't mask actionable errors and that timer lifecycle (start/clear) is correctly managed.
• Confirm preventIframe?: boolean is backward-compatible and appropriately typed where ModalOptions is consumed.

Possibly related PRs

• reclaimprotocol/reclaim-js-sdk#45 — Related edits to ModalOptions and modal behavior surface.
• reclaimprotocol/reclaim-js-sdk#33 — Prior work on modal flow and QR modal lifecycle that this change extends.
• reclaimprotocol/reclaim-js-sdk#59 — Other changes touching modalOptions handling and modal UI logic.

Suggested reviewers

• Sajjad21990
• Karam19
• Kushal7788

Poem

🐰 I peek where frames might hide the light,
I check the frame and choose what's right—
If trapped within an iframe's seam,
I close my door and skip the gleam,
I hop away with code so bright.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main changes: adding a preventIframe option to the QR modal and improving modal behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

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.}