Landing: give the last section a subject

[adnaan]

Two rounds of feedback on one section: the heading said nothing, then the eyebrow said nothing, then the lead was too long.

What was wrong

The section held three different taxonomies at once, so no heading could summarise it:

• eyebrow — "Everything else", a non-label
• heading — about the documentation
• first lead — app types: admin panels, CRUD, dashboards
• eight links — capabilities: uploads, pubsub, sessions, errors, CLI, client, observability, scaling

slot	before	after
eyebrow	Everything else	More capabilities
heading	The rest of the docs covers the ordinary screens.	Your app has file uploads and a login. Both are here.
lead	Admin panels, internal tools, CRUD, dashboards, approvals, uploads, auth, and the occasional shared view. That is what this is for.	Admin screens, internal tools, CRUD and dashboards are the point.

The lead was a table of contents for a visible grid

An intermediate draft ran three sentences, each containing a list, with the middle one mixing three single-word nouns against a ten-word clause. All of it enumerated the eight links sitting directly below, where each already carries its own gloss.

It also opened "the wall is one screen, and it needed neither" — false about the grid, since the wall uses sessions and the browser client. Cut to the one thing the grid can't say: who this is for. That claim appears nowhere else on the page.

Two links contradicted the new heading

"Shared views / Subscribe & Publish" is exactly what the Multi-user section demonstrates, and "Forms & errors" is exactly what the Validation section demonstrates. Both references now sit at the end of the section that shows them off, where a reader who wants the API is already standing. Their grid slots go to two genuine gaps:

• Auth & login → /recipes/login/ — the old lead said "auth" and never linked it
• Navigation → /reference/navigate — nothing on the page mentioned it

One false claim, cut before it shipped

A draft of the lead promised "sessions that outlive a restart". Wrong by default — reference/session documents the SessionStore as "in-memory or Redis", and every persistence claim on that page is scoped to surviving a page refresh, not a process restart. Redis-backed behavior presented as the baseline. Same failure mode as the Alpine row in #142, one section later.

Verification

• voice-check.sh — pass, every ceiling unchanged
• tinkerdown validate — 98/98, 0 errors
• go test ./e2e/ — pass, 135s
• make sweep at desktop + iphone-14 — 196 visits, 2 flagged, both the pre-existing large-table timeout
• Read at 1440px in a browser
• All 10 headings still carry a finite verb; no dead in-page anchors

🤖 Generated with Claude Code

https://claude.ai/code/session_0166MK1arBYbVZq6wfm8EsQZ

[adnaan]

The template side is the other two lines you read: We can simply say: On the template side:

[adnaan]

Done in 35b134a — On the template side: verbatim.

Also dropped the trailing and the error handling reference has the rest from the same sentence, which was the same padding as the one you flagged on line 313. It was there because the error-handling link got relocated out of the capabilities grid and a trailing clause was the lazy place to put it. It now hangs off the word "error" instead, so the paragraph goes back to ending on "Scroll up and type admin".

[adnaan]

The pubsub reference has the topic rules and the ACL in full: sentence is nonsensical and doesnt mean anything

[adnaan]

Agreed, it was padding — "has the topic rules and the ACL in full" bolted onto a paragraph that had already finished, and the reader had just read the ACL in main anyway.

Fixed in 35b134a by deleting the sentence and linking WithTopicACL itself to the pubsub reference. The link survives, no sentence needed.

Both this and the error-handling one existed because I pulled those two references out of the capabilities grid below (they duplicated what the Multi-user and Validation sections already demonstrate) and needed to re-home the links. A trailing sentence was the wrong answer twice.

[adnaan]

Second commit: the upload-modes-e2e flake, diagnosed

The PR body above covers the landing section. This is the other commit — 331887a, unrelated to the copy, which is why it's called out separately.

upload-modes-e2e failed on this PR, as it has four times now:

upload-modes_test.go:119: proxied flow: context deadline exceeded

Always at 60.0s, always the proxied flow, always on PRs that touch only markdown, always green on re-run. I'd re-run it three times before actually reading it.

It's a race

Every upload in that suite is driven by a change event on an input[lvt-upload]. That input is server-rendered — present and visible in the initial HTML, well before the deferred client bundle loads and binds its listener. chromedp.WaitVisible waits only for DOM visibility, so SetUploadFiles can fire into the gap. The event is dropped with no error, no upload starts, #proxied-result never appears, and the WaitVisible on it burns the whole 60s deadline from newChromiumCtx.

The CI timestamps show the gap directly — session group created at :32.85, client logs WebSocket connected at :33.07, and navigate → WaitVisible → SetValue → SetUploadFiles all complete in the milliseconds after :32.85.

Reproduced under controlled conditions

It passes 5/5 in ~1.6s locally, so I widened the window with 300ms of emulated network latency and ran the identical action sequence both ways:

	result
without readiness wait	context deadline exceeded @ 60.04s — CI's exact signature
with readiness wait	pass @ 2.12s

Same code, same conditions, one line different.

Two things the measurement changed

All four tests were affected, not just the failing one. The three WS-disabled variants reproduce the same hang under latency — they have a narrower window only because DeadSocket fails immediately instead of doing a real handshake. Fixing one would have left three latent.

The readiness condition three other suites in this repo use is too weak. Measured against this app with the socket killed:

signal	true after
typeof window.liveTemplateClient !== 'undefined'	1.8ms
window.liveTemplateClient.isReady()	637ms

The weak check clears 635ms early. isReady() also resolves on the HTTP-fallback path, so all four tests wait on the same signal.

Verification

Against the bundle CI pins (@livetemplate/client@0.20.0, fetched the way build.yml fetches it):

• all four tests pass unthrottled — 1.61s / 0.75s / 0.81s / 0.80s
• the proxied flow passes under the 300ms latency that reproduced the failure
• upload-modes-e2e in CI here: pass in 31s, down from 49s passing / 1m37s failing

Both diagnostic files deleted; the commit touches one test file.

[adnaan]

Follow-up worth filing, deliberately not done here.

isReady() is the strong signal. Three other suites in this repo wait on the weaker typeof window.liveTemplateClient !== 'undefined':

• examples/chat/chat_e2e_test.go:89
• examples/live-preview/live_preview_test.go:273
• examples/seat-picker/seat_picker_test.go:144

Measured against the upload-modes app with the socket killed, that condition goes true at 1.8ms while isReady() goes true at 637ms. So those three clear the gate ~635ms early and carry the same latent race this commit fixes — they just haven't lost it in CI yet.

Left alone because they're passing and it's outside this PR's scope. Happy to do it as its own change.