Skip to content

fix(www): break long URLs in tutorial prose, and widen the sideways-scroll guard - #858

Merged
choraria merged 3 commits into
mainfrom
fix/mobile-prose-url-overflow
Jul 31, 2026
Merged

fix(www): break long URLs in tutorial prose, and widen the sideways-scroll guard#858
choraria merged 3 commits into
mainfrom
fix/mobile-prose-url-overflow

Conversation

@choraria

Copy link
Copy Markdown
Contributor

Follow-up to #857, found by extending that PR's mobile sweep across every marketing route at 320 / 360 / 375 / 393px.

The defect

Three provider pages dragged the whole document sideways on a narrow phone:

Page Document width Viewport
/test/calendly 381px 360px
/test/github 372px 360px
/test/notion 345px 320px

Tutorial prose is authored per provider in lib/tutorials.ts and routinely carries a bare URL — "POST to https://api.calendly.com/webhook_subscriptions with url, events…". Under the default overflow-wrap: normal a URL is one unbreakable token: it doesn't wrap, it runs past the paragraph, and the document widens with it. The terminal blocks on these pages are correctly overflow-x-auto and scroll inside their own box; the paragraphs had nothing.

Why nothing caught it

no page scrolls sideways on a phone already existed — and reported green on every run. It ran at exactly one viewport, the mobile project's Pixel 5 default of 393px, which all three pages happen to fit.

A viewport-sensitive assertion pinned to a single viewport is not a guard against layout; it is a guard against one phone. This is the same shape as the bug in #857, where the check was blind because the hero section is overflow-hidden.

The guard now runs at 320 / 360 / 393px — 111 checks instead of 37. Before this fix it is red on all three pages (5 failures: three at 320px, two at 360px) and still green at 393px — the blindness demonstrated, not asserted.

The fix

break-words on the shared body prose class.

  • Not break-all. overflow-wrap: break-word breaks a long token only when it cannot fit a line of its own, so ordinary sentences still wrap at their spaces.
  • The event-name chips in the same file already carry break-words, with a comment giving the same reasoning. This is that idiom, applied to the prose.
  • The "Worth knowing first" paragraph spelled the same class string out by hand instead of using body, so it would have been left behind. It now uses the constant — hand-copying a shared class string is exactly how one of two identical paragraphs ends up without the fix.

Test plan

  • Playwright mobile191 passed (was 117; +74 from the widened guard)
  • Playwright chromium138 passed
  • apps/www vitest — 562 passed
  • pnpm lint (eslint + all repo guards, incl. content-dup-guard over the 16 sibling tutorial pages) ✓ · typecheck ✓ · format:check
  • test:seo ✓ · test:anchors ✓ · test:orphans ✓ · test:links ✓ · check:export

Human verification

Lower risk than #857 — this is a wrapping rule on body copy, no layout or control moved. Worth a glance at /test/calendly on a phone to confirm the long URL now wraps mid-token rather than running off, and that surrounding sentences still break at spaces.

🤖 Generated with Claude Code

https://claude.ai/code/session_012gEktpYFKUo4FweY9BeuzU

…croll guard

Three provider pages dragged the whole document sideways on a narrow phone,
and the guard that exists to catch exactly this reported green on every run.

THE DEFECT. Tutorial prose is authored per provider in `lib/tutorials.ts` and
routinely carries a bare URL — "POST to
https://api.calendly.com/webhook_subscriptions with url, events…". Under the
default `overflow-wrap: normal` a URL is one unbreakable token: it does not
wrap, it runs past the paragraph, and the document widens with it.
`/test/calendly` held 381px of content in a 360px viewport, `/test/github`
372px, and `/test/notion` 345px at 320px. The terminal blocks on these pages
are correctly `overflow-x-auto` and scroll inside their own box; the
paragraphs had nothing.

WHY NOTHING CAUGHT IT. `no page scrolls sideways on a phone` ran at exactly
one viewport — the mobile project's Pixel 5 default of 393px — and all three
pages happen to fit there. A viewport-sensitive assertion pinned to a single
viewport is not a guard against layout, it is a guard against one phone. It
now runs at 320 / 360 / 393px, which is 111 checks instead of 37, and is red
on all three pages before this fix (5 failures: three at 320px, two at 360px)
while still green at 393px — the blindness, demonstrated rather than asserted.

THE FIX. `break-words` on the shared `body` prose class. Not `break-all`:
`overflow-wrap: break-word` breaks a long token only when it cannot fit a line
of its own, so ordinary sentences still wrap at their spaces. The event-name
chips in the same file already carry it, for the same reason.

The "Worth knowing first" paragraph spelled the same class string out by hand
instead of using `body`, so it would have been left behind. It now uses the
constant — that duplication is precisely how one of two identical paragraphs
ends up without the fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012gEktpYFKUo4FweY9BeuzU
@choraria
choraria merged commit d731003 into main Jul 31, 2026
30 checks passed
@choraria
choraria deleted the fix/mobile-prose-url-overflow branch July 31, 2026 21:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant