From 4e33e56d7aaa59ad3116005c41ed21e3ce58ae1b Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 18 Sep 2025 11:34:59 +0800 Subject: [PATCH 01/13] Add principles for task sources --- index.bs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/index.bs b/index.bs index 2cc3ce42..8448d492 100644 --- a/index.bs +++ b/index.bs @@ -2327,6 +2327,34 @@ See also: * [Command–query separation on Wikipedia](https://en.wikipedia.org/wiki/Command–query_separation) +

Prefer existing task sources; mint new ones only for clear, spec-driven reasons

+Specs use task sources to group related work so UAs can schedule them sensibly. +A task is queued on a task source, +and each task source is associated with a task queue for an event loop. +Order is guaranteed within a source, while the UA chooses which queue to service next. + +Use the generic or preexisting task sources whenever possible. +HTML defines [[html##generic-task-sources|generic task sources]] meant for broad reuse across specs. +This includes, but is not limited to: +the [=DOM manipulation task source=], +[=user interaction task source=], +[=networking task source=], +[=navigation and traversal task source=], +and [=rendering task source=]. +If your feature matches one of these categories, +queue on that source rather than creating a new one. +Doing so improves interoperability, predictability, and performance scheduling across the platform. + +Only mint a new task source when you have a concrete, testable need. +For example when the feature's timing/execution model must be isolated +from the generic task sources +(e.g., media elements get their own media element event task source to align with decoder/timeline semantics). + +When writing a spec, prefer HTML's wrapper algorithms +([=queue a global task=], [=queue an element task=]) +and avoid relying on a particular event loop. +And only be explicit about the event loop when appropriate (see [[#event-design]]). +

Event Design

Use promises for one time events

From 315ab14d9b4a1fcb854b89f2d6f8e46f6a5a6540 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 18 Sep 2025 11:49:11 +0800 Subject: [PATCH 02/13] remove unexported tasks sources --- index.bs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 8448d492..970bb000 100644 --- a/index.bs +++ b/index.bs @@ -2338,9 +2338,7 @@ HTML defines [[html##generic-task-sources|generic task sources]] meant for broad This includes, but is not limited to: the [=DOM manipulation task source=], [=user interaction task source=], -[=networking task source=], -[=navigation and traversal task source=], -and [=rendering task source=]. +and the [=networking task source=]. If your feature matches one of these categories, queue on that source rather than creating a new one. Doing so improves interoperability, predictability, and performance scheduling across the platform. From f80b54d7a6e41ba7847303971cdb57a408a7e9b7 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 18 Sep 2025 11:50:09 +0800 Subject: [PATCH 03/13] fixup --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 970bb000..86888132 100644 --- a/index.bs +++ b/index.bs @@ -2334,7 +2334,7 @@ and each task source is associated with a task queue for an event loop. Order is guaranteed within a source, while the UA chooses which queue to service next. Use the generic or preexisting task sources whenever possible. -HTML defines [[html##generic-task-sources|generic task sources]] meant for broad reuse across specs. +HTML defines [[html#generic-task-sources|generic task sources]] meant for broad reuse across specs. This includes, but is not limited to: the [=DOM manipulation task source=], [=user interaction task source=], From 0ce16c2dd3d446db38018329c972681076cbbfc5 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 18 Sep 2025 11:51:26 +0800 Subject: [PATCH 04/13] add id --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 86888132..76379361 100644 --- a/index.bs +++ b/index.bs @@ -2327,7 +2327,7 @@ See also: * [Command–query separation on Wikipedia](https://en.wikipedia.org/wiki/Command–query_separation) -

Prefer existing task sources; mint new ones only for clear, spec-driven reasons

+

Prefer existing task sources; mint new ones only for clear, spec-driven reasons

Specs use task sources to group related work so UAs can schedule them sensibly. A task is queued on a task source, and each task source is associated with a task queue for an event loop. From 590761a955b6d065115b8235adbd04c6e163bfaf Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 18 Sep 2025 11:56:14 +0800 Subject: [PATCH 05/13] fix typo --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 76379361..85fd5658 100644 --- a/index.bs +++ b/index.bs @@ -2337,7 +2337,7 @@ Use the generic or preexisting task sources whenever possible. HTML defines [[html#generic-task-sources|generic task sources]] meant for broad reuse across specs. This includes, but is not limited to: the [=DOM manipulation task source=], -[=user interaction task source=], +the [=user interaction task source=], and the [=networking task source=]. If your feature matches one of these categories, queue on that source rather than creating a new one. From 9e96c661cddf0fe1d233aa4de933f3f35e44737a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 18 Sep 2025 11:58:02 +0800 Subject: [PATCH 06/13] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 85fd5658..4adddca6 100644 --- a/index.bs +++ b/index.bs @@ -2328,7 +2328,7 @@ See also: * [Command–query separation on Wikipedia](https://en.wikipedia.org/wiki/Command–query_separation)

Prefer existing task sources; mint new ones only for clear, spec-driven reasons

-Specs use task sources to group related work so UAs can schedule them sensibly. +Specs use [=task sources=] to group related work (or "[=tasks=]") so UAs can schedule them sensibly. A task is queued on a task source, and each task source is associated with a task queue for an event loop. Order is guaranteed within a source, while the UA chooses which queue to service next. From 9acf8dc6c2d638a65bcc7d2ede03be84ee513a2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 18 Sep 2025 11:59:37 +0800 Subject: [PATCH 07/13] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 4adddca6..90d45a08 100644 --- a/index.bs +++ b/index.bs @@ -2330,7 +2330,7 @@ See also:

Prefer existing task sources; mint new ones only for clear, spec-driven reasons

Specs use [=task sources=] to group related work (or "[=tasks=]") so UAs can schedule them sensibly. A task is queued on a task source, -and each task source is associated with a task queue for an event loop. +and each task source is associated with a task queue for an [=event loop=]. Order is guaranteed within a source, while the UA chooses which queue to service next. Use the generic or preexisting task sources whenever possible. From d67cbe14a9403734f6c9a594832d62fd37140812 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 18 Sep 2025 12:00:12 +0800 Subject: [PATCH 08/13] Update index.bs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 90d45a08..2518fb00 100644 --- a/index.bs +++ b/index.bs @@ -2344,7 +2344,7 @@ queue on that source rather than creating a new one. Doing so improves interoperability, predictability, and performance scheduling across the platform. Only mint a new task source when you have a concrete, testable need. -For example when the feature's timing/execution model must be isolated +For example, when the feature's timing/execution model must be isolated from the generic task sources (e.g., media elements get their own media element event task source to align with decoder/timeline semantics). From aa619770338dda704de8522f220cd73c1b768225 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 18 Sep 2025 12:00:36 +0800 Subject: [PATCH 09/13] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 2518fb00..8f2f3582 100644 --- a/index.bs +++ b/index.bs @@ -2350,7 +2350,7 @@ from the generic task sources When writing a spec, prefer HTML's wrapper algorithms ([=queue a global task=], [=queue an element task=]) -and avoid relying on a particular event loop. +and avoid relying on a particular [=event loop=]. And only be explicit about the event loop when appropriate (see [[#event-design]]).

Event Design

From e44c6af797461ec897c23bfee0d95474fae896cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 18 Sep 2025 12:01:25 +0800 Subject: [PATCH 10/13] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 8f2f3582..c6c890c8 100644 --- a/index.bs +++ b/index.bs @@ -2351,7 +2351,7 @@ from the generic task sources When writing a spec, prefer HTML's wrapper algorithms ([=queue a global task=], [=queue an element task=]) and avoid relying on a particular [=event loop=]. -And only be explicit about the event loop when appropriate (see [[#event-design]]). +And only be explicit about the event loop when appropriate (see also [[#event-design]]).

Event Design

From 6736c8f2887ad87e47889da942e36ef263294192 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 18 Sep 2025 12:10:55 +0800 Subject: [PATCH 11/13] fix for / event loops --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 54b7befb..bb54741f 100644 --- a/index.bs +++ b/index.bs @@ -2332,7 +2332,7 @@ See also:

Prefer existing task sources; mint new ones only for clear, spec-driven reasons

Specs use [=task sources=] to group related work (or "[=tasks=]") so UAs can schedule them sensibly. A task is queued on a task source, -and each task source is associated with a task queue for an [=event loop=]. +and each task source is associated with a task queue for an [=/event loop=]. Order is guaranteed within a source, while the UA chooses which queue to service next. Use the generic or preexisting task sources whenever possible. @@ -2352,7 +2352,7 @@ from the generic task sources When writing a spec, prefer HTML's wrapper algorithms ([=queue a global task=], [=queue an element task=]) -and avoid relying on a particular [=event loop=]. +and avoid relying on a particular [=/event loop=]. And only be explicit about the event loop when appropriate (see also [[#event-design]]).

Event Design

From 08e703a9cbba1ec9a368cdbd87869b246f007904 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 23 Sep 2025 12:44:30 +1000 Subject: [PATCH 12/13] Update index.bs Co-authored-by: Martin Thomson --- index.bs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 480804c7..efbdcb28 100644 --- a/index.bs +++ b/index.bs @@ -2329,7 +2329,11 @@ See also: * [Command–query separation on Wikipedia](https://en.wikipedia.org/wiki/Command–query_separation) -

Prefer existing task sources; mint new ones only for clear, spec-driven reasons

+

Prefer existing task sources

+ +Use existing [=task sources=] for dispatching work where possible. + +Only create a new [=task source=] when there is a clear reason to do so. Specs use [=task sources=] to group related work (or "[=tasks=]") so UAs can schedule them sensibly. A task is queued on a task source, and each task source is associated with a task queue for an [=/event loop=]. From def454b1c6a9df6adb23d770767b6c57fe3e7c40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 23 Sep 2025 12:44:55 +1000 Subject: [PATCH 13/13] Update index.bs Co-authored-by: Martin Thomson --- index.bs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.bs b/index.bs index efbdcb28..5d1b4ab8 100644 --- a/index.bs +++ b/index.bs @@ -2349,6 +2349,8 @@ If your feature matches one of these categories, queue on that source rather than creating a new one. Doing so improves interoperability, predictability, and performance scheduling across the platform. +Adding a task source has performance and complexity costs +that all browser implementations pay. Only mint a new task source when you have a concrete, testable need. For example, when the feature's timing/execution model must be isolated from the generic task sources