Bootstrap's text-success, text-warning, text-info and text-danger are fill tones, so used as text they failed contrast (amber on white was 1.6:1, info 2.0:1), and nothing adjusted them for dark mode. base.html now defines per-theme status text tokens that pass 4.5:1 on every surface tier, and the text utilities, text-muted, form-text, code, links and the outline buttons resolve through them. Info and warning badges carry dark text. Ink Muted moves a step darker so it holds on paper-sunk.
The dark message bubbles on Realtime were solid navy, forest green and purple, which overpowered the page and dropped the sender names to 1.7:1. They are now low-alpha tints of the signal and lamp hues over the card, like the dashboard delta chips, and the error bubble is red in both themes instead of purple in dark.
Also: the light log levels and level toggles move to tones that pass on the log well, the dark ERROR toggle uses dark text, Realtime drops its local orange text-warning and its opacity on message times, and the four copies of the dark .table td * rule no longer force body text color onto badges and buttons. DESIGN.md records the tokens and the rule that a fill hue never goes on text directly.
The per-row checkbox labels added in ae4235dc interpolate the contact name into an aria-label through escapeAttribute(), which is the right escaper inside an attribute because escapeHtml() leaves quotes alone. The guard only knew escapeHtml(), so it failed. It now accepts either, and a new test pins escapeAttribute() to encoding both quote styles and angle brackets.
A scan of the rendered pages found about 300 Plugins settings fields whose visible label wasn't tied to the control, so screen readers announced them without names. renderField now links each label (and its help text, via aria-describedby) to the control it renders. Contacts gets names for its search box, export range, purge threshold and the select-all and per-row checkboxes ("Select <name>"); the Radio create-channel labels gain for=; and the Multibyte time range and repeater search get aria-labels.
Icon-only buttons were named only by title, or not at all: the Realtime scroll buttons, the Mesh toolbar, contact row actions, the Plugins remove and reveal buttons, the Feeds and Radio row actions, every Bootstrap close button and the navbar toggler. Each now has an aria-label (scoped where it helps, such as "Scroll packets to newest" or "Remove Webhook 2"), with its icon hidden from assistive tech. Toggles that hold state expose it: the Mesh hot-connections button and the password reveal buttons set aria-pressed. The Plugins filter box and the dynamic key/value fields also get names, and repeating blocks name their enable switch after the block.
The Feeds form labels had no for=, so screen readers announced the fields without names, and the new-channel box, the three JSON config boxes and the Greeter search relied on placeholder text alone. Labels are now linked to their fields, the unlabeled boxes get aria-label, and the Output Format Help button sits beside its label instead of inside it. The empty spacer label above Preview Format is now a hidden div, and the accordion toggles declare aria-expanded and aria-controls.
Packet rows with raw hex only opened their detail modal on a mouse click. They now act as buttons (role, tabindex, Enter and Space), show the hover treatment plus a focus ring when focused, and closing the modal sends focus back to the row that opened it, since Bootstrap doesn't do that for a modal opened from script.
The header that opens a plugin's settings was a <div> with a click handler, so Expand all was the only keyboard route into a card. The title area is now a <button> with aria-expanded and aria-controls, kept separate from the enable switch, and Expand/Collapse all update it through the same path. The enable switch also gets an accessible name, since it had no label.
The sort headers were plain <th> cells with a click handler, so keyboard and screen reader users couldn't sort. Each header label is now a <button> inside the <th>, the active column carries aria-sort, and the focus ring follows the header text color. The Hops info tip sits outside the sort button, so opening it no longer re-sorts the table.
PRODUCT.md records who the web viewer serves and its four jobs; DESIGN.md records the design system the dashboard follows, so the remaining pages can be brought in line with it.
Fixes from a Codex review of the previous commit, plus the shared settings the rebase onto dev showed were still missing.
Settings that misstated or changed what runs:
- sports never read [Sports_Command] api_timeout (documented in the example config); the new field did nothing. It now sets the ESPN timeout.
- The path-byte requirement help on test, multitest and path said "bytes per hop"; the gate checks the path's total size (at least 2, or exactly 3).
- feed's allow_private_urls showed false while it inherited true from [Feed_Manager]. Fields can now name an inherit_section whose value they show when unset.
- notify_on_prefix_bytes was an int field for a value the service reads as a list (2,3), so the form refused a valid setting.
- The greeter's form defaults differed from the fallbacks it uses when the keys are missing. Both now come from shared constants.
- The MQTT weather limits accepted values the service clamps (payload 256 to 1 MiB, staleness 5 s to 7 days, length 64 to 4000).
Shared settings: the wx card now carries the [Weather] temperature, wind and precipitation units and the three temperature_*_format templates (with previews through format_temperature_high_low), next to wx's own [Wx_Command] unit overrides, which default to "Same as [Weather]". Two fields with one key in different sections are told apart as key@Section in the save payload; a bare key still resolves when only one field has it. An enum's "" option, like a blank number, removes the key. Packet capture brokers gain username, password, topic prefix, JWT timings and include_decoded; blank inheriting values are left out of block saves, since the service reads them with getint/getboolean when present.
Previews:
- They use the bot's saved config: a blank test format falls back to [Keywords] test, multitest lays out paths per condense_paths, and MQTT applies passthrough_max_length.
- A quoted empty template ("") counts as blank, as the commands strip the quotes first.
- A str.format width or precision over 500 isn't rendered, so `{sender:100000000}` can't make the endpoint build a huge string.
- The page invalidates an in-flight preview as soon as the field changes, and shows the server's note about fallbacks instead of guessing it.
The endpoint inventory golden gains the preview route (401 for anonymous requests when a password is set).
The Plugins page now has a field for every setting the plugins read. I compared each plugin's settings_schema against config.ini.example and the keys the code reads; fourteen plugins had gaps (greeter, trace, stats, path, wx/gwx, rain, test, multitest, sports, worldcup, cmd, feed, the webhook, weather, packet capture, earthquake and prefix-collision services) and the World Cup service had no form at all. Webhook URLs, bot tokens and channel keys use the password field. A guard test needed four [Rain_Command] keys documented in config.ini.example.
Template fields get a { } button that opens a reference of the placeholders they take, with click-to-insert. Fields rendered by the piped engine (test's response_format, path's reply_prefix) also list the filters and conditionals. Every template field previews as you type: piped fields against a 2-byte, a 1-byte and a direct sample message, so a conditional's effect shows before saving, and the str.format fields (greeter, mesh info, multitest, MQTT weather) as their plugin renders them, including what it sends when the template has a mistake. The specs and renderers live in modules/template_reference.py; the preview endpoint only renders and never saves. The greeter's channel_greetings parser and multi-part split moved into module functions so the command and the preview share them.
Fixes the new fields would otherwise have exposed:
- Clearing a number field saved `key =`, which makes getint/getfloat raise and the plugin fail to load. A cleared number now removes the key.
- The weather service raised in __init__ when only some blitz_area_* corners were set. It now needs all four and logs a warning otherwise.
- A blank MQTT weather json_template saved an empty template, so every reply said no message had arrived. Blank now saves the default.
Nominatim was never given a language, so place names in wx, gwx and other location replies came back in each place's local language ("千代田区, JP" for Tokyo). Forward and reverse lookups now pass [Localization] language, with English as the fallback where OpenStreetMap has no name in it. [Localization] place_name_language overrides it: "local" keeps the previous behavior, a language tag picks another language. Reverse-lookup cache keys include the language, so addresses cached in local languages are looked up again; "local" keeps the old keys.
Conflict in wx_command.py: the refactor split _get_weather_for_location_sync into _locate_*, _noaa_forecast_body and _with_noaa_alerts. The fallback now checks coverage after _locate_* and when _noaa_forecast_body returns its fetch error. _openmeteo_weather takes no address_info: a city's label comes from city_to_lat_lon again, answered from the geocoding cache the first lookup filled.
Conflict in modules/core.py: #345 changed _validate_config_snapshot, which this branch moved to config_reload.py. The method there now matches dev's version; reload_config's warning merged cleanly.
_validate_config_snapshot expanded '%' interpolation on every value, so a value read raw with a literal '%' (an [MqttWeather] json_template with "% RH", which config.ini.example documents as fine) failed every reload, although startup accepts the same file. Such values are now returned and named in a warning, and the reload goes ahead. Typed schema keys are still checked as before.
[Weather] openmeteo_fallback (default false, only with weather_provider = noaa) answers wx from Open-Meteo when NWS reports a point as outside its coverage (HTTP 400/404 from /points), in gwx's format and labels and wx's units. Timeouts and server errors keep today's error. The point goes into the existing NWS no-coverage cache, so later requests skip NWS for 24 hours. wx <place> alerts there replies that alerts are not available.
gwx's per-point body moves into _weather_for_point so wx can reuse it without geocoding twice; gwx's output is unchanged.
Codex on f0649558: inspect.signature follows __wrapped__, so an operator-installed command under modules/commands that wraps PingCommand.get_help_text with a get_help_text(self) override looked like it accepted the message, was called with it, and raised where dev retried and returned its help. _accepts_message now uses follow_wrapped=False. New test covers that override. No bundled get_help_text is decorated.
Space bunny on d60e7cf1: operators may install their own command files inside modules/commands or modules/commands/alternatives (documented, and preserved across upgrades), so a class under modules. is not necessarily bundled. Such a command written as get_help_text(self) was treated as bundled, called with the message and raised, so help returned nothing where dev returned its text. help_text_for now calls once with the message only when the method comes from a class under modules. and its signature binds the message; otherwise, including when the signature can't be read, it uses dev's call-then-retry. New test: an operator command in the modules.commands namespace with get_help_text(self) gets its help.
Codex on d60e7cf1 found two more edges where dispatch differed from dev: the retry called the captured method instead of reading command.get_help_text again, so a local plugin that replaced its help callable before raising got the original back; and a local class that reuses a bundled function (get_help_text = PingCommand.get_help_text) was classified as local, so a TypeError inside the bundled body ran it twice. The retry reads the attribute again, and a function counts as bundled when any bundled class in the MRO holds it in its __dict__. Both reproductions now match dev.
Accepted: a local override that forwards *args to a bundled get_help_text now passes the message through (the bundled method accepts it), and adapters that pass a message to a formerly no-message bundled method now succeed instead of raising.
Codex on ba293bb2: functools.wraps copies __module__, so a local subclass that wraps PingCommand.get_help_text with a no-message override looked bundled and lost the retry it needs (it raised instead of returning its help), and callables with odd __module__ values could fail or be misclassified. help_text_for now treats a method as bundled only when it is a plain bound method of this command whose function is defined, per the command class's MRO, by a class whose own __module__ is under modules. Everything else (local classes and overrides, partials, Mocks, other callables) gets dev's call-then-retry. New test: a wrapped local override of PingCommand still gets its help.
Accepted residual, besides joke and rain: an instance-level wrapper (functools.partial, Mock(wraps=...)) around a bundled get_help_text whose body raises TypeError now runs the body twice, since the bundled method accepts the message.
Codex on 495df80e: choosing the help call by signature also dropped the TypeError retry for local plugins written as get_help_text(self, message=None), which used to fall back to generic help when the message call raised, and inspect.signature itself can raise TypeError on odd callables and then take the wrong branch. help_text_for now decides by where get_help_text is defined: bundled commands (defined under modules.) are called once with the message, so an error from their body propagates as it did before 7aba432b; anything else gets exactly the old call-then-retry. Tests pin both: a bundled body's TypeError runs once, a local plugin's is retried without the message. joke and rain stay the accepted residual (no retry for a TypeError inside their help bodies).
Codex also found two inaccuracies in b569ed5d's docs: ChannelBridgeBase subclasses must also supply _open_http_session and _init_queues, and an empty [Keywords] format means no reply.
S0's missing replay guard. The packet_decode move was checked at the time by replaying a private 4,009-packet capture that cannot go in the repository. This golden decodes the ten public packets in tests/fixtures/mqtt_packets.json, each whole, halved, header-only and with an odd-length hex string, at 2-, 4- and 6-character path prefixes, plus calculate_packet_hash. dev's MessageHandler.decode_meshcore_packet (c44e8f47) produces the same output byte for byte.
S7's units item. GlobalWxCommand and WeatherService each read [Weather] temperature_unit, wind_speed_unit and precipitation_unit, lowercased them and fell back to fahrenheit/mph/inch with the same three warnings; weather_common.load_open_meteo_units does that once, next to load_open_meteo_model. Both still accept kn. wx keeps its own NOAA unit reading (_unit_setting), which has different fallbacks and sources. Old-vs-new over 5,000 random configs matched on values and warnings.
S3, scoped to what was still duplicated. effective_channel_send_scope exists to predict the scope send_channel_message will apply, and the two carried the same resolve → outgoing override → global-marker test → normalize steps. Both now call _send_scope(scope, channel), which returns (resolved, scope_to_use, is_global); send_channel_message still uses resolved for its scope-source log line, and the predictor still maps a global scope to None and any exception to "#unknown". The plan's ScopeResolution record is not needed: flood_scope.py already holds the shared lookups (channel_scope_entry, outgoing_override, section_flood_scope) and the three public contracts call them. The scope matrix golden passes unchanged.
Local plugin authors had no way to learn about enabled_attr, admin_only, keywords_format_key, the get_help_text(self, message=None) signature, translated_or, run_periodic, _cancel_tasks, _subscribe/_unsubscribe_all or ChannelBridgeBase short of reading the base classes. A new "Base class hooks" section lists what each does, with the facts checked against base_command.py, base_service.py and channel_bridge_utils.py.
assert_golden used to write a golden that didn't exist yet whenever CI was unset, so a deleted or misnamed golden re-recorded whatever the code did and the test passed locally. It now writes only with UPDATE_GOLDEN=1 and otherwise fails with the same message CI already gave. Space bunny flagged this earlier; the public-API guards were hardened the same way in b62806f5.
Plan rule 3c said every module this refactor creates is type-checked from its first commit; web_viewer/tracking.py was on the ignore list because it moved out of app.py with app's existing errors, and mypy skipped the bodies of untyped helpers in all the new modules. tracking.py is off the ignore list, and the 30 new modules get check_untyped_defs. The 25 errors that surfaced were all missing annotations: container annotations (paths_by_key, tracking, server_stats, result, daily_by_role, feed params), casts for page/page_size where pagination guarantees ints, FeedSubscriptionsMixin's two host attributes, and an ignore for Flask-SocketIO's request.sid. No runtime change.
Codex found that after 7aba432b a TypeError raised inside one of the 40 newly widened help bodies reached the retry in help and command_manager, so the body ran a second time (and could then succeed); before, the no-message call ran it once and the error propagated. Both call sites now go through base_command.help_text_for(command, message), which binds the message against get_help_text's signature first: commands that accept it get get_help_text(message), local plugins written as get_help_text(self) get get_help_text(), and an error from the body propagates after one call. A callable with no introspectable signature keeps the old try-and-retry.
Accepted residual difference: joke and rain already took the message, and a TypeError raised inside their help bodies used to be retried without it; it now propagates. help's no-message test now uses a real get_help_text(self) instead of a Mock that raised TypeError, and a new test pins the single call.
Phase 9's _broadcast item, scoped down. The six live-stream handlers (command, packet, mesh edge, mesh node, message and log line) each copied the same "take the clients lock, list the sids with this subscribed_* flag" block. LiveStreamMixin._subscribed_clients(flag) now returns that list; each handler keeps its own emit, event name, payload, debug line and error handling, in the same order. Moving to Socket.IO rooms would change delivery and stays out.
Phase 8's mechanical part. The 19 asyncio.get_event_loop() calls that run directly in an async def (found by walking each file's AST; calls inside nested sync functions or lambdas don't count) become asyncio.get_running_loop(). Inside a running coroutine both return the same loop; get_running_loop says so and never creates one. The five calls in sync functions (maintenance.run_data_retention, radio_link._handle_serial_probe_error, scheduler._run_in_current_loop and run_scheduler, weather_service._run_daily_forecast) can run on threads without a loop, where the two differ, so they stay. No test patches get_event_loop.
S4. _check_admin_access and announcements' _check_announcements_access ran the same pubkey validation and logging, differing only in wording; both now call BaseCommand._pubkey_in_acl(message, acl, kind, denied), which builds each log line from those two words, so every line keeps its exact text and level. The admin check still runs it inside its try, announcements outside, as before.
ping and magic8 had identical get_response_format overrides reading [Keywords] <name>; a keywords_format_key class attribute on BaseCommand now does that, and commands without one still get None. typing.Optional stays importable from both modules.
Old-vs-new over 20,000 randomized configs and senders (missing, malformed, mixed-case and listed keys; missing sections; quoted and empty formats) matched on results and log calls; three mutations were each caught.
S4. BaseCommand and the 40 bundled overrides that took no argument now take `message: MeshMessage | None = None`, matching joke and rain, which already use the message. None of the 40 bodies read it, so their help text is unchanged. help and command_manager keep their TypeError retry, since local plugins may still implement get_help_text(self). For bundled commands the retry no longer runs: `help <command>` calls get_help_text(message) once instead of failing and calling it again. A new test pins the signature for every bundled command class. The offline smoke run against the real config produces the same help text for all 46 commands.
S6. The sender's latest position (airplanes, path, test) and the repeater-or-room-server lookup by name (prefix, solarforecast) were each pasted into the commands, alongside location.py's own copies for get_companion_lat_lon and lookup_repeater_lat_lon. They now run through location.latest_contact_position_rows and location.repeater_by_name_rows. The copies differed only in how they drop a zero coordinate, so that is a zero_rule parameter: "both" (location.py's helpers: drop only 0,0) or "either" (the commands: drop a fix with either coordinate zero), and each caller passes the rule it had. Each command keeps its private wrapper, its pubkey access, try/except, log text and value conversion; airplanes' _get_bot_location now calls get_bot_lat_lon, which is the same code.
I did not move the commands onto resolve_location: its labels and geocoding rules differ from what each command does today. Old-vs-new over 20,000 randomized cases against a real SQLite table (zero coordinates, ties, near-duplicate names, missing pubkeys, database errors, no db_manager) matched on results and log calls for all eight functions; four mutations were each caught.
Codex's final review found that moving code out of modules dropped imports that local plugins could import from them, for example `from modules.service_plugins.discord_bridge_service import EventType`, which would make such a plugin fail to load. Comparing every top-level name bound on dev against the branch (both trees imported, so names under TYPE_CHECKING are excluded) found 24 in 11 modules: EventType, copy and contextlib in both bridges; sha256, Iterable and hmac_mod in message_handler; RotatingFileHandler, colorlog, contextlib, contextvars and functools in core; hashlib and re in utils; contextlib in feed_manager, earthquake_service and weather_service; Any in cmd and help; time in path. Each is re-imported exactly as dev imported it.
The public-import guard only covered `from modules... import` statements, so it missed these. It now records every unconditional top-level import and assignment, regenerated from dev's tree (461 → 1,597 names), and fails if the discord bridge stops exposing EventType.
The golden was recorded on macOS, whose MIME table maps .ico to image/x-icon; the Linux CI runners map it to image/vnd.microsoft.icon through /etc/mime.types, so /favicon.ico failed the inventory on every Python version. The app's behavior is unchanged; the test now normalizes that one alias.
_start_cleanup_scheduler and _cleanup_old_data move verbatim to modules/web_viewer/cleanup.py (AST-identical; the other 23 BotDataViewer methods are unchanged). app.py keeps importing delete_timestamp_rows_in_chunks and retention_delete_settings so modules.web_viewer.app still exposes them; as with the earlier mixins, patching those names on app no longer reaches the moved code. app.py is 4,808 lines.
_setup_socketio_handlers, _mark_subscribed, _replay_packet_stream, _disconnect_login_sockets and _cleanup_stale_clients move verbatim to modules/web_viewer/socket_clients.py (AST-identical; the other 25 BotDataViewer methods are unchanged). app.py keeps importing disconnect and emit so modules.web_viewer.app.disconnect and .emit still resolve; as with the earlier mixins, patching those names on app no longer reaches the moved handlers. app.py is 4,868 lines.
_collect_alert_entry parses one ATOM entry and appends it to the new-alert list (its early continues become returns; the append stays before the debug line, so a timestamp the log cannot format still leaves the alert queued, as before); _send_new_alerts sends them two seconds apart. Each loop keeps its own try/except in place. AST comparison shows the helpers and the rest of _check_weather_alerts identical to the original apart from continue → return.
_forecast_location_name reverse geocodes the bot's position once and caches it; _append_tomorrow_forecast appends tomorrow's sky and high/low. Both bodies and the rest of _get_weather_forecast_result are AST-identical to the original statements, called at the same points inside the same try, so its error handling and log lines are unchanged.
_visibility_miles converts Open-Meteo's visibility from feet or meters; _open_meteo_extra_conditions builds the dew point, visibility and pressure strings. Both bodies and the rest of _open_meteo_current are AST-identical to the original statements, called at the same points, so translate calls and log lines keep their order. The Open-Meteo characterization passes unchanged.
The "wx <place> alerts" branch (geocode coordinates, zipcode or city, reply with the error or the full alert list) moves verbatim into one async helper; execute calls it inside the same try. The helper body and the rest of execute are AST-identical to the original, and the execute dispatch characterization (which covers the alert inputs for each location type) passes unchanged.
Codex found that 3c5f31ec built the city prefix for an unrecognized location_type and then threw it away, so a geocoder returning a string subclass whose formatting raises turned a forecast into an error reply. _locate_city now takes labeled and skips the prefix entirely, as the original did. The old-vs-new fuzz now includes that case: 30,000 cases, 0 differences.
_noaa_current_summary builds the current period's line with its details, UV and precipitation; _append_noaa_tomorrow appends the Tomorrow period. Both bodies are statement-for-statement the original code (checked by AST comparison), and an old-vs-new run over 30,000 perturbed real NOAA forecasts (fixtures in tests/fixtures/noaa, varied units, budgets, names, temperatures, wind, fetch failures and JSON errors) matched on replies, fetch calls and log calls.
_locate_coordinates, _locate_zipcode and _locate_city each return the error reply (or None), the coordinates and the location prefix; _noaa_forecast_body fetches and formats one forecast type; _with_noaa_alerts builds the default reply and its two-message alert tuple. An unrecognized location_type still geocodes as a city without the city prefix, as before. Old-vs-new over 30,000 randomized cases (fake geocoders, NOAA fetches and alert results, including exceptions and error sentinels) matched on replies, call traces and log calls; four mutations were each caught.
agessaman