Minor docs improvement

...which need to also be turned into a changenote

core/modules/background-actions.js

@@ -0,0 +1,116 @@
+/*\
+title: $:/core/modules/background-actions.js
+type: application/javascript
+module-type: global
+
+Class to dispatch actions when filters change
+
+\*/
+
+"use strict";
+
+class BackgroundActionDispatcher {
+	constructor(filterTracker, wiki) {
+		this.filterTracker = filterTracker;
+		this.wiki = wiki;
+		this.nextTrackedFilterId = 1;
+		this.trackedFilters = new Map(); // Use Map for better key management
+		// Track the filter for the background actions
+		this.filterTracker.track({
+			filterString: "[all[tiddlers+shadows]tag[$:/tags/BackgroundAction]!is[draft]]",
+			fnEnter: title => this.trackFilter(title),
+			fnLeave: (title, enterValue) => this.untrackFilter(enterValue),
+			fnChange: (title, enterValue) => {
+				this.untrackFilter(enterValue);
+				return this.trackFilter(title);
+			},
+			fnProcess: changes => this.process(changes)
+		});
+	}
+
+	trackFilter(title) {
+		const tiddler = this.wiki.getTiddler(title);
+		const id = this.nextTrackedFilterId++;
+		const tracker = new BackgroundActionTracker({
+			wiki: this.wiki,
+			title,
+			trackFilter: tiddler.fields["track-filter"],
+			actions: tiddler.fields.text
+		});
+		this.trackedFilters.set(id, tracker);
+		return id;
+	}
+
+	untrackFilter(enterValue) {
+		const tracker = this.trackedFilters.get(enterValue);
+		if(tracker) {
+			tracker.destroy();
+		}
+		this.trackedFilters.delete(enterValue);
+	}
+
+	process(changes) {
+		for(const tracker of this.trackedFilters.values()) {
+			tracker.process(changes);
+		}
+	}
+}
+
+/*
+Represents an individual tracked filter. Options include:
+wiki: wiki to use
+title: title of the tiddler being tracked
+trackFilter: filter string to track changes
+actions: actions to be executed when the filter changes
+*/
+class BackgroundActionTracker {
+	constructor({wiki, title, trackFilter, actions}) {
+		this.wiki = wiki;
+		this.title = title;
+		this.trackFilter = trackFilter;
+		this.actions = actions;
+		this.filterTracker = new $tw.FilterTracker(this.wiki);
+		this.hasChanged = false;
+		this.trackerID = this.filterTracker.track({
+			filterString: this.trackFilter,
+			fnEnter: () => { this.hasChanged = true; },
+			fnLeave: () => { this.hasChanged = true; },
+			fnProcess: changes => {
+				if(this.hasChanged) {
+					this.hasChanged = false;
+					console.log("Processing background action", this.title);
+					const tiddler = this.wiki.getTiddler(this.title);
+					let doActions = true;
+					if(tiddler && tiddler.fields.platforms) {
+						doActions = false;
+						const platforms = $tw.utils.parseStringArray(tiddler.fields.platforms);
+						if(($tw.browser && platforms.includes("browser")) || ($tw.node && platforms.includes("node"))) {
+							doActions = true;
+						}
+					}
+					if(doActions) {
+						this.wiki.invokeActionString(
+							this.actions,
+							null,
+							{
+								currentTiddler: this.title
+							},{
+								parentWidget: $tw.rootWidget
+							}
+						);
+					}
+				}
+			}
+		});
+	}
+
+	process(changes) {
+		this.filterTracker.handleChangeEvent(changes);
+	}
+
+	destroy() {
+		this.filterTracker.untrack(this.trackerID);
+	}
+}
+
+exports.BackgroundActionDispatcher = BackgroundActionDispatcher;

core/modules/filter-tracker.js

@@ -0,0 +1,106 @@
+/*\
+title: $:/core/modules/filter-tracker.js
+type: application/javascript
+module-type: global
+
+Class to track the results of a filter string
+
+\*/
+
+"use strict";
+
+class FilterTracker {
+	constructor(wiki) {
+		this.wiki = wiki;
+		this.trackers = new Map();
+		this.nextTrackerId = 1;
+	}
+
+	handleChangeEvent(changes) {
+		this.processTrackers();
+		this.processChanges(changes);
+	}
+
+	/*
+	Add a tracker to the filter tracker. Returns null if any of the parameters are invalid, or a tracker id if the tracker was added successfully. Options include:
+	filterString: the filter string to track
+	fnEnter: function to call when a title enters the filter results. Called even if the tiddler does not actually exist. Called as (title), and should return a truthy value that is stored in the tracker as the "enterValue"
+	fnLeave: function to call when a title leaves the filter results. Called as (title,enterValue)
+	fnChange: function to call when a tiddler changes in the filter results. Only called for filter results that identify a tiddler or shadow tiddler. Called as (title,enterValue), and may optionally return a replacement enterValue
+	fnProcess: function to call each time the tracker is processed, after any enter, leave or change functions are called. Called as (changes)
+	*/
+	track(options = {}) {
+		const {
+			filterString,
+			fnEnter,
+			fnLeave,
+			fnChange,
+			fnProcess
+		} = options;
+		const id = this.nextTrackerId++;
+		const tracker = {
+			id,
+			filterString,
+			fnEnter,
+			fnLeave,
+			fnChange,
+			fnProcess,
+			previousResults: [],
+			resultValues: {}
+		};
+		this.trackers.set(id, tracker);
+		// Process the tracker
+		this.processTracker(id);
+		return id;
+	}
+
+	untrack(id) {
+		this.trackers.delete(id);
+	}
+
+	processTrackers() {
+		for(const id of this.trackers.keys()) {
+			this.processTracker(id);
+		}
+	}
+
+	processTracker(id) {
+		const tracker = this.trackers.get(id);
+		if(!tracker) return;
+		const results = [];
+		// Evaluate the filter and remove duplicate results
+		$tw.utils.each(this.wiki.filterTiddlers(tracker.filterString), title => {
+			$tw.utils.pushTop(results, title);
+		});
+		// Process the newly entered results
+		results.forEach(title => {
+			if(!tracker.previousResults.includes(title) && !tracker.resultValues[title] && tracker.fnEnter) {
+				tracker.resultValues[title] = tracker.fnEnter(title) || true;
+			}
+		});
+		// Process the results that have just left
+		tracker.previousResults.forEach(title => {
+			if(!results.includes(title) && tracker.resultValues[title] && tracker.fnLeave) {
+				tracker.fnLeave(title, tracker.resultValues[title]);
+				delete tracker.resultValues[title];
+			}
+		});
+		// Update the previous results
+		tracker.previousResults = results;
+	}
+
+	processChanges(changes) {
+		for(const tracker of this.trackers.values()) {
+			Object.keys(changes).forEach(title => {
+				if(title && tracker.previousResults.includes(title) && tracker.fnChange) {
+					tracker.resultValues[title] = tracker.fnChange(title, tracker.resultValues[title]) || tracker.resultValues[title];
+				}
+			});
+			if(tracker.fnProcess) {
+				tracker.fnProcess(changes);
+			}
+		}
+	}
+}
+
+exports.FilterTracker = FilterTracker;

core/modules/info/mediaquerytracker.js

@@ -0,0 +1,67 @@
+/*\
+title: $:/core/modules/info/mediaquerytracker.js
+type: application/javascript
+module-type: info
+
+Initialise $:/info/ tiddlers derived from media queries via 
+
+\*/
+
+"use strict";
+
+exports.getInfoTiddlerFields = function(updateInfoTiddlersCallback) {
+	if($tw.browser) {
+		// Functions to start and stop tracking a particular media query tracker tiddler
+		function track(title) {
+			var result = {},
+				tiddler = $tw.wiki.getTiddler(title);
+			if(tiddler) {
+				var mediaQuery = tiddler.fields["media-query"],
+					infoTiddler = tiddler.fields["info-tiddler"],
+					infoTiddlerAlt = tiddler.fields["info-tiddler-alt"];
+				if(mediaQuery && infoTiddler) {
+					// Evaluate and track the media query
+					result.mqList = window.matchMedia(mediaQuery);
+					function getResultTiddlers() {
+						var value = result.mqList.matches ? "yes" : "no",
+							tiddlers = [];
+						tiddlers.push({title: infoTiddler, text: value});
+						if(infoTiddlerAlt) {
+							tiddlers.push({title: infoTiddlerAlt, text: value});
+						}
+						return tiddlers;
+					};
+					updateInfoTiddlersCallback(getResultTiddlers());
+					result.handler = function(event) {
+						updateInfoTiddlersCallback(getResultTiddlers());
+					};
+					result.mqList.addEventListener("change",result.handler);
+				}
+			}
+			return result;
+		}
+		function untrack(enterValue) {
+			if(enterValue.mqList && enterValue.handler) {
+				enterValue.mqList.removeEventListener("change",enterValue.handler);
+			}
+		}
+		// Track media query tracker tiddlers
+		function fnEnter(title) {
+			return track(title);
+		}
+		function fnLeave(title,enterValue) {
+			untrack(enterValue);
+		}
+		function fnChange(title,enterValue) {
+			untrack(enterValue);
+			return track(title);
+		}
+		$tw.filterTracker.track({
+			filterString: "[all[tiddlers+shadows]tag[$:/tags/MediaQueryTracker]!is[draft]]",
+			fnEnter: fnEnter,
+			fnLeave: fnLeave,
+			fnChange: fnChange
+		});
+	}
+	return [];
+};

core/modules/info/platform.js

@@ -33,13 +33,6 @@ exports.getInfoTiddlerFields = function(updateInfoTiddlersCallback) {
 		// Screen size
 		infoTiddlerFields.push({title: "$:/info/browser/screen/width", text: window.screen.width.toString()});
 		infoTiddlerFields.push({title: "$:/info/browser/screen/height", text: window.screen.height.toString()});
- 		// Dark mode through event listener on MediaQueryList
- 		var mqList = window.matchMedia("(prefers-color-scheme: dark)"),
- 			getDarkModeTiddler = function() {return {title: "$:/info/darkmode", text: mqList.matches ? "yes" : "no"};};
- 		infoTiddlerFields.push(getDarkModeTiddler());
- 		mqList.addListener(function(event) {
- 			updateInfoTiddlersCallback([getDarkModeTiddler()]);
- 		});
 		// Language
 		infoTiddlerFields.push({title: "$:/info/browser/language", text: navigator.language || ""});
 	}

core/modules/startup/load-modules.js

@@ -13,6 +13,11 @@ Load core modules
 exports.name = "load-modules";
 exports.synchronous = true;
 
+// Set to `true` to enable performance instrumentation
+var PERFORMANCE_INSTRUMENTATION_CONFIG_TITLE = "$:/config/Performance/Instrumentation";
+
+var widget = require("$:/core/modules/widgets/widget.js");
+
 exports.startup = function() {
 	// Load modules
 	$tw.modules.applyMethods("utils",$tw.utils);
@@ -31,6 +36,27 @@ exports.startup = function() {
 	$tw.modules.applyMethods("tiddlerdeserializer",$tw.Wiki.tiddlerDeserializerModules);
 	$tw.macros = $tw.modules.getModulesByTypeAsHashmap("macro");
 	$tw.wiki.initParsers();
+	// --------------------------
+	// The rest of the startup process here is not strictly to do with loading modules, but are needed before other startup
+	// modules are executed. It is easier to put them here than to introduce a new startup module
+	// --------------------------
+	// Create a root widget for attaching event handlers. By using it as the parentWidget for another widget tree, one can reuse the event handlers
+	$tw.rootWidget = new widget.widget({
+		type: "widget",
+		children: []
+	},{
+		wiki: $tw.wiki,
+		document: $tw.browser ? document : $tw.fakeDocument
+	});
+	// Set up the performance framework
+	$tw.perf = new $tw.Performance($tw.wiki.getTiddlerText(PERFORMANCE_INSTRUMENTATION_CONFIG_TITLE,"no") === "yes");
+	// Kick off the filter tracker
+	$tw.filterTracker = new $tw.FilterTracker($tw.wiki);
+	$tw.wiki.addEventListener("change",function(changes) {
+		$tw.filterTracker.handleChangeEvent(changes);
+	});
+	// Kick off the background action dispatcher
+	$tw.backgroundActionDispatcher = new $tw.BackgroundActionDispatcher($tw.filterTracker,$tw.wiki);
 	if($tw.node) {
 		$tw.Commander.initCommands();
 	}

core/modules/startup/startup.js

@@ -14,11 +14,6 @@ exports.name = "startup";
 exports.after = ["load-modules"];
 exports.synchronous = true;
 
-// Set to `true` to enable performance instrumentation
-var PERFORMANCE_INSTRUMENTATION_CONFIG_TITLE = "$:/config/Performance/Instrumentation";
-
-var widget = require("$:/core/modules/widgets/widget.js");
-
 exports.startup = function() {
 	// Minimal browser detection
 	if($tw.browser) {
@@ -54,16 +49,6 @@ exports.startup = function() {
 	}
 	// Initialise version
 	$tw.version = $tw.utils.extractVersionInfo();
-	// Set up the performance framework
-	$tw.perf = new $tw.Performance($tw.wiki.getTiddlerText(PERFORMANCE_INSTRUMENTATION_CONFIG_TITLE,"no") === "yes");
-	// Create a root widget for attaching event handlers. By using it as the parentWidget for another widget tree, one can reuse the event handlers
-	$tw.rootWidget = new widget.widget({
-		type: "widget",
-		children: []
-	},{
-		wiki: $tw.wiki,
-		document: $tw.browser ? document : $tw.fakeDocument
-	});
 	// Kick off the language manager and switcher
 	$tw.language = new $tw.Language();
 	$tw.languageSwitcher = new $tw.PluginSwitcher({

core/wiki/config/MediaQueryTrackers/DarkLightPreferred.tid

@@ -0,0 +1,5 @@
+title: $:/core/wiki/config/MediaQueryTrackers/DarkLightPreferred
+tags: $:/tags/MediaQueryTracker
+media-query: (prefers-color-scheme: dark)
+info-tiddler: $:/info/browser/darkmode
+info-tiddler-alt: $:/info/darkmode

editions/tw5.com/tiddlers/mechanisms/Background Actions.tid

@@ -0,0 +1,28 @@
+title: Background Actions
+created: 20250212154426403
+modified: 20250212154426403
+tags: Mechanisms
+
+Background actions are performed whenever there are changes to the results of a filter.
+
+They can be useful for hooking into existing functionality by tracking changes to the tiddler store.
+
+The following example tracks changes to the story list, reusing itself as the text of a notification at the same time:
+
+<<.demo-tiddler """
+title: SampleBackgroundAction: Story Change
+tags: $:/tags/BackgroundAction
+track-filter: [list[$:/StoryList]]
+
+<$action-sendmessage $message="tm-notify" $param="SampleBackgroundAction: Story Change" list={{$:/StoryList!!list}}/>
+
+Story List:
+
+<ol>
+<$list filter="[enlist<list>]">
+<li>
+<$text text=<<currentTiddler>>/>
+</li>
+</$list>
+</ol>
+""">>

editions/tw5.com/tiddlers/mechanisms/InfoMechanism.tid

@@ -4,8 +4,8 @@ tags: Mechanisms
 title: InfoMechanism
 type: text/vnd.tiddlywiki
 
-\define example(name)
-<$transclude tiddler="""$:/info/url/$name$""" mode="inline"/>
+\procedure example(name)
+<$text text={{{ [[$:/info/url/]addsuffix<name>get[text]] }}} />
 \end
 
 System tiddlers in the namespace `$:/info/` are used to expose information about the system (including the current browser) so that WikiText applications can adapt themselves to available features.
@@ -19,6 +19,8 @@ System tiddlers in the namespace `$:/info/` are used to expose information about
 |[[$:/info/browser/language]] |<<.from-version "5.1.20">> Language as reported by browser (note that some browsers report two character codes such as `en` while others report full codes such as `en-GB`) |
 |[[$:/info/browser/screen/width]] |Screen width in pixels |
 |[[$:/info/browser/screen/height]] |Screen height in pixels |
+|[[$:/info/browser/darkmode]] |<<.from-version "5.4.0">> Is dark mode preferred? ("yes" or "no") |
+|[[$:/info/darkmode]] |<<.deprecated-since "5.4.0">> Alias for  $:/info/browser/darkmode |
 |`$:/info/browser/window/*` |<<.from-version "5.4.0">> Tiddlers reporting window dimensions, updated when the windows are resized |
 |[[$:/info/node]] |Running under [[Node.js]]? ("yes" or "no") |
 |[[$:/info/url/full]] |<<.from-version "5.1.14">> Full URL of wiki (eg, ''<<example full>>'') |

editions/tw5.com/tiddlers/mechanisms/MediaQueryTrackerMechanism.tid

@@ -0,0 +1,13 @@
+title: Media Query Tracker Mechanism
+tags: Mechanisms
+created: 20250212154426403
+modified: 20250212154426403
+
+
+<<.from-version "5.4.0">> The media query tracker mechanism allows you to define [[custom CSS media queries|https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries]] to be bound to a specified [[info|InfoMechanism]] tiddler. The info tiddler will be dynamically update to reflect the current state of the media query.
+
+Adding or modifying a tiddler tagged $:/tags/MediaQueryTracker takes effect immediately.
+
+The media queries are always applied against the main window. This is relevant for viewport related media queries such as `min-width` which will always respect the main window and ignore the sizes of any external windows.
+
+The core includes a media query tracker that is used for tracking the operating system dark/light setting. See $:/core/wiki/config/MediaQueryTrackers/DarkLightPreferred for details.

editions/tw5.com/tiddlers/releasenotes/5.4.0/#9641.tid

@@ -0,0 +1,14 @@
+title: $:/changenotes/5.4.0/#9641
+description: Background actions and media query tracking
+tags: $:/tags/ChangeNote
+release: 5.4.0
+change-type: enhancement
+change-category: internal
+github-links: https://github.com/TiddlyWiki/TiddlyWiki5/pull/9641
+github-contributors: Jermolene
+
+Introduces[[Background Actions]] that are triggered whenever there is a change to the results of a specified filter.
+
+Building on that, it also introduces a new [[Media Query Tracker Mechanism]] that can track the results of any CSS media query (not just dark mode), storing the results in a shadow `$:/info/...` tiddler
+
+These improvements were cherrypicked from [[#8702 - Colour Handling Improvements|https://github.com/TiddlyWiki/TiddlyWiki5/pull/8702]] when it was deferred until v5.5.0.