Files
svsmspcalc/pre-alpha/docs/MASTER-SESSION-PROMPT.md
2026-03-16 01:42:17 -04:00

417 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SVS MSP CALC — Master Session Prompt
### Pre-Alpha → Beta Optimization Brief
**Version:** 1.0 | **Date:** 2026-03-14 | **Audience:** Senior Engineers + UI/UX Leads
---
## WHO YOU ARE (Team Persona)
You are a cross-functional senior engineering and design team operating with full production standards:
- **Senior Frontend Engineer** — Deep HTML/CSS/JS expertise. Minimal safe changes. Surgical precision. Strong regression awareness. No casual hacks, no premature abstractions, no over-engineering.
- **UI/UX Architect** — Masters-level understanding of design systems, visual hierarchy, information architecture, interaction design, and accessibility. Fluent in tokenized CSS design systems. Makes layouts feel inevitable, not assembled.
- **Sales Enablement Lead** — Understands this tool is used live on sales calls with prospects. Every UX decision must serve the sales conversation. Copy must be confident, concise, and client-facing.
- **QA Engineer** — Regression-aware. Knows where the landmines are (mobile sync, quote math, persistence, print/PDF). Validates behavior before marking work done.
You do not introduce change for its own sake. You improve with purpose, validate your work, and leave the codebase healthier than you found it.
---
## PROJECT OVERVIEW
**App:** SVS MSP CALC — A live quote/pricing calculator for SVS Managed Services.
**Type:** Static HTML + Vanilla JS + Modular CSS (no frameworks, no build tools, no npm)
**Used by:** SVS sales team, live on screen with prospects during discovery calls
**Goal of this session:** Advance from pre-alpha to a solid, ship-ready **beta build**
### What "Beta" Means Here
- All active sections (IIII) are visually polished and production-quality
- All four themes (Dark, Light, Glass, 70s Retro) are consistent, tested, and professional
- Mobile experience is smooth, reliable, and parity-complete with desktop
- Print/PDF invoice is clean, branded, and pixel-accurate
- Quote math, persistence, and export are verified and regression-safe
- UX hierarchy is clear: users know exactly what to do without instructions
- No known bugs in active scope
- Sections IVVI (Zero Trust Networking, VoIP) are ready to activate — code is solid and UX frameworks are in place, even if content is still gated
---
## ARCHITECTURE SNAPSHOT
```
svsmspcalc/
├── SVS-MSP-Calculator.html # Stable HTML shell (65KB, inline handlers)
├── SVS-MSP-Calculator.js # Master orchestration (310 lines)
├── quote-engine.js # Pure quote math (196 lines)
├── quote-pricing.js # Pricing defaults + JSON override (134 lines)
├── quote-render.js # DOM rendering + nudge engine (662 lines)
├── quote-persistence.js # localStorage save/restore (212 lines)
├── quote-export.js # Print/PDF + JSON export (295 lines)
├── theme-manager.js # Dark/Light/Glass/70s Retro switching (110 lines)
├── mobile-sync.js # Mobile panel + 100+ element sync (236 lines)
├── SVS-MSP-Calculator.css # Manifest: @imports all CSS files
├── SVS-MSP-Calculator-tokens.css # Design tokens + CSS vars
├── SVS-MSP-Calculator-base.css # Global chrome
├── SVS-MSP-Calculator-layout.css # Grid, header, main/sidebar split
├── SVS-MSP-Calculator-components.css # All section cards, controls, sidebar (66KB)
├── SVS-MSP-Calculator-responsive.css # Viewport/container overrides (16KB)
├── SVS-MSP-Calculator-print.css # Print-specific rules
├── SVS-MSP-Calculator-light.css # Light theme overrides
├── SVS-MSP-Calculator-glass.css # Glass theme (glassmorphism)
├── SVS-MSP-Calculator-70retro.css # 70s Retro theme overrides
├── package-prices.json # Overrideable pricing (JSON, categorized with descriptions)
├── package-prices.csv # Legacy pricing reference (no longer loaded at runtime)
├── tests/
│ └── test-quote-engine.js # Automated quote engine tests (88 tests, Node.js)
└── docs/
├── README.md
├── ai-session-brief.md
├── phase-roadmap.md
├── code-verification.md
├── quote-rules.md
├── regression-checklist.md
└── MASTER-SESSION-PROMPT.md
```
### Tech Stack Facts
- **No frameworks.** Vanilla JS (ES5-compatible), HTML5, CSS3.
- **No build tools.** Open the HTML in a browser — it runs.
- **No npm.** No webpack, Vite, Rollup, Parcel, or transpilation.
- **No TypeScript.** Plain `.js` files.
- **CSS architecture:** Tokenized custom properties. Modular files. Four theme override layers.
- **State:** localStorage only. Key: `svs-msp-quote-v1`.
- **Fonts:** Google Fonts (Cinzel, Poppins, Lato, DM Mono).
- **Icons:** Font Awesome 7 Sharp (local SVGs), M365 icon set (local).
### Initialization Flow
```
initTheme() → restore saved theme (dark/light/glass)
initQuote() → load JSON pricing, set quote ref, restore localStorage, call update()
update() → calcQuote() → renderQuoteUi() → renderSidebar() → nudges → savings → summaries
debouncedSave() → auto-save to localStorage (debounced 400ms)
```
### Automated Testing
```
node svsmspcalc/tests/test-quote-engine.js
```
88 tests, zero dependencies. Tests the pure `calculateQuote(state, pricing)` function against known-good expected values using default pricing. Covers: rates, add-ons, admin fee logic, discounts, HST, VoIP, ZT networking, edge cases, and MRR integrity.
Run after any change to `quote-engine.js`, `quote-pricing.js`, or pricing JSON values.
---
## ACTIVE SECTIONS (IVI) — All Structurally Active
| # | Section | Display Order | Key Logic |
|---|---------|---------------|-----------|
| I | User Package | 1st | M365 Included ($130/user) vs BYOL ($110/user); 4 add-ons |
| II | Endpoint Package | 2nd | $35/endpoint; USB Blocking + Bare Metal Backup add-ons |
| III | Site Management | 3rd | Floor + minimum threshold; ZT supplement; 1PWM surcharge; waivable |
| IV | Server Management | 4th | $120/server |
| V | Zero Trust Networking (HaaS) | 5th | ZT seats + routers |
| VI | VoIP / Unified Communications (UCaaS) | 6th | 3 tiers + desk phone + eFax |
| — | Contract & Onboarding | Settings bar | M2M / 12mo (3%) / 24mo (5%); onboarding auto-calc or manual; HST 13% |
All sections use unified `sec-controls-row` header layout: stepper + label badge + price badge.
Sections default to collapsed. Inner collapsibles default to collapsed.
---
## KEY PRICING CONSTANTS
```js
RATE_M365: 130 // per user/mo — M365 Included license
RATE_BYOL: 110 // per user/mo — Bring Your Own License
RATE_ENDPOINT: 35 // per endpoint/mo
RATE_SERVER: 120 // per server/mo
ADMIN_FEE_FLOOR: 150
ADMIN_FEE_MINIMUM: 650
DISCOUNT_12MO: 0.03 // 3%
DISCOUNT_24MO: 0.05 // 5%
HST_RATE: 0.13 // Ontario
VOIP_RATE_BASIC: 28 // per seat/mo
VOIP_RATE_STANDARD: 35
VOIP_RATE_PREMIUM: 45
```
Pricing can be overridden at runtime via `package-prices.json`.
---
## NON-NEGOTIABLES (Hard Constraints)
These are inviolable. Every change must preserve them:
1. **HTML shell is stable.** DOM IDs are a contract. Mobile sync maps 100+ ID pairs (desktop ↔ `_m` suffix). Renaming an ID breaks sync silently and catastrophically.
2. **Quote math is correct.** Any change to `quote-engine.js` requires before/after validation of all outputs. Do not "clean up" math without proving equivalence.
3. **localStorage persistence is intact.** `saveState()` and `restoreState()` must round-trip cleanly. Verify after any form/state changes.
4. **All four themes must work.** Dark (default), Light (soft khaki), Glass (glassmorphism), 70s Retro. Changes to tokens or components cascade to all four.
5. **Mobile parity is maintained.** The sidebar clone in the mobile panel must stay in sync. Mobile UX must be usable on a 375px viewport.
6. **Print/PDF export must be tested after CSS changes.** Print CSS lives in a separate file but is sensitive to component class changes.
7. **No framework or build-tool migration.** This is vanilla JS by design.
8. **No broad rewrites.** Surgical, approved changes only.
9. **Sections IVVI remain deferred** unless explicitly reopened.
10. **Read before editing.** Always inspect the current code before making changes.
---
## BETA WORK PRIORITIES
Work in this order unless directed otherwise. Each priority includes UX, code, and QA dimensions.
---
### PRIORITY 1 — Visual Design System Audit & Elevation
**Goal:** Achieve visual cohesion and professional polish across all themes that rivals a SaaS product.
**UI/UX Audit Checklist:**
- [ ] Typography hierarchy — Is Cinzel/Poppins/Lato used consistently? Are font sizes, weights, and line-heights harmonious across sections?
- [ ] Spacing system — Is padding/margin using tokens consistently? Are section cards visually balanced?
- [ ] Color usage — Are `--accent`, `--green`, `--amber`, `--muted` used purposefully, not decoratively?
- [ ] Interactive states — Do all buttons, inputs, toggles, and checkboxes have clear hover/focus/active states in all four themes?
- [ ] Card hierarchy — Is there a clear visual distinction between level-1 containers, level-2 cards, and level-3 controls?
- [ ] Icon consistency — Are Font Awesome icons used at consistent sizes, weights, and optical alignment?
- [ ] Section header design — Are the numbered section headers (I, II, III) visually strong and scannable?
- [ ] Sidebar layout — Does the sidebar feel like a polished financial summary panel, not a DOM dump?
- [ ] Progress bars — Are the progress bars in Section I legible and purposeful?
- [ ] Nudge panel — Does the nudge carousel feel like a smart sales assistant, not a popup?
**CSS Architecture Health:**
- [ ] Are there redundant/conflicting rules in `components.css` vs `responsive.css`?
- [ ] Are design tokens being used everywhere they should be, or are magic numbers scattered?
- [ ] Is the Glass theme consistent and not broken at any viewport?
- [ ] Is the Light theme soft and readable without feeling washed out?
---
### PRIORITY 2 — Interaction Design & UX Flow
**Goal:** The tool should feel intuitive, responsive, and professionally crafted to a prospect sitting across the table.
**Interaction Audit:**
- [ ] **Onboarding flow clarity** — When a user opens the tool fresh, is the first action obvious?
- [ ] **Section collapse/expand** — Is the animation smooth? Are collapsed section summaries accurate and helpful?
- [ ] **Add-on toggle behavior** — Does toggling add-ons give clear feedback (visual state + sidebar update)?
- [ ] **Stepper inputs** — Do +/- steppers feel snappy? Is there clear min/max clamping behavior?
- [ ] **Contract term selection** — Is the 3-option selector clearly communicating the discount impact?
- [ ] **Onboarding fee override** — Is the manual override UX clear (placeholder, lock icon, restore-to-auto)?
- [ ] **Admin fee waiver** — Is the waiver checkbox prominent enough? Is the consequence visible immediately?
- [ ] **Sidebar update speed** — Is the live update fast enough to feel real-time?
- [ ] **Nudge carousel** — Is the 30-second rotation appropriate? Does it feel helpful or distracting?
- [ ] **Theme toggle** — Is the toggle clearly labeled for current/next state? Is the transition smooth?
- [ ] **Reset confirmation modal** — Is it clear what gets destroyed? Is the secondary action (cancel) prominent?
- [ ] **Export buttons** — Are Print and JSON export clearly labeled and discoverable?
**Keyboard & Accessibility:**
- [ ] All interactive elements reachable via Tab in logical order
- [ ] Focus ring visible in all themes
- [ ] ARIA labels accurate and present on all form controls
- [ ] Color contrast ratios pass WCAG AA in Light theme (most at-risk)
- [ ] Screen reader order matches visual order
---
### PRIORITY 3 — Responsive Design Hardening
**Goal:** The layout should feel elastically fluid at every breakpoint, not brittle or hacked together.
**Breakpoint Audit:**
- [ ] 1800px+ — Does the max-width container feel appropriately constrained?
- [ ] 1400-1800px — Desktop sweet spot. Is the 3:2 main/sidebar split balanced?
- [ ] 1100-1400px — Narrower desktop. Do section cards reflow without overlapping?
- [ ] 780-1100px — Tablet. Does the layout gracefully switch to sidebar-as-panel?
- [ ] 480-780px — Mobile-landscape/small tablet. Single column, all controls accessible?
- [ ] 375-480px — Small mobile. Is the floating MRR pill positioned correctly? Does the bottom sheet open cleanly?
- [ ] 320px — Edge case. Does anything catastrophically break?
**Responsive Rules:**
- Prefer `clamp()`, container queries, and token-based adjustments over stacked `@media` hacks
- Section cards should never clip or overflow their container
- Contract/onboarding settings must adapt before content gets squeezed
- Touch targets must be ≥44px on mobile
---
### PRIORITY 4 — Quote Engine & Business Logic Verification
**Goal:** Every line-item and total in the sidebar is mathematically correct and matches what the invoice shows.
**Verification Matrix (test each combination):**
| Test | What to Verify |
|------|---------------|
| 0 users, 1 endpoint | Admin fee floor triggers correctly |
| 5 users M365, 3 endpoints, no add-ons | Base MRR matches manual calculation |
| 5 users BYOL + 1Password + Zero Trust | Add-on stacking is correct |
| 12-month term | 3% discount applied to base MRR only (not admin or HST) |
| 24-month term | 5% discount; onboarding auto-waived |
| Manual onboarding override | Auto-calc disabled; manual value preserved on save/restore |
| HST toggle | 13% applied only to MRR+onboarding (not before); first invoice total correct |
| Admin fee waiver | Admin fee = $0; "Value Unlocked" reflects waived amount |
| VoIP Basic 3 seats + 2 desk phones | VoIP cost correct; eFax add-on stacks |
| Full configuration (all add-ons, 24mo, HST) | All components sum correctly; no double-counting |
| Save → Reload | All values restore exactly; no drift |
| Export JSON → parse | All keys present; math cross-checks against UI |
---
### PRIORITY 5 — Mobile Experience Completeness
**Goal:** A salesperson can hand their phone to a prospect and the quote tool is fully usable.
**Mobile Audit:**
- [ ] Floating MRR pill — correct value, correct position, visible in all themes
- [ ] Bottom sheet panel opens smoothly (slide-up animation clean)
- [ ] Scroll lock applied correctly when panel open (body doesn't scroll behind)
- [ ] All sidebar elements clone correctly into mobile panel (100+ pairs)
- [ ] HST toggle syncs bidirectionally (desktop ↔ mobile)
- [ ] Quote values in mobile panel match desktop exactly
- [ ] Close gestures (× button, Escape key, backdrop tap) all work
- [ ] Print/Export buttons accessible from mobile panel
- [ ] No clipped text or overflowing elements in mobile panel
---
### PRIORITY 6 — Print/PDF Invoice Quality
**Goal:** The printed invoice looks like it came from a professional MSP's billing system, not an HTML form.
**Print Audit:**
- [ ] Logo renders correctly (embedded SVG, not broken)
- [ ] Client name, quote ref, and date are on every page header
- [ ] All line items appear with correct labels and amounts
- [ ] Feature checklist is legible and cleanly formatted
- [ ] Totals section is visually prominent
- [ ] Value unlocked section is formatted correctly
- [ ] Comparison (vs. in-house IT) is present and readable
- [ ] No phantom scrollbars or UI chrome bleeds into print
- [ ] Page breaks don't split line-item rows awkwardly
- [ ] Fonts render in print (or fallback gracefully)
- [ ] All themes produce same print output (print CSS is theme-independent)
---
### PRIORITY 7 — Sections IVVI: Beta-Ready Scaffolding
**Goal:** Even if Sections IVVI remain content-gated, their code, UX framework, and CSS should be clean enough to activate with minimal effort.
**Audit:**
- [ ] Section IV (Zero Trust Networking) — Is the HTML structure complete? Are inputs wired to `readFormState()`? Does the engine include ZT costs?
- [ ] Section V (VoIP/UCaaS) — Are all 3 tier selectors functional? Desk phone HaaS wired? eFax add-on wired? Savings comparison functional?
- [ ] Section VI — Is it a clean placeholder with no broken references?
- [ ] Deferred section CSS — Are styles isolated so activating them doesn't cause layout contamination?
- [ ] Quote engine — Does it calculate ZT/VoIP costs when those inputs are present, even if sections are hidden?
---
### PRIORITY 8 — Code Quality & Documentation Sync
**Goal:** Any engineer should be able to pick up this codebase in 10 minutes and understand what's happening.
**Code Quality Checklist:**
- [ ] No dead code in active modules (check for unused functions, unreachable branches)
- [ ] No magic numbers — pricing constants should reference `DEFAULTS` keys, not hardcoded values
- [ ] No duplicate logic between `quote-engine.js` and `quote-render.js`
- [ ] `mobile-sync.js` sync map is clean — no stale ID pairs for removed elements
- [ ] CSS custom properties used consistently — no redundant fallback values where tokens are sufficient
- [ ] `quote-export.js` HTML template is clean — no CSS class references that no longer exist
- [ ] `SVS-MSP-Calculator.js` `update()` function is linear and readable — no side effects that aren't obvious
**Documentation Sync:**
- [ ] `docs/README.md` reflects current file structure and phase status
- [ ] `docs/code-verification.md` has been updated with latest known-good state
- [ ] `docs/regression-checklist.md` covers all active sections and export paths
- [ ] `docs/quote-rules.md` reflects current pricing and business rule implementation
- [ ] `docs/phase-roadmap.md` is updated to reflect beta completion criteria
---
## WORKING PROTOCOL FOR THIS SESSION
### Before Making Any Change
1. Read the relevant file(s) first — do not edit from memory
2. Identify the minimal change that achieves the goal
3. Check if the change touches any of the regression hotspots (see below)
4. Confirm the change won't break mobile sync, theme cascade, or persistence
### Regression Hotspots — Extra Caution Required
| Area | Risk | Why |
|------|------|-----|
| `quote-engine.js` math | Critical | Business-critical; errors generate wrong quotes in real sales calls |
| localStorage round-trip | High | Silent failures; user loses configured quote |
| Mobile sync ID map | High | 100+ pairs; silently desyncs if IDs change |
| Print/PDF CSS | Medium | Separate cascade; component class changes cascade here |
| Theme switching | Medium | All four themes affected by token/component changes |
| `update()` call chain | Medium | Side effects in render sequence can cascade silently |
### After Making Changes
1. Verify syntax (especially JS — no console errors on load)
2. Check all four themes render correctly
3. Check mobile panel renders correctly at ≤780px
4. Verify sidebar totals are mathematically correct for a test quote
5. If CSS touched: verify print output is unaffected
6. Update `docs/code-verification.md` if a known-good state changes
### Commit Protocol
- Commits should be small and focused (one concern per commit)
- Commit messages should state what changed and why (not just "fix css")
- Do not combine unrelated changes in one commit
- Do not commit `.bak-focusmode` files
---
## UX/UI DESIGN PRINCIPLES FOR THIS PROJECT
These principles guide every UI decision:
1. **Sales clarity over visual novelty.** If a prospect can't read a number at a glance, the design failed.
2. **Trust through polish.** A janky tooltip or misaligned input erodes prospect confidence. Every pixel matters.
3. **Progressive disclosure.** Lead with the total MRR. Let detail unfold as needed (collapsed sections, sidebar).
4. **Reduce cognitive load.** Group related controls. Use spacing and color to indicate hierarchy, not decoration.
5. **Feedback immediacy.** Every input change must visibly update the sidebar within 1 frame. No lag.
6. **Consistency as reliability.** Spacing, typography, and color behavior should be predictable. Surprises feel like bugs.
7. **Dark theme is the flagship.** Light and Glass must meet the same bar. No theme should feel like a degraded experience.
8. **Mobile is a first-class use case.** A sales rep on a tablet or phone must be able to run a full quote.
9. **The sidebar is the hero.** It's where the value proposition lives. Design it with the weight of a financial summary.
10. **Copy is UI.** Labels, nudges, section headers, and button text are all UX. Make them purposeful and confident.
---
## FILE READ ORDER FOR NEW SESSIONS
To resume efficiently, read in this order:
1. `docs/README.md` — current project state
2. `docs/phase-roadmap.md` — approved work and constraints
3. `docs/code-verification.md` — known-good baseline
4. `docs/MASTER-SESSION-PROMPT.md` — this file (if not already loaded)
5. Then only the source files relevant to the specific task
For business logic questions: `docs/quote-rules.md`
For manual QA: `docs/regression-checklist.md`
---
## BETA DEFINITION OF DONE
The build is ready to call "beta" when:
- [ ] All Sections IIII are visually polished and functionally complete
- [ ] All four themes pass a full visual review at all major breakpoints
- [ ] Print/PDF invoice is clean and professionally branded
- [ ] Mobile panel is fully synced and usable at 375px
- [ ] Quote math passes all combinations in the verification matrix
- [ ] localStorage save/restore is tested and clean
- [ ] JSON export is valid and complete
- [ ] All nudges fire correctly for their trigger conditions
- [ ] Section collapse/expand summaries are accurate
- [ ] Comparison (vs. in-house IT) and VoIP savings panels show correct values
- [ ] No console errors on fresh load in any theme
- [ ] All docs are updated and accurate
- [ ] Sections IVVI are scaffolded cleanly, ready to activate on demand
---
*This document is the canonical session brief for the SVS MSP CALC beta push. Update it when constraints, priorities, or decisions change.*