6 Commits

Include renames

Author	SHA1	Message	Date
ChuckandClaude Opus 5.5	ba6eccb489	build(web): generate the UI's Tailwind CSS with the pinned standalone CLI (#685) ... Replaces the hand-written Tailwind subset in app.css with a real, purged Tailwind build: scripts/build_css.py runs the pinned, SHA-256-checked standalone Tailwind CLI (no Node), the generated tailwind.css and plugin-frame.css are committed, and CI fails when they are stale. The Pi never builds anything. The login page (#683) now links tailwind.css too, and the load-order test covers every template that links app.css. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-09-30 09:38:16 -04:00
ChuckandClaude Opus 5.5	f6afbdbb15	fix(web): Cache/Logs error mix-up, store errors, tab fallbacks; remove ~2.5k lines of dead JS (#639) ... * fix(web): keep Cache and Logs helpers out of each other's way Both partials declared top-level showError and escapeHtml. Their scripts run at global scope after every HTMX swap, so whichever tab was opened last owned window.showError, and a Cache failure after visiting Logs rendered into the Logs panel (and the other way round). Each script is now an IIFE; Cache still exports deleteCacheFile for its row buttons. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): make the HTMX-failure fallbacks for tab panels actually run - The "HTMX never loaded" fallback read appElement.__x.$data, which is Alpine 2. The page ships Alpine 3, so the check was always false and the Overview never loaded without HTMX. It now reads Alpine.$data(). - The Overview and WiFi panels used hx-on::htmx:response-error, which htmx expands to "htmx:htmx:response-error", an event that never fires. - loadTabContent sent requests with <body> as the source, so htmx fired its events on <body> and no panel's hx-on handler ran at all. The panel is now the source. htmx also resolves its promise on a 4xx/5xx, and the panel was stamped data-loaded anyway, leaving a skeleton that never retried; it is now stamped only when no responseError fired. loadPluginsDirect, loadOverviewDirect and loadWifiDirect are merged into one window.loadPartialDirect(id, url), which also runs the partial's inline scripts before Alpine sees the markup (as htmx-config.js does on htmx:afterSwap). The ~10 s "htmx never arrived" path in loadTabContent uses it for every tab instead of four hard-coded ones. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): store and registry failures no longer wipe the Plugin Manager showError replaced the whole #plugins-content with an error message, so one failed store search, custom-registry install or saved-repository call took the installed list, the store and every control with it, with no way back short of reloading the tab. Those failures are now error notifications. The full-panel message is kept only for a first load of the installed list that failed (nothing to show yet); a failed refresh of an already-rendered list is a notification too. showSuccess's fallback branch, which wrote the message into innerHTML unescaped, is gone: showNotification always exists. The "Please try refreshing your browser" hint tested for the text "Failed to Fetch", which no browser produces (Chrome says "Failed to fetch", Firefox "NetworkError..."), so it never appeared. It now keys on the failure itself: a TypeError from fetch(), or PluginAPI's NETWORK_ERROR wrapper around one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): escape plugin action and install output on every path executePluginAction escaped data.message and data.output when an action failed but put data.message straight into innerHTML when it succeeded, and set the OAuth step-2 button's innerHTML from the manifest's step2_button_text. Plugin actions run plugin code, so that is plugin- or server-controlled markup in the page. Both paths now escape, and the button label is set with textContent. The same pattern sat in the install-from-GitHub-URL status lines (plugin_id, the server's message, and error.message, which can echo a repository URL) and the custom-registry load error; those are escaped too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): file-upload widget owns the image list and schedule editor plugins_manager.js loads after the widget bundle, so its older copies of deleteUploadedFile, updateImageList, hideUploadProgress, formatDate, openImageSchedule, toggleImageScheduleEnabled, updateImageSchedule{Mode, Time,Day} and updateCheckboxGroupData replaced the widget's. They are deleted; the widget files are the only definitions. Before switching over, the two sets were diffed and fixed so nothing regresses: - The old copy labelled the schedule/delete buttons for screen readers and lazy-loaded thumbnails; the widget now does both. - The schedule button did nothing on a card rendered by plugin_config.html whenever the image id is a UUID (every upload): the template turns "-" into "_" in the editor's id, and neither JS copy did. Both now use the template's rule. - The widget's "keep the open editor open" copied the editor's innerHTML into the new list. That dropped its event listeners and showed the old values, so after the first change the editor looked live but ignored input. A schedule edit now saves to the hidden input and updates the card's summary in place without re-rendering the list; a list re-render (upload, delete) rebuilds an open editor from the data. Editor controls are routed by one delegated change listener, so there are no per-element listeners to lose. - The old deleteUploadedFile had a JSON branch that removed a #file_<id> element and skipped the re-render. No template or script renders such an element, and JSON uploads are listed through updateImageList like images, so re-rendering (the widget's behaviour) is the consistent one; the branch was not carried over. - The template always renders the summary line (".image-schedule-summary", "Always shown" when unscheduled) so an edit has a line to update. The inline-handler test evaluated plugins_manager.js's updateImageList; test_file_upload_widget.js now covers the widget's list and editor. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): delete the unused handleCredentialsUpload Its last caller went when plugin_config.html switched credential uploads to the file-upload widget's handleSingleFileSelect. Nothing in the web UI, the tests or the plugin monorepo references it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): delete dead and shadowed front-end code Nothing calls any of these (checked across web_interface/, test/ and the ledmatrix-plugins monorepo, including hx-*/x-*/onclick attributes): - app-shell.js: the Alpine methods refreshPlugins (it called a nonexistent this.searchPluginStore), loadPluginConfig, savePluginConfig, getSchemaPropertyType, escapeCssSelector, formatCommitInfo and formatDateInfo, and the top-level copies of savePluginConfig, getSchemaPropertyType, escapeCssSelector, formatCommitInfo, formatDateInfo and togglePluginFromTab. Plugin config forms save through hx-post in plugin_config.html. - window.reconnectSSE (app-shell.js); window.updateArrayTableAddButtonState (array-table.js). - toggleNestedSection, defined twice (app-shell.js and plugins_manager.js) and called from nowhere. - plugins_manager.js: the window.initializePlugins wrapper around an IIFE-local origInit that was always undefined, and __pluginDomReady, which was written but never read. - display.html's fixInvalidNumberInputs fallback: app-shell.js defines it before any partial loads. - base.html's window.loadCodeMirror and the two CodeMirror stylesheet preloads, and the .CodeMirror rules in plugins.html. The raw JSON editor is a plain textarea. Also deleted: app-shell.js definitions that a later script always replaced, so they never ran: executePluginAction (plugins_manager.js assigns its own), uninstallPlugin and its pollUninstallOperation (plugins_manager.js), and updateAllPlugins (install_manager.js). vendor/codemirror stays: test/test_web_smoke.py still requests codemirror.min.js as a sample static asset. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): call showNotification without checking it exists app-shell.js defines window.showNotification (a stand-in that queues until the notification widget loads) and base.html runs it, deferred, before every other script that notifies: app.js, the utilities, the widget bundle, plugins_manager.js, and all partials, which HTMX loads after the page. The 81 `typeof showNotification === 'function'` / `!== 'undefined'` checks, the `window.showNotification || console.log` and `|| alert` fallbacks, and their else branches (alert(), console output, and schedule.html's own hand-built toast) could never take the fallback path. They are removed, as is fonts.html's second copy of the queueing stand-in. The stand-in in app-shell.js keeps its guard (it must not replace the widget's implementation if load order ever changes), and BaseWidget's public notify()/getNotificationFunction() keep their shape for widgets that plugins ship. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): one HTML escaper, window.LEDEscape About 30 files each carried their own escapeHtml / escapeAttr / escHtml / _esc / escapeJs. They disagreed: several (notification.js, display.html's escapeHtml, operation_history.html, the app() stub) did not escape quotes, google-calendar-picker.js and tools.html's escHtml left ' alone, and some turned 0 into ''. Most were fine only because the quote-safe widget copies were preferred at runtime. window.LEDEscape now lives at the top of app-early.js, a blocking script in <head>, so it exists before any other script runs: html(v) & < > " ' as entities, null/undefined as '' attr(v) the same, for call sites that want to say "attribute" jsStringAttr(v) a JS string literal safe inside an inline handler Every former copy is now a one-line name for it (kept so call sites do not change), widgets included, with no fallback. plugins_manager.js loses its four escapeJs wrappers (callers use jsStringAttr), the duplicate escapeAttr and escapeHtml inside renderInstalledCards and renderCustomRegistryPlugins, and the window.escapeHtml / window.escapeAttribute exports, which nothing read. addArrayObjectItem's fallback markup (with a sixth hand-written escape chain) is gone too: window.renderArrayObjectItem is defined earlier in the same file, so the fallback could not run. The unused escapeHtml methods on the Alpine app (app-early.js stub and app-shell.js) are deleted. test_html_escaping.js now runs LEDEscape and every remaining name for it, and fails if a hand-rolled escaper reappears anywhere in web_interface/. Suites that evaluate slices of plugins_manager.js or widget files load LEDEscape from app-early.js through test/js/led_escape.js. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): stop htmx re-running partial scripts after every tab load htmx-config.js runs each swapped-in <script> itself on htmx:afterSwap and meant to turn htmx's own script handling off with htmx.config.allowScriptTags = false. It did that once, while setting up, but base.html loads htmx with a dynamic <script>, so htmx was not defined yet and the setting never applied. On every tab load htmx then tried to run each script again in its settle phase, found it already replaced (no parent node) and threw "Cannot read properties of null (reading 'insertBefore')" into the console, which also skipped the rest of that swap's settle tasks. The setting is now applied in the afterSwap handler, which always runs after htmx exists and before htmx settles the same swap. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): show "--" for a system stat the server could not read The stats stream and /system/status now send null for a metric they cannot read (cpu_temp off a Pi, for one) instead of 0. updateSystemStats built the header and Overview text as value + unit, so a null showed as "null°C". CPU, memory and temperature, in the header and on the Overview, now render "--" plus the unit for null or a missing field -- the same placeholder the page starts with, and what tools.html already shows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): one Alpine accessor and one plugin-list signal window.getApp() (app-early.js) returns the root <body x-data="app()"> component through Alpine's public Alpine.$data, or null before Alpine has initialised it. It replaces the private el._x_dataStack[0] reads in app.js, app-early.js, app-shell.js, settings-search.js, overview.html and plugins_manager.js, the three local getAppComponent/appData/getAppData copies, and the Alpine 2 el.__x.$data fallbacks, which Alpine 3 never provides. Publishing the installed-plugin list: one load set window.installedPlugins and dispatched pluginsUpdated twice (loadInstalledPlugins, then renderInstalledPlugins), then wrote into the Alpine component through _x_dataStack[0] and called its updatePluginTabs() directly, and app-early.js's global listener set window.installedPlugins a third time and called updatePluginTabs() again. Now renderInstalledPlugins is the one publisher: it sets window.installedPlugins and dispatches pluginsUpdated once, and the full app()'s listener (app-shell.js) is the receiver. The app-early.js listener only builds the tab row while the app is not the full implementation yet. The "grid not loaded yet" case is a normal state (Plugin Manager tab not opened), so it logs through pluginLog instead of console.warn. updatePluginTabs had a "Debounce" comment and clearTimeout over a timer nothing ever set, and two identical branches; it now just calls _doUpdatePluginTabs (app-early.js detects the full implementation by that name in its source, which the new comment says). app()'s unused baseComponent lookup is removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): reload the plugin list after installs and failed toggles Several callers refreshed the installed list with if (typeof loadInstalledPlugins === 'function') loadInstalledPlugins(); else if (typeof window.loadInstalledPlugins === 'function') ... but loadInstalledPlugins is local to the plugin-manager IIFE and window.loadInstalledPlugins is never defined, so from outside that IIFE both tests were false and nothing reloaded: - A failed plugin toggle left the switch drawn in the new state while the data said the old one. It now re-renders from the reverted data. The optimistic in-place edit also has to forget the grid's last-rendered markup, or setGridHtmlIfChanged sees identical HTML and skips the revert. A successful toggle still keeps the switch (and focus) as drawn. - Installing from a GitHub URL (the early handleGitHubPluginInstall), installing or uploading a Starlark app, and toggling a Starlark app on its config tab never refreshed the list, so the new app had no tab or Installed badge until the page was reloaded. They now force a reload through window.pluginManager.loadInstalledPlugins(true), and the Starlark grid redraws when that finishes instead of after a fixed 500 ms. - The Starlark uninstall inside the IIFE reloaded from the 3 s cache, which could still hold the app; it now forces a reload. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): route debug output through debugLog base.html defines window.debugLog, gated on localStorage.pluginDebug. plugins_manager.js read the same key twice more into its own flags (_PLUGIN_DEBUG_EARLY, and PLUGIN_DEBUG behind a pluginLog() wrapper), and api_client.js's RequestThrottler had a separate `debug` property with a setDebug() that nothing called. All of it now goes through debugLog. The "functions defined" dumps with their ✓ lines, and two per-plugin "enabled=" loops that ran on every render, are dropped; "[PLUGINS STUB]" labels on code that has not been a stub for a long time read "[PLUGINS]". Ungated console.log calls that announced normal events on every page load or action (settings search and tooltips registering, every toast repeated to the console, the schedule pickers initialising, widget registry unregister/clear) go through debugLog too. What remains on console.log is the widget registry's on-demand LEDMatrixWidgets.debug() dump and BaseWidget.notify's no-notifier fallback. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): drop waits and guards that could never fire - handlePluginAction polled up to 10 x 50 ms for window.togglePlugin, configurePlugin, updatePlugin and uninstallPlugin before calling them. All four are defined when the scripts load, before any card can be clicked, so the poll always succeeded at once; it now calls them. The long thinking-aloud comment over the toggle state is replaced by two lines on why the stored state, not the checkbox, decides. - initializePlugins checked typeof on setupGitHubInstallHandlers and applyStoreFiltersAndSort, function declarations in the same IIFE, and wrapped window.checkGitHubAuthStatus(), which returns a promise with its own .catch, in try/catch. - searchPluginStore wrapped each "#store-count" update (a getElementById and an innerHTML assignment) in try/catch four times; one setStoreCount() helper does it. The store's post-render re-attach of the GitHub token handler dropped its try/catch and existence checks for the same reason. - The load-time fallback outside the IIFE tested typeof initializePluginPageWhenReady, which is IIFE-local and so always undefined there; it calls window.initPluginsPage directly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): delete two unused plugin-manager helpers stopOnDemand (IIFE-local; the page's stop button calls window.stopOnDemand from app-shell.js) and debounce had no callers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): document the plugin-config handlers templates call validatePluginConfigForm, handleConfigSave, handleToggleResponse, handlePluginUpdate and refreshPluginConfig each get a JSDoc naming the attribute in partials/plugin_config.html that calls it and what the return value means (only validatePluginConfigForm's matters: false cancels the submit). - The `if (!window.__pluginConfigHandlersInitialized)` wrapper is gone: app-shell.js runs once per page, so it was never false. The block is dedented one level; `git diff -w` shows the real change. - The three handlers read xhr.responseJSON first. XMLHttpRequest has no such property (it is jQuery's), so that branch never ran; one xhrJson(xhr) helper parses responseText for all of them, with the same fallbacks as before. - runPluginOnDemand and stopOnDemand checked that plugins_manager.js's openOnDemandModal/requestOnDemandStop exist; plugins_manager.js is on every page, so they call them. - fixInvalidNumberInputs had a stray "Notification helper function" comment on top of its own; a leftover "section toggle ... duplicate definition removed" note is gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): one toast per save, and a failed durations save says so app.js's global htmx:afterRequest listener showed the server's message for every htmx request, and every form and button that posts through htmx (plugin config save/toggle/update, Display, Durations, General, Schedule, Dim schedule, the Overview actions) also reports its own result from hx-on after-request. Each save showed two toasts. The global listener now stays quiet for a request whose element, or its form, has its own after-request handler. That exposed the Rotation & Durations form's handler, which read xhr.responseJSON: XMLHttpRequest has no such property, so it always said "Durations saved" in green, even when the save failed (the global toast had been the only place the error showed). display.html already had a correct version (2xx only counts as saved; the server's message wins; its status may refine success but never overturn failure). That is now window.showSaveResult(xhr, savedText, failedText) in app.js, used by the Display, Durations and General forms; General's inline copy of the same logic is gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(web): file headers and comments that say what the code does now - plugins_manager.js, app-shell.js, app.js and app-early.js open with a header: what the file owns, how base.html loads it and in what order relative to the others, and the globals it defines. app-early.js's app() stub also says why it exists and that, with app-shell.js now loaded before Alpine, it does not run in practice. - base.html's note on plugins_manager.js said it must load last to win over same-named functions in app.js/app-shell.js; there are none left, so it now gives the real reason (it uses everything loaded before it). - Change-narration and "already defined at the top, no need to redefine" notes are gone or rewritten as present-tense reasons; comments that were wrong are fixed ("Toggle password visibility" over the function that opens the token panel, "Insert before the closing </nav>" over an appendChild, "(from v2)", the export note that still listed escapeHtml). About forty comments that restated the line below them are removed, and a second window.currentPluginConfig = null outside the IIFE is dropped (the IIFE sets it). - The file-upload, checkbox-group and custom-feeds widgets' render() stubs say plainly that the widget is rendered server-side, instead of "for now" / "placeholder for future client-side rendering". test_plugin_action_delegation.js sliced the source up to one of the removed notes; it now ends the slice at the next section header. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): keep the escapeHtml/escapeAttribute globals for plugin pages 6da77363 removed window.escapeHtml and window.escapeAttribute because nothing in core or the plugin monorepo read them. Plugin web UIs served through serve_plugin_web_ui and third-party plugin pages may still call them, so they come back as aliases of window.LEDEscape.html and .attr, defined in app-early.js before any other script runs. test_html_escaping.js checks the aliases exist. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(changelog): web-frontend Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): encode the image thumbnail path; match script tags case-insensitively CodeQL flagged the upload widget building an <img> src from a stored path, and the escaper test extracting inline scripts with a case-sensitive regex. Each path segment is now URL-encoded (still a same-origin path, and correct for names with spaces or * fix(web): clear Codacy findings in the escaper, app shell and upload widget - LEDEscape looks entities up in a Map instead of indexing an object. - showNotification is declared as a global for app-shell.js. - openImageSchedule checks the index is a non-negative integer and reads the image with Array.prototype.at. - The schedule editor calls escapeHtml directly and documents why its innerHTML template is safe: every value is escaped or constrained. The remaining rule hits are suppressed on that line with the reason. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): build the image schedule editor with DOM calls Codacy does not honour inline suppressions, and the editor's innerHTML template kept tripping its XSS rules even though every value was escaped. The editor is now built with a small element helper (createElement and setAttribute), so no value is ever parsed as HTML, and the file's own escapeHtml goes away. Also for Codacy: - LEDEscape.attr is its own function rather than a second name for html. - The tab loader records a failed load on the panel (data-load-failed) from a named handler, instead of a closure over a local flag. The fake DOM in test_file_upload_widget.js gains append/replaceChildren, its hostile-id check now asserts the id arrives as attribute data with no innerHTML anywhere in the editor, and test_html_escaping.js drops the file-upload.js escaper it no longer has. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): schedule editor helpers as plain functions Codacy's lint flags arrow functions held in local constants and a forEach callback that returns a value. The editor's pieces are now named function declarations (displayStyle, scheduleModeOption, scheduleRangeTime, scheduleDayTime, scheduleDayRow) taking what they need as arguments, and the element helper loops with for...of. htmx is declared as a global in app-shell.js. Output is unchanged; test_file_upload_widget.js passes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>	2026-09-24 17:36:53 -04:00
ChuckandClaude Opus 5.5	3967a6cffc	fix(security): re-harden root sudo helpers; installer fixes; ARCHITECTURE and PERMISSIONS docs (#640) ... * docs: add ARCHITECTURE and PERMISSIONS guides ARCHITECTURE.md maps the processes, the state the display and web services share through the cache, the display loop, the plugin system, the web UI and the update path, with links into the code and a where-to-start table. PERMISSIONS.md lists who owns what after install, both sudoers files (and why iptables is not granted), the polkit rule, and which scripts/fix_perms script to run as which user. Both are linked from the docs index, along with the MQTT bridge README and src/common/README.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: correct stale setup, service and troubleshooting claims - README: quick actions run systemctl on ledmatrix.service (run.py), not display_controller.py; use_short_date_format has no effect; the installer uses system pip with --break-system-packages, not a venv. - CONFIG_DEBUGGING: LEDMATRIX_DEBUG must be "true"; logs are in journald. - GETTING_STARTED, WEB_INTERFACE_GUIDE, TROUBLESHOOTING: enabling a plugin, plugin settings, brightness and Vegas settings apply without a restart; matrix hardware settings still need one. - TROUBLESHOOTING: install dependencies with sudo so the root service sees them; point permission problems at PERMISSIONS.md instead of a project-wide chown. - ADVANCED_FEATURES: real BackgroundDataService stats keys; Vegas hooks return VegasDisplayMode and None falls back to capture; cache files are 0660; fix_web_permissions.sh runs as the web user and does not touch sudoers. - STARLARK_APPS_GUIDE: only the linux-arm64 pixlet binary is downloaded. - HOW_TO_RUN_TESTS: test class examples that exist. - CLAUDE.md: PluginStoreManager, plugin_dirs.py, monorepo installs via the Trees API with ZIP fallback, requirements.txt is optional. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: mark deprecated plugin APIs and state manifest fields once Methods @deprecated("3.7.0") (the set pinned in test_deprecation.py) were shown as current API in the quick reference, API reference, advanced guide, development guide and FONT_MANAGER. Each is now marked deprecated with its replacement. FONT_MANAGER is rewritten around the current API; the override editor is gone and override methods are deprecated. Required manifest fields were stated three different ways. The API reference now has one section: the 7 schema-required fields, the 4 the store refuses without, class_name for the loader, and the 8 to set. The other guides link to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: document every src/common module and every widget - src/common/README.md covered 7 of 17 modules. It now has a table of all of them (purpose, whether plugins import it, release to floor on), a short entry each, and logging advice that matches the code. - SPORTS_UNIFICATION listed two shared modules and called sports_helpers the first; it now lists all six. - The widgets README lists all 28 registered widgets plus the support files, and absorbs the parts that only docs/widget-guide.md had (x-options.labels, x-advanced, x-display hidden, plugin-file-manager). docs/widget-guide.md is now a pointer to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(security): fix_web_permissions.sh re-hardens the root sudo helpers The script chowns the whole project to the web user. That included scripts/fix_perms/safe_plugin_rm.sh and safe_pip_install.sh -- the two helpers /etc/sudoers.d/ledmatrix_web lets the web user run as root -- so running it turned both into a root shell for whoever can edit them. It also re-grouped config_secrets.json away from ledmatrix. After the chown it now does what first_time_install.sh's Steps 11 and 11.1 do: helpers back to root:root 755, and config_secrets.json back to the web unit's User=:ledmatrix 640. Each step is non-fatal and prints the manual command if it fails. Also fixes what the script and its docs claimed: it never configured sudoers, its closing hint pointed at ./configure_web_sudo.sh (wrong path), and the README and ADVANCED_FEATURES.md said to run it with sudo, which it refuses. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(security): validate and harden every sudoers drop-in the scripts write configure_wifi_permissions.sh copied its rules into /etc/sudoers.d/ledmatrix_wifi without `visudo -c`. A malformed drop-in makes sudo refuse every command for every user, which on a headless Pi leaves no way back in. It now checks first and leaves the installed file alone when the rules do not parse, as the other two writers do. (It already used mktemp, so that part of the review did not apply.) It also grants the two literal commands wifi_manager.py runs for NetworkManager's shared-mode dnsmasq drop-in -- `cp /tmp/ledmatrix-nm-dnsmasq.conf .../dnsmasq-shared.d/ledmatrix-captive.conf` and `rm -f` of that file. The directory's mkdir was granted, the file was not. Both are pinned in test_sudo_allowlist_covers_calls.py. configure_web_sudo.sh wrote its rules to /tmp/ledmatrix_web_sudoers_$$, a predictable name in a world-writable directory; it now uses mktemp with an EXIT trap, as first_time_install.sh does. It sets mode 440 on the installed file instead of leaving the temp file's mode, and finds visudo in /usr/sbin when that is not on the user's PATH, which skipped the check silently. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(install): escape the project path in the DNS-fix and MQTT unit renderers install_dns_fix.sh and install_mqtt_bridge.sh substituted __PROJECT_ROOT_DIR__ with the raw path, while the other three renderers go through sed_escape_replacement from lib_systemd_render.sh. A checkout under a path containing `&`, `\` or `|` rendered a corrupted unit from these two only. Both now source the helper and use it, and a test checks that every placeholder substitution in scripts/install uses an escaped value. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(install): stop the installer scripts reporting things that are not true - first_time_install.sh printed "Password: ledmatrix123" for the setup access point. wifi_manager creates it as an open network ("No password" on the panel), so it now says so. - Step 10.1 printed "✓ WiFi management permissions configured" straight after its own failure message; install_wifi_monitor.sh printed "✓ Package installation completed" after a failed apt install. The tick now only follows success. - Step 7 printed "Web dependencies already installed ... in Step 5" in the one branch that runs because Step 5 did not install them, then created .web_deps_installed on that basis. It now warns and leaves the marker off so the next run retries, as the comment below it intends. - check_system_compatibility.sh called Debian 12 Bookworm "full compatibility confirmed" while first_time_install.sh refuses anything but Debian 13. Bookworm, older Debian and non-Debian systems are now errors. Its counters used ((X++)), which under `set -e` exits the script at the first warning or error (the expression is 0), so the check never reached its summary on any system with one. - configure_web_sudo.sh and configure_wifi_permissions.sh finished by testing `sudo -n test -f ...` and `sudo -n nmcli device status`, neither of which is granted, so they always reported a failure. They now ask `sudo -n -l` about commands the new rules do grant, which checks the rule without running anything. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(install): print the completion summary before rebooting With -y -- and so for every one-shot `curl | bash` install, which always passes -y -- first_time_install.sh ran `reboot` about 180 lines before its "Installation Complete / Web UI Access" summary. reboot returns at once, so the summary printed while the Pi was going down and the SSH session usually dropped before the web UI address could be read. The reboot block moves, unchanged, to the very end of the script. The interactive prompt now also follows the summary. Because the summary now runs before the -y reboot, its one command that could fail under `set -Eeuo pipefail` (the SSID lookup, when nmcli reports a connected device but no active network line) gets `|| true`; a missing SSID was already handled as "SSID unknown". one-shot-install.sh prints its "Next steps" after the installer returns, by which time the reboot is under way, so it now says so, and README's Quick Install mentions the automatic reboot. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(scripts): correct wrong comments and messages, drop dead code No behaviour change except the output text noted below. - 2775 is setgid, not the sticky bit (first_time_install.sh Step 3.1, fix_plugin_permissions.sh), and root needs no "PWM hardware access" to plugin files. - The 777 comments in first_time_install.sh Step 3's fallback and fix_assets_permissions.sh said root needs it to write. Root ignores mode bits; the comments now say what 777 actually opens. The 777 itself is unchanged. - apt_remove ends in `|| true`, so Step 12's "Some packages could not be removed" branch could never run; it is gone and the helper stays non-fatal. - detect_web_service_user's comment named Step 8 for the web unit (install_service.sh installs it in Step 7.5) and now says which branch actually runs. - Step 5 described an "already installed" check that does not exist; the ACTUAL_USER comment described the re-exec backwards. - on_error printed a literal "\n" before "Common fixes:". - Dead code: one-shot-install.sh's uncalled fix_tmp_permissions, LEDMATRIX_ELEVATED=1 (never read) on the sudo re-exec, and configure_web_sudo.sh's unused PYTHON_PATH, which also made a missing python3 fatal for rules that never mention it. - start_display.sh / stop_display.sh said "for user: <you>"; the service runs as root. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(fix_perms): fix_cache_permissions.sh uses setup_cache.sh's model There were two models for /var/cache/ledmatrix. setup_cache.sh (the installer's Step 2) and install_web_service.sh share it through the ledmatrix group: root:ledmatrix, 2775, files 660, which is also what DiskCache relies on to give files the directory's group. fix_cache_permissions.sh instead made it 777 and re-grouped it to the invoking user's group, undoing that. It now runs setup_cache.sh for /var/cache/ledmatrix and keeps its own handling of ~/.ledmatrix_cache. Dropped: /var/cache/ledmatrix/ placeholder_logos (nothing reads it) and the checks against the `daemon` user (no service runs as daemon). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * ci: pin actions/checkout in the Claude workflows, drop template comments claude.yml and claude-code-review.yml used actions/checkout@v4 while test.yml and release-version-check.yml pin the v4.2.2 commit SHA; they now pin the same SHA. The commented-out starter-template settings (prompt, claude_args, paths, author filter) are removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(scripts): index every script and list removal candidates New scripts/README.md gives one line per top-level script and scripts directory, marked keep, dev-only or diagnostic, and lists the eight scripts nothing in the repo refers to as candidates for removal (kept for now). The install, utils and dev READMEs now list the files they were missing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test: tighten two checks that mutation testing showed were too loose - The wifi sudoers check matched `visudo -c -f "$TEMP_SUDOERS"` in the error report too, so replacing the check with `if false` still passed. It now requires the command as the condition. - The summary test never had the setup access point up, so reinstating the bogus "Password: ledmatrix123" line went unnoticed. A case with hostapd active now checks the AP is described as open. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(permissions): describe the repaired fix_perms scripts and new WiFi grants Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(changelog): docs-scripts Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>	2026-09-24 17:31:41 -04:00
ChuckandClaude Opus 5	69d408b321	feat(core): one per-element display-customization framework, wired into the web UI (#566) ... * fix(sports): rebuild un-shared faces through the pinned layout engine unshare_element_fonts re-instantiates a duplicate font face so two elements can be told apart by id(). It did so through bare ImageFont.truetype, which takes PIL's default layout engine rather than the one src/common/font_layout.py pins. Raqm and Basic disagree on fractional advances -- that disagreement is the reason the pin exists, having broken golden images across machines -- so a rebuilt face could measure differently from the shared face it replaced, on any host where Raqm is installed. These were the only two call sites in src/ bypassing the pin. The guard asserts that the rebuild goes through the pinned loader rather than comparing engine values: where Raqm is absent, bare truetype returns BASIC anyway, so an engine comparison passes whether or not the pin is honoured. The first draft of this test did exactly that and passed with the bug reintroduced. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(web): drop the two dead client-side config-form renderers generateConfigForm and generateSimpleConfigForm (580 lines) were defined on the Alpine component and never called: server-side Jinja replaced them, as pages_v3.py:641 records. Nothing in any template invokes them -- there is no x-html in the templates and no bracket access on the component. They carried their own x-widget dispatch, which made them an active trap: the next person adding a widget would reasonably think both renderers needed updating. plugins/config_manager.js (PluginConfigManager, 133 lines) goes for the same reason -- loaded on every page from base.html, referenced only by itself and by an archived doc. Kept, having checked them: widgets/example-color-picker.js is the worked example docs/widget-guide.md points plugin authors at, and widgets/plugin-loader.js is the client half of a documented feature (manifest-declared plugin widgets) whose server route is missing -- soccer-scoreboard already ships a widgets/custom-leagues.js that this loader is meant to fetch. That is an unfinished feature to complete, not dead code to delete. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(web): serve plugin-declared widgets, and actually ask for them LEDMatrixWidgets.loadPluginWidget has always fetched /static/plugin-widgets/<plugin>/<widget>.js, and docs/widget-guide.md has always documented that path, but nothing served it. soccer-scoreboard has shipped a 17KB widgets/custom-leagues.js since August that could never load. Both halves were missing, not just the route: - serve_plugin_widget serves the script from the plugin's widgets/ directory as text/javascript. The manifest is the allowlist -- only a widget the plugin declares is reachable -- so installing a plugin does not publish everything it ships. Path handling mirrors the sibling serve_plugin_web_ui: allowlist regexes, os.path.basename, resolve() + relative_to() containment, and the ledmatrix- prefix fallback. The declared script name is guarded too, since it comes from the plugin rather than the request. - The config form never requested one. Its x-widget dispatch is a hardcoded list of core widget names, so a plugin's own widget fell through to a plain text input. An unrecognised x-widget on a string field now asks ensureWidget() for it. The text input stays as the fallback and is removed only once the widget has actually rendered, so a missing or broken widget costs the user an editor rather than their configured value on the next save. - manifest_schema.json gains "widgets", so the declaration is validated rather than merely tolerated by additionalProperties. Verified in a browser against the real partial: a declared widget loads, registers and renders, and its field posts exactly one value; a field whose widget 404s keeps its text input and still posts its value. Not addressed: loadPluginWidgetsFromManifest still has no caller. The per-field ensureWidget path is lazier and is what the form now uses, so that bulk helper is dead weight -- worth removing, but left alone here rather than inventing a call site for it. Known limitation, documented: only string-typed fields take this path. object/array/boolean/number fields and enums are dispatched by the template's own branches, which still only know core widgets. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(element-style): a wrong-size BDF now keeps its font, not its size BDF fonts are fixed-size bitmap strikes: FreeType accepts only the pixel size baked into the file and raises for anything else. 32 of the 35 shipped fonts are BDF, so a size picked in the web UI usually is not a valid strike -- and load_font caught that failure with its generic "unloadable font" handler, which substitutes PressStart2P. Asking for 5x7.bdf at size 10 therefore rendered a completely different typeface, silently. It now falls back to the file's own native size instead, which is what SportsCore._load_custom_font_from_element_config has always done. The native size is read via FontManager._read_bdf_native_size rather than a fourth copy of that parser, matching how core.py already delegates. Also here, because they are the same code path: - native_bdf_size() is exposed for the web UI, which needs to know when a size field can take effect at all. None means "free choice". - ElementStyle.font_size now reports the size actually realised rather than the one requested. Callers lay out from it, and reserving space for a size nothing was drawn at is how this surfaces. - The module font cache is a bounded LRU (256) instead of an unbounded dict. The display process runs for weeks and every config save can add a (font, size) pair; every other hot cache in the codebase is bounded this way. Untouched configs are unaffected: the shipped classic fonts are the three TTFs, so nothing was hitting the substitution path by default. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(element-style): per-mode style and offset overrides Lets one element be styled differently per situation -- a scoreboard's live / upcoming / recent cards, weather's current / hourly / daily screens -- under customization.modes.<mode>. The mode is bound at construction rather than passed per call. That is what makes this cheap to adopt: SportsUpcoming and SportsRecent are already separate instances with distinct SKIN_MODE values, so binding once makes every existing style()/offset_value() call site mode-aware without editing any of them. A per-call mode argument exists for the rare host that renders more than one mode. The two layers answer different questions, deliberately: - The base layer keeps the existing "differs from the schema default" rule, because the save flow writes the full default object into config.json whether or not the user touched it. - A mode layer is pure override -- its fields default to None, so presence is intent. Nothing writes into it unasked, so there is nothing for the stricter rule to protect against. None therefore means inherit, and has to stay distinct from 0: a mode y_offset of 0 means "sit at the base position", not "no preference". This is the same distinction scroll_card.switch_* draws with "inherit". A malformed mode value falls back to the resolved base value rather than to the caller's default -- caught by the degradation tests, which is what they are for: resolving the mode first let one bad string in a mode block silently discard a good base offset. With no modes block, and for every existing caller, resolution is unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(element-style): declare per-mode overrides in config_schema.json A plugin adds "x-style-modes": ["live", "upcoming", "recent"] alongside its x-style-elements declaration and gets a customization.modes.<mode> group per mode, with every field of every declared element repeated as an override. Those override fields are typed nullable and default to null, which is the whole trick. The save flow writes schema defaults into config.json wholesale, so giving a mode field the base element's default would make every mode a frozen copy of the base the first time a user pressed Save, and the base would stop reaching them. Null means inherit. The mutation test for this is explicit: with concrete defaults, a base font_size of 14 resolves as 10 with user_forced set. min/max from the declaration carry into the mode blocks, so an out-of-range override is rejected by validation rather than clamped silently at render time. Also: the emitted font field now carries "x-widget": "font-selector". The widget already shipped and the config form already allowlisted it -- the hint was simply never emitted, so the field rendered as a bare text box that the user had to type a font filename into. Verified through the real SchemaManager path -- load_schema, defaults extraction, merge_with_defaults, validation, then resolution -- rather than against a hand-built dict, since the thing at risk is what that pipeline does to a null. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(web): render the config form from the schema the save route validates The form read config_schema.json with a raw json.load while api_v3.save_plugin_config went through SchemaManager. Those are not the same schema: SchemaManager applies expand_style_elements, which turns a compact customization.x-style-elements declaration into the per-element blocks the form knows how to render. Without it, that customization object has an x-style-elements key and no "properties", so the template's object branch matched nothing and the section rendered as empty space -- while saving still validated against the expanded shape. of-the-day ships the compact form, so its customization section has been invisible in the web UI. pages_v3 gains a schema_manager the way it already has config_manager and plugin_manager. use_cache=False matches the save route, so an edited schema is not served stale during plugin development. The raw read stays as a fallback for callers that register this blueprint without one. Checked before making the change: load_schema does nothing here except read, validate and expand -- inject_skin_selector is a separate method it does not call -- so this is not a behaviour change for schemas without the declaration. The test pair renders the same compact schema with and without a SchemaManager, so it documents exactly what was broken as well as what is fixed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(web): style-editor widget -- a row per element instead of 65 accordions Rendered element by element, a realistic scoreboard's customization block is 65 nested sections, and reaching one per-mode font size takes five levels of expanding. The widget collapses that to one compact row per element -- font, size, colour, X, Y -- with a tab per declared mode. It emits ordinary inputs under the same dotted names the generic renderer would produce, so the save/validate/merge pipeline is untouched: no hidden JSON blob and no new server-side parsing. It is driven entirely by the schema block it is handed, so fields added to the schema later appear without editing the widget. If it fails to load or throws, the generic nested rendering it replaces is left in place. Fixing two things the save path got wrong for nullable fields, found by posting what the widget actually emits: - The indexed-array recombiner (text_color.0/.1/.2 -> one list) compared the declared type to the string 'array', so a per-mode colour, typed ["array", "null"], was never reassembled and failed validation on save. _parse_form_value_with_schema had the same comparison. - A blank nullable field became [] rather than None, which then failed the minItems the colour array declares. Null is the inherit sentinel, so it has to survive. And two things the widget itself got wrong, found by looking at it: - An unset base control fell back to the select's first option, so an untouched scoreboard claimed every element used 10x20.bdf -- and the size box then locked itself to that bitmap font's fixed size. Base controls now show the schema default; mode controls stay blank, because blank there means inherit. - Elements arrived alphabetised (Detail and Odds above Score). Flask's JSON provider sorts keys, so declaration order has to be stated explicitly; expand_style_elements now emits x-propertyOrder, which the generic renderer already honoured too. Size is disabled and shown as fixed for a bitmap font, using the scalable/native_size the font catalog now reports. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(element-style): visibility, alignment and scale per element Completes the customization vocabulary: hide an element, align it, and resize a logo, alongside the font/size/colour/offset that already existed. All three per mode. They resolve to "change nothing" until the user asks for something -- True, None and 1.0 -- rather than to whatever the schema declares. That is the same invariant the font fields keep: a caller that honours them still renders an untouched config exactly as it did before they existed. A schema default therefore does not count as a choice, which matters because the save flow writes that default into config either way. scale sits in the layout block with the offsets rather than in the element block, because it is geometry: a logo has a scale and no font. The widget's columns come from the schema, so a logo row shows visibility, offsets and scale and no empty font cell. Two bugs found by the tests rather than by reading: - A nullable enum needs null in its enum list, not just in its type. The mode copy of `align` defaulted to null and then failed its own schema, so a plugin declaring any enum field with modes could not save at all. Six tests failed on this before any of them reached what they were testing. - defaults_from_schema only ever extracted font/font_size/text_color, so the schema defaults for the new fields were invisible to the resolver and a declared default read as a user choice. Widget: the table scrolls horizontally and pins the element-name column. Nine columns do not fit the config panel, and clipping them hid the offsets entirely while scrolling them made every row anonymous. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(element-style): resolve elements under the names plugins actually use Two naming conventions collided as the scoreboards grew. Counted across the published schemas: the style block names elements with a _text suffix (score_text, status_text, detail_text), while the layout block mostly uses the bare noun (score, date, time, odds) -- except status_text, which kept the suffix in seven plugins and lost it in two. records vs record splits seven to two the same way. A lookup now tries the exact name first and then the spellings that mean the same thing. Exact-first is what makes this inert for any config that already matches; the aliases only decide cases that resolved to nothing before. This is also what makes migrating to the compact declaration form safe. That form uses one key for both blocks, so a scoreboard adopting it asks for layout.score_text while its users have layout.score saved -- without the aliases, every offset they had dialled in would silently become 0. Applies to the style block, the layout block, the schema defaults and the per-mode overrides, since the drift shows up in all four. Not attempting to canonicalise on write: renaming keys in config.json would break the plugins still reading the old spelling from their own bundled code, and the drift costs a dict miss rather than correctness. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(plugins): BasePlugin.styles -- per-element styling every plugin inherits Adopting the element-style system meant repeating three things in every plugin: a guarded import, finding its own config_schema.json, and rebuilding the resolver when on_config_change swapped the config dict. This is those three things once, on the class all 45 plugins already inherit from. title = self.styles.style('title_text', classic_font='PressStart2P-Regular.ttf', classic_size=8, classic_color=(255, 255, 255)) The classic_* arguments are the adoption contract: with nothing configured they come back verbatim, so a plugin that switches to this renders exactly as before until a user changes something. A plugin with one instance per display mode sets STYLE_MODE on the class and every existing lookup becomes mode-aware without a call site changing -- which is the point of binding the mode to the resolver rather than passing it per call. styles_for() covers a plugin that renders several modes from one instance. Schema discovery reads the concrete class's own module rather than this file, because this file lives in src/plugin_system where no plugin schema exists -- the same trap SportsCore._config_schema_path documents. The first mutation test for that passed anyway: an installed plugin's module directory and its entry under plugins_dir are the same path, so the test could not tell the two apart. The case where they diverge is a plugin symlinked in for development, and the test now forces that shape. Getting discovery wrong is silent rather than loud: with no schema the resolver has no defaults to compare against, so every configured value reads as a deliberate override and the plugin quietly stops honouring its own shipped styling. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(element-style): adopt hand-written customization blocks, and widen the font list Nineteen plugins spell their style elements out longhand instead of declaring them -- football's block is 701 lines for seven elements -- and predate this system entirely. Core now recognises that shape, so they pick up the row-per-element editor and the real font picker on a core update rather than on a plugin release. Checked against every published schema: 21 plugins adopt, and the defaults of each still validate against the schema generated for it. Detection requires *every* field in a block to be one this system understands. A looser "has at least one style field" rule sweeps in baseball's `count`, which carries a text_color beside geometry that means nothing here. That distinction took three attempts to test: the first two assertions passed under both rules, because an over-eager rule leaves a fontless block looking untouched and only surfaces as an extra row in the editor. The hardcoded font enum is replaced rather than extended. Football lists five of the thirty-five installed fonts, which is why a font a user uploads can never appear in one. It is not a curated safe set -- it omits some twenty other faces that fit the declared size cap just as well -- it is the fonts that happened to exist when it was written. Widening it does need a guard, though, and not the one the schema already has: a bitmap font ignores font_size and renders at its size baked into the file, so `maximum: 16` cannot stop a 27px face. The picker now filters out fixed-size fonts taller than the element's own declared ceiling, which drops exactly the four that would overflow a 32px panel and keeps the other thirty. Per-mode overrides stay opt-in: core cannot invent a plugin's display modes, so `x-style-modes` remains the one line that unlocks them. Their layout half covers every positionable element rather than only those with a style block -- the two namespaces do not line up in a hand-written schema, and football positions six things (logos, timeouts, possession) that have no style block at all. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(web): remove the two Fonts-tab panels that reported invented data "Element Font Overrides" let a user configure an override, showed a success toast, and changed nothing. All three endpoints behind it were stubs -- GET returned a hardcoded {}, POST and DELETE returned success without calling anything -- each marked "This would integrate with the actual font system". Wiring them to FontManager would not have fixed it. The machinery there is real (_load_overrides/_save_overrides persist config/font_overrides.json, resolve_font applies them, and the countdown plugin genuinely consumes it), but the panel's element dropdown offered eleven invented keys -- nfl.live.score, clock.time, weather.current -- that no plugin has ever read. An override saved against one of those would have persisted correctly and still done nothing. "Detected Manager Fonts" goes for the same reason. It claimed to show "fonts currently in use by managers (auto-detected)"; its own comment said "we'll simulate this", and it listed every font in the catalog with a hardcoded usage_count of 1 -- the panel beside it, with fabricated numbers attached. Per-element font choice now lives in each plugin's own config editor, against the elements that plugin actually has, and covers size, colour, offsets, visibility, alignment and scale rather than family and size. Kept: the font library (upload, preview, delete), which works, and /fonts/tokens, which is a stub but genuinely feeds the preview's size dropdown. FontManager's override methods are untouched -- countdown uses them. Verified in a browser with the tab's JS running: no console errors, 35 fonts listed, upload and preview intact. Removing the panel meant unwiring it from populateFontSelects too, which would otherwise have bailed out early on the missing select and left the preview dropdown empty. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(sports): one reader for element colours and layout offsets There were two copies of the per-element colour read and three of the layout-offset read. They had already drifted -- the scroll-card renderer carries a comment about having ignored offsets its own schema advertised -- and each new capability had to be added to all of them or silently work in some places and not others. All of them now go through src.element_style, which is what carries the alias handling and the per-mode lookup. That lands immediately for the nine plugins importing these modules: a scoreboard asking for `score_text` offsets finds the `layout.score` its users configured, and a Live instance resolves its own colours through SKIN_MODE without any call site passing a mode. _normalize_color learned "#RRGGBB" in the process. The scoreboards' own readers have always accepted it, so the shared one had to, or consolidating would have quietly dropped a form users' configs may hold. _coerce_offset picked up the non-finite guard the scroll-card reader had and the other two did not. _get_layout_offset is promoted onto SportsCoreSharedMixin. Each plugin still carries its own copy in its bundled sports.py, which wins by MRO -- so adopting this is a deletion in the plugin, and until that deletion nothing changes for it. Note for whoever runs the suite next: test_display_dirty_tracking.py is order-dependent. Fifteen of its tests failed in one full run and passed in the next with no change in between, and pass in isolation. Pre-existing, unrelated to this, but it makes a full-run diff untrustworthy until it is fixed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(changelog): record the element-style work under Unreleased This file's own preamble asks for it: a plugin may delete its bundled fallback copy of a core module only when its manifest floors on the first release that shipped that module, which requires the additions to be recorded here against a version. Names a plugin can now import and floor on -- the stateless layout_offset and element_color readers, alias_keys, native_bdf_size, the resolver's mode binding, BasePlugin.styles, and the promoted SportsCoreSharedMixin._get_layout_offset -- plus the schema and web-UI changes, the four fixes and the three removals. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(fonts): log the BDF native-size read failure instead of swallowing it The bdf-native-size lookup in get_fonts_catalog() caught any exception and silently discarded it. Every other guarded read added in this PR (the manifest parse in _declared_widget_script, the SchemaManager fallback in _load_plugin_config_partial) logs before falling through to the same degraded behavior. This one didn't, which is the shape a silent-exception-swallow lint rule flags. Behavior is unchanged -- native_size still comes back None -- but a corrupt or unreadable BDF file now leaves a trace. Verified: font-related tests (140) and the full suite still pass, with only the 2 pre-existing Europe/Kiev/Asia/Calcutta tzdata-alias failures already present on origin/main. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix: address CodeRabbit findings on the style-editor/font-selector PR - Fix _load_font_sized double-wrapping the (font, size) tuple on the missing-font path, which handed callers a tuple instead of a font. - Fix _set_nested_value skipping an explicit None when the key already existed, which silently kept stale overrides when a user cleared a nullable per-mode field or blanked all channels of an indexed color. - Preserve BDF scalable/native_size metadata through fetchFontCatalog's catalog-format mapping so maxFixedSize filtering actually applies. - Stop caching an empty array on a failed font-catalog fetch so a later call can retry instead of being stuck with the failed result. - Keep a saved font selected in the style editor even when it no longer fits a newly declared maxFixedSize, instead of silently deselecting it. - Don't drop in-progress user edits to fallback fields when a plugin widget finishes loading asynchronously and takes over the form. - Tighten the removed font-override endpoint test to assert 405, not just != 200. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(web): a partial save no longer switches off checkboxes it never showed An HTML checkbox posts nothing when unchecked, so the save route walked the schema and forced every boolean missing from the form to False. That is right for the rendered form and wrong for every other caller: a script, the MQTT bridge or a curl against the documented endpoint never rendered a checkbox, and reading its silence as "all off" turns a one-field save into a mass disable. Found on hardware. Posting four customization.* keys to a live device switched off nfl.enabled, ncaa_fb.enabled and every display-mode toggle in one request. The form now reports the top-level sections it drew (__rendered_section), and inside those an absent checkbox still means unchecked -- including a section whose only fields are checkboxes that are all off, which no heuristic could recover. A post with no marker only touches objects it actually posted a field from. Meta fields are dropped before form keys are treated as config paths, because unknown keys are otherwise written straight into config.json. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(sports): resolve element colour by name, and honour visible/align/scale Two of the three gaps this framework shipped with. Colour by name. A draw resolved its colour by comparing the *identity* of the font object it was handed, which cannot tell two elements apart when they share a face -- so those draws went out white. Every bitmap font is in that case, because a freetype.Face cannot be re-instantiated to un-share it, which is how an element rendered in any of the 32 shipped BDF fonts silently lost a colour its picker had offered all along. _draw_text_with_outline now takes element="score_text" and reads the colour by name; the identity path remains for un-annotated callers, but narrows before giving up -- one configured colour among the sharers is the only thing the user can have meant. Visible, align and scale. The resolver has understood these since the framework landed and nothing consumed them: an element could be marked hidden in the web UI and still render. Adds the stateless readers, the mixin accessors, and a scale parameter on the one shared logo-sizing seam (keyed into the cache, so two elements scaled differently cannot be served each other's image). Naming an element in a draw also honours its visibility. Untouched configs are unaffected: every new parameter defaults to today's behaviour, and all ten affected plugins render pixel-identically to main across every harness size. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(plugins): how to declare styleable elements; harden the widget's lookups The plugin-author guide for the compact x-style-elements declaration -- what each key does, how to read values back without breaking the "user-forced only when it differs from the default" rule, and why a hand-written block needs no changes to be adopted. Also clears the static-analysis findings on style-editor.js. Every lookup in that file is keyed by something out of a schema or a saved config, so a key of __proto__ or constructor would walk the prototype chain and hand back a function instead of a schema; reads now go through an own-property helper. The panel registry became a list, and the flagged vars moved to their function roots. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(web): clear the remaining static-analysis findings Five, all on lines this branch touched. The Python one is not a new defect: _set_missing_booleans_to_false's first parameter was always named `config`, which shadows the `config` submodule imported for its side effects at the bottom of this module. Editing the signature simply put the existing warning on a changed line. The parameter is the plugin's config dict, so `plugin_config` is what it should have been called anyway; callers pass it positionally and are unaffected. The JavaScript ones are the object-injection rule firing on reads keyed by data. own() now goes through a property descriptor, so the one unavoidable data-keyed read is no longer a computed member access; at() consumes its path instead of indexing it; and the column set is a Map, which has no prototype to pollute and needs no guarded reads at all. Verified the widget still renders identically against football's real schema: 29 element rows, all four mode tabs, values populated, no console errors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(web): drop the hasOwnProperty alias the descriptor read made redundant own() now reads through Object.getOwnPropertyDescriptor, so the alias it used to call has no remaining reference. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-09-13 11:53:50 -04:00
3 people	6812dfe7a6	docs: refresh and correct stale documentation across repo (#306) ... * docs: refresh and correct stale documentation across repo Walked the README and docs/ tree against current code and fixed several real bugs and many stale references. Highlights: User-facing - README.md: web interface install instructions referenced install_web_service.sh at the repo root, but it actually lives at scripts/install/install_web_service.sh. - docs/GETTING_STARTED.md: every web UI port reference said 5050, but the real server in web_interface/start.py:123 binds 5000. Same bug was duplicated in docs/TROUBLESHOOTING.md (17 occurrences). Fixed both. - docs/GETTING_STARTED.md: rewrote tab-by-tab instructions. The doc referenced "Plugin Store", "Plugin Management", "Sports Configuration", "Durations", and "Font Management" tabs - none of which exist. Real tabs (verified in web_interface/templates/v3/base.html) are: Overview, General, WiFi, Schedule, Display, Config Editor, Fonts, Logs, Cache, Operation History, Plugin Manager (+ per-plugin tabs). - docs/GETTING_STARTED.md: removed references to a "Test Display" button (doesn't exist) and "Show Now" / "Stop" plugin buttons. Real controls are "Run On-Demand" / "Stop On-Demand" inside each plugin's tab (partials/plugin_config.html:792). - docs/TROUBLESHOOTING.md: removed dead reference to troubleshoot_weather.sh (doesn't exist anywhere in the repo); weather is now a plugin in ledmatrix-plugins. Developer-facing - docs/PLUGIN_API_REFERENCE.md: documented draw_image() doesn't exist on DisplayManager. Real plugins paste onto display_manager.image directly (verified in src/base_classes/{baseball,basketball,football, hockey}.py). Replaced with the canonical pattern. - docs/PLUGIN_API_REFERENCE.md: documented cache_manager.delete() doesn't exist. Real method is clear_cache(key=None). Updated the section. - docs/PLUGIN_API_REFERENCE.md: added 10 missing BasePlugin methods that the doc never mentioned: dynamic-duration hooks, live-priority hooks, and the full Vegas-mode interface. - docs/PLUGIN_DEVELOPMENT_GUIDE.md: same draw_image fix. - docs/DEVELOPMENT.md: corrected the "Plugin Submodules" section. Plugins are NOT git submodules - .gitmodules only contains rpi-rgb-led-matrix-master. Plugins are installed at runtime into the plugins directory configured by plugin_system.plugins_directory (default plugin-repos/). Both internal links in this doc were also broken (missing relative path adjustment). - docs/HOW_TO_RUN_TESTS.md: removed pytest-timeout from install line (not in requirements.txt) and corrected the test/integration/ path (real integration tests are at test/web_interface/integration/). Replaced the fictional file structure diagram with the real one. - docs/EMULATOR_SETUP_GUIDE.md: clone URL was a placeholder; default pixel_size was documented as 16 but emulator_config.json ships with 5. Index - docs/README.md: rewrote. Old index claimed "16-17 files after consolidation" but docs/ actually has 38 .md files. Four were missing from the index entirely (CONFIG_DEBUGGING, DEV_PREVIEW, PLUGIN_ERROR_HANDLING, STARLARK_APPS_GUIDE). Trimmed the navel-gazing consolidation/statistics sections. Out of scope but worth flagging: - src/plugin_system/resource_monitor.py:343 and src/common/api_helper.py:287 call cache_manager.delete(key) but no such method exists on CacheManager. Both call sites would AttributeError at runtime if hit. Not fixed in this docs PR - either add a delete() shim or convert callers to clear_cache(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix WEB_INTERFACE_GUIDE and WIFI_NETWORK_SETUP WEB_INTERFACE_GUIDE.md - Web UI port: 5050 -> 5000 (4 occurrences) - Tab list was almost entirely fictional. Documented tabs: General Settings, Display Settings, Durations, Sports Configuration, Plugin Management, Plugin Store, Font Management. None of these exist. Real tabs (verified in web_interface/templates/v3/base.html: 935-1000): Overview, General, WiFi, Schedule, Display, Config Editor, Fonts, Logs, Cache, Operation History, plus Plugin Manager and per-plugin tabs in the second nav row. Rewrote the navigation section, the General/Display/Plugin sections, and the Common Tasks walkthroughs to match. - Quick Actions list referenced "Test Display" button (doesn't exist). Replaced with the real button list verified in partials/overview.html:88-152: Start/Stop Display, Restart Display Service, Restart Web Service, Update Code, Reboot, Shutdown. - API endpoints used /api/* paths. The api_v3 blueprint mounts at /api/v3 (web_interface/app.py:144), so the real paths are /api/v3/config/main, /api/v3/system/status, etc. Fixed. - Removed bogus "Sports Configuration tab" walkthrough; sports favorites live inside each scoreboard plugin's own tab now. - Plugin directory listed as /plugins/. Real default is plugin-repos/ (verified in config/config.template.json:130 and display_controller.py:132); plugins/ is a fallback. - Removed "Swipe navigation between tabs" mobile claim (not implemented). WIFI_NETWORK_SETUP.md - 21 occurrences of port 5050 -> 5000. - All /api/wifi/* curl examples used the wrong path. The real wifi API routes are at /api/v3/wifi/* (api_v3.py:6367-6609). Fixed. - ap_password default was documented as "" (empty/open network) but config/wifi_config.json ships with "ledmatrix123". Updated the Quick Start, Configuration table, AP Mode Settings section, and Security Recommendations to match. Also clarified that setting ap_password to "" is the way to make it an open network. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix ADVANCED_FEATURES and REST_API_REFERENCE REST_API_REFERENCE.md - Wrong path: /fonts/delete/<font_family> -> /fonts/<font_family> (verified the real DELETE route in web_interface/blueprints/api_v3.py). - Diffed the documented routes against the real api_v3 blueprint (92 routes vs the 71 documented). Added missing sections: - Error tracking (/errors/summary, /errors/plugin/<id>, /errors/clear) - Health (/health) - Schedule dim/power (/config/dim-schedule GET/POST) - Plugin-specific endpoints (calendar/list-calendars, of-the-day/json/upload+delete, plugins/<id>/static/<path>) - Starlark Apps (12 endpoints: status, install-pixlet, apps CRUD, repository browse/install, upload) - Font preview (/fonts/preview) - Updated table of contents with the new sections. - Added a footer note that the API blueprint mounts at /api/v3 (app.py:144) and that SSE stream endpoints are defined directly on the Flask app at app.py:607-615. ADVANCED_FEATURES.md - Vegas Scroll Mode section was actually accurate (verified all config keys match src/vegas_mode/config.py:15-30). - On-Demand Display section had multiple bugs: - 5 occurrences of port 5050 -> 5000 - All API paths missing /v3 (e.g. /api/display/on-demand/start should be /api/v3/display/on-demand/start) - "Settings -> Plugin Management -> Show Now Button" UI flow doesn't exist. Real flow: open the plugin's tab in the second nav row, click Run On-Demand / Stop On-Demand. - "Python API Methods" section showed controller.show_on_demand() / clear_on_demand() / is_on_demand_active() / get_on_demand_info() — none of these methods exist on DisplayController. The on-demand machinery is all internal (_set_on_demand_*, _activate_on_demand, etc) and is driven through the cache_manager. Replaced the section with a note pointing to the REST API. - All Use Case Examples used the same fictional Python calls. Replaced with curl examples against the real API. - Cache Management section claimed "On-demand display uses Redis cache keys". LEDMatrix doesn't use Redis — verified with grep that src/cache_manager.py has no redis import. The cache is file-based, managed by CacheManager (file at /var/cache/ledmatrix/ or fallback paths). Rewrote the manual recovery section: - Removed redis-cli commands - Replaced cache.delete() Python calls with cache.clear_cache() (the real public method per the same bug already flagged in PLUGIN_API_REFERENCE.md) - Replaced "Settings -> Cache Management" with the real Cache tab - Documented the actual cache directory candidates - Background Data Service section: - Used "nfl_scoreboard" as the plugin id in the example. The real plugin is "football-scoreboard" (handles both NFL and NCAA). Fixed. - "Implementation Status: Phase 1 NFL only / Phase 2 planned" section was severely outdated. The background service is now used by all sports scoreboards (football, hockey, baseball, basketball, soccer, lacrosse, F1, UFC), the odds ticker, and the leaderboard plugin. Replaced with a current "Plugins using the background service" note. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix plugin config + store + dependency docs PLUGIN_STORE_GUIDE.md - 19 occurrences of port 5050 -> 5000 - All API paths missing /v3 (e.g. /api/plugins/install -> /api/v3/plugins/install). Bulk fix. PLUGIN_REGISTRY_SETUP_GUIDE.md - Same port + /api/v3 fixes (3 occurrences each) - "Go to Plugin Store tab" -> "Open the Plugin Manager tab and scroll to the Install from GitHub section" (the real flow for registry setup is the GitHub install section, not the Plugin Store search) PLUGIN_CONFIG_QUICK_START.md - Port 5001 -> 5000 (5001 is the dev_server.py default, not the web UI) - "Plugin Store tab" install flow -> real Plugin Manager + Plugin Store section + per-plugin tab in second nav row - Removed reference to PLUGIN_CONFIG_TABS_SUMMARY.md (archived doc) PLUGIN_CONFIGURATION_TABS.md - "Plugin Management vs Configuration" section confusingly described a "Plugins Tab" that doesn't exist as a single thing. Rewrote to describe the real two-piece structure: Plugin Manager tab (browse, install, toggle) vs per-plugin tabs (configure individual plugins). PLUGIN_DEPENDENCY_GUIDE.md - Port 5001 -> 5000 PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Wrong port (8080) and wrong UI nav ("Plugin Store or Plugin Management"). Fixed to the real flow. PLUGIN_QUICK_REFERENCE.md - "Plugin Location: ./plugins/ directory" -> default is plugin-repos/ (verified in config/config.template.json:130 and display_controller.py:132). plugins/ is a fallback. - File structure diagram showed plugins/ -> plugin-repos/. - Web UI install flow: "Plugin Store tab" -> "Plugin Manager tab -> Plugin Store section". Also fixed Configure ⚙️ button (doesn't exist) and "Drag and drop reorder" (not implemented). - API examples: replaced ad-hoc Python pseudocode with real curl examples against /api/v3/plugins/* endpoints. Pointed at REST_API_REFERENCE.md for the full list. - "Migration Path Phase 1-5" was a roadmap written before the plugin system shipped. The plugin system is now stable and live. Removed the migration phases as they're history, not a roadmap. - "Quick Migration" section called scripts/migrate_to_plugins.py which doesn't exist anywhere in the repo. Removed. - "Plugin Registry Structure" referenced ChuckBuilds/ledmatrix-plugin-registry which doesn't exist. The real registry is ChuckBuilds/ledmatrix-plugins. Fixed. - "Next Steps" / "Questions to Resolve" sections were pre-implementation planning notes. Replaced with a "Known Limitations" section that documents the actually-real gaps (sandboxing, resource limits, ratings, auto-updates). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix misc remaining docs (architecture, dev quickref, sub-dir READMEs) PLUGIN_ARCHITECTURE_SPEC.md - Added a banner at the top noting this is a historical design doc written before the plugin system shipped. The doc is ~1900 lines with 13 stale /api/plugins/* paths (real is /api/v3/plugins/*), references to web_interface_v2.py (current is app.py), and a Migration Strategy / Implementation Roadmap that's now history. Banner points readers at the current docs (PLUGIN_DEVELOPMENT_GUIDE, PLUGIN_API_REFERENCE, REST_API_REFERENCE) without needing to retrofit every section. PLUGIN_CONFIG_ARCHITECTURE.md - 10 occurrences of /api/plugins/* missing /v3 prefix. Bulk fixed. DEVELOPER_QUICK_REFERENCE.md - cache_manager.delete("key") -> cache_manager.clear_cache("key") with comment noting delete() doesn't exist. Same bug already documented in PLUGIN_API_REFERENCE.md. SSH_UNAVAILABLE_AFTER_INSTALL.md - 4 occurrences of port 5001 -> 5000 in AP-mode and Ethernet/WiFi recovery instructions. PLUGIN_CUSTOM_ICONS_FEATURE.md - Port 5001 -> 5000. CONFIG_DEBUGGING.md - Documented /api/v3/config/plugin/<id> and /api/v3/config/validate endpoints don't exist. Replaced with the real endpoints: /api/v3/config/main, /api/v3/plugins/schema?plugin_id=, /api/v3/plugins/config?plugin_id=. Added a note that validation runs server-side automatically on POST. STARLARK_APPS_GUIDE.md - "Plugins -> Starlark Apps" UI navigation path doesn't exist (5 occurrences). Replaced with the real path: Plugin Manager tab, then the per-plugin Starlark Apps tab in the second nav row. - "Navigate to Plugins" install step -> Plugin Manager tab. web_interface/README.md - Documented several endpoints that don't exist in the api_v3 blueprint: - GET /api/v3/plugins (list) -> /api/v3/plugins/installed - GET /api/v3/plugins/<id> -> doesn't exist - POST /api/v3/plugins/<id>/config -> POST /api/v3/plugins/config - GET /api/v3/plugins/<id>/enable + /disable -> POST /api/v3/plugins/toggle - GET /api/v3/store/plugins -> /api/v3/plugins/store/list - POST /api/v3/store/install/<id> -> POST /api/v3/plugins/install - POST /api/v3/store/uninstall/<id> -> POST /api/v3/plugins/uninstall - POST /api/v3/store/update/<id> -> POST /api/v3/plugins/update - POST /api/v3/display/start/stop/restart -> POST /api/v3/system/action - GET /api/v3/display/status -> GET /api/v3/system/status - Also fixed config/secrets.json -> config/config_secrets.json - Replaced the per-section endpoint duplication with a current real endpoint list and a pointer to docs/REST_API_REFERENCE.md. - Documented that SSE stream endpoints are defined directly on the Flask app at app.py:607-615, not in the api_v3 blueprint. scripts/install/README.md - Was missing 3 of the 9 install scripts in the directory: one-shot-install.sh, configure_wifi_permissions.sh, and debug_install.sh. Added them with brief descriptions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: clarify plugin paths and fix systemd manual install bug PLUGIN_DEVELOPMENT_GUIDE.md - Added a "Plugin directory note" callout near the top explaining the plugins/ vs plugin-repos/ split: - Dev workflow uses plugins/ (where dev_plugin_setup.sh creates symlinks) - Production / Plugin Store uses plugin-repos/ (the configurable default per config.template.json:130) - The plugin loader falls back to plugins/ so dev symlinks are picked up automatically (schema_manager.py:77) - User can set plugins_directory to "plugins" in the General tab if they want both to share a directory CLAUDE.md - The Project Structure section had plugins/ and plugin-repos/ exactly reversed: - Old: "plugins/ - Installed plugins directory (gitignored)" "plugin-repos/ - Development symlinks to monorepo plugin dirs" - Real: plugin-repos/ is the canonical Plugin Store install location and is not gitignored. plugins/* IS gitignored (verified in .gitignore) and is the legacy/dev location used by scripts/dev/dev_plugin_setup.sh. Reversed the descriptions and added line refs. systemd/README.md - "Manual Installation" section told users to copy the unit file directly to /etc/systemd/system/. Verified the unit file in systemd/ledmatrix.service contains __PROJECT_ROOT_DIR__ placeholders that the install scripts substitute at install time. A user following the manual steps would get a service that fails to start with "WorkingDirectory=__PROJECT_ROOT_DIR__" errors. Added a clear warning and a sed snippet that substitutes the placeholder before installing. src/common/README.md - Was missing 2 of the 11 utility modules in the directory (verified with ls): permission_utils.py and cli.py. Added brief descriptions for both. Out-of-scope code bug found while auditing (flagged but not fixed): - scripts/dev/dev_plugin_setup.sh:9 sets PROJECT_ROOT="$SCRIPT_DIR" which resolves to scripts/dev/, not the project root. This means the script's PLUGINS_DIR resolves to scripts/dev/plugins/ instead of the project's plugins/ — confirmed by the existence of scripts/dev/plugins/of-the-day/ from prior runs. Real fix is to set PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)". Not fixing in this docs PR. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: flag aspirational/regressed features in plugin docs These docs describe features that exist as documented in the doc but either never wired up or regressed when v3 shipped. Each gets a clear status banner so plugin authors don't waste time chasing features that don't actually work. FONT_MANAGER.md - The "For Plugin Developers / Plugin Font Registration" section documents adding a "fonts" block to manifest.json that gets registered via FontManager.register_plugin_fonts(). The method exists at src/font_manager.py:150 but is **never called from anywhere** in the codebase (verified: zero callers). A plugin shipping a manifest "fonts" block has its fonts silently ignored. Added a status warning and a note about how to actually ship plugin fonts (regular files in the plugin dir, loaded directly). PLUGIN_IMPLEMENTATION_SUMMARY.md - Added a top-level status banner. - Architecture diagram referenced src/plugin_system/registry_manager.py (which doesn't exist) and listed plugins/ as the install location. Replaced with the real file list (plugin_loader, schema_manager, health_monitor, operation_queue, state_manager) and pointed at plugin-repos/ as the default install location. - "Dependency Management: Virtual Environments" — verified there's no per-plugin venv. Removed the bullet and added a note that plugin Python deps install into the system Python environment, with no conflict resolution. - "Permission System: File Access Control / Network Access / Resource Limits / CPU and memory constraints" — none of these exist. There's a resource_monitor.py and health_monitor.py for metrics/warnings, but no hard caps or sandboxing. Replaced the section with what's actually implemented and a clear note that plugins run in the same process with full file/network access. PLUGIN_CUSTOM_ICONS.md and PLUGIN_CUSTOM_ICONS_FEATURE.md - The custom-icon feature was implemented in the v2 web interface via a getPluginIcon() helper in templates/index_v2.html that read the manifest "icon" field. When the v3 web interface was built, that helper wasn't ported. Verified in web_interface/templates/v3/base.html:515 and :774, plugin tab icons are hardcoded to `fas fa-puzzle-piece`. The "icon" field in plugin manifests is currently silently ignored (verified with grep across web_interface/ and src/plugin_system/ — zero non-action- related reads of plugin.icon or manifest.icon). - Added a status banner to both docs noting the regression so plugin authors don't think their custom icons are broken in their own plugin code. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix .cursor/ helper docs The .cursor/ directory holds the dev-side helper docs that Cursor and contributors using AI tooling rely on to bootstrap plugin development. Several of them had the same bug patterns as the user-facing docs. .cursor/plugin_templates/QUICK_START.md - "Adding Image Rendering" section showed display_manager.draw_image(image, x=0, y=0). That method doesn't exist on DisplayManager (same bug as PLUGIN_API_REFERENCE.md and PLUGIN_DEVELOPMENT_GUIDE.md). Replaced with the canonical display_manager.image.paste((x,y)) pattern, including the transparency-mask form. .cursor/plugins_guide.md - 10 occurrences of ./dev_plugin_setup.sh — the script lives at scripts/dev/dev_plugin_setup.sh, so anyone copy-pasting these examples gets "command not found". Bulk fixed via sed. - "Test with emulator: python run.py --emulator" — there's no --emulator flag. Replaced with the real options: EMULATOR=true python3 run.py for the full display, or scripts/dev_server.py for the dev preview. - Secrets management section showed a fictional "config_secrets": { "api_key": "my-plugin.api_key" } reference field. Verified in src/config_manager.py:162-172 that secrets are loaded by deep-merging config_secrets.json into the main config. There is no separate reference field — just put the secret under the same plugin namespace and read it from the merged config. Rewrote the section with the real pattern. - "ssh pi@raspberrypi" -> "ssh ledpi@your-pi-ip" (consistent with the rest of LEDMatrix docs which use ledpi as the default user) .cursor/README.md - Same ./dev_plugin_setup.sh -> ./scripts/dev/dev_plugin_setup.sh fix (×6 occurrences via replace_all). - Same "python run.py --emulator" -> "EMULATOR=true python3 run.py" fix. Also added a pointer to scripts/dev_server.py for previewing plugins without running the full display. - "Example Plugins: plugins/hockey-scoreboard/" — the canonical source is the ledmatrix-plugins repo. Installed copies land in plugin-repos/ or plugins/. Updated the line to point at the ledmatrix-plugins repo and explain both local locations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix .cursorrules — the file Cursor auto-loads to learn the API This is the file that Cursor reads to learn how plugin development works. Stale entries here directly mislead AI-assisted plugin authors on every new plugin. Several of the same bug patterns I've been fixing in the user-facing docs were here too. Display Manager section (highest impact) - "draw_image(image, x, y): Draw PIL Image" — that method doesn't exist on DisplayManager. Same bug already fixed in PLUGIN_API_REFERENCE.md, PLUGIN_DEVELOPMENT_GUIDE.md, ledmatrix-stocks/README.md, and .cursor/plugin_templates/QUICK_START.md. Removed the bullet and replaced it with a paragraph explaining the real pattern: paste onto display_manager.image directly, then update_display(). Includes the transparency-mask form. - Added the small_font/centered args to draw_text() since they're the ones that matter most for new plugin authors - Added draw_weather_icon since it's commonly used Cache Manager section - "delete(key): Remove cached value" — there's no delete() method on CacheManager. The real method is clear_cache(key=None) (also removes everything when called without args). Same bug as before. - Added get_cached_data_with_strategy and get_background_cached_data since contributors will hit these when working on sports plugins Plugin System Overview - "loaded from the plugins/ directory" — clarified that the default is plugin-repos/ (per config.template.json:130) with plugins/ as the dev fallback used by scripts/dev/dev_plugin_setup.sh Plugin Development Workflow - ./dev_plugin_setup.sh -> ./scripts/dev/dev_plugin_setup.sh (×2) - Manual setup step "Create directory in plugins/<plugin-id>/" -> plugin-repos/<plugin-id>/ as the canonical location - "Use emulator: python run.py --emulator or ./run_emulator.sh" — the --emulator flag doesn't exist; ./run_emulator.sh isn't at root (it lives at scripts/dev/run_emulator.sh). Replaced with the real options: scripts/dev_server.py for dev preview, or EMULATOR=true python3 run.py for the full emulator path. Configuration Management - "Reference secrets via config_secrets key in main config" — this is the same fictional reference syntax I just fixed in .cursor/plugins_guide.md. Verified in src/config_manager.py:162-172 that secrets are deep-merged into the main config; there's no separate reference field. Replaced with a clear explanation of the deep-merge approach. Code Organization - "plugins/<plugin-id>/" -> the canonical location is plugin-repos/<plugin-id>/ (or its dev-time symlink in plugins/) - "see plugins/hockey-scoreboard/ as reference" — the canonical source for example plugins is the ledmatrix-plugins repo. Updated the pointer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add LICENSE (GPL-3.0) and CONTRIBUTING.md LICENSE - The repository previously had no LICENSE file. The README and every downstream plugin README already reference GPL-3.0 ("same as LEDMatrix project"), but the canonical license text was missing — contributors had no formal record of what they were contributing under, and GitHub couldn't auto-detect the license for the repo banner. - Added the canonical GPL-3.0 text from https://www.gnu.org/licenses/gpl-3.0.txt (verbatim, 674 lines). - Compatibility verified: rpi-rgb-led-matrix is GPL-2.0-or-later (per its COPYING file and README; the "or any later version" clause in lib/*.h headers makes GPL-3.0 distribution legal). CONTRIBUTING.md - The repository had no CONTRIBUTING file. New contributors had to reconstruct the dev setup from DEVELOPMENT.md, PLUGIN_DEVELOPMENT_GUIDE.md, SUBMISSION.md, and the root README. - Added a single page covering: dev environment setup (preview server, emulator, hardware), running tests, PR submission flow, commit message convention, plugin contribution pointer, and the license terms contributors are agreeing to. > Note for the maintainer: I (the AI assistant doing this audit) am > selecting GPL-3.0 because every reference in the existing > documentation already says GPL-3.0 — this commit just makes that > declaration legally binding by adding the actual file. Please > confirm during PR review that GPL-3.0 is what you want; if you > prefer a different license, revert this commit before merging. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add CODE_OF_CONDUCT, SECURITY, PR template; link them from README Tier 1 organizational files that any open-source project at LEDMatrix's maturity is expected to have. None of these existed before. They're additive — no existing content was rewritten. CODE_OF_CONDUCT.md - Contributor Covenant 2.1 (the de facto standard for open-source projects). Mentions both the Discord and the GitHub Security Advisories channel for reporting violations. SECURITY.md - Private vulnerability disclosure flow with two channels: GitHub Security Advisories (preferred) and Discord DM. - Documents the project's known security model as intentional rather than vulnerabilities: no web UI auth, plugins run unsandboxed, display service runs as root for GPIO access, config_secrets.json is plaintext. These match the limitations already called out in PLUGIN_QUICK_REFERENCE.md and the audit flagging from earlier in this PR. - Out-of-scope section points users at upstream (rpi-rgb-led-matrix, third-party plugins) so reports land in the right place. .github/PULL_REQUEST_TEMPLATE.md - 10-line checklist that prompts for the things that would have caught the bugs in this very PR: did you load the changed plugin once, did you update docs alongside code, are there any plugin compatibility implications. - Linked from CONTRIBUTING.md for the full flow. README.md - Added a License section near the bottom (the README previously said nothing about the license despite the project being GPL-3.0). - Added a Contributing section pointing at CONTRIBUTING.md and SECURITY.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Customize bug report template for LEDMatrix hardware The bug_report.md template was the GitHub default and asked "Desktop (OS/Browser/Version)" and "Smartphone (Device/OS)" — neither of which is relevant for a project that runs on a Raspberry Pi with hardware LED panels. A user filing a bug under the old template was giving us none of the information we'd actually need to triage it. Replaced with a LEDMatrix-aware template that prompts for: - Pi model, OS/kernel, panel type, HAT/Bonnet, PWM jumper status, display chain dimensions - LEDMatrix git commit / release tag - Plugin id and version (if the bug is plugin-related) - Relevant config snippet (with redaction reminder for API keys) - journalctl log excerpt with the exact command to capture it - Optional photo of the actual display for visual issues Kept feature_request.md as-is — generic content there is fine. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix bare /api/plugins paths in PLUGIN_CONFIGURATION_TABS Found 5 more bare /api/plugins/* paths in PLUGIN_CONFIGURATION_TABS.md that I missed in the round 2 sweep — they're inside data flow diagrams and prose ("loaded via /api/plugins/installed", etc.) so the earlier grep over Markdown code blocks didn't catch them. Fixed all 5 to use /api/v3/plugins/* (the api_v3 blueprint mount path verified at web_interface/app.py:144). Also added a status banner noting that the "Implementation Details" section references the pre-v3 file layout (web_interface_v2.py, templates/index_v2.html) which no longer exists. The current implementation is in web_interface/app.py, blueprints/api_v3.py, and templates/v3/. Same kind of historical drift I flagged in PLUGIN_ARCHITECTURE_SPEC.md and the PLUGIN_CUSTOM_ICONS_FEATURE doc. The user-facing parts of the doc (Overview, Features, Form Generation Process) are still accurate. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(widgets): list the 20 undocumented built-in widgets The widget registry README documented 3 widgets (file-upload, checkbox-group, custom-feeds) but the directory contains 23 registered widgets total. A plugin author reading this doc would think those 3 were the only built-in options and either reach for a custom widget unnecessarily or settle for a generic text input. Verified the actual list with: grep -h "register('" web_interface/static/v3/js/widgets/*.js \ | sed -E "s|.*register\\('([^']+)'.*|\\1|" | sort -u Added an "Other Built-in Widgets" section after the 3 detailed sections, listing the remaining 20 with one-line descriptions organized by category: - Inputs (6): text-input, textarea, number-input, email-input, url-input, password-input - Selectors (7): select-dropdown, radio-group, toggle-switch, slider, color-picker, font-selector, timezone-selector - Date/time/scheduling (4): date-picker, day-selector, time-range, schedule-picker - Composite/data-source (2): array-table, google-calendar-picker - Internal (2): notification, base-widget Pointed at the .js source files as the canonical source for each widget's exact schema and options — keeps this list low-maintenance since I'm not duplicating each widget's full options table. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix README_NBA_LOGOS and PLUGIN_CONFIGURATION_GUIDE scripts/README_NBA_LOGOS.md - "python download_nba_logos.py" — wrong on two counts. The script is at scripts/download_nba_logos.py (not the project root), and "python" is Python 2 on most systems. Replaced all 4 occurrences with "python3 scripts/download_nba_logos.py". - The doc framed itself as the way to set up "the NBA leaderboard". The basketball/leaderboard functionality is now in the basketball-scoreboard and ledmatrix-leaderboard plugins (in the ledmatrix-plugins repo), which auto-download logos on first run. Reframed the script as a pre-population utility for offline / dev use cases. - Bumped the documented Python minimum from 3.7 to 3.9 to match the rest of the project. docs/PLUGIN_CONFIGURATION_GUIDE.md - The "Plugin Manifest" example was missing 3 fields the plugin loader actually requires: id, entry_point, and class_name. A contributor copying this manifest verbatim would get PluginError("No class_name in manifest") at load time — the same loader bug already found in stock-news. Added all three. - The same example showed config_schema as an inline object. The loader expects config_schema to be a file path string (e.g. "config_schema.json") with the actual schema in a separate JSON file — verified earlier in this audit. Fixed. - Added a paragraph explaining the loader's required fields and the case-sensitivity rule on class_name (the bug that broke hello-world's manifest before this PR fixed it). - "Plugin Manager Class" example had the wrong constructor signature: (config, display_manager, cache_manager, font_manager). The real BasePlugin.__init__ at base_plugin.py:53-60 takes (plugin_id, config, display_manager, cache_manager, plugin_manager). A copy-pasted example would TypeError on instantiation. Fixed, including a comment noting which attributes BasePlugin sets up. - Renamed the example class from MyPluginManager to MyPlugin to match the project convention (XxxPlugin / XxxScoreboardPlugin in actual plugins). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(requirements): document optional dependencies (scipy, psutil, Flask-Limiter) A doc-vs-code crosscheck of every Python import in src/ and web_interface/ against requirements.txt found 3 packages that the code uses but requirements.txt doesn't list. Verified with grep that all 3 are wrapped in try/except blocks with documented fallback paths, so they're optional features rather than missing required deps: - scipy src/common/scroll_helper.py:26 → from scipy.ndimage import shift; HAS_SCIPY flag. Used for sub-pixel interpolation in scrolling. Falls back to a simpler shift algorithm without it. - psutil src/plugin_system/resource_monitor.py:15 → import psutil; PSUTIL_AVAILABLE flag. Used for per-plugin CPU/memory monitoring. Silently no-ops without it. - flask-limiter web_interface/app.py:42-43 → from flask_limiter import Limiter; wrapped at the caller. Used for accidental-abuse rate limiting on the web interface (not security). Web interface starts without rate limiting when missing. These were latent in two ways: 1. A user reading requirements.txt thinks they have the full feature set after `pip install -r requirements.txt`, but they don't get smoother scrolling, plugin resource monitoring, or rate limiting. 2. A contributor who deletes one of the packages from their dev env wouldn't know which feature they just lost — the fallbacks are silent. Added an "Optional dependencies" section at the bottom of requirements.txt with the version constraint, the file:line where each is used, the feature it enables, and the install command. The comment-only format means `pip install -r requirements.txt` still gives the minimal-feature install (preserving current behavior), while users who want the full feature set can copy the explicit pip install commands. Other findings from the same scan that came back as false positives or known issues: - web_interface_v2: dead pattern flagged in earlier iteration (still no real implementation; affects 11+ plugins via the same try/except dead-fallback pattern) - urllib3: comes with `requests` transitively - All 'src.', 'web_interface.', 'rgbmatrix', 'RGBMatrixEmulator' imports: internal modules - base_plugin / plugin_manager / store_manager / mocks / visual_display_manager: relative imports to local modules - freetype: false positive (freetype-py is in requirements.txt under the package name) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: fix broken file references found by path-existence crosscheck Ran a doc-vs-filesystem crosscheck: extracted every backtick-quoted path with a file extension or known directory prefix from docs/*.md and verified each exists. After filtering false positives (placeholder paths, config keys mistaken for paths, paths inside docs that already have historical-status banners), found 4 real broken references — 3 fixed in docs, 1 fixed by creating the missing file: docs/HOW_TO_RUN_TESTS.md:339 - Claimed ".github/workflows/tests.yml" exists and runs pytest on multiple Python versions in CI. There is no such workflow. The only GitHub Actions file is security-audit.yml (bandit + semgrep). - Pytest runs locally but is NOT gated on PRs. - Replaced the fictional CI section with the actual state and a note explaining how someone could contribute a real test workflow. docs/MIGRATION_GUIDE.md:92 - Referenced scripts/fix_perms/README.md "(if exists)" — the hedge betrays that the writer wasn't sure. The README didn't exist. The 6 scripts in scripts/fix_perms/ were never documented. - Created the missing scripts/fix_perms/README.md from scratch with one-line descriptions of all 6 scripts (fix_assets, fix_cache, fix_plugin, fix_web, fix_nhl_cache, safe_plugin_rm) + when-to-use-each guidance + usage examples. - Updated MIGRATION_GUIDE link to drop the "(if exists)" hedge since the file now exists. docs/FONT_MANAGER.md:376 - "See test/font_manager_example.py for a complete working example" — that file does not exist. Verified by listing test/ directory. - Replaced with a pointer to src/font_manager.py itself and the existing scoreboard base classes in src/base_classes/ that actually use the font manager API in production. Path-existence check methodology: - Walked docs/ recursively, regex-extracted backtick-quoted paths matching either /\.(py|sh|json|yml|yaml|md|txt|service|html|js|css|ttf|bdf|png)/ or paths starting with known directory prefixes (scripts/, src/, config/, web_interface/, systemd/, assets/, docs/, test/, etc.) - Filtered out URLs, absolute paths (placeholders), and paths without slashes (likely not relative refs). - Checked existence relative to project root. - Out of 80 unique relative paths in docs/, 32 didn't exist on disk. Most were false positives (configkeys mistaken for paths, example placeholders like 'assets/myfont.ttf', historical references inside docs that already have status banners). The 4 above were genuine broken refs. This pattern is reusable for future iterations and worth wiring into CI (link checker like lychee, scoped to fenced code paths rather than just markdown links, would catch the same class). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: address CodeRabbit review comments on #306 Reviewed all 12 CodeRabbit comments on PR #306, verified each against the current code, and fixed the 11 valid ones. The 12th finding is a real code bug (cache_manager.delete() calls in api_helper.py and resource_monitor.py) that's already in the planned follow-up code-fix PR, so it stays out of this docs PR. Fixed: .cursor/plugins_guide.md, .cursor/README.md, .cursorrules - I claimed "there is no --emulator flag" in 3 places. Verified in run.py:19-20 that the -e/--emulator flag is defined and functional (it sets os.environ["EMULATOR"]="true" before the display imports). Other docs I didn't touch (.cursor/plugin_templates/QUICK_START.md, docs/PLUGIN_DEVELOPMENT_GUIDE.md) already use the flag correctly. Replaced all 3 wrong statements with accurate guidance that both forms work and explains the CLI flag's relationship to the env var. .cursorrules, docs/GETTING_STARTED.md, docs/WEB_INTERFACE_GUIDE.md, docs/PLUGIN_DEVELOPMENT_GUIDE.md - Four places claimed "the plugin loader also falls back to plugins/". Verified that PluginManager.discover_plugins() (src/plugin_system/plugin_manager.py:154) only scans the configured directory — no fallback. The fallback to plugins/ exists only in two narrower places: store_manager.py:1700-1718 (store install/update/uninstall operations) and schema_manager.py:70-80 (schema lookup for the web UI form generator). Rewrote all four mentions with the precise scope. Added a recommendation to set plugin_system.plugins_directory to "plugins" for the smoothest dev workflow with dev_plugin_setup.sh symlinks. docs/FONT_MANAGER.md - The "Status" warning told plugin authors to use display_manager.font_manager.resolve_font(...) as a workaround for loading plugin fonts. Verified in src/font_manager.py that resolve_font() takes a family name, not a file path — so the workaround as written doesn't actually work. Rewrote to tell authors to load the font directly with PIL or freetype-py in their plugin. - The same section said "the user-facing font override system in the Fonts tab still works for any element that's been registered via register_manager_font()". Verified in web_interface/blueprints/api_v3.py:5404-5428 that /api/v3/fonts/overrides is a placeholder implementation that returns empty arrays and contains "would integrate with the actual font system" comments — the Fonts tab does not have functional integration with register_manager_font() or the override system. Removed the false claim and added an explicit note that the tab is a placeholder. docs/ADVANCED_FEATURES.md:523 - The on-demand section said REST/UI calls write a request "into the cache manager (display_on_demand_config key)". Wrong — verified via grep that api_v3.py:1622 and :1687 write to display_on_demand_request, and display_on_demand_config is only written by the controller during activation (display_controller.py:1195, cleared at :1221). Corrected the key name and added controller file:line references so future readers can verify. docs/ADVANCED_FEATURES.md:803 - "Plugins using the background service" paragraph listed all scoreboard plugins but an orphaned "⏳ MLB (baseball)" bullet remained below from the old version of the section. Removed the orphan and added "baseball/MLB" to the inline list for clarity. web_interface/README.md - The POST /api/v3/system/action action list was incomplete. Verified in web_interface/app.py:1383,1386 that enable_autostart and disable_autostart are valid actions. Added both. - The Plugin Store section was missing GET /api/v3/plugins/store/github-status (verified at api_v3.py:3296). Added it. - The SSE line-range reference was app.py:607-615 but line 619 contains the "Exempt SSE streams from CSRF and add rate limiting" block that's semantically part of the same feature. Extended the range to 607-619. docs/GETTING_STARTED.md - Rows/Columns step said "Columns: 64 or 96 (match your hardware)". The web UI's validation accepts any integer in 16-128. Clarified that 64 and 96 are the common bundled-hardware values but the valid range is wider. Not addressed (out of scope for docs PR): - .cursorrules:184 CodeRabbit comment flagged the non-existent cache_manager.delete() calls in src/common/api_helper.py:287 and src/plugin_system/resource_monitor.py:343. These are real CODE bugs, not doc bugs, and they're the first item in the planned post-docs-refresh code-cleanup PR (see /home/chuck/.claude/plans/warm-imagining-river.md). The docs in this PR correctly state that delete() doesn't exist on CacheManager — the fix belongs in the follow-up code PR that either adds a delete() shim or updates the two callers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Chuck <chuck@example.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-07 21:04:25 -04:00
ChuckandChuck	71584d4361	Feature/widget registry system (#190) ... * chore: Update basketball-scoreboard submodule for odds font fix * feat(widgets): Add widget registry system for plugin configuration forms - Create core widget registry system (registry.js, base-widget.js) - Extract existing widgets to separate modules: - file-upload.js: Image upload with drag-and-drop, preview, delete, scheduling - checkbox-group.js: Multi-select checkboxes for array fields - custom-feeds.js: Table-based RSS feed editor with logo uploads - Implement plugin widget loading system (plugin-loader.js) - Add comprehensive documentation (widget-guide.md, README.md) - Include example custom widget (example-color-picker.js) - Maintain backwards compatibility with existing plugins - All widget handlers available globally for existing functionality This enables: - Reusable UI components for plugin configuration forms - Third-party plugins to create custom widgets without modifying LEDMatrix - Modular widget architecture for future enhancements Existing plugins (odds-ticker, static-image, news) continue to work without changes. * fix(widgets): Security and correctness fixes for widget system - base-widget.js: Fix escapeHtml to always escape (coerce to string first) - base-widget.js: Add sanitizeId helper for safe DOM ID usage - base-widget.js: Use DOM APIs in showError instead of innerHTML - checkbox-group.js: Normalize types in setValue for consistent comparison - custom-feeds.js: Implement setValue with full row creation logic - example-color-picker.js: Validate hex colors before using in style attributes - file-upload.js: Replace innerHTML with DOM creation to prevent XSS - file-upload.js: Preserve open schedule editors when updating image list - file-upload.js: Normalize types when filtering deleted files - file-upload.js: Sanitize imageId in openImageSchedule and all schedule handlers - file-upload.js: Fix max-files check order and use allowed_types from config - README.md: Add security guidance for ID sanitization in examples * fix(widgets): Additional security and error handling improvements - scripts/update_plugin_repos.py: Add explicit UTF-8 encoding and proper error handling for file operations - scripts/update_plugin_repos.py: Fix git fetch/pull error handling with returncode checks and specific exception types - base-widget.js: Guard notify method against undefined/null type parameter - file-upload.js: Remove inline handlers from schedule template, use addEventListener with data attributes - file-upload.js: Update hideUploadProgress to show dynamic file types from config instead of hardcoded list - README.md: Update Color Picker example to use sanitized fieldId throughout * fix(widgets): Update Slider example to use sanitized fieldId - Add sanitizeId helper to Slider example render, getValue, and setValue methods - Use sanitizedFieldId for all DOM IDs and query selectors - Maintain consistency with Color Picker example pattern * fix(plugins_manager): Move configurePlugin and togglePlugin to top of file - Move configurePlugin and togglePlugin definitions to top level (after uninstallPlugin) - Ensures these critical functions are available immediately when script loads - Fixes 'Critical functions not available after 20 attempts' error - Functions are now defined before any HTML rendering checks * fix(plugins_manager): Fix checkbox state saving using querySelector - Add escapeCssSelector helper function for safe CSS selector usage - Replace form.elements[actualKey] with form.querySelector for boolean fields - Properly handle checkbox checked state using element.checked property - Fix both schema-based and schema-less boolean field processing - Ensures checkboxes with dot notation names (nested fields) work correctly Fixes issue where checkbox states were not properly saved when field names use dot notation (e.g., 'display.scroll_enabled'). The form.elements collection doesn't reliably handle dot notation in bracket notation access. * fix(base.html): Fix form element lookup for dot notation field names - Add escapeCssSelector helper function (both as method and standalone) - Replace form.elements[key] with form.querySelector for element type detection - Fixes element lookup failures when field names use dot notation - Ensures checkbox and multi-select skipping logic works correctly - Applies fix to both Alpine.js method and standalone function This complements the fix in plugins_manager.js to ensure all form element lookups handle nested field names (e.g., 'display.scroll_enabled') reliably across the entire web interface. * fix(plugins_manager): Add race condition protection to togglePlugin - Initialize window._pluginToggleRequests map for per-plugin request tokens - Generate unique token for each toggle request to track in-flight requests - Disable checkbox and wrapper UI during request to prevent overlapping toggles - Add visual feedback with opacity and pointer-events-none classes - Verify token matches before applying response updates (both success and error) - Ignore out-of-order responses to preserve latest user intent - Clear token and re-enable UI after request completes Prevents race conditions when users rapidly toggle plugins, ensuring only the latest toggle request's response affects the UI state. * refactor(escapeCssSelector): Use CSS.escape() for better selector safety - Prefer CSS.escape() when available for proper CSS selector escaping - Handles edge cases: unicode characters, leading digits, and spec compliance - Keep regex-based fallback for older browsers without CSS.escape support - Update all three instances: plugins_manager.js and both in base.html CSS.escape() is the standard API for escaping CSS selectors and provides more robust handling than custom regex, especially for unicode and edge cases. * fix(plugins_manager): Fix syntax error - missing closing brace for file-upload if block - Add missing closing brace before else-if for checkbox-group widget - Fixes 'Unexpected token else' error at line 3138 - The if block for file-upload widget (line 3034) was missing its closing brace - Now properly structured: if (file-upload) { ... } else if (checkbox-group) { ... } * fix(plugins_manager): Fix indentation in file-upload widget if block - Properly indent all code inside the file-upload if block - Fix template string closing brace indentation - Ensures proper structure: if (file-upload) { ... } else if (checkbox-group) { ... } - Resolves syntax error at line 3138 * fix(plugins_manager): Skip checkbox-group [] inputs to prevent config leakage - Add skip logic for keys ending with '[]' in handlePluginConfigSubmit - Prevents checkbox-group bracket notation inputs from leaking into config - Checkbox-group widgets emit name="...[]" checkboxes plus a _data JSON field - The _data field is already processed correctly, so [] inputs are redundant - Prevents schema validation failures and extra config keys The checkbox-group widget creates: 1. Individual checkboxes with name="fullKey[]" (now skipped) 2. Hidden input with name="fullKey_data" containing JSON array (processed) 3. Sentinel hidden input with name="fullKey[]" and empty value (now skipped) * fix(plugins_manager): Normalize string booleans when checkbox input is missing - Fix boolean field processing to properly normalize string booleans in fallback path - Prevents "false"/"0" from being coerced to true when checkbox element is missing - Handles common string boolean representations: 'true', 'false', '1', '0', 'on', 'off' - Applies to both schema-based (lines 2386-2400) and schema-less (lines 2423-2433) paths When a checkbox element cannot be found, the fallback logic now: 1. Checks if value is a string and normalizes known boolean representations 2. Treats undefined/null as false 3. Coerces other types to boolean using Boolean() This ensures string values like "false" or "0" are correctly converted to false instead of being treated as truthy non-empty strings. * fix(base.html): Improve escapeCssSelector fallback to match CSS.escape behavior - Handle leading digits by converting to hex escape (e.g., '1' -> '\0031 ') - Handle leading whitespace by converting to hex escape (e.g., ' ' -> '\0020 ') - Escape internal spaces as '\ ' (preserving space in hex escapes) - Ensures trailing space after hex escapes per CSS spec - Applies to both Alpine.js method and standalone function The fallback now better matches CSS.escape() behavior for older browsers: 1. Escapes leading digits (0-9) as hex escapes with trailing space 2. Escapes leading whitespace as hex escapes with trailing space 3. Escapes all special characters as before 4. Escapes internal spaces while preserving hex escape format This prevents selector injection issues with field names starting with digits or whitespace, matching the standard CSS.escape() API behavior. --------- Co-authored-by: Chuck <chuck@example.com>	2026-01-16 14:09:38 -05:00