mega-plant/HANDOFF-PROMPT-4.md

Mega Plant — Round 4

Two parts: three regressions from round 3, then the mobile standard.

The desktop layout is signed off. Do not change how any page looks at ≥1024px. Everything below is about what happens below that width, plus three data bugs.

---

Part A — Round 3 regressions

A.1 verify-cost-reconciliation.mjs crashes, and reports success anyway

TypeError: Failed to parse URL from /api/collections/_superusers/auth-with-password
exit=0

The script never loads .env.local, so the PocketBase URL is empty and every request fails. It then exits 0. A script whose entire job is to catch drift currently cannot run and claims it passed.

• Load .env.local the way scripts/seed.mjs does.
• Wrap the body in try/catch and process.exit(1) on any failure.
• Exit non-zero when the reconciliation total is off, not just when it throws.
• Run it and paste the real output.

A.2 Vehicle Costs regressed — the workbook's error was adopted

Round 3 changed Vehicle Costs from R14,996.31 to R9,673.87 by dropping Santam versekering (R5,322.44).

That is backwards. Round 3 §B.4 said explicitly: the workbook's row-50 SUM starts one row too low and omits Santam, so the app was right and the spreadsheet was wrong. The fix was to report the spreadsheet error to the client — not to reproduce it.

• Restore Santam versekering to the Vehicle Costs section. Correct total is R14,996.31 across 4 rows.
• Add a comment in the seed and a line in the reconciliation output recording that the app deliberately differs from the workbook by +R5,322.44 here, and why.
• Never "fix" app data to match a source error that has been identified as an error. Report the mismatch instead.

A.3 The incl < excl validation isn't firing

Round 3 §B.3 asked the seed to reject any row where incl < excl or VAT falls outside 0–20%. This row is still in PocketBase:

Buildsmart Yearly update   excl 14,827.91   vat 2,224.19   incl 1,421.01

incl is less than excl, which is arithmetically impossible.

• Add the validation and make it actually fail the seed.
• Confirm it trips on this row. Paste the failure output.
• Do not silently correct the value — it needs the client's confirmation (correct figure is most likely R17,052.10).

A.4 Correction to the round-3 target figure

The acceptance number in round 3 (R689,640.49) was wrong — I subtracted the R5,322.44 Santam amount twice. The workbook's grand total already excludes it via the broken subtotal.

The correct arithmetic:

Workbook grand total (Cost row 98)        R1,110,486.87
less Plant Overheads (now on assets)      − R415,523.94
                                          = R694,962.93   ← reconciliation target

Current app total is R675,162.93. After restoring Santam (A.2) it becomes R680,485.37. The remaining R14,477.56 is fully explained:

Amount	Cause
R19,800.00	Workbook's own Personnel total (row 77 = R412,000) exceeds its two line items (157,200 + 235,000 = 392,200). Source error — ask the client.
−R5,322.44	Santam, where the app is deliberately correct and the workbook is not

• Encode R694,962.93 as the target in the reconciliation script, with both reconciling items listed explicitly so the delta is expected, not mysterious.

A.5 The "Lines" view draws filled areas, not lines

The toggle works and all three series now render with the validated colours — good. But the "Lines" view uses recharts-area-curve with translucent fills, so the amber Fixed area paints over the teal Income area.

The client asked for this view specifically because it matches their spreadsheet, and the spreadsheet draws lines.

• Make the "Lines" view actual lines — stroked, no fill. It is the view whose whole purpose is matching the workbook.
• Keep fills in "Cost stack", where stacking is meaningful.

---

Part B — The mobile standard

The client works from a phone. Desktop is signed off; mobile is not. Below is the definition of done — apply it to every page that exists now and every page added later.

B.1 The hard rule: no page scrolls sideways

A page may never be wider than the viewport. Individual tables may scroll inside their own container; the page may not.

Measured at 375px right now:

Page	Page width	Over by
/income	549px	+174	✗
/charts	406px	+31	✗
/overheads	397px	+22	✗
/running	389px	+14	✗
/expenses	383px	+8	✗
/	375px	0	✓
/plant	375px	0	✓

Five of seven pages fail. Run this in the console on every page at 375px — it must return false everywhere:

document.documentElement.scrollWidth > document.documentElement.clientWidth

The usual cause is a flex … justify-between header whose right-hand element can't shrink. /income is the worst: the "YTD Income" gradient card and the Sort: Profit | Income control both hang off the right edge.

• Fix all five. Headers wrap to a second row on small screens rather than overflowing.

B.2 Content must stay readable, not just fit

On /income at 375px the machine names are truncated to a single character — "C…", "D…", "I…". The code badge and profit badge hold their width while the name column collapses to nothing. A card you can't identify is worse than no card.

• Below sm, stack the card contents: name on its own full-width line, badges on the line beneath. Never truncate the name to less than ~20 characters.
• Same review for /running and the charts cards.

B.3 Filters must not bury the data

/plant has 18 type-filter pills. At 375px they wrap to 13 rows and consume the entire first screen — you scroll past every pill before reaching a single row.

• Below lg, collapse the type filter into a <select> dropdown, or a horizontally-scrolling single row of pills. Not a 13-row block.
• Same for the Sort: control on /income and the view toggle on /charts.

B.4 Wide tables: scroll inside the card, with an anchor column

/plant does this right — the table is 917px inside a 375px overflow-x-auto container, so the page itself doesn't move. Keep that pattern. But scrolling six columns of financials on a phone is still hard work.

• The first column (Code, or Description on expense pages) stays pinned with position: sticky; left: 0 and a background, so you always know which row you're reading.
• Add -webkit-overflow-scrolling: touch and a visible affordance that the table scrolls — a fade on the right edge is enough.
• On expense pages, consider hiding GL Account and Supplier below md. Description and the three money columns are what matter on a phone.

B.5 Tap targets and text size

Measured on /charts at 375px: 19 interactive elements under 44px tall. On / : 10 text elements under 11px.

• Every button, a, and input is at least 44×44px on touch. Keep the visual size if you like — add padding to the hit area.
• No text below 12px on mobile. The text-[10px] labels need bumping.

B.6 Charts on a phone

• The legend on /charts is cut off at the right edge ("Income · Fixed · Ru…"). Wrap it below the title on small screens.
• Charts need a minimum height on mobile — squashing to 176px with 8 x-labels makes them unreadable. Go taller on narrow screens, not shorter.
• The machine card grid must be a single column below sm.

B.7 The PWA angle

The app is meant to install to the home screen, so mobile isn't a nice-to-have — it's the primary surface.

• Verify the installed standalone app at 375px, not just Safari/Chrome. Standalone has no browser chrome, so sticky headers and safe-area insets behave differently.
• Add viewport-fit=cover and use env(safe-area-inset-*) padding on the sticky header and the mobile drawer, so content clears the notch and home indicator.

B.8 How to verify — do this, and report it

Do not report mobile work as done without this. For every route (/, /plant, /income, /running, /charts, /overheads, /expenses, and each /expenses/*):

1. Set the viewport to 375×812.
2. Run the overflow check from B.1 — record the number.
3. Screenshot the page.
4. Count tap targets under 44px and text under 12px.
5. Repeat at 768×1024 (tablet).

• Paste a table of route → overflow → tap-target count for all routes.
• Attach 375px screenshots.
• Any route that still overflows is not done.

---

Standing rule for future work

Add this to the project's AGENTS.md so it applies to every future change:

Every page must pass the mobile checklist before it is considered complete: no horizontal page scroll at 375px, no text under 12px, no tap target under 44px, wide tables scroll inside their own container with a sticky first column, and filter controls collapse rather than stacking into many rows. Verify at 375×812 and 768×1024 and report the measurements — do not assert it from reading the code.

• Create AGENTS.md with that rule if it doesn't exist.

---

Acceptance criteria

• npm run typecheck exits clean
• npm run build succeeds
• verify-cost-reconciliation.mjs runs, and exits non-zero when it fails
• Vehicle Costs is back to R14,996.31 with Santam included
• Seed rejects the Buildsmart row; failure output pasted
• Reconciliation targets R694,962.93 with both deltas itemised
• "Lines" view draws lines, not filled areas
• Zero routes report horizontal page overflow at 375px
• No tap target under 44px; no text under 12px
• Wide tables scroll in-container with a sticky first column
• Verification table + 375px screenshots pasted for every route
• Desktop (≥1024px) is visually unchanged — palette, roundness, gradients, spacing, dark mode all identical to today