Warn on, then fix, browser uploads that break phone playback

[jlocala1]

Laptop drag-and-drop is the one upload path no phone-side fix can reach. A 4K/HEVC/~25 Mbps file dropped into the dropzone stays unplayable on phones for the life of that pulse.

Two commits: detect and warn, then convert.

The contract

H.264 · long edge <= 1920 · <= 5 Mbps · AAC · faststart

Not arbitrary — it is what the PulseCam recorder already pins itself to, and what export.ts already produces.

1. Detection (client/src/lib/videoContract.ts)

Dependency-free inspection of the picked File:

• resolution and duration from a detached <video>, falling back to the MP4 boxes when the browser cannot decode the file at all — which is exactly the Android + HEVC case being warned about
• bitrate as size * 8 / duration
• video/audio fourcc by walking the top-level box chain by size. These files are not faststart, so moov sits at the very end and scanning the first N bytes finds nothing. The walk handles the 64-bit largesize form (real 4K recordings use it for mdat), then descends moov > trak > mdia > minf > stbl > stsd
• faststart from the same walk: moov before mdat

Reads are ranged, so a 344MB file costs a few hundred bytes plus the moov box. Nothing throws into the UI — an unparseable file reports unknown and produces no violation.

2. Conversion (client/src/lib/transcodeToContract.ts)

Re-encodes in the browser via WebCodecs before upload. Measured on a real 344MB 4K HEVC phone capture:

	source	output
codec	hevc 3840x2160 (-90 matrix)	h264 1080x1920
bitrate	24.8 Mbps	5.2 Mbps
index	moov at 100%	moov at 0.0%
size	344 MB	72 MB

22 seconds, duration preserved to 13ms, zero decode errors on a full decode. Verified in real Chrome and WebKit.

MediaRecorder over a canvas was not an option: realtime-bound, and WebM outside Safari. Nor was a <video>-element pipeline — Chrome decodes HEVC through WebCodecs but reports canPlayType('video/mp4; codecs="hvc1"') === '', so it would fail silently on precisely the captures this exists for.

Dependencies: mp4box (BSD-3) demuxes, mp4-muxer (MIT) muxes. Deliberate — a subtly wrong hand-rolled sample-table reader corrupts a user's upload, and the variations (co64 vs stco, ctts, edit lists, hvc1 vs hev1) are not something this repo can regression-test. mediabunny would have done more of the work but is MPL-2.0, which felt like a licensing decision rather than an implementation one. The transcoder is a dynamic import, so the ~220KB only loads for a file that actually needs converting; the main bundle is unchanged.

Three non-obvious things, all found by running it rather than reading it:

• Rotation is baked in, not passed through as a display matrix, so the output needs no orientation metadata. That makes the long-edge cap apply to display dimensions — a 3840x2160 + 90deg capture displays as 2160x3840, and capping its coded width yields 1920x3414: taller than the source and still over the ceiling. Verified by extracting frames from source and output and comparing them.
• Timestamps are zero-based at demux. A capture with B-frames starts its first composition time above zero, and the muxer requires the first chunk at 0. Without this every frame was rejected, and the failure surfaced far away as a null decoder config at finalize().
• The engines disagree on decoderConfig.description for AAC. Chrome returns the bare AudioSpecificConfig; WebKit returns a whole ES_Descriptor. Written verbatim into an esds, WebKit's version produced a file whose video was perfect and whose audio read as object type 0 ... 0 channels — the dangerous kind of bug, because it looks like it worked.

3. Making it usable on a phone

Everything above was built for laptop drag-and-drop, then tested on an actual iPhone against prod, which surfaced four things:

• The warning rendered while the file was converting. Explaining how to re-export a video by hand, with an ffmpeg command, while we are busy doing exactly that, is noise. It now appears only when conversion actually failed — which is the only time it is actionable.
• It was far too long: a headline, four bullets with "should be" clauses, a paragraph, and an always-visible ffmpeg command. Now a headline, one line, and the recipe folded behind a toggle.
• It could widen the page. The command is a nowrap <code>; without max-w-full/overflow-hidden on the alert a long line pushed the document wider than the viewport on a narrow screen.
• Converting is now capped by device. Peak memory is a multiple of the file, which a laptop absorbs and a phone does not, and a 300MB+ capture runs for minutes on the device whose own camera app is the intended path anyway. Phones cap at 250MB and warn past it.

Separately — and this is a pre-existing bug, not introduced here — the editor could not be scrolled on a phone at all. .app--split is a fixed-viewport shell (100dvh, overflow: hidden, touch-action: none) whose panes scroll internally. That works where there is room for the panes; on a phone the video, controls and transcript do not fit, and the document lock made everything below the fold unreachable. Measured at 430px: scrollHeight === clientHeight, html and body both overflow: hidden, and a wheel event moved scrollY by zero.

The shell (and the html/body lock in index.scss) now applies only at >= 768px. Verified at both viewports: mobile scrolls (scrollY 0 -> 311), desktop behaviour is unchanged.

Behaviour

Conversion failure is never upload failure: on an unsupported browser, an undecodable source, or a file too large to convert on this device, the original is uploaded and the warning is shown then — and only then.

Verification

• 50 tests (node --test, no new test deps), including the portrait cap, both description shapes, and two opt-in integration tests against real files via PULSECLIP_TEST_MP4.
• Typecheck adds zero errors versus the same branch without these changes.
• Exercised end to end against the real 344MB capture in Chrome and WebKit.
• Exercised end to end through this UI on a deployed instance. A 4K HEVC clip (3840x2160, 23 Mbps) selected in the real dropzone rendered the progress label (0% -> 92%), uploaded, and landed on the server as:

h264  1080x1920  5.18 Mbps   aac 48kHz   ftyp@0.0% moov@0.0% mdat@0.1%
11.8 MB in, 2.76 MB out

Driven in real Chrome rather than a bundled Chromium build, since the bundled one has no HEVC decode — which is the exact case under test.

Running in production. All of the above is deployed on pulseclip.os.mieweb.org and pulseclip-dev2.os.mieweb.org and has been exercised by hand on an iPhone.

No server changes.