feat(android): cast viewport crop mirror (spec 061 T010) #1231

Merged
chris merged 1 commit from feat/061-cast-crop-android into main 2026-10-15 00:06:23 +02:00
Owner

Spec 061 T010, client-side only (the API crop endpoint is built in a parallel lane against the same fixed contract). While casting a PHOTO, pinching/panning in the viewer mirrors the crop onto the TV; zooming back to 1x returns the TV to the full preview. No backend changes, no web changes, no new strings, no new dependencies.

How it talks to the API crop endpoint (the fixed contract)

  • After the gesture settles (500ms idle), the app mints the existing POST /api/media/token with rendition "crop" (same client method, new rendition string) and LOADs
    {serverUrl}/api/media/{id}/crop?sx=&sy=&sw=&sh=&maxW=1280&st=<token>
    — sx/sy/sw/sh are normalized floats in [0,1] (5 decimals, Locale.US) describing the source rect within the FULL image; the token rides as ?st= via the existing withSignedToken, exactly like every other cast URL. Response is consumed by the Default Receiver as image/jpeg; the client assumes nothing beyond that.
  • The rect is computed against the full image's aspect (payload width/height), so the phone's preview-rendition geometry and the server's full-image geometry always agree.

Pieces

  • cast/ViewportCrop.kt (new, pure, JVM-tested): visibleSourceRect(...) inverts exactly the transform the viewer draws with (scale about the viewport centre + pan translate, documented on ViewerZoomState) and re-uses that transform's own fitContentSize so the two can never drift; clamped into [0,1]² with the endpoint's 0.01 minimum; returns null at ~1x or when dimensions are unknown (→ no crop, normal rendition).
  • CastController: the mint+sign+load tail of loadItem was extracted into performTokenedLoad (behaviour-identical, now shared); new showCrop(item, rect) is latest-wins on the same showJob as show() (a rapid gesture's in-flight load is cancelled by the next one); cropItemId tracks whether the TV shows a crop (set on crop-load success, cleared by any full-rendition load success, disconnect and session loss) and isCropShowing(item) guards the restore.
  • MediaViewerScreen: a third snapshotFlow over zoom scale/offset combined with connection + settledPage feeds cropDecisions (debounce(500).map(::cropAction)); viewport size comes from onSizeChanged. While disconnected nothing is ever LOADed — the viewer behaves exactly as before. Zoom reset → cast.show(item) (the full preview) only when the TV actually shows a crop, so the settle-sync swipe load never double-LOADs.
  • Slideshow interaction is deliberately best-effort: a crop LOAD simply replaces whatever is on the receiver; the slideshow keeps running on its own timer (and in practice the album screen stops it before the viewer is opened).

Edge cases

  • Videos never crop (gated in the screen's decision, in showCrop, and in cropMediaRequest).
  • Token mint failure → same cast_error_token snackbar pattern as show(); structural skips (no server url) are silent.
  • Rapid gestures: each new signal restarts the 500ms wait (last transform wins), and each LOAD supersedes in-flight ones (latest-wins showJob) — the TV can never land behind the phone.
  • Unknown payload dimensions → no crop (the zoom clamp falls back the same way).

Verification

From apps/android: ./gradlew :app:testDebugUnitTest :app:assembleDebug → BUILD SUCCESSFUL, 495 tests, 0 failures (new: ViewportCropTest 11 — zoom=1→null, centred zoom portrait/landscape, corner pans clamped, extreme 8:1 aspect, 0.01 floor, unit-square invariant; CropMirrorTest 8 — decision matrix + gesture-burst/quiet debounce on the virtual clock, latest-transform-wins; CastMediaTest +4 — crop URL/rendition/token appending and structural skips).

Merge note: the crop endpoint does not need to exist for this to merge — showCrop mints its token and LOADs exactly per contract, and while the endpoint 404s the receiver just keeps the previous media (mint failure already surfaces as the existing snackbar).

Spec 061 T010, client-side only (the API crop endpoint is built in a parallel lane against the same fixed contract). While casting a PHOTO, pinching/panning in the viewer mirrors the crop onto the TV; zooming back to 1x returns the TV to the full preview. No backend changes, no web changes, no new strings, no new dependencies. ## How it talks to the API crop endpoint (the fixed contract) - After the gesture settles (500ms idle), the app mints the existing `POST /api/media/token` with rendition `"crop"` (same client method, new rendition string) and LOADs `{serverUrl}/api/media/{id}/crop?sx=&sy=&sw=&sh=&maxW=1280&st=<token>` — sx/sy/sw/sh are normalized floats in [0,1] (5 decimals, Locale.US) describing the source rect within the FULL image; the token rides as `?st=` via the existing `withSignedToken`, exactly like every other cast URL. Response is consumed by the Default Receiver as `image/jpeg`; the client assumes nothing beyond that. - The rect is computed against the full image's aspect (payload `width`/`height`), so the phone's preview-rendition geometry and the server's full-image geometry always agree. ## Pieces - **`cast/ViewportCrop.kt` (new, pure, JVM-tested):** `visibleSourceRect(...)` inverts exactly the transform the viewer draws with (scale about the viewport centre + pan translate, documented on `ViewerZoomState`) and re-uses that transform's own `fitContentSize` so the two can never drift; clamped into [0,1]² with the endpoint's 0.01 minimum; returns **null** at ~1x or when dimensions are unknown (→ no crop, normal rendition). - **`CastController`:** the mint+sign+load tail of `loadItem` was extracted into `performTokenedLoad` (behaviour-identical, now shared); new `showCrop(item, rect)` is latest-wins on the same `showJob` as `show()` (a rapid gesture's in-flight load is cancelled by the next one); `cropItemId` tracks whether the TV shows a crop (set on crop-load success, cleared by any full-rendition load success, disconnect and session loss) and `isCropShowing(item)` guards the restore. - **`MediaViewerScreen`:** a third `snapshotFlow` over zoom scale/offset combined with connection + settledPage feeds `cropDecisions` (`debounce(500).map(::cropAction)`); viewport size comes from `onSizeChanged`. While disconnected nothing is ever LOADed — the viewer behaves exactly as before. Zoom reset → `cast.show(item)` (the full preview) only when the TV actually shows a crop, so the settle-sync swipe load never double-LOADs. - Slideshow interaction is deliberately best-effort: a crop LOAD simply replaces whatever is on the receiver; the slideshow keeps running on its own timer (and in practice the album screen stops it before the viewer is opened). ## Edge cases - Videos never crop (gated in the screen's decision, in `showCrop`, and in `cropMediaRequest`). - Token mint failure → same `cast_error_token` snackbar pattern as `show()`; structural skips (no server url) are silent. - Rapid gestures: each new signal restarts the 500ms wait (last transform wins), and each LOAD supersedes in-flight ones (latest-wins `showJob`) — the TV can never land behind the phone. - Unknown payload dimensions → no crop (the zoom clamp falls back the same way). ## Verification From `apps/android`: `./gradlew :app:testDebugUnitTest :app:assembleDebug` → BUILD SUCCESSFUL, **495 tests, 0 failures** (new: `ViewportCropTest` 11 — zoom=1→null, centred zoom portrait/landscape, corner pans clamped, extreme 8:1 aspect, 0.01 floor, unit-square invariant; `CropMirrorTest` 8 — decision matrix + gesture-burst/quiet debounce on the virtual clock, latest-transform-wins; `CastMediaTest` +4 — crop URL/rendition/token appending and structural skips). Merge note: the crop endpoint does not need to exist for this to merge — `showCrop` mints its token and LOADs exactly per contract, and while the endpoint 404s the receiver just keeps the previous media (mint failure already surfaces as the existing snackbar).
feat(android): cast viewport crop mirror — spec 061 T010
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 6m32s
3a0eb79588
While casting a photo, a pinch/pan in the viewer now LOADs the same crop
on the TV: after the gesture has been idle for 500ms the phone mints a
'crop' rendition token and casts GET /api/media/{id}/crop?sx&sy&sw&sh&maxW=1280
(normalized source rect of the full image, spec 061 contract); zooming
back to 1x hands the TV the full preview again — but only when a crop is
actually showing there, so a plain swipe never double-LOADs.

- cast/ViewportCrop.kt (new, pure): visibleSourceRect inverts exactly the
  viewer's transform (scale about centre + pan translate, via the shared
  fitContentSize), clamps into [0,1] with the endpoint's 0.01 floor, and
  returns null at 1x / unknown dimensions; CropSignal/cropAction decision
  matrix; cropDecisions = debounce(500ms) + decide, the pipeline the
  screen uses and the JVM suite drives on the virtual clock
- CastController: mint+sign+load tail of loadItem extracted into
  performTokenedLoad (behaviour-identical); showCrop is latest-wins on the
  same showJob; cropItemId tracks what the TV shows (cleared by any full
  load success, disconnect and session loss); isCropShowing guards the
  full-preview restore
- CastMedia: CastRendition.CROP + cropUrl/cropMediaRequest (Locale.US
  %.5f, maxW=1280); the token rides via the existing withSignedToken
- MediaViewerScreen: third snapshotFlow over zoom scale/offset combined
  with connection + settledPage, viewport size from onSizeChanged; videos
  never crop; disconnected sessions never produce an action

Tests: ViewportCropTest (11, rect math incl. corner pans, extreme aspect
mismatch, API-minimum floor), CropMirrorTest (8, decision matrix +
burst/quiet debounce on the virtual clock), CastMediaTest +4 (crop URL,
rendition, token appending, structural skips). 495 tests green.

No backend changes, no new strings, no new dependencies.
chris merged commit 642513d7be into main 2026-10-15 00:06:23 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1231
No description provided.