jkarlin / pause-document Goto Github PK

See https://ariya.io/2011/08/hall-of-api-shame-boolean-trap

Instead use a dictionary, so pause({ withUI: true }) or something.

I'm not sure what the right thing is here. Having it be a boolean means pages that want to pause/unpause from multiple places might need to keep track of the number of pause/unpause calls themselves, out of band. On the other hand, that does mean that it's possible to unpause no matter how many pause calls happen, if you want to do so...

This last would be particularly useful if we do want the UA to be able to unpause things that script pauses.

If a paused frame is larger than the browser window, is the entire frame required to be snapshotted by the browser (such that scrolling the toplevel page does not need to repaint)? Or is the expectation that scrolling would repaint (and fire rAF) in that situation?

If a site loads a cross-origin frame and then pauses it, is that OK? Has any security analysis been done on this?

The name "PauseFrame API" seems problematic to me, because "frame" already means at least three different things on the Web platform:

1. an element that holds a subdocument (as in <iframe>)
2. a tick of an animation or of the browser refresh cycle (as in requestAnimationFrame())
3. a stack frame in JS

Associating the words "pause" and "frame" together leads me, and I suspect others, to assume that frame in this context is usage (2) (i.e., that this is an api about animations) rather than usage (1).

My inclination is that you should probably avoid the term "frame" in the title of the specification because of this potential confusion, and because of the (maybe) general principle that overused/confusable terms should be used as little as possible.

I'm not sure if that implies anything about the names exposed in the API surface...

(I got here from w3ctag/design-reviews#196. But just my own opinion at this point; not speaking for the TAG.)

The explainer currently describes a frameElement.paused attribute, but isn't clear about whether this is true or false if an ancestor frame has been pause()d. It should probably be clear about which way this works.

I think there are arguments for both sides:

• reflecting state on ancestors makes it a better source of truth
• not reflecting state from ancestors makes it correspond better to the pause() and unpause() methods.

What happens if a paused frame is removed from the document? Does beforeunload fire? Does unload fire? Do they fire in this situation currently?

Say I have page A, which has frame B, which has subframe C.

If A pauses B, then pauses C, then unpauses B, is C paused?

If A pauses C, then pauses B, then unpauses B, is C paused?

If A pauses B (which pauses C, right?), then unpauses C, is C still paused? If A then unpauses B, is C paused?

If B pauses C, then A pauses B, then A unpauses B, is C paused?

This may be related to #21

I don't have a specific solution in mind, but wondering about what UI would look like for resuming a frame that is either offscreen or very tiny.

The paused frame might want to be made aware that it's about to be paused so that it can do some cleanup or log something.

Perhaps it could be an option:

frame_element.pause({notify: true});

It's not clear from the explainer whether the UA can unpause something that was paused from script.

UI is generally not a term that is often used in APIs.

What are these things? Can these become links?

That is, pause() doesn't pause script execution or painting or anything that's ongoing. It just ensures that future turns of the event loop are paused, i.e. anything previously queued up or queued up in the future will not run until resume()ed.

This is not immediately clear from "A bit more about what pausing does", but I think it's pretty important to avoid people freaking out and misinterpreting this proposal as something very weird.

Likewise, any resource requests generated by the frame will be queued as well, to be started upon resuming.

This doesn't really match how most resource requests work on the platform. If a resource request is generated (e.g. by fetch()), it will happen anyway. It will then queue a task to resolve the promise, or fire the event, or update the DOM, or whatever. So, when paused, no code will happen to actually process the response. But the resource request will definitely start, and even finish, despite being paused.

This throwaway mention deserves more attention. Without this one line, it seems like the proposal is only about developer-controlled pause() and resume() methods.

With this line, I think the interpretation is instead that this repo is attempting to define the general concept of pausing/resuming a frame. This can happen in at least two ways: developer-initiated, via these new APIs we're speccing; and browser-initiated, via an intervention.

If so, I'd suggest reframing the document to deemphasize the API and emphasize the introduction of this general new concept.

It's not exactly clear to me when .paused starts/stops returning true. Is it when the pause/unpause promises get resolved? When the API calls happen? Something else?

frame.pauseFrame() is pretty redundant. Can we just do pause() and resume()?

Can the load event on the parent fire before the frame is unpaused? I'd assume not, because the load event on the frame itself can't fire, and the load event on the parent needs to fire after the one for the frame...

On the other hand, since there's no way to create a frame in an "already paused" state, this could be a bit of a footgun, unless people make sure to pause frames from those frames' load events or something.

As part of review w3ctag/design-reviews#196,

While conceptually interesting to pause yourself, this seems like a footgun. Might be worth limiting this to iframes. :-)

Speaking of applying this feature to iframes, maybe this is better organized through Feature Policy?

What happens when the user uses developer tools to interact with a paused frame? Does it stay paused? Do promises created during devtool evaluation in the paused frame resolve?

https://github.com/jkarlin/pause-document#pause-details says:

When script is paused, any running script task is completed and future tasks on the event queue (e.g., events (including WebSocket) and timers) remain queued until the document is unpaused.

But "the event queue" is shared by multiple documents, some of which may have script paused and some may not. This needs a much clearer explanation of how things are expected to work.

The explainer says that events for paused frames are queued. As a user, I think it would be really weird if I clicked a link in a subframe, nothing happened, then sometime later the navigation randomly happened (when the frame got unpaused).

The explainer says that pausing can happen either through the pause()/unpause() API or as an intervention by the user agent. It should be clear whether the paused attribute reflects only the first type of pausing, or whether it reflects both types of pausing.

(It's not clear to me which is better, but making it explicit will make people who read the explainer more likely to think about and provide feedback on the issue.)

(I got here from w3ctag/design-reviews#196. But just my own opinion at this point; not speaking for the TAG.)

Consider a site which as an "anti-copying" feature puts all its content into a frame that it then pauses. It allows scrolling the parent document of that frame. Per the letter of the explainer, this means the user cannot select text in the subframe. Can the user even bring up a context menu for things in the frame? What about other sorts of interaction?