docs for https://github.com/wez/wezterm/discussions/796

docs/changelog.md

@@ -28,6 +28,7 @@ As features stabilize some brief notes about them will accumulate here.
 * It is now possible to set `selection_fg` and `selection_bg` to be fully or partially transparent. [Read more](config/appearance.md). [#1615](https://github.com/wez/wezterm/issues/1615)
 * Experimental (and incomplete!) support for Bidi/RTL can be enabled through the config. [Follow along in the tracking issue](https://github.com/wez/wezterm/issues/784)
 * Primary selection is now supported on Wayland systems that implement [primary-selection-unstable-v1](https://wayland.app/protocols/primary-selection-unstable-v1) or the older Gtk primary selection protocol. Thanks to [@lunaryorn](https://github.com/lunaryorn)! [#1423](https://github.com/wez/wezterm/issues/1423)
+* [pane:has_unseen_output()](config/lua/pane/has_unseen_output.md) and [PaneInformation.has_unseen_output](config/lua/PaneInformation.md) allow coloring or marking up tabs based on unseen output. [#796](https://github.com/wez/wezterm/discussions/796)
 
 #### Changed
 

docs/config/lua/PaneInformation.md

@@ -58,3 +58,41 @@ end)
 return {
 }
 ```
+
+*Since: nightly builds only*
+
+The `has_unseen_output` field returns true if the there has been output
+in the pane since the last time it was focused.
+
+This example shows how to use this event to change the color of the
+tab in the tab bar when there is unseen output.
+
+```lua
+local wezterm = require 'wezterm'
+
+wezterm.on("format-tab-title", function(tab, tabs, panes, config, hover, max_width)
+  if tab.is_active then
+    return {
+      {Background={Color="blue"}},
+      {Text=" " .. tab.active_pane.title .. " "},
+    }
+  end
+  local has_unseen_output = false
+  for _, pane in ipairs(tab.panes) do
+    if pane.has_unseen_output then
+      has_unseen_output = true
+      break;
+    end
+  end
+  if has_unseen_output then
+    return {
+      {Background={Color="Orange"}},
+      {Text=" " .. tab.active_pane.title .. " "},
+    }
+  end
+  return tab.active_pane.title
+end)
+
+return {
+}
+```

docs/config/lua/pane/has_unseen_output.md

@@ -0,0 +1,10 @@
+# `pane:has_unseen_output()`
+
+*Since: nightly builds only*
+
+Returns true if there has been output in the pane since the last time
+the time the pane was focused.
+
+See also [PaneInformation.has_unseen_output](../PaneInformation.md) for
+an example using equivalent information to color tabs based on this state.
+