Incubation: patching (interleaved out-of-order streaming)

[noamr]

Explainer

https://github.com/WICG/declarative-partial-updates/blob/main/patching-explainer.md

The explainer

• Includes the information requested by the Explainer Explainer.
• Follows the Web Platform Design Principles.
• Includes or links to answers to the Security/Privacy Questionnaire.
• Describes user research you did to validate the problem and/or design.

Where and by whom is the work is being done?

• GitHub repo: https://github.com/WICG/declarative-partial-updates
• Primary contacts:
  • @noamr, Google
  • @foolip, Google
• Organization/project driving the design: Google
• This work is being funded by: Google
• Incubation and standards groups that have discussed the design:
  • WICG
  • WHATWG
• Standards group(s) that you expect to discuss and/or adopt this work when it's
  ready: WHATWG

Feedback so far

• Multi-stakeholder feedback:
  • Chromium comments:
  • Mozilla comments: https://github.com/mozilla/standards-positions/issues/NNN
  • WebKit comments: https://github.com/WebKit/standards-positions/issues/NNN
  • {{...include feedback/review from developers, implementers, civil society, and others}}
• Major unresolved issues with or opposition to this design:

You should also know that...

No response

---

Track conversations at https://tag-github-bot.w3.org/gh/w3ctag/design-reviews/1134

[dandclark]

Thanks for sending this to the TAG! We have some questions and things you may want to consider.

• Since perceived performance is a primary motivation, we're wondering if you have expectations about how much time can be saved and where specifically the saved time is going to come from. Maybe the benefit of one-off (JS-driven) patches could be measured as INP improvement? How about Interleaved (HTML-driven) patches? Or is the goal more about reducing JS payload size because streamed updates no longer need to be managed in JS? Maybe both?
• It's good to see patchid used to target patches rather than id, but consider also https://github.com/webplatformco/explainers/blob/main/html-element-references/README.md. How does the scoping of patchid work with shadow DOM?
• Regarding "The first patch for a target in the document stream replaces its content, and the next ones append." The need to append is clear but it seems like it'd be simpler if all patches appended, without the first one replacing. If there's a desire to show a "Loading" message/icon that goes away when the first patch comes in, that could alternatively be managed with the proposed :patch-pending pseudo.
• If the first patch appended rather than replaced the initial content, would there still be a use case for replacing a range?
• The Security & Privacy self-review answer to "Does data exposed by your specification carry related but distinct information that may not be obvious to users?" should probably be "Yes" since this is about streaming HTML, which carries lots of different kinds of information, to an arbitrary node, where different nodes might expect different kinds of information.
• What does interaction with the BFCache look like if the page navigates while there's an active stream? Does the streaming continue? Or does the fetch get cancelled in a way that might not be recoverable when the page is reloaded?
• The pending state in [css-selectors] CSS reflection of "patching" w3c/csswg-drafts#12579 seems useful, especially since it seems to replace the use case for the first patch to replace the initial content as discussed above. Triggering it based on the presence of the patchid attribute is a little worrying. Maybe the declarative patch should also be able to update the original node's attributes? We're happy that the CSSWG is exploring how and whether to merge the proposed :patching pseudo-classes into other pseudo-classes that already exist.
• "Patch" might not be the right name. The action is either to replace or append to an existing node (and we'd prefer to avoid "replace" if possible), while "patch" implies changes in the middle of the content. Perhaps something like appendto as the declarative attribute is a better fit?
• We see that the API shape and naming question has continued in Coherent story for HTML-setting methods whatwg/html#11669. We think that's going in a good direction, with a consistent structure across the streaming and non-streaming methods, and different names for synchronous vs asynchronous methods. We don't have any further comments on the details.
• Can multiple patches be active at once? Can a patch be started when the main HTML parser is still active on the document? Would any issues arise from allowing multiple instances of the HTML parser to be active (in a paused state) simultaneously on the same document?
• If started before the load event fires, do active patches block the load event? Or DOMContentsLoaded? More generally, is there a need for a central way for developers to track whether there are active patches, or is it enough to be able to track them individually?
• Patching contents from a URL kind of sounds like what HTML imports was trying to do; it's worth revisiting the history there to ensure the same issues aren't getting repeated that led to its deprecation. An issue with HTML imports was that it was a new type of dependency that didn't integrate well with ES modules (also new at the time). Is that a problem for this proposal? ES modules seem incompatible with streaming, as they require all module dependencies to be loaded prior to execution.
• Can a single patch be directed into multiple elements?
• Can interleaved patches be chained as follows?

<section patchid=gallery>Loading...</section>
<template patchfor=gallery>
 <div patchid=gallery-item>Loading item...</div>
...
</template>
<template patchfor=gallery-item>...</template>

[noamr]

Thanks for sending this to the TAG! We have some questions and things you may want to consider.

Thanks for the detailed review!

• Since perceived performance is a primary motivation, we're wondering if you have expectations about how much time can be saved and where specifically the saved time is going to come from. Maybe the benefit of one-off (JS-driven) patches could be measured as INP improvement? How about Interleaved (HTML-driven) patches? Or is the goal more about reducing JS payload size because streamed updates no longer need to be managed in JS? Maybe both?

These numbers are going to be very difficult to produce effectively. We do have evidence however that this technique is used in production today.

• It's good to see patchid used to target patches rather than id, but consider also https://github.com/webplatformco/explainers/blob/main/html-element-references/README.md. How does the scoping of patchid work with shadow DOM?

References here are both tree-scoped and element-scoped to the parent of the patch template (the latter applies if it's not a child of body).

• Regarding "The first patch for a target in the document stream replaces its content, and the next ones append." The need to append is clear but it seems like it'd be simpler if all patches appended, without the first one replacing. If there's a desire to show a "Loading" message/icon that goes away when the first patch comes in, that could alternatively be managed with the proposed :patch-pending pseudo.

The rationale, which came from userland solutions that implement this, is that you want to be able to "replay" all the patches and reach the same result, e.g. when traversing history.

We are thinking of adding a patch "mode" (replace/set/append/prepend/before/after), with an "auto" mode that uses this mechanism.

• If the first patch appended rather than replaced the initial content, would there still be a use case for replacing a range?

See above. We are currently thinking of using those modes rather than replacing a range.

• The Security & Privacy self-review answer to "Does data exposed by your specification carry related but distinct information that may not be obvious to users?" should probably be "Yes" since this is about streaming HTML, which carries lots of different kinds of information, to an arbitrary node, where different nodes might expect different kinds of information.

Ack

• What does interaction with the BFCache look like if the page navigates while there's an active stream? Does the streaming continue? Or does the fetch get cancelled in a way that might not be recoverable when the page is reloaded?

If you're navigating away from the page, what would be cancelled is the fetch that instantiated the response rather than the stream itself. if you have an ongoing JS stream I don't think it would be affected. But it's a good detail to flesh out.

• The pending state in [css-selectors-4] CSS reflection of "patching" w3c/csswg-drafts#12579 seems useful, especially since it seems to replace the use case for the first patch to replace the initial content as discussed above. Triggering it based on the presence of the patchid attribute is a little worrying. Maybe the declarative patch should also be able to update the original node's attributes? We're happy that the CSSWG is exploring how and whether to merge the proposed :patching pseudo-classes into other pseudo-classes that already exist.

Ack.

• "Patch" might not be the right name. The action is either to replace or append to an existing node (and we'd prefer to avoid "replace" if possible), while "patch" implies changes in the middle of the content. Perhaps something like appendto as the declarative attribute is a better fit?

Thinking of contentfor

• Can multiple patches be active at once? Can a patch be started when the main HTML parser is still active on the document? Would any issues arise from allowing multiple instances of the HTML parser to be active (in a paused state) simultaneously on the same document?

Currently patching the same element twice would cancel previous patches. There are a few permuations of this that are yet to be defined.

• If started before the load event fires, do active patches block the load event? Or DOMContentsLoaded? More generally, is there a need for a central way for developers to track whether there are active patches, or is it enough to be able to track them individually?

Patches from <template> would block the load event by definition, since the HTML is not fully loaded.
With patchsrc - they probably should as well but patchsrc is currently on the back burner.
Patches instantiated in JS are likely not going to block the load event.

• Patching contents from a URL kind of sounds like what HTML imports was trying to do; it's worth revisiting the history there to ensure the same issues aren't getting repeated that led to its deprecation. An issue with HTML imports was that it was a new type of dependency that didn't integrate well with ES modules (also new at the time). Is that a problem for this proposal? ES modules seem incompatible with streaming, as they require all module dependencies to be loaded prior to execution.

Yes we've revisited the history carefully. But currently patchsrc is on the back burner so we'll come back to it later on.

• Can a single patch be directed into multiple elements?
  No

• Can interleaved patches be chained as follows?

Loading...

Loading item...

... ...

Yes as long as the scoping rules work and the outlet's parent is an ancestor of the patching template.

[jyasskin]

Thank you! It looks like this is being discussed in the right places, and we're happy to see it proceed.

[noamr]

Hello! Not sure if to re-open it or just put this as an FYI, but the work on this has evolved a lot, and the current direction is to allow the HTML parser to parse processing instructions, and then use them for patching. See updated explainer.

@jyasskin @dandclark can you think if this aligns with the previous resolution of sending this back to WHATWG, or does TAG want to take another look?

[jyasskin]

Thanks for letting us know about this change! We have some questions about it.

Mainly we'd like to better understand the reason for the switch away from using an element combined with contentmethod as the target for the patch. Introducing a new node type to HTML that can represent an arbitrary range of the document seems more complex, so we'd expect to see this switch satisfy a clear user or developer need.

The explainer's outline of the weaknesses of the element approach is helpful but still leaves questions.

Doesn't support replacing arbitrary ranges of nodes, only an element or all of its children.

Most cases where only some children need to be replaced seem to be achievable with the contentmethod/contentname approach from earlier versions of the explainer by just wrapping the content to be replaced with more elements.

For instance this example:

<div marker="part-one part-two">
 <?start name="part-one">
 Placeholder content
 <?end name="part-one">
 <hr>
 <?start name="part-two">
 Placeholder content
 <?end name="part-two">
</div>

<template for="part-one">
  <p>Actual 1st part of the content</p>
</template>

<template for="part-two">
  <p>Actual 2nd part of the content</p>
</template>

Could be rewritten as:

<div>
 <span contentname="part-one">
 Placeholder content
 </span>
 <hr>
 <span contentname="part-two">
 Placeholder content
 </span>
</div>

<template for="part-one" contentmethod="replace">
  <p>Actual 1st part of the content</p>
</template>

<template for="part-two" contentmethod="replace">
  <p>Actual 2nd part of the content</p>
</template>

A case where the contentname element falls short would be if the desired start and end of the range to be replaced do not fall under the same parent, e.g.:

<body>
  <?start name="patch">
  <section>
   Content to replace
   <?end name="patch">
    This probably isn't replaced
   </section>
</body>

Is this sort of scenario really something developers are asking for? It's not clear to us that there's a use case for replacing ranges whose start and end don't share a parent.

The algorithm to decide what content to delete when replacing a lopsided range like this will not be trivial. Would the algorithm for Range.deleteContents be reused here? And where would inserted nodes wind up? After the start, before the end, or at the highest point in the tree within the range?

Another stated weakness of the contentmethod approach is:

In order to support patching <title>, which uses the RCDATA tokenizer state, the tag name of the target element must be repeated. This is because switching to the RCDATA (or RAWTEXT) state in a <template> element would change how the content is parsed in supporting and non-supporting parsers, which could be a security concern.

Unclear why repeating the tag is needed -- why doesn't this "just work"?

<title contentname="title">To be patched...</title>
<template for="title" contentmethod="replace-children">
  Title content from the patch
</template>

It does seem that patching only a substring of the <title> would be tough with this approach. But have you confirmed that there's a real developer need to patch substrings of <title>, or patch <title> at all?

Lastly:

prepend can fail if the original first child of the element is removed, meaning that a patch can fail mid-stream, requiring some error handling/reporting.

This one is hard to follow. Once the patch has started, there is a single parser insertion point regardless of whether it was set using an element or ProcessingInstructions. Wouldn't we need to handle DOM mutations around that insertion point for either use case?

Other miscellaneous bits of feedback:

• The explainer shows the marker attribute set on the parent node of ranges to be patched, but it's not clear why this is needed. Could the reason be stated more explicitly? Could this work without the attribute, only the patch ranges?
• The script-initiated-patching section mentions <template contentmethod>, should this say <template for> in the ProcessingInstructions version of the proposal?
• What happens when patches overlap?

<div marker="part-one part-two">
 <?start name="part-one">
One
 <?start name="part-two">
Two
 <?end name="part-one">
Three
 <?end name="part-two">
Four
</div>

[Thanks to @dandclark for drafting this comment!]