diff --git a/AGENTS.md b/AGENTS.md index 6b38685..5fbfd5a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — Project state, review findings, open items, and working rules **Last updated: 2026-08-30** (owner findings batch - vehicle pin, tile chevrons, select arrows, -SmartDeal dialog, address cache and pull-to-refresh; manifest `2026.8.30.16`, see sections AO and AP. +SmartDeal dialog, address cache and pull-to-refresh; manifest `2026.8.30.19`, see sections AO, AP and AQ. Before that: design-audit follow-through - the five priority items applied to both codebases, plus the location preview's wrong pin; manifest `2026.8.30.8`, see section AN. Before that: third parity round — the panel had never actually rendered Audi @@ -6007,6 +6007,49 @@ the flag disappear. A check that has never been seen to fail is not evidence of --- + +## AQ. `node --check` cannot verify the panel bundle - check it as a module (2026.8.30.19) + +**The failure.** `audi-dashboard-app.js` was syntactically broken from `2026.8.30.14` to `.18` - five +versions, all pushed to Gitea. The panel could not be parsed, `connectedCallback()` aborted, the +custom element ended up with **no shadow root at all**, and every page rendered blank. The owner hit +it on the real instance after updating to `.17` and restarting. + +**The cause** was a one-line editing mistake: the rationale comment for the "Zündung an" change went +*inside* a `${...}` expression instead of into the surrounding markup text. Inside `${ }` the content +is JavaScript, so ``) are explicitly legal under Annex B +of the language standard. The browser loads the very same file as a **module**, where they are +forbidden. So the project's habitual verification step is structurally incapable of catching this +class of error - it is not that it was run carelessly, it cannot find it. + +**Rule from now on:** verify the panel bundle with the module grammar before shipping. + +```bash +cp custom_components/audi_dashboard/frontend/audi-dashboard-app.js /tmp/probe.mjs && node --check /tmp/probe.mjs +``` + +The `.mjs` extension is the whole point - it switches Node to the same grammar the browser uses. Run +it over every file in `frontend/`, not just the big one. Applied retroactively across the day's +commits, this pinpointed `.14` as the first broken version in seconds. + +**A second failure made it last five versions.** After `.14` the panel tab was never reloaded. Every +later "verified live" statement about the panel ran against the still-resident old script and was +therefore worthless - the page kept working precisely *because* it was stale. **Reload the panel +after every deploy before claiming anything about it**, and confirm the version actually served: + +```js +performance.getEntriesByType('resource').filter(e => /audi-dashboard-app/.test(e.name)).map(e => e.name) +``` + +A blank panel has a reliable signature worth recognising: the element exists but `element.shadowRoot` +is `null`. That means `connectedCallback()` threw - look for a parse error in the bundle, not for a +rendering bug in a view. + +--- + ## Working conventions (observed — keep them) - German is the project language: identifiers, comments, commits, UI texts. Exceptions: