Document Picture in Picture API Implementation for Qwik

[mrhoodz]

What is it about?

Providing developers with a simple hook and component-based approach to create floating windows with synchronized styles and state management.

What's the motivation for this proposal?

Problems Im trying to solve:

• Currently, there's no standardized way to implement Chrome's Document Picture-in-Picture API in Qwik applications, leading to inconsistent implementations
• The PIP window starts as a blank slate without styles or scripts, requiring manual synchronization of styles between main and PIP windows
• Managing state and content movement between main window and PIP window is complex and error-prone
• Handling PIP window lifecycle events (enter/exit) requires boilerplate code that could be standardized

Goals Im trying to achieve:

• Provide a simple, declarative API for implementing Picture-in-Picture functionality in Qwik applications
• Automatically handle style synchronization between main window and PIP window
• Create a reusable solution that follows Qwik's performance-first philosophy
• Establish best practices for PIP implementation in Qwik applications

Any other context or information I want to share:

The styling and event listeners issue is particularly challenging because the new PIP window doesn't inherit any <script> or <style> tags from the parent window. This means all styles must be explicitly copied over, including:

• Inline styles
• Stylesheet rules
• Dynamic styles from JavaScript
• Third-party CSS frameworks
• Custom fonts and icons

The current implementation includes a style synchronization solution, but it might need further refinement for edge cases.

---

Proposed Solution / Feature

What do I propose?

A reusable Qwik hook and component implementation for Chrome's Document Picture-in-Picture API that provides a simple, declarative way to create floating windows with synchronized styles and state management. The implementation handles all the complexity of style copying, state management, and event handling through a clean API.

Code examples

// Basic usage
import { component$, useSignal } from "@builder.io/qwik";
import { useDocumentPictureInPicture } from "./document-pip";

export default component$(() => {
  const pipTriggerRef = useSignal<HTMLButtonElement>();
  const { DPIPcomponent } = useDocumentPictureInPicture();

  return (
    <>
      <button ref={pipTriggerRef}>Open Picture-in-Picture</button>
      <DPIPcomponent pipTrigger={pipTriggerRef}>
        <div>Your PIP content here</div>
      </DPIPcomponent>
    </>
  );
});

// Advanced usage with events
export default component$(() => {
  const pipTriggerRef = useSignal<HTMLButtonElement>();
  const { DPIPcomponent, setLeaveEvents, setEnterEvents } = useDocumentPictureInPicture();

  setLeaveEvents($(() => {
    // Handle PIP window close
  }));

  setEnterEvents($(() => {
    // Handle PIP window open
  }));

  return (
    <DPIPcomponent pipTrigger={pipTriggerRef}>
      <div>
        <h2>Complex PIP Content</h2>
        <video controls src="/video.mp4" />
      </div>
    </DPIPcomponent>
  );
});

---

Links / References

For demo of default behavior here

For demo of proposed syntax and behavior here

[wmertens]

I think it would be better to make each window a separate qwik container, no? Then everything would just work.

The DPIPComponent would be an inline component, it would take its children and give them to render, and then inject the generated html into the new window.

Would that work? How would communication happen?

Care must be taken not to pass signals and not to rely on context though. The optimizer must be made aware of this somehow so it doesn't forward signals.

[wmertens]

Actually the context will be easy to notice, and the children can be walked to find all signals and maybe proxy then somehow?
Context could even be proxied too.

[mrhoodz]

I want to note that upon further consideration of the Document Picture-in-Picture (PIP) API's purpose, it seems designed more for displaying specific content from the main document (like video players, music controls, or countdowns) rather than creating entirely separate document windows. This makes me wonder if a full separate Qwik container might be overengineering for the typical use cases.

However, if we do proceed with the separate container approach, I have some specific questions:

Container Setup and Communication

• What's the recommended way to set up a separate Qwik container in the PIP window while maintaining the parent-child relationship that seems central to the API's design?
• What's the recommended way to handle communication between the two Qwik containers, considering that the PIP window is meant to be controlled by the parent window?

Signal and Context Handling

• Can you elaborate on how signals could be proxied between the two windows? This seems particularly important for maintaining state synchronization for interactive elements within the PIP window.
• What's the best approach to detect and handle signals in the child components while respecting the parent-child relationship of the API?

Optimizer Considerations

• What's the proper way to notify the optimizer about not forwarding signals? This seems crucial for maintaining proper performance and avoiding serialization issues.

Would love to hear your thoughts on these questions, particularly in the context of the API's intended use case as a way to "pop out" specific content rather than create fully independent windows.

[wmertens]

Qwik containers are very lightweight, they're basically a boundary for vDOM metadata. They don't really add much overhead.

Setting up is just generating the container as a string and having the browser execute it. The renderer will add the qwikloader so everything will just work.

For communication, I don't know what is possible, but Qwik doesn't get in the way of the browser APIs.

For proxying signals, it's a little complex. The given children's props would need to be deeply inspected for signals, and each would need to be replaced with a new signal. Then the whole thing would need to be wrapped in a component that uses signals to receive and send new values for the created signals. In v2, that should work.

For context, there's no way to detect their use, so they would have to be listed explicitly and also proxied.

The optimizer wouldn't need changes.

[serbyxp]

Would this be better as a more generic approach… like useMssage() ( or whatever you want to call it), I just started looking at this qwik-evolution so I’m reading it from the top down.

but for example passing messages from the DOM to Any other “thread” or “window” / “worker”…

Qwik-worker already exists but what it’s specific to regular workers not service workers shared workers, the key take away from it is the searlization of data and the QRL callback for the messages. If that is “deconstructed” pull the searlization and QRL callback method can’t that be used to exchange data from the DOM to any other window or web API maybe even custom APIs like chromes PiP , or am I thinking about this wrong 🤷‍♂️.

*edit
Another thing I had thought of and had mentioned in discord a while back, was to have something similar to the server$ but for workers, that you can stick it into your components to communicate to workers, maybe another approach for multi window (from my understanding multi window things communicate with each other through a shared-worker)… if this is the case, and if the chrome PiP api works in a similar fashion… maybe an idea
💡 could be a similar to server$ but a workers$ or window$ which can accept component$ in it

const MyPipComponent = component$(() => {…})

export default component$(() => {
  return <button onClick$={() => ( 
    window$((props, options:{ pip:true }) => (
      <MyPipComponent {…props}/> )))}>
    <PipIcon aria-label={”open Picture in Picture”}/>
  </button>;
})

Where window$() acts like a “portal” and options can be the API / worker whatever you want it to be “portaled” to …( where you want the code to actually be)