Repository navigation
Description
CSS Architecture Hardening — audited against main (2026-10-26)
Repository: masarray/arsonmix · baseline main commit 4f017acbfcfbbb7c646017e8c103daab0499fdc2 · GUI v0.8 visual contract and latest PR #34 retained. This is an architecture / audit handoff, not proof of a performance regression. No UI or audio files were modified in this audit.
Verified static inventory
- Canonical runtime stylesheet:
web/styles.css(~558,159 source characters, 850 physical lines). JUCECMakeLists.txtembeds it viajuce_add_binary_data;src/Main.cppserves/styles.cssastext/css.web/index.htmlloads it directly. - Offline
AR-MIX-Live-FX-Host-Standalone-v0.3.htmlembeds the byte-identical CSS (~558,159 characters); existing contract tests enforce this. GitHub Pages publishes that standalone viascripts/build_pages.py. - Four inline data assets in stylesheet: one Inter WOFF2 plus three PNG assets. Removing data URL payloads leaves ~79,150 characters of CSS; ~479,009 characters are embedded asset payloads. Font embedding is intentional for offline WebView2; do not extract into remote runtime HTTP dependencies.
- Lightweight brace-level source inventory: ~627 leaf rule blocks, ~466 distinct rule headers, 103 repeated header groups (many may be valid media variants; do NOT treat all as bugs), ~2,395 declarations, 90
!importantoccurrences, no@layerdeclaration. These counts are approximate syntax-level diagnostics, not an AST-validated cascade verdict. - Heuristic source cross-reference: 195 CSS class names; 32 were not found in
web/index.html,web/app.js,web/bridge.js,web/monitor.js, orweb/native-bridge.js(not proof of unreachable CSS). Examples:.right-rail(29 CSS references),.master-right(11),.mode-pill(10),.master-tabs(8). Verify in real DOM states before pruning. - Two other independently styled surfaces,
site/index.html(about 4.4k inline CSS chars) andsite/preview/index.html(about 2.0k). Explicitly assign those page styles a distinct owner from the mixer console.
Actionable root causes / risk register
H1 — Responsive cascade inversion: web/styles.css lines ~527–530 hide .toolbar .spec-buffer at <=1370 and .toolbar .scene-select at <=1190, but later unconditional base rules at ~542–543 restore display:flex. Later narrow media rules at ~553 and ~562 re-hide them. CSS specificity/order can consequently produce an unintended reappearance in the intermediate viewport ranges (e.g. 1251–1370 and 981–1190). Audit every breakpoint, consolidate responsive ownership, verify computed style at each boundary +/-1px.
H2 — Override-based Button 180 ownership: base/active/disabled Button 180 at ~609–658, geometry correction at ~671–678, state colors twice at ~679–688 and ~719–728, pressed recipe at ~698–716, and late hover/OFF rules at ~820–845. This is historical accretion, not one authoritative state machine. :is(...,#masterLeft ...) gives the whole selector the maximum branch specificity, even for generic buttons, increasing CSS friction. Important declarations add further lock-in. Consolidate without changing the accepted 3D shape/color/geometry/pressed behavior. transition:150ms all!important (~634) should be evaluated for explicit safe properties; do not assume performance improvement without profiling.
H3 — PAN multi-owner geometry: .pan-track::after repeated at source lines ~58, ~173, ~342, ~808; .pan-track .pan-fill around ~102, ~171, ~814; final offsets at ~807–815 use !important. The last approved offsets are groove top=13px, fill top=15px, center top=12px, layering 0/2/1/3 for groove/fill/detent/thumb as documented. Create exactly one component owner with those exact runtime values and asset bytes.
H4 — Legacy/unreachable surface risk: .right-rail, old .master-right, .mode-pill, .talk-btn, and source strip .fader-tools references may date from earlier layouts. #mixer > .strip:not(.master-strip) > .fader-tools{display:none!important} (~818) targets markup not emitted by present makeStrip; source strips already omit this bay, while MASTER retains its legitimate .fader-tools. Remove only after DOM selector reachability verified across MIX/FX Rack/Signal Flow, EASY/PRO, popovers and native-bridge states.
H5 — Inconsistent visual state & specificity: Button 180 disabled rule paints #dcdcdc!important (~656), visually distinct from approved dark OFF hardware; review whether this is appropriate for actual disabled states. One control may currently receive state through .active, .selected, .on, or aria-pressed. Define a canonical semantic mapping; preserve aria-pressed for accessibility and existing JS behavior.
H6 — Validation blind spots: tests/ui_smoke.py has many computed-style/geometry assertions and writes screenshot artifacts; it is not a fully automatic pixel-diff regression harness. Do not replace its structural tests with screenshots alone. Present documentation has cumulative historical directions (e.g. left-rail pushable description at GUI lock lines ~81–82 superseded by unified Button 180 at ~84–85), so document current-state precedence explicitly.
Target architecture / ownership (build-time modular, one runtime CSS)
web/styles-src/
00-assets.generated.css # embedded Inter/PNG, generated; licensing retained
01-tokens.css # color, radius, spacing, shadow and geometry tokens
02-foundation.css # only reset/type/base
10-shell.css # toolbar, sidebar, status, workspace
20-button-180.css # ONE owner for skin, OFF/ON/hover/pressed/focus/disabled
21-channel-strip.css # strip grid and channel identity
22-pan.css # PAN offsets/stacking/metal cap
23-fader-meter.css # fader, cap, meter + clip displays
24-master.css # 168px stereo master, LUFS-I + dBTP layout
30-fx-rack.css # inserts, plugins, rack editor
31-dialogs.css # modals + popovers
40-responsive.css # consolidated breakpoint policy, shell/component owners
50-accessibility.css # reduced-motion and focus policies
90-compat.css # explicitly limited temporary migration only
web/styles.css # deterministic generated runtime artifact, not hand-edited
AR-MIX-Live-FX-Host-Standalone-v0.3.html # deterministic generated offline artifact
- Ownership contract: each visual property family has one primary owner. Components own their appearance; shell owns placement; responsive defines deliberate breakpoint deltas only; tokens own shared design vocabulary. No more trailing emergency selector overrides. New classes may use
asm-prefix; do not rewrite the whole DOM to BEM/CSS Modules. - Prefer low-specificity
:where()+ component classes, controlled design tokens, explicit semantic variants. Avoid umbrella ID selectors and universalbuttonskins. Do not use!importantexcept documented compatibility/accessibility necessity. - Consider
@layer tokens, reset, base, layout, components, states, utilitiesonly after normal/important cascade semantics are analyzed: unlayered normal rules outrank layered ones, while layer order reverses for!important. Blind conversion will regress the approved GUI. - Build-time consolidation must yield one CSS resource for WebView2 and one embed in standalone; no runtime
@import, network font fetch, or JS-driven global theme styling. Current JS inline custom-property values for meters, PAN/faders, channel colors and popover pointer placement may remain where data-driven. - Deterministic rebuild/check command checks SHA and exact CSS/JS/HTML parity, and prevents manual edits to generated outputs.
Implementation plan (one cohesive refactor, guarded milestones)
- Inventory/cascade oracle: use a real CSS AST parser (PostCSS / Lightning CSS equivalent, pinned) to produce selectors, locations, media scopes, importance, specificity and shadowed-property diagnostics. Baseline current runtime computed styles and screenshots; collect DOM selector reachability, including native views, before any delete.
- Build ownership & tokens: extract asset data without changing bytes; split readable CSS into owner modules, add deterministic compiler and
--checkdrift guard, keepweb/styles.css/ standalone output byte/behavior parity after regeneration. - Consolidate high-risk components: fix responsive inversion; centralize Button 180 state recipe, PAN geometry, master/source grid. Remove confirmed dead rules and duplicate losing declarations using AST-based diffs. Preserve approved
#223541OFF, glossy OFF hover, inset ON, 27px sidebar buttons, 168px master, exact fader/PAN PNGs and all event actions. - CI hardening: stylelint + custom AST checks (unowned selector, duplicate property collisions in overlapping scopes, specificity escalation, forbidden global button selectors, new
!important, source/build drift). Quality-gate new violations, not a naive ban on all duplicate selectors or legitimate responsive changes. - Matrix validation: Chromium 980/1100/1190/1250/1370/1440/1580/1680/1920 widths plus each relevant breakpoint +/-1, compact heights 730/760/790, EASY/PRO, toolbar/sidebar/MIX/FX Rack/Signal Flow, all 13 strips, all button states, keyboard/focus/reduced motion and UI with native data. Static geometry/state assertions + baseline visual comparisons; Windows WebView2/DPI 100/125/150% remains a distinct hardware validation gate.
Definition of done
- Pixel-consistent approved mixer at target resolutions, zero unexpected toolbar show/hide inversions, zero interactive/keyboard regressions.
- Exactly one Button 180 skin owner, one PAN geometry owner, one responsive owner policy, no obsolete live-CSS dependency or unsafe
!importantescalation. - Direct WebView2/CMake BinaryData, browser preview, GitHub Pages standalone all load identical intended CSS/assets; existing tests pass.
- Every removed legacy selector justified by reachability evidence, not text search guesses.
- CI validates ownership/parity automatically; no audio-engine code changes and no claim of native real-device validation from browser results.
Locked references: AGENTS.md, docs/GUI_BASELINE_LOCK_2026-10-25.md latest entry (2026-10-26), tests/button_asset_test.py, tests/pan_button_asset_test.py, tests/gui_baseline_lock_test.py, tests/ui_smoke.py.
Activity
masarray commentedon Oct 25, 2026
Milestone 1 implemented on PR #38 (commit
7874f2b7b5d97e046a80a0e27e85f7c29c4fd2fa; not yet merged at comment time).20-button-180.csssolely owns shared OFF/ON/hover styling; duplicated old ON palette removed.Remaining: Chromium GUI + Windows CI acceptance on PR #38; historic layout and responsive cascade still in legacy module. Next: DOM-backed obsolete CSS cleanup, toolbar breakpoint consolidation, AST specificity/duplicate checks, then Windows DPI visual FAT.
See
docs/CSS_ARCHITECTURE_MILESTONES_2026-10-26.mdandAGENTS.mdon the branch.masarray commentedon Oct 25, 2026
Milestone 1d merged — PR #41: tactile raised dark-crystal Button 180 OFF (#202832), crisp top/left glint + short hard 3D lower bevel; pointer-down and ON recessed with unchanged semantic colors; stronger brightness-only hover (1.32), no extra border or hitbox movement. CSS owner source + WebView2/standalone generated parity retained. Chromium and Windows native CI both passed on PR head
529b54dd6. Next architecture milestone: AST-based responsive / legacy ownership cleanup; no engine code modified.masarray commentedon Oct 26, 2026
Milestone 1e — latest owner-approved Button 180 skin merged via PR #43, merge commit
a8c7fc2.The previous raised dark-cube OFF experiment is superseded. OFF/ON/selected share the same original ON inset shadow geometry and fixed 3px radius; only colorway changes. OFF face
#858283, border#636363, ink#2b2b2b(single-source tokens). ON functional colors unchanged; hover stays brightness-only 1.32, no extra border. Removed obsolete raised-OFF shadow and pressed shadow switch from component owner; canonical CSS and standalone HTML regenerated in parity. Chromium and Windows Native PR CI PASS. Remaining CSS work: AST-backed responsive/legacy owner migration; no DSP changes.masarray commentedon Oct 26, 2026
Milestone 1f merged — PR #47, commit
df27b891aa0fa32c749a5eff15a3bb40aa3b28d6. Button 180 retains identical OFF/ON resting face and exact OFF gray #858283 / border #636363 / ink #2b2b2b, plus instant physical feedback on:active:not(:disabled)only: 1px face travel (75ms), deeper inset/shorter outer shadow (90ms). Releases return to shared resting depth even after toggling ON, with no latch on .active/.selected. Hover brightness 1.32 unchanged, no hover border. Chromium UI regression tests press both OFF and ON; Windows Native VST3 CI and Chromium both PASS on PR. Deterministic CSS/offline parity retained; no audio engine or mixer geometry updates.masarray commentedon Oct 26, 2026
Milestone 1g MERGED — PR #51: toolbar-actions (7 nav buttons) and left-rail (8 utility buttons) now use dedicated
fx-navFX-power-inspired gradient, border/glint, hover and focus styling (OFF matches bypassed power, ON matches powered FX slot). Button 180 stays exclusively on mixer channel/master controls and toolbar-context Audio Device, preserving its neutral OFF #858283/#636363/#2b2b2b and 1px tactile press. New ownerweb/styles-src/21-navigation-fx-power.css; source CSS, WebView2 and offline HTML in parity. Tests assert style isolation and FX power visual match. Chromium UI + Windows Native both PASS on PR headb758f9e; merge commite758c806. No DSP or event handler changes.masarray commentedon Oct 26, 2026
2026-10-26 merge reconciliation checkpoint: PR #59 documents actual main head/CI, 12 historical PR dispositions and GUI ownership. CSS ownership is PARTIAL (deterministic builder and Button 180/current Button 19 nav skin);
10-console-legacy.css, responsive cascade overlap and AST-level reachability/specificity lint remain UNFINISHED. Keep #37 open. Note #53 superseded earlier FX-power nav #51 while the file still has its old name.masarray commentedon Oct 26, 2026
GUI reconciliation complete — 2026-10-26 (latest main)
PR #57 MERGED as
8d7ccab5522dae2f813ca13fc01e700fc1e1a9fb, docs-only; Chromium UI and Windows native VST3 CI both PASS before merge. Authoritative handoff:docs/GUI_MERGE_RECONCILIATION_2026-10-26.md, updatedAGENTS.mdand CSS milestone history.web/styles-src/21-navigation-fx-power.cssis a historical filename. Never replay older FX-power nav PR GUI: FX Power skin for left-rail and toolbar-actions (remove Button 180 ownership) #49 (closed unmerged) or restore Button 180 onto nav..maintop gutter to 2px. This GUI polish is already merged, not pending.fx-powerstays independent.8d5f974before the reconciliation had verified Chromium, Windows, Pages PASS; audio DIRECT safety PR P0: latch ASIO DIRECT route on hotplug; mute substituted backend before DSP #55 already merged. New PR docs(gui): reconcile approved Button 19 / compositor baseline; prevent stale GUI merges #57 has no runtime changes. No outstanding GUI/CSS polish PR found on the audit.Operational checkpoint: always fetch latest main, follow the documented newer GUI ownership, and never overwrite current GUI with old branches.
masarray commentedon Oct 31, 2026
ISSUE RECONCILIATION — historical/overlap closed, NOT declared solved. CSS cascade ownership, deterministic generated CSS and low-spec GPU performance are continuing invariants under owner baseline #176 and ARD v5 UI section. This old standalone task mixed audit history with current performance acceptance; close as duplicate while keeping its reports searchable.
Current authority: PRD v5, ARD v5, native epic #192, GUI L2 #176, and hardware #15. Existing original comments and links remain.