Skip to content

CSS architecture hardening: audited cascade, component ownership, deterministic build and CI #37

Closed as duplicate

Description

@masarray

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). JUCE CMakeLists.txt embeds it via juce_add_binary_data; src/Main.cpp serves /styles.css as text/css. web/index.html loads it directly.
  • Offline AR-MIX-Live-FX-Host-Standalone-v0.3.html embeds the byte-identical CSS (~558,159 characters); existing contract tests enforce this. GitHub Pages publishes that standalone via scripts/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 !important occurrences, no @layer declaration. 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, or web/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) and site/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 universal button skins. Do not use !important except documented compatibility/accessibility necessity.
  • Consider @layer tokens, reset, base, layout, components, states, utilities only 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)

  1. 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.
  2. Build ownership & tokens: extract asset data without changing bytes; split readable CSS into owner modules, add deterministic compiler and --check drift guard, keep web/styles.css / standalone output byte/behavior parity after regeneration.
  3. 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 #223541 OFF, glossy OFF hover, inset ON, 27px sidebar buttons, 168px master, exact fader/PAN PNGs and all event actions.
  4. 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.
  5. 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 !important escalation.
  • 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

  1. masarray commented on Oct 25, 2026

    @masarray
    OwnerAuthor

    Milestone 1 implemented on PR #38 (commit 7874f2b7b5d97e046a80a0e27e85f7c29c4fd2fa; not yet merged at comment time).

    • Five source CSS files now compile deterministically into the single runtime WebView2 stylesheet and the byte-identical standalone; CI + Pages verify parity.
    • 20-button-180.css solely owns shared OFF/ON/hover styling; duplicated old ON palette removed.
    • Owner-requested OFF visually becomes square smoked-black crystal (solid #171c23, dark edge, subtle upper translucent inset glint, no cylinder/convex gradient). Existing ON inset/shapes/colors unaffected by design.
    • Locked GUI geometry/PAN 13-15-12/master 168px/native audio unchanged.

    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.md and AGENTS.md on the branch.

  2. masarray commented on Oct 25, 2026

    @masarray
    OwnerAuthor

    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.

  3. masarray commented on Oct 26, 2026

    @masarray
    OwnerAuthor

    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.

  4. masarray commented on Oct 26, 2026

    @masarray
    OwnerAuthor

    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.

  5. masarray commented on Oct 26, 2026

    @masarray
    OwnerAuthor

    Milestone 1g MERGED — PR #51: toolbar-actions (7 nav buttons) and left-rail (8 utility buttons) now use dedicated fx-nav FX-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 owner web/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 head b758f9e; merge commit e758c806. No DSP or event handler changes.

  6. masarray commented on Oct 26, 2026

    @masarray
    OwnerAuthor

    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.

  7. masarray commented on Oct 26, 2026

    @masarray
    OwnerAuthor

    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, updated AGENTS.md and CSS milestone history.

    Operational checkpoint: always fetch latest main, follow the documented newer GUI ownership, and never overwrite current GUI with old branches.

  8. masarray commented on Oct 31, 2026

    @masarray
    OwnerAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions