Question & Feature Request: Enabling client_side_replay with framed_replay: false

[KazuhiroAND]

Thank you for developing and maintaining pywb. It is an essential tool for our web archiving operations at the Web Archiving Project (WARP), National Diet Library, Japan (NDL) (https://warp.ndl.go.jp/).

Issue

We encountered a problem where websites using <script type="module"> could not be properly replayed with pywb. Enabling client_side_replay: true (as suggested in #771) resolves the issue.

However, in our testing, client_side_replay mode ( client_side_replay: true ) appeared to work only when framed_replay: true was also set. With framed_replay: false, it did not seem to take effect. We could not find explicit documentation on the relationship between these two options.

Related issue: #771
Docs: client-side-replay

Our Constraint

Due to our system architecture and UI design, we must operate pywb with framed_replay: false. This is a hard constraint that cannot easily be changed on our side.

Question

Is there any way to enable client_side_replay while keeping framed_replay: false? If any configuration or workaround exists, we would appreciate your guidance.

Feature Request

If this is not currently possible, we would like to kindly request that pywb be enhanced to support client_side_replay under framed_replay: false.

This combination would greatly benefit institutions like ours that require frameless replay for architectural reasons while also needing robust support for modern JavaScript features such as ES modules.

Thank you for considering our request.

Environment

pywb version: 2.9.1

[ato]

Implementing the combination of frameless mode with client-side replay would likely be moderately complex. It would first need support added to wabac.js. I also worry about introducing another significant deployment configuration variant and the implications for testing and maintenance.

Due to our system architecture and UI design, we must operate pywb with framed_replay: false. This is a hard constraint that cannot easily be changed on our side.

Is it correct that warp.ndl.go.jp uses a separate application to provide the UI which embeds pywb in an iframe? This seems similar to how the National Library of Australia uses pywb. The NLA configuration overrides banner.html to turn off the pywb Vue.js UI and forward messages to the UI application's top-level frame:

https://github.com/nla/nla-pywb/blob/master/awa/templates/banner.html

I wonder if a similar solution would work for WARP or if there are other reasons you require framed_replay: false specifically.

[KazuhiroAND]

Thank you very much for your detailed and thoughtful response, and for pointing us to the NLA example. It is very helpful to see how other institutions have integrated pywb.

About the WARP Architecture

Your understanding is correct. WARP has its own UI application, which embeds pywb via an iframe. In that sense, our overall structure is similar to NLA’s approach.

Why We Need framed_replay: false

There are two main reasons specific to our environment:

1. Complex access control requirements

At NDL, access to content is subject to fine-grained access control based on various statuses. We determined that pywb’s standard banner UI would not be sufficient to express and enforce these controls, which is why we implemented our own UI layer on top of pywb.

2. URL routing across a very large number of collections

WARP is built on top of over 7,000 pywb collections. The combined CDXJ index across all collections contains approximately 15 billion lines. To handle this scale, we designed a URL scheme of the form /web/{timestamp}/{URL}, and our UI application dynamically determines the appropriate collection to serve based on the timestamp before delegating to pywb. This routing logic sits in our UI application, not in pywb itself.

For these reasons, NDL uses framed_replay: false.

On the NLA-style Approach

Thank you for suggesting the banner.html override + postMessage forwarding approach used by NLA. We will investigate internally whether this pattern can be adapted to our environment while satisfying the constraints described above. We will report back with our findings.

Thank you again for your time and for the very constructive discussion.