2026-01-11 16:59:33 -08:00
# AGENTS.md
feat(video,chat): native player, ad-break awareness, chat send/delay reliability, and tab redesign (#567)
Squash-merge commit. Covers four areas: native video player, chat reliability, multi-tab, and hardening.
## Native video player
- Direct HLS playback via `better_native_video_player` (forked from `plug-and-pay/flutter-native-video-player`, patched on `frosty-patches` branch)
- Twitch GQL playback token fetching with platform cookie extraction (iOS Swift + Android Kotlin plugins) for authenticated streams
- Quality selection (source, 720p, 480p, 360p, 160p, audio-only) persisted per channel
- Picture-in-picture: iOS automatic inline PiP, Android auto-PiP on API 31+ guarded against older devices
- Latency polling, chat latency sync, stall detection/recovery, startup auto-pause recovery, watchdog timers
- **Twitch stitched-ad break detection** (HLS `EXT-X-DATERANGE`) on both platforms, emitting `adBreakChanged` so the host suspends latency/stall recovery and chat sync during ads (program-date-time is unreliable then). Matches `CLASS="twitch-stitched-ad"` / `ID="stitched-ad-"` **and** the `X-TV-TWITCH-AD-*` attribute prefix (the durable signal streamlink/yt-dlp use)
- Shared `VideoPlayerInterface` so WebView and native paths are interchangeable via settings toggle
- `PlaybackAccessToken` model, `TwitchGqlApi` client
## Chat delay & send reliability
- **Optimistic send-finalize**: Twitch acks a sent message with a per-PRIVMSG USERSTATE (not an echo), which it can intermittently drop — more so under a long chat delay. A missing ack no longer shows a false "message may not have been sent" error; the send is finalized optimistically (local echo rendered), and only genuine rejection NOTICEs surface an error. Ack timeout scaled by the chat delay.
- **Per-line chat-delay bypass**: control/state lines (USERSTATE/ROOMSTATE/GLOBALUSERSTATE), rejection NOTICEs, the reconnect notice, and untagged server lines bypass the delay so send-acks and PONGs aren't stalled; only displayable chat content is delayed, staying in sync with delayed video.
- **Measured chat bottom-bar height**: the message list reflows to the composer's real measured height, fixing the input overlapping messages when a long message expands it (replaces a fixed-constant estimate).
- IRC tag parsing handles valueless and escaped tags per the IRCv3 message-tags spec (fixes a recent-messages RangeError on certain tags).
## Chat / multi-tab
- Redesigned tab chips: unread dot indicator, chips dim until WebSocket connects
- Animated tab options popover replacing `MenuAnchor` (no animation hook in Flutter 3.44)
- Simplified `ChatTabs` from `StatefulWidget` to `StatelessWidget`
- Focus-current-channel fade bump to 0.55; section-header alpha lifted to match the muted-label tier
- `addTab` now calls `setActiveTab` to snapshot outgoing tab's `lastSeenMessageId` — fixes spurious unread dots after adding a tab
- `onActivateSourceTab` threaded into `ChatUserModal` so Reply in merged mode switches to the correct source tab's composer
## Bug fixes and hardening
- **Reverted the experimental iOS low-latency mode** (5s live-edge join + 1.05x catch-up): AVPlayer can't sustain <~18s on Twitch (declared `TARGETDURATION:6` paces playlist refreshes), and the offset starved the buffer into pause-on-launch. Default join distance restored.
- Fork (Android): **cap `BEHIND_LIVE_WINDOW` recovery** so a stream repeatedly falling off the live window can't silently re-prepare forever; emits `error` on exhaustion so the host recovery ladder takes over
- Guard all Android `setAutoPipMode` calls with `_autoPipAvailable` — prevents `PlatformException` on Android 8–11; check `_disposed` after `isAutoPipAvailable` await to prevent post-dispose auto-PiP re-enable
- Remove `_isInPipMode` guard from `_onPaused` so `_paused` tracks actual state, fixing PiP play/pause toggle getting stuck
- Tighten iOS cookie domain check to exact `twitch.tv` / `.twitch.tv` suffix
- Invalidate the stored web session token when Twitch rejects it with a 401 (profile card flips back to unlinked; future loads skip the doomed authenticated request), and re-extract the cookie on launch when logged in without a linked session
- Send `play_session_id` and `player_backend=mediaplayer` to Usher, matching the web client / streamlink
- Fork (iOS): restore program-date-time latency measurement (a prior rev measured distance to the manifest edge, reading ~0s and silently disabling high-latency recovery / chat-delay auto-sync); release platform views on dispose (per-stream view + AVPlayerViewController leak), track the observed AVPlayerItem for KVO removal (sibling-view crash), main-thread seek results, resolve superseded load futures
- Fork (Android): clean up method handlers orphaned by PiP-time view disposal (leaked audio-focus listeners), drop the live-offset re-anchoring seekTo on metadata updates (latency creep), restore pre-duck volume, respect user pause in the stall watchdog, resolve superseded load futures
- Deep review pass: expire the quality-switch flag so stall recovery isn't disabled for the session, cap latency-driven recovery (clock-skew loop), generation-guard the error overlay, two-strike offline confirmation, controller null-safety on quality switch
- Tighten `/me` local-echo match (no longer renders `/meow ...` as an action); clear pending send text on disconnect
## Web / docs
- Remove stale Cloudflare Images binding from `wrangler.jsonc` (covered by `images.unoptimized: true`)
- Correct `web/AGENTS.md` Cache Components claim (feature not enabled)
- Repo and agent config cleanup
## Test plan
- [x] `flutter analyze` — clean (frosty + plugin lib)
- [x] `flutter test` — 319/319 pass (adds `ChatLatencySync`, `StreamInfoPoller`, video timing invariants, `PlaybackAccessToken`, IRC tag parsing)
- [x] Android plugin Kotlin compiles against the bumped fork rev
- [ ] Native player plays live streams on iOS and Android
- [ ] Quality switching works and persists across channel reopens
- [ ] PiP enters/exits correctly; pause/resume toggle in PiP window works
- [ ] Audio-only mode does not crash on Android < API 31
- [ ] Sending under a long synced chat delay no longer shows a false "may not have been sent" error
- [ ] Long composer text reflows the message list (no input/message overlap)
- [ ] Multi-tab: adding a tab does not mark previous tab as unread
- [ ] Merged chat: Reply from user modal targets the correct tab's composer
🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-06-13 17:06:24 -04:00
---
2026-03-07 00:32:04 -08:00
feat(video,chat): native player, ad-break awareness, chat send/delay reliability, and tab redesign (#567)
Squash-merge commit. Covers four areas: native video player, chat reliability, multi-tab, and hardening.
## Native video player
- Direct HLS playback via `better_native_video_player` (forked from `plug-and-pay/flutter-native-video-player`, patched on `frosty-patches` branch)
- Twitch GQL playback token fetching with platform cookie extraction (iOS Swift + Android Kotlin plugins) for authenticated streams
- Quality selection (source, 720p, 480p, 360p, 160p, audio-only) persisted per channel
- Picture-in-picture: iOS automatic inline PiP, Android auto-PiP on API 31+ guarded against older devices
- Latency polling, chat latency sync, stall detection/recovery, startup auto-pause recovery, watchdog timers
- **Twitch stitched-ad break detection** (HLS `EXT-X-DATERANGE`) on both platforms, emitting `adBreakChanged` so the host suspends latency/stall recovery and chat sync during ads (program-date-time is unreliable then). Matches `CLASS="twitch-stitched-ad"` / `ID="stitched-ad-"` **and** the `X-TV-TWITCH-AD-*` attribute prefix (the durable signal streamlink/yt-dlp use)
- Shared `VideoPlayerInterface` so WebView and native paths are interchangeable via settings toggle
- `PlaybackAccessToken` model, `TwitchGqlApi` client
## Chat delay & send reliability
- **Optimistic send-finalize**: Twitch acks a sent message with a per-PRIVMSG USERSTATE (not an echo), which it can intermittently drop — more so under a long chat delay. A missing ack no longer shows a false "message may not have been sent" error; the send is finalized optimistically (local echo rendered), and only genuine rejection NOTICEs surface an error. Ack timeout scaled by the chat delay.
- **Per-line chat-delay bypass**: control/state lines (USERSTATE/ROOMSTATE/GLOBALUSERSTATE), rejection NOTICEs, the reconnect notice, and untagged server lines bypass the delay so send-acks and PONGs aren't stalled; only displayable chat content is delayed, staying in sync with delayed video.
- **Measured chat bottom-bar height**: the message list reflows to the composer's real measured height, fixing the input overlapping messages when a long message expands it (replaces a fixed-constant estimate).
- IRC tag parsing handles valueless and escaped tags per the IRCv3 message-tags spec (fixes a recent-messages RangeError on certain tags).
## Chat / multi-tab
- Redesigned tab chips: unread dot indicator, chips dim until WebSocket connects
- Animated tab options popover replacing `MenuAnchor` (no animation hook in Flutter 3.44)
- Simplified `ChatTabs` from `StatefulWidget` to `StatelessWidget`
- Focus-current-channel fade bump to 0.55; section-header alpha lifted to match the muted-label tier
- `addTab` now calls `setActiveTab` to snapshot outgoing tab's `lastSeenMessageId` — fixes spurious unread dots after adding a tab
- `onActivateSourceTab` threaded into `ChatUserModal` so Reply in merged mode switches to the correct source tab's composer
## Bug fixes and hardening
- **Reverted the experimental iOS low-latency mode** (5s live-edge join + 1.05x catch-up): AVPlayer can't sustain <~18s on Twitch (declared `TARGETDURATION:6` paces playlist refreshes), and the offset starved the buffer into pause-on-launch. Default join distance restored.
- Fork (Android): **cap `BEHIND_LIVE_WINDOW` recovery** so a stream repeatedly falling off the live window can't silently re-prepare forever; emits `error` on exhaustion so the host recovery ladder takes over
- Guard all Android `setAutoPipMode` calls with `_autoPipAvailable` — prevents `PlatformException` on Android 8–11; check `_disposed` after `isAutoPipAvailable` await to prevent post-dispose auto-PiP re-enable
- Remove `_isInPipMode` guard from `_onPaused` so `_paused` tracks actual state, fixing PiP play/pause toggle getting stuck
- Tighten iOS cookie domain check to exact `twitch.tv` / `.twitch.tv` suffix
- Invalidate the stored web session token when Twitch rejects it with a 401 (profile card flips back to unlinked; future loads skip the doomed authenticated request), and re-extract the cookie on launch when logged in without a linked session
- Send `play_session_id` and `player_backend=mediaplayer` to Usher, matching the web client / streamlink
- Fork (iOS): restore program-date-time latency measurement (a prior rev measured distance to the manifest edge, reading ~0s and silently disabling high-latency recovery / chat-delay auto-sync); release platform views on dispose (per-stream view + AVPlayerViewController leak), track the observed AVPlayerItem for KVO removal (sibling-view crash), main-thread seek results, resolve superseded load futures
- Fork (Android): clean up method handlers orphaned by PiP-time view disposal (leaked audio-focus listeners), drop the live-offset re-anchoring seekTo on metadata updates (latency creep), restore pre-duck volume, respect user pause in the stall watchdog, resolve superseded load futures
- Deep review pass: expire the quality-switch flag so stall recovery isn't disabled for the session, cap latency-driven recovery (clock-skew loop), generation-guard the error overlay, two-strike offline confirmation, controller null-safety on quality switch
- Tighten `/me` local-echo match (no longer renders `/meow ...` as an action); clear pending send text on disconnect
## Web / docs
- Remove stale Cloudflare Images binding from `wrangler.jsonc` (covered by `images.unoptimized: true`)
- Correct `web/AGENTS.md` Cache Components claim (feature not enabled)
- Repo and agent config cleanup
## Test plan
- [x] `flutter analyze` — clean (frosty + plugin lib)
- [x] `flutter test` — 319/319 pass (adds `ChatLatencySync`, `StreamInfoPoller`, video timing invariants, `PlaybackAccessToken`, IRC tag parsing)
- [x] Android plugin Kotlin compiles against the bumped fork rev
- [ ] Native player plays live streams on iOS and Android
- [ ] Quality switching works and persists across channel reopens
- [ ] PiP enters/exits correctly; pause/resume toggle in PiP window works
- [ ] Audio-only mode does not crash on Android < API 31
- [ ] Sending under a long synced chat delay no longer shows a false "may not have been sent" error
- [ ] Long composer text reflows the message list (no input/message overlap)
- [ ] Multi-tab: adding a tab does not mark previous tab as unread
- [ ] Merged chat: Reply from user modal targets the correct tab's composer
🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-06-13 17:06:24 -04:00
# Author Preferences
2026-01-11 16:59:33 -08:00
feat(video,chat): native player, ad-break awareness, chat send/delay reliability, and tab redesign (#567)
Squash-merge commit. Covers four areas: native video player, chat reliability, multi-tab, and hardening.
## Native video player
- Direct HLS playback via `better_native_video_player` (forked from `plug-and-pay/flutter-native-video-player`, patched on `frosty-patches` branch)
- Twitch GQL playback token fetching with platform cookie extraction (iOS Swift + Android Kotlin plugins) for authenticated streams
- Quality selection (source, 720p, 480p, 360p, 160p, audio-only) persisted per channel
- Picture-in-picture: iOS automatic inline PiP, Android auto-PiP on API 31+ guarded against older devices
- Latency polling, chat latency sync, stall detection/recovery, startup auto-pause recovery, watchdog timers
- **Twitch stitched-ad break detection** (HLS `EXT-X-DATERANGE`) on both platforms, emitting `adBreakChanged` so the host suspends latency/stall recovery and chat sync during ads (program-date-time is unreliable then). Matches `CLASS="twitch-stitched-ad"` / `ID="stitched-ad-"` **and** the `X-TV-TWITCH-AD-*` attribute prefix (the durable signal streamlink/yt-dlp use)
- Shared `VideoPlayerInterface` so WebView and native paths are interchangeable via settings toggle
- `PlaybackAccessToken` model, `TwitchGqlApi` client
## Chat delay & send reliability
- **Optimistic send-finalize**: Twitch acks a sent message with a per-PRIVMSG USERSTATE (not an echo), which it can intermittently drop — more so under a long chat delay. A missing ack no longer shows a false "message may not have been sent" error; the send is finalized optimistically (local echo rendered), and only genuine rejection NOTICEs surface an error. Ack timeout scaled by the chat delay.
- **Per-line chat-delay bypass**: control/state lines (USERSTATE/ROOMSTATE/GLOBALUSERSTATE), rejection NOTICEs, the reconnect notice, and untagged server lines bypass the delay so send-acks and PONGs aren't stalled; only displayable chat content is delayed, staying in sync with delayed video.
- **Measured chat bottom-bar height**: the message list reflows to the composer's real measured height, fixing the input overlapping messages when a long message expands it (replaces a fixed-constant estimate).
- IRC tag parsing handles valueless and escaped tags per the IRCv3 message-tags spec (fixes a recent-messages RangeError on certain tags).
## Chat / multi-tab
- Redesigned tab chips: unread dot indicator, chips dim until WebSocket connects
- Animated tab options popover replacing `MenuAnchor` (no animation hook in Flutter 3.44)
- Simplified `ChatTabs` from `StatefulWidget` to `StatelessWidget`
- Focus-current-channel fade bump to 0.55; section-header alpha lifted to match the muted-label tier
- `addTab` now calls `setActiveTab` to snapshot outgoing tab's `lastSeenMessageId` — fixes spurious unread dots after adding a tab
- `onActivateSourceTab` threaded into `ChatUserModal` so Reply in merged mode switches to the correct source tab's composer
## Bug fixes and hardening
- **Reverted the experimental iOS low-latency mode** (5s live-edge join + 1.05x catch-up): AVPlayer can't sustain <~18s on Twitch (declared `TARGETDURATION:6` paces playlist refreshes), and the offset starved the buffer into pause-on-launch. Default join distance restored.
- Fork (Android): **cap `BEHIND_LIVE_WINDOW` recovery** so a stream repeatedly falling off the live window can't silently re-prepare forever; emits `error` on exhaustion so the host recovery ladder takes over
- Guard all Android `setAutoPipMode` calls with `_autoPipAvailable` — prevents `PlatformException` on Android 8–11; check `_disposed` after `isAutoPipAvailable` await to prevent post-dispose auto-PiP re-enable
- Remove `_isInPipMode` guard from `_onPaused` so `_paused` tracks actual state, fixing PiP play/pause toggle getting stuck
- Tighten iOS cookie domain check to exact `twitch.tv` / `.twitch.tv` suffix
- Invalidate the stored web session token when Twitch rejects it with a 401 (profile card flips back to unlinked; future loads skip the doomed authenticated request), and re-extract the cookie on launch when logged in without a linked session
- Send `play_session_id` and `player_backend=mediaplayer` to Usher, matching the web client / streamlink
- Fork (iOS): restore program-date-time latency measurement (a prior rev measured distance to the manifest edge, reading ~0s and silently disabling high-latency recovery / chat-delay auto-sync); release platform views on dispose (per-stream view + AVPlayerViewController leak), track the observed AVPlayerItem for KVO removal (sibling-view crash), main-thread seek results, resolve superseded load futures
- Fork (Android): clean up method handlers orphaned by PiP-time view disposal (leaked audio-focus listeners), drop the live-offset re-anchoring seekTo on metadata updates (latency creep), restore pre-duck volume, respect user pause in the stall watchdog, resolve superseded load futures
- Deep review pass: expire the quality-switch flag so stall recovery isn't disabled for the session, cap latency-driven recovery (clock-skew loop), generation-guard the error overlay, two-strike offline confirmation, controller null-safety on quality switch
- Tighten `/me` local-echo match (no longer renders `/meow ...` as an action); clear pending send text on disconnect
## Web / docs
- Remove stale Cloudflare Images binding from `wrangler.jsonc` (covered by `images.unoptimized: true`)
- Correct `web/AGENTS.md` Cache Components claim (feature not enabled)
- Repo and agent config cleanup
## Test plan
- [x] `flutter analyze` — clean (frosty + plugin lib)
- [x] `flutter test` — 319/319 pass (adds `ChatLatencySync`, `StreamInfoPoller`, video timing invariants, `PlaybackAccessToken`, IRC tag parsing)
- [x] Android plugin Kotlin compiles against the bumped fork rev
- [ ] Native player plays live streams on iOS and Android
- [ ] Quality switching works and persists across channel reopens
- [ ] PiP enters/exits correctly; pause/resume toggle in PiP window works
- [ ] Audio-only mode does not crash on Android < API 31
- [ ] Sending under a long synced chat delay no longer shows a false "may not have been sent" error
- [ ] Long composer text reflows the message list (no input/message overlap)
- [ ] Multi-tab: adding a tab does not mark previous tab as unread
- [ ] Merged chat: Reply from user modal targets the correct tab's composer
🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-06-13 17:06:24 -04:00
## Code Opinions
- Package imports (`import 'package:frosty/...'` ), not relative imports
- Trailing commas always
- Single quotes
- Extract related/grouped logic (state, reactions, actions) into dedicated stores when it improves readability — keep widgets focused on rendering
## Infrastructure Checklist
When creating new infrastructure (screens, API clients, stores), use exploration findings as a **checklist** — systematically verify each convention is followed before writing code.
## Never
- Never edit `.g.dart` files directly — always regenerate with `dart run build_runner build`
---
# Project
Flutter mobile app for browsing Twitch on iOS and Android. Uses MobX for state management with code generation.
2026-01-11 16:59:33 -08:00
migrate web to next 16 template and redesign landing page (#526)
* migrate web to next-template stack (next 16, react 19, tailwind 4)
replace all infrastructure with next-template conventions:
- next.js 14 -> 16 (turbopack default, typed routes, react compiler)
- react 18 -> 19
- tailwind css 3 -> 4 (css-first config, oklch theme system)
- eslint 8 (.eslintrc) -> 9 (flat config with stricter rules)
- add shadcn/ui, base-ui, cva component primitives
- upgrade theme toggle to light/dark/system dropdown
- migrate hardcoded neutral classes to semantic oklch tokens
- drop unused @tailwindcss/forms, autoprefixer
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add no-misused-promises config for async JSX handlers, warn on array index keys
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* base-vega
* sync frosty web with next-template runtime and claude tooling for cloudflare parity
* gitignore .dev.vars per cloudflare best practice
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add observability configuration to wrangler.jsonc
* remove marquee emote background from hero section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* improve CLAUDE.md and AGENTS.md files across project
Remove redundant root CLAUDE.md (kept in .claude/ instead), add Commands
and Source Structure sections to Flutter AGENTS.md, clarify global vs
feature store placement, and fill gaps in web AGENTS.md (shadcn base-vega
style, constants.ts, no-array-index-key rule, commit conventions).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* switch shadcn theme from neutral to violet, replace twitch-purple with primary token
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* initial redesign
* auto-infer nativeButton in Button wrapper when render prop is used
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* replace skeleton carousel with real screenshots and video, add responsive phone scaling and mobile menu
- Replace PhoneSkeleton with PhoneFrame/PhoneMedia using actual app screenshots and video
- Fluid phone sizing via aspect-ratio with responsive max-h/max-w caps
- Non-circular carousel with swipe gestures, dot indicator, and hover opacity boost
- Video plays only when focused, pauses when off-screen
- Collapse header actions into dropdown menu on mobile, add Contact link
- Viewport-height layout with no scrolling on any screen size
- Remove footer, move contact to header
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* improve header consistency, carousel layout, and responsive centering
- add icons to all header buttons (Contact, Donate, GitHub)
- switch theme toggle to ghost variant for consistency
- bump header collapse breakpoint from md to lg
- move carousel arrows to overlay positions with animated enter/exit
- hide arrows at first/last slide
- fix vertical centering of phone+description group across all screen sizes
- add smooth blur+slide transition for description text
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add contact dropdown with copy email toast
- replace direct mailto link with dropdown: send email or copy email
- install sonner for toast notifications, show top-center on copy
- extract emailAddress constant for clipboard use
- add copy option to mobile hamburger menu too
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* replace mobile hamburger menu with icon buttons
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* redesign hero copy, badge-style download buttons, and mobile layout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add consistent padding and object-contain to carousel media
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add emote physics background to hero section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* move container styling to hero panel, refresh emote set with 2025 trending picks
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add staggered entrance animations and remove grid gap
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add 30-day cache headers for video and logo assets
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add emote collisions and aspect-ratio tracking, refine hero layout
Emote physics: add particle-particle elastic collisions, per-particle
width measurement for correct aspect ratios, new emotes (aga, WW, o7,
FLASHBANG, LULW, Deadass), bump count to 30. Layout: absolute-position
header with z-20, increase mobile carousel ratio to 2fr/4fr, reserve
min-h-10 for description text, remove panel rounding.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix carousel lint warnings: useSyncExternalStore, ref naming, stable keys
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add seo metadata, sitemap, and robots.txt
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add privacy link to header and footer credit
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* update privacy policy content and restyle with mono layout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* reorder header nav and add mobile hamburger menu
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refresh web dependencies and smooth footer credit hover transition
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-17 22:53:43 -05:00
## Commands
```bash
flutter pub get # Install dependencies
flutter run --dart-define=clientId=ID --dart-define=secret=SECRET # Run with Twitch credentials
flutter analyze # Static analysis (run after changes)
flutter test # Run tests (if changes touch testable logic)
dart run build_runner build # Regenerate .g.dart files (MobX/JSON models)
dart run build_runner build --delete-conflicting-outputs # Same, but clears stale outputs
```
## Source Structure
- `lib/apis/` — API services (all extend `BaseApiClient` )
- `lib/models/` — Data models (`@JsonSerializable` with `.g.dart` codegen)
- `lib/screens/{feature}/` — Feature screens with co-located `stores/` subdirectories
- `lib/stores/` — Global stores only (e.g., `global_assets_store.dart` )
- `lib/services/` — App-level services
- `lib/widgets/` — Shared widgets
- `lib/utils/` — Utility functions
feat(video,chat): native player, ad-break awareness, chat send/delay reliability, and tab redesign (#567)
Squash-merge commit. Covers four areas: native video player, chat reliability, multi-tab, and hardening.
## Native video player
- Direct HLS playback via `better_native_video_player` (forked from `plug-and-pay/flutter-native-video-player`, patched on `frosty-patches` branch)
- Twitch GQL playback token fetching with platform cookie extraction (iOS Swift + Android Kotlin plugins) for authenticated streams
- Quality selection (source, 720p, 480p, 360p, 160p, audio-only) persisted per channel
- Picture-in-picture: iOS automatic inline PiP, Android auto-PiP on API 31+ guarded against older devices
- Latency polling, chat latency sync, stall detection/recovery, startup auto-pause recovery, watchdog timers
- **Twitch stitched-ad break detection** (HLS `EXT-X-DATERANGE`) on both platforms, emitting `adBreakChanged` so the host suspends latency/stall recovery and chat sync during ads (program-date-time is unreliable then). Matches `CLASS="twitch-stitched-ad"` / `ID="stitched-ad-"` **and** the `X-TV-TWITCH-AD-*` attribute prefix (the durable signal streamlink/yt-dlp use)
- Shared `VideoPlayerInterface` so WebView and native paths are interchangeable via settings toggle
- `PlaybackAccessToken` model, `TwitchGqlApi` client
## Chat delay & send reliability
- **Optimistic send-finalize**: Twitch acks a sent message with a per-PRIVMSG USERSTATE (not an echo), which it can intermittently drop — more so under a long chat delay. A missing ack no longer shows a false "message may not have been sent" error; the send is finalized optimistically (local echo rendered), and only genuine rejection NOTICEs surface an error. Ack timeout scaled by the chat delay.
- **Per-line chat-delay bypass**: control/state lines (USERSTATE/ROOMSTATE/GLOBALUSERSTATE), rejection NOTICEs, the reconnect notice, and untagged server lines bypass the delay so send-acks and PONGs aren't stalled; only displayable chat content is delayed, staying in sync with delayed video.
- **Measured chat bottom-bar height**: the message list reflows to the composer's real measured height, fixing the input overlapping messages when a long message expands it (replaces a fixed-constant estimate).
- IRC tag parsing handles valueless and escaped tags per the IRCv3 message-tags spec (fixes a recent-messages RangeError on certain tags).
## Chat / multi-tab
- Redesigned tab chips: unread dot indicator, chips dim until WebSocket connects
- Animated tab options popover replacing `MenuAnchor` (no animation hook in Flutter 3.44)
- Simplified `ChatTabs` from `StatefulWidget` to `StatelessWidget`
- Focus-current-channel fade bump to 0.55; section-header alpha lifted to match the muted-label tier
- `addTab` now calls `setActiveTab` to snapshot outgoing tab's `lastSeenMessageId` — fixes spurious unread dots after adding a tab
- `onActivateSourceTab` threaded into `ChatUserModal` so Reply in merged mode switches to the correct source tab's composer
## Bug fixes and hardening
- **Reverted the experimental iOS low-latency mode** (5s live-edge join + 1.05x catch-up): AVPlayer can't sustain <~18s on Twitch (declared `TARGETDURATION:6` paces playlist refreshes), and the offset starved the buffer into pause-on-launch. Default join distance restored.
- Fork (Android): **cap `BEHIND_LIVE_WINDOW` recovery** so a stream repeatedly falling off the live window can't silently re-prepare forever; emits `error` on exhaustion so the host recovery ladder takes over
- Guard all Android `setAutoPipMode` calls with `_autoPipAvailable` — prevents `PlatformException` on Android 8–11; check `_disposed` after `isAutoPipAvailable` await to prevent post-dispose auto-PiP re-enable
- Remove `_isInPipMode` guard from `_onPaused` so `_paused` tracks actual state, fixing PiP play/pause toggle getting stuck
- Tighten iOS cookie domain check to exact `twitch.tv` / `.twitch.tv` suffix
- Invalidate the stored web session token when Twitch rejects it with a 401 (profile card flips back to unlinked; future loads skip the doomed authenticated request), and re-extract the cookie on launch when logged in without a linked session
- Send `play_session_id` and `player_backend=mediaplayer` to Usher, matching the web client / streamlink
- Fork (iOS): restore program-date-time latency measurement (a prior rev measured distance to the manifest edge, reading ~0s and silently disabling high-latency recovery / chat-delay auto-sync); release platform views on dispose (per-stream view + AVPlayerViewController leak), track the observed AVPlayerItem for KVO removal (sibling-view crash), main-thread seek results, resolve superseded load futures
- Fork (Android): clean up method handlers orphaned by PiP-time view disposal (leaked audio-focus listeners), drop the live-offset re-anchoring seekTo on metadata updates (latency creep), restore pre-duck volume, respect user pause in the stall watchdog, resolve superseded load futures
- Deep review pass: expire the quality-switch flag so stall recovery isn't disabled for the session, cap latency-driven recovery (clock-skew loop), generation-guard the error overlay, two-strike offline confirmation, controller null-safety on quality switch
- Tighten `/me` local-echo match (no longer renders `/meow ...` as an action); clear pending send text on disconnect
## Web / docs
- Remove stale Cloudflare Images binding from `wrangler.jsonc` (covered by `images.unoptimized: true`)
- Correct `web/AGENTS.md` Cache Components claim (feature not enabled)
- Repo and agent config cleanup
## Test plan
- [x] `flutter analyze` — clean (frosty + plugin lib)
- [x] `flutter test` — 319/319 pass (adds `ChatLatencySync`, `StreamInfoPoller`, video timing invariants, `PlaybackAccessToken`, IRC tag parsing)
- [x] Android plugin Kotlin compiles against the bumped fork rev
- [ ] Native player plays live streams on iOS and Android
- [ ] Quality switching works and persists across channel reopens
- [ ] PiP enters/exits correctly; pause/resume toggle in PiP window works
- [ ] Audio-only mode does not crash on Android < API 31
- [ ] Sending under a long synced chat delay no longer shows a false "may not have been sent" error
- [ ] Long composer text reflows the message list (no input/message overlap)
- [ ] Multi-tab: adding a tab does not mark previous tab as unread
- [ ] Merged chat: Reply from user modal targets the correct tab's composer
🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-06-13 17:06:24 -04:00
## Architecture
2026-01-11 16:59:33 -08:00
migrate web to next 16 template and redesign landing page (#526)
* migrate web to next-template stack (next 16, react 19, tailwind 4)
replace all infrastructure with next-template conventions:
- next.js 14 -> 16 (turbopack default, typed routes, react compiler)
- react 18 -> 19
- tailwind css 3 -> 4 (css-first config, oklch theme system)
- eslint 8 (.eslintrc) -> 9 (flat config with stricter rules)
- add shadcn/ui, base-ui, cva component primitives
- upgrade theme toggle to light/dark/system dropdown
- migrate hardcoded neutral classes to semantic oklch tokens
- drop unused @tailwindcss/forms, autoprefixer
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add no-misused-promises config for async JSX handlers, warn on array index keys
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* base-vega
* sync frosty web with next-template runtime and claude tooling for cloudflare parity
* gitignore .dev.vars per cloudflare best practice
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add observability configuration to wrangler.jsonc
* remove marquee emote background from hero section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* improve CLAUDE.md and AGENTS.md files across project
Remove redundant root CLAUDE.md (kept in .claude/ instead), add Commands
and Source Structure sections to Flutter AGENTS.md, clarify global vs
feature store placement, and fill gaps in web AGENTS.md (shadcn base-vega
style, constants.ts, no-array-index-key rule, commit conventions).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* switch shadcn theme from neutral to violet, replace twitch-purple with primary token
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* initial redesign
* auto-infer nativeButton in Button wrapper when render prop is used
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* replace skeleton carousel with real screenshots and video, add responsive phone scaling and mobile menu
- Replace PhoneSkeleton with PhoneFrame/PhoneMedia using actual app screenshots and video
- Fluid phone sizing via aspect-ratio with responsive max-h/max-w caps
- Non-circular carousel with swipe gestures, dot indicator, and hover opacity boost
- Video plays only when focused, pauses when off-screen
- Collapse header actions into dropdown menu on mobile, add Contact link
- Viewport-height layout with no scrolling on any screen size
- Remove footer, move contact to header
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* improve header consistency, carousel layout, and responsive centering
- add icons to all header buttons (Contact, Donate, GitHub)
- switch theme toggle to ghost variant for consistency
- bump header collapse breakpoint from md to lg
- move carousel arrows to overlay positions with animated enter/exit
- hide arrows at first/last slide
- fix vertical centering of phone+description group across all screen sizes
- add smooth blur+slide transition for description text
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add contact dropdown with copy email toast
- replace direct mailto link with dropdown: send email or copy email
- install sonner for toast notifications, show top-center on copy
- extract emailAddress constant for clipboard use
- add copy option to mobile hamburger menu too
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* replace mobile hamburger menu with icon buttons
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* redesign hero copy, badge-style download buttons, and mobile layout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add consistent padding and object-contain to carousel media
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add emote physics background to hero section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* move container styling to hero panel, refresh emote set with 2025 trending picks
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add staggered entrance animations and remove grid gap
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add 30-day cache headers for video and logo assets
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add emote collisions and aspect-ratio tracking, refine hero layout
Emote physics: add particle-particle elastic collisions, per-particle
width measurement for correct aspect ratios, new emotes (aga, WW, o7,
FLASHBANG, LULW, Deadass), bump count to 30. Layout: absolute-position
header with z-20, increase mobile carousel ratio to 2fr/4fr, reserve
min-h-10 for description text, remove panel rounding.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix carousel lint warnings: useSyncExternalStore, ref naming, stable keys
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add seo metadata, sitemap, and robots.txt
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add privacy link to header and footer credit
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* update privacy policy content and restyle with mono layout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* reorder header nav and add mobile hamburger menu
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refresh web dependencies and smooth footer credit hover transition
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-17 22:53:43 -05:00
- Feature stores live in `lib/screens/{feature}/stores/` — don't create new top-level store files (only `lib/stores/` holds global stores)
2026-02-07 01:02:47 -08:00
- All API services extend `BaseApiClient` (`lib/apis/base_api_client.dart` ) — don't create standalone API classes
- MobX stores use a generated mixin pattern — see `lib/screens/settings/stores/auth_store.dart` for the canonical example
2026-02-07 00:46:01 -08:00
2026-02-07 01:02:47 -08:00
## Gotchas
2026-02-07 00:46:01 -08:00
migrate web to next 16 template and redesign landing page (#526)
* migrate web to next-template stack (next 16, react 19, tailwind 4)
replace all infrastructure with next-template conventions:
- next.js 14 -> 16 (turbopack default, typed routes, react compiler)
- react 18 -> 19
- tailwind css 3 -> 4 (css-first config, oklch theme system)
- eslint 8 (.eslintrc) -> 9 (flat config with stricter rules)
- add shadcn/ui, base-ui, cva component primitives
- upgrade theme toggle to light/dark/system dropdown
- migrate hardcoded neutral classes to semantic oklch tokens
- drop unused @tailwindcss/forms, autoprefixer
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add no-misused-promises config for async JSX handlers, warn on array index keys
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* base-vega
* sync frosty web with next-template runtime and claude tooling for cloudflare parity
* gitignore .dev.vars per cloudflare best practice
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add observability configuration to wrangler.jsonc
* remove marquee emote background from hero section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* improve CLAUDE.md and AGENTS.md files across project
Remove redundant root CLAUDE.md (kept in .claude/ instead), add Commands
and Source Structure sections to Flutter AGENTS.md, clarify global vs
feature store placement, and fill gaps in web AGENTS.md (shadcn base-vega
style, constants.ts, no-array-index-key rule, commit conventions).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* switch shadcn theme from neutral to violet, replace twitch-purple with primary token
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* initial redesign
* auto-infer nativeButton in Button wrapper when render prop is used
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* replace skeleton carousel with real screenshots and video, add responsive phone scaling and mobile menu
- Replace PhoneSkeleton with PhoneFrame/PhoneMedia using actual app screenshots and video
- Fluid phone sizing via aspect-ratio with responsive max-h/max-w caps
- Non-circular carousel with swipe gestures, dot indicator, and hover opacity boost
- Video plays only when focused, pauses when off-screen
- Collapse header actions into dropdown menu on mobile, add Contact link
- Viewport-height layout with no scrolling on any screen size
- Remove footer, move contact to header
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* improve header consistency, carousel layout, and responsive centering
- add icons to all header buttons (Contact, Donate, GitHub)
- switch theme toggle to ghost variant for consistency
- bump header collapse breakpoint from md to lg
- move carousel arrows to overlay positions with animated enter/exit
- hide arrows at first/last slide
- fix vertical centering of phone+description group across all screen sizes
- add smooth blur+slide transition for description text
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add contact dropdown with copy email toast
- replace direct mailto link with dropdown: send email or copy email
- install sonner for toast notifications, show top-center on copy
- extract emailAddress constant for clipboard use
- add copy option to mobile hamburger menu too
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* replace mobile hamburger menu with icon buttons
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* redesign hero copy, badge-style download buttons, and mobile layout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add consistent padding and object-contain to carousel media
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add emote physics background to hero section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* move container styling to hero panel, refresh emote set with 2025 trending picks
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add staggered entrance animations and remove grid gap
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add 30-day cache headers for video and logo assets
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add emote collisions and aspect-ratio tracking, refine hero layout
Emote physics: add particle-particle elastic collisions, per-particle
width measurement for correct aspect ratios, new emotes (aga, WW, o7,
FLASHBANG, LULW, Deadass), bump count to 30. Layout: absolute-position
header with z-20, increase mobile carousel ratio to 2fr/4fr, reserve
min-h-10 for description text, remove panel rounding.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix carousel lint warnings: useSyncExternalStore, ref naming, stable keys
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add seo metadata, sitemap, and robots.txt
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add privacy link to header and footer credit
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* update privacy policy content and restyle with mono layout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* reorder header nav and add mobile hamburger menu
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refresh web dependencies and smooth footer credit hover transition
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-17 22:53:43 -05:00
- After changing MobX stores or `@JsonSerializable` models, regenerate with `dart run build_runner build` . Never edit `.g.dart` files directly. Commit `.g.dart` files to source control.
2026-02-07 01:02:47 -08:00
- The secure storage cleanup in `main.dart` looks unnecessary but handles an Android/iOS edge case where secure storage persists after uninstall. Don't remove it.
2026-01-11 16:59:33 -08:00
2026-03-07 00:32:04 -08:00
## Testing
- `flutter test` runs all tests; `flutter test test/path/to/file.dart` for a single file
- HTTP mocking: `http_mock_adapter` (`DioAdapter` ) — use full URLs in `onGet` /`onPost`
- General mocking: `mocktail` (no codegen required)
- Fixtures live in `test/fixtures/` (e.g., `irc_messages.dart` , `api_responses.dart` )
