@@ -103,6 +103,13 @@ class SLDKApp:
     # a boot-time hang parked the box forever.
     BOOT_WATCHDOG_TIMEOUT = 120
 
+    # Floor for the global software brightness. 0.0 here (the library imposes no
+    # product policy); an app overrides it to keep its panel readable. A stored
+    # 0 is applied before the boot splash, so it reads as a sign that flashes
+    # once and then stays black behind a perfectly healthy app — which is
+    # exactly the field failure this floor exists to make unreachable.
+    MIN_BRIGHTNESS = 0.0
+
     # Supervision deadlines (see _supervise_progress). ATTEMPT_STALL_S bounds a
     # single update_data() call that never returns (a native call ignoring its
     # socket timeout); it must comfortably exceed the longest legitimate
@@ -558,23 +565,29 @@ def _apply_library_settings(self):
 
         Called by the display loop (see _display_process) when a web save sets
         _settings_dirty, immediately before on_settings_changed(). Handles
-        settings the library owns: brightness (pushed to the display hardware)
+        settings the library owns: brightness (a global software colour scale)
         and scroll speed (propagated to every queue item that exposes a .speed
         attribute). Runs on the display-loop task, never from the web server.
         """
         if self.display is not None:
             try:
                 brightness = float(self.settings.get("brightness_scale", 0.5))
-                brightness = max(0.0, min(1.0, brightness))
-                self.display._brightness = brightness
-                # .display is the underlying displayio display on every path
-                # (S3 wrapper display, Interstate 75 FramebufferDisplay, or the
-                # simulator Display). self.display.hardware may be a raw
-                # rgbmatrix.RGBMatrix with no .display attribute — never reach
-                # through it.
-                disp = getattr(self.display, "display", None)
-                if disp is not None:
-                    disp.brightness = brightness
+                brightness = max(self.MIN_BRIGHTNESS, min(1.0, brightness))
+                # set_color_scale stores the scale, pins the hardware property to
+                # full and drops the stale paint-index cache — all three together
+                # so they cannot drift. Dimming is done in software because the
+                # hardware property is on/off on the MatrixPortal S3; see
+                # UnifiedDisplay.set_color_scale.
+                setter = getattr(self.display, "set_color_scale", None)
+                if setter is not None:
+                    setter(brightness)
+                else:
+                    # A display predating color_scale: keep the old behaviour
+                    # rather than silently ignoring the setting.
+                    self.display._brightness = brightness
+                    disp = getattr(self.display, "display", None)
+                    if disp is not None:
+                        disp.brightness = brightness
             except Exception as e:
                 print("brightness apply error:", e)
 
 
@@ -64,6 +64,16 @@ class GraphicsMixin:
 
     PAINT_VALUE_COUNT = 256
 
+    # Global software brightness: every colour written to the panel is scaled by
+    # this. A class attribute so it exists BEFORE _init_graphics() runs — boot
+    # status frames draw on some paths before initialize() has finished.
+    #
+    # It is software because the hardware property isn't a dimmer: on the
+    # MatrixPortal S3 `display.brightness` is effectively on/off (0.0 blanks the
+    # panel, 0.15 and 1.0 are indistinguishable), which is how a customer's sign
+    # sat dark for months on a stored "0". See UnifiedDisplay.set_color_scale.
+    color_scale = 1.0
+
     # --- setup ----------------------------------------------------------------
     def _init_graphics(self, displayio_mod, bitmaptools_mod):
         """Create the content/layer sub-groups inside main_group and cache gfx.
@@ -162,6 +172,25 @@ def _ensure_paint(self):
         self._paint_colors = {}              # 0xRRGGBB -> palette index (0 reserved)
         self.add_layer(tile)
 
+    def _dim(self, color):
+        """``color`` scaled by the global software brightness.
+
+        Identity at 1.0, so the common case costs one float compare. The maths
+        is inlined rather than imported from ``.colors``: this module keeps zero
+        module-level imports on purpose, and a per-call import in a function the
+        paint path hits for every colour is not worth the tidiness. Integer
+        shifts, no float in the arithmetic (colors.scale uses the same form).
+        """
+        f = self.color_scale
+        if f >= 1.0:
+            return color
+        if f <= 0.0:
+            return 0
+        q = int(f * 256)
+        return (((((color >> 16) & 0xFF) * q) >> 8) << 16 |
+                ((((color >> 8) & 0xFF) * q) >> 8) << 8 |
+                (((color & 0xFF) * q) >> 8))
+
     def _paint_index(self, color):
         idx = self._paint_colors.get(color)
         if idx is not None:
@@ -172,9 +201,9 @@ def _paint_index(self, color):
             # it, so the most recently painted color is always the correct one
             # (caching here would alias several colors to one mutable slot).
             idx = self.PAINT_VALUE_COUNT - 1
-            self._paint_palette[idx] = color
+            self._paint_palette[idx] = self._dim(color)
             return idx
-        self._paint_palette[idx] = color
+        self._paint_palette[idx] = self._dim(color)
         self._paint_colors[color] = idx
         return idx
 
@@ -291,7 +320,7 @@ async def fill(self, color):
         if getattr(self, "_gfx", None) is None or self._content_group is None:
             return
         self._ensure_bg()
-        self._bg_palette[0] = color
+        self._bg_palette[0] = self._dim(color)
         self._bg_tile.hidden = False
 
     # --- measurement ----------------------------------------------------------
 
@@ -134,39 +134,73 @@ def _peak_profile(n):
                  for i in range(n))
 
 
-class RainbowChase:
+class _Dimmable:
+    """Global-brightness support for the palette effects.
+
+    Each effect rewrites all RAMP slots every frame from a cached ramp, so the
+    dim belongs in the ramp rather than in the write — the library's rule is to
+    build a ramp once and never inside a per-frame loop (see display/colors.py).
+    ``_rebuild`` therefore runs only when the scale actually changes, and
+    ``BitmapText._build`` re-runs on every ``start()``, so a brightness change
+    reaches the effect when its content next begins.
+    """
+
+    _dim = 1.0
+
+    def set_color_scale(self, f):
+        if f != self._dim:
+            self._dim = f
+            self._rebuild()
+
+    def _rebuild(self):
+        """Recompute the cached ramp from the effect's original colours."""
+
+
+class RainbowChase(_Dimmable):
     """Palette effect: rotate the colour ramp so a rainbow travels through the
     letters. Pure palette rewrites — no glyph rebuild. ``period`` advances the
     phase every N frames (>1 = a calmer, slower chase)."""
 
     def __init__(self, step=1, period=1):
         self.step = step
         self.period = period if period > 1 else 1
+        self._ramp = _RAINBOW          # shared tuple at full brightness: no copy
         self._phase = 0
         self._tick = 0
 
+    def _rebuild(self):
+        f = self._dim
+        self._ramp = _RAINBOW if f >= 1.0 else tuple(_scale(c, f) for c in _RAINBOW)
+
     def apply(self, palette):
         for i in range(RAMP):
-            palette[1 + i] = _RAINBOW[(i + self._phase) % RAMP]
+            palette[1 + i] = self._ramp[(i + self._phase) % RAMP]
         self._tick += 1
         if self._tick >= self.period:
             self._tick = 0
             self._phase = (self._phase + self.step) % RAMP
 
 
-class NeonTubeCrawl:
+class NeonTubeCrawl(_Dimmable):
     """A bright pulse crawls along an otherwise-dim neon tube of one colour: one ramp
     slot glows at full ``color`` while the rest hold a dimmed version of it. Pass
     ``glow``/``base`` to set the two shades directly instead. Pure palette rewrites —
     no glyph rebuild. ``period`` advances the pulse every N frames."""
 
     def __init__(self, color=0x66FFCC, glow=None, base=None, period=2):
-        self.glow = glow if glow is not None else color
-        self.base = base if base is not None else _scale(color, 0.18)
+        self._glow0 = glow if glow is not None else color
+        self._base0 = base if base is not None else _scale(color, 0.18)
+        self.glow = self._glow0
+        self.base = self._base0
         self.period = period if period > 1 else 1
         self._phase = 0
         self._tick = 0
 
+    def _rebuild(self):
+        f = self._dim
+        self.glow = _scale(self._glow0, f)
+        self.base = _scale(self._base0, f)
+
     def apply(self, palette):
         for i in range(RAMP):
             palette[1 + i] = self.glow if i == self._phase else self.base
@@ -176,7 +210,7 @@ def apply(self, palette):
             self._phase = (self._phase + 1) % RAMP
 
 
-class ChromeSheen:
+class ChromeSheen(_Dimmable):
     """A metallic sheen: a dark→bright ramp of ``color`` (default silver/white) with a
     highlight band that sweeps across the letters as the ramp rotates. Pass
     ``highlight`` to make the sheen a smooth TWO-colour gradient (dim ``color`` → full
@@ -191,13 +225,21 @@ def __init__(self, color=0xFFFFFF, highlight=None, period=1):
         self.color = color
         self.highlight = highlight
         self.period = period if period > 1 else 1
+        self._rebuild()
+        self._phase = 0
+        self._tick = 0
+
+    def _rebuild(self):
+        # One multiply, not two truncations: fold the dim into the profile
+        # rather than scaling an already-scaled ramp.
+        d = self._dim
+        color, highlight = self.color, self.highlight
         if highlight is None:
-            self._ramp = tuple(_scale(color, f) for f in self._PROFILE)
+            self._ramp = tuple(_scale(color, f * d) for f in self._PROFILE)
         else:
             # dim base of `color` -> full `highlight`: a smooth two-colour sheen ramp.
-            self._ramp = gradient(_scale(color, self._PROFILE[0]), highlight, RAMP)
-        self._phase = 0
-        self._tick = 0
+            self._ramp = gradient(_scale(color, self._PROFILE[0] * d),
+                                  _scale(highlight, d), RAMP)
 
     def apply(self, palette):
         for i in range(RAMP):
@@ -208,18 +250,24 @@ def apply(self, palette):
             self._phase = (self._phase + 1) % RAMP
 
 
-class HazardStripes:
+class HazardStripes(_Dimmable):
     """Marching hazard stripes: an accent ``color`` alternating with a ``dark`` ground,
     shifting one slot each step. Pass ``a``/``b`` to set the two colours directly.
     Pure palette rewrites — no glyph rebuild."""
 
     def __init__(self, color=0xFFCC00, dark=0x101010, a=None, b=None, period=2):
-        self.a = a if a is not None else color
-        self.b = b if b is not None else dark
+        self._a0 = a if a is not None else color
+        self._b0 = b if b is not None else dark
+        self.a, self.b = self._a0, self._b0
         self.period = period if period > 1 else 1
         self._phase = 0
         self._tick = 0
 
+    def _rebuild(self):
+        f = self._dim
+        self.a = _scale(self._a0, f)
+        self.b = _scale(self._b0, f)
+
     def apply(self, palette):
         for i in range(RAMP):
             palette[1 + i] = self.a if ((i + self._phase) % 2 == 0) else self.b
@@ -229,7 +277,7 @@ def apply(self, palette):
             self._phase = (self._phase + 1) % 2
 
 
-class MonoChase:
+class MonoChase(_Dimmable):
     """A single bright band of one ``color`` chases through the letters — RainbowChase,
     but monochrome (one hue at varying brightness). Pure palette rewrites — no glyph
     rebuild. ``period`` advances the chase every N frames."""
@@ -241,10 +289,14 @@ class MonoChase:
     def __init__(self, color=0xFFFFFF, period=1):
         self.color = color
         self.period = period if period > 1 else 1
-        self._ramp = tuple(_scale(color, f) for f in self._PROFILE)
+        self._rebuild()
         self._phase = 0
         self._tick = 0
 
+    def _rebuild(self):
+        d = self._dim
+        self._ramp = tuple(_scale(self.color, f * d) for f in self._PROFILE)
+
     def apply(self, palette):
         for i in range(RAMP):
             palette[1 + i] = self._ramp[(i + self._phase) % RAMP]
@@ -321,8 +373,14 @@ def _build(self, display):
         bitmap = gfx.Bitmap(width, GLYPH_H, RAMP + 1)
         palette = gfx.Palette(RAMP + 1)
         palette.make_transparent(0)              # background transparent
+        # _build re-runs on every start(), so this is where a brightness change
+        # reaches the effect's cached ramp.
+        dim = getattr(display, "color_scale", 1.0)
+        setter = getattr(self.palette_effect, "set_color_scale", None)
+        if setter is not None:
+            setter(dim)
         for i in range(RAMP):
-            palette[1 + i] = _RAINBOW[i]
+            palette[1 + i] = _scale(_RAINBOW[i], dim) if dim < 1.0 else _RAINBOW[i]
         # Render every glyph ONCE; each lit pixel's palette index is its column
         # position in the ramp, so rotating the palette makes the colour chase.
         cx = 0
 
@@ -17,7 +17,7 @@
 """
 
 
-__all__ = ['wheel', 'spectrum', 'lerp', 'gradient', 'multi_gradient', 'scale', 'depth_palette', 'hsv']
+__all__ = ['wheel', 'spectrum', 'lerp', 'gradient', 'multi_gradient', 'scale', 'dim_for', 'depth_palette', 'hsv']
 
 def _clamp8(v):
     if v < 0:
@@ -119,6 +119,19 @@ def scale(color, factor):
     return (r << 16) | (g << 8) | b
 
 
+def dim_for(display, color):
+    """``color`` scaled by ``display``'s global software brightness.
+
+    The one-liner every effect needs, so none of them has to remember the
+    ``getattr`` default. That default matters: it keeps effects working against
+    a display that predates ``color_scale`` (an older library build, a test
+    double, a mock), where the right answer is "don't dim" rather than
+    AttributeError.
+    """
+    f = getattr(display, "color_scale", 1.0)
+    return color if f >= 1.0 else scale(color, f)
+
+
 def depth_palette(color, strength=0.4, steps=2):
     """Two (or more) close shades of ``color`` for subtle "lit from above" depth.
 
 
@@ -191,8 +191,14 @@ def _grad_active(self, display) -> bool:
     def _ensure_grad(self, display) -> None:
         """Build (or rebuild on change) the gradient layer; idempotent per frame."""
         from .gradient_text import GradientTextLayer  # lazy: gradient path only
+        # color_scale is in the key because GradientTextLayer bakes the global
+        # software brightness into its palette at build time and never rewrites
+        # it. Without this, moving the brightness slider would leave the
+        # scrolling ride name — the default path, and the largest thing on the
+        # panel — sitting at the old brightness until the content cycled.
         key = (self.text, self.palette, self.direction, self.palette_steps,
-               self.y, id(getattr(display, "font", None)))
+               self.y, id(getattr(display, "font", None)),
+               getattr(display, "color_scale", 1.0))
         if (self._grad is not None and self._grad_key == key
                 and self._grad_display is display):
             return
 
@@ -18,6 +18,7 @@
 """
 
 from .colors import gradient, multi_gradient
+from .colors import scale as _scale
 from .text_fill import clamp_palette_steps, normalize_direction
 from .text_pixels import font_text_ascent, font_text_width, pixels_from_font_text
 
@@ -104,8 +105,18 @@ def build(self, display):
         bitmap = gfx.Bitmap(width, height, n + 1)
         palette = gfx.Palette(n + 1)
         palette.make_transparent(0)                 # index 0 = transparent ground
-        for i in range(n):
-            palette[1 + i] = ramp[i]
+        # Global software brightness. This palette is built ONCE and never
+        # rewritten per frame, so the dim has to be baked in here — and the
+        # owner's cache key must include the scale, or a brightness change would
+        # keep serving this layer at the old brightness (see
+        # _GradientFillMixin._ensure_grad).
+        dim = getattr(display, "color_scale", 1.0)
+        if dim >= 1.0:
+            for i in range(n):
+                palette[1 + i] = ramp[i]
+        else:
+            for i in range(n):
+                palette[1 + i] = _scale(ramp[i], dim)
 
         # Each lit pixel's palette index is its position along the axis (NO modulo,
         # so the ramp spans the whole word end-to-end rather than tiling). One O(1)