9ade5d1ad1
🤖 ## Summary When you read a channel or thread on the phone, the web and desktop app (buzz-app) should show it as read too, and the reverse. buzz-app no longer saves a "read" mark for each ordinary message. It saves one "caught up to here" mark per channel and per thread, and keeps per-message marks only for mentions, DMs, broadcasts and replies. Mobile already reads those marks. This PR makes mobile write them, so reading on the phone clears unread on other devices and saved read state stays small. What changes on the phone: - Reaching the bottom of a channel, and staying there for 300 ms, marks it caught up. Reaching the end of a thread does the same for that thread. - A message you see fully on screen, away from the bottom, is marked read on its own. - Mentions, DMs, broadcasts and thread replies you see keep their own read marks, as in buzz-app. - Automatic reading never marks the whole channel read. Only the explicit **Mark read** action does that. DMs and forums are the exception: opening one marks it all read, as mobile does today. - Reaching the bottom of a channel you marked unread ends that manual unread. Unseen mentions and replies stay unread. - Activity rows clear when you have read every message in the row, not just the newest. ### Related issue None found. buzz-app makes the same DM and manual-unread changes in https://github.com/block/buzz-app/pull/616. ### Testing - Unit tests cover the new write rules, Activity rows and the size limit on saved read state. - Widget tests cover reading on the channel page and the thread page, opening a DM, and reaching the bottom of a channel you marked unread. - No visual changes. ## Details **Read marks.** "Caught up" is saved as `activity:<channel>` for a channel and `thread-activity:<root>` for a thread. A caught-up mark reads only ordinary top-level messages (channel) or that thread's replies (thread). A per-message mark is `msg:<id>`. **Caught-up time.** The mark is set to the time of the bottom row, and never later than the current time. The time of a newer reply is not used. So a top-level message that arrives late, with an earlier timestamp, stays unread. A clock that runs fast, on this phone or the sender's, cannot mark messages read before they arrive. **Nested threads.** A thread opened on a nested reply shows only one branch. Reaching its end writes per-message marks only, so unread messages in other branches stay unread. **Reading delay.** The 300 ms reading delay now restarts only when messages arrive or leave. Before, any page rebuild restarted it, for example a typing indicator. **Activity rows.** A row that groups several events is done only when each event is read. Each event is checked against the channel mark, its own `msg:` mark, and its thread marks if it is a reply. Opening a row goes to the oldest unread event. **Publishing.** Mobile no longer republishes per-message marks it got from other devices. buzz-app removes those once a caught-up mark covers them. Broad marks (channel, thread, caught-up) are still republished, so they stay available after the fetch window. The published blob is capped at buzz-app's 40 KiB limit. Channel marks are kept first, then thread marks, then caught-up marks, then the newest per-message marks. Before, a blob over the encryption limit (about 64 KiB) turned off sync for the rest of the session. **DMs and manual unread.** Opening a DM reads it through the newest loaded message, replies included, as mobile does today. Reaching the bottom of a channel ends a manual unread. Manual unread on mobile is local to this session, so ending it does not change what other devices see. **Compatibility.** Older desktop builds read only channel and per-message marks. They may show extra unread for channels read on the phone. **Follow-ups, not in this PR** - Unread catch-up fetches start after the channel mark and are capped at 1,000 events. In a busy channel, an old unread mention can drop out of the badge. The fetch should also start from the caught-up mark, or load more pages. - Each mark triggers its own save and rebuild. They could be batched. - Broadcast replies are counted slightly differently from buzz-app. - buzz-app can also move its caught-up mark past the current time. --------- Signed-off-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz> Co-authored-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz>
Buzz Mobile
Flutter mobile client for Buzz.
See VISION_MOBILE.md for intended behavior and architecture.
Setup
Use the Flutter SDK pinned by the repository. Activate Hermit from the repo root before resolving packages or running any Flutter command:
cd /path/to/buzz
. ./bin/activate-hermit
./bin/just mobile-install
mobile-build-android intentionally builds with --no-pub. If an IDE or an
external Flutter SDK has touched mobile/.dart_tool, rerun mobile-install
with the pinned SDK before building so flutter_test, sky_engine, and the
engine all come from the same Flutter version.
Run
# From repo root (applies a worktree-isolated debug identity and starts/reuses Simulator):
just mobile-dev
# Direct (uses the app's configured community; apply worktree overrides first):
cd mobile && flutter run --dart-define=BUZZ_PUSH_GATEWAY_URL=https://push.example
Worktree-aware debug identity
Debug builds produced from a git worktree get a unique app identifier keyed
to the worktree directory name
(xyz.block.buzz.dev.mobile.<slug> on iOS,
xyz.block.buzz.mobile.<slug> on Android) plus a display-only branch label
in the app name (Buzz (my-branch), or a short SHA when the worktree is
detached). Because the identifier follows the directory rather than the
branch, one worktree keeps exactly one installed app — and its login state —
across branch switches, and builds from multiple worktrees install side by
side, mirroring the desktop dev experience. Release and profile builds
always keep the production identity and name.
just mobile-dev and just mobile-build-android apply this automatically by
running scripts/mobile-worktree-overrides.sh, which writes two gitignored
files:
mobile/ios/Flutter/WorktreeOverrides.xcconfig(included by Debug builds only; a developer'sAppOverrides.xcconfigis included after it, so app-specific overrides like a personalBUNDLE_IDENTIFIERfor device signing always win)mobile/android/worktree.properties(read by the debug build type only)
Android developers can keep a stable local test identity that takes precedence
over the generated worktree values by creating the gitignored
mobile/android/AppOverrides.properties:
appName=Buzz Pairing
applicationIdSuffix=.device_pairing_e2e1
These values are consumed by the debug build type only. The standard
just mobile-build-android command can still be used; regenerating
worktree.properties does not overwrite AppOverrides.properties. Release
and profile builds keep the production Buzz name and application ID.
For direct Xcode / Android Studio / flutter run development, run
./scripts/mobile-worktree-overrides.sh from the repo root once per branch
switch to refresh the display label (the install identity never changes);
the persisted files are then picked up by any subsequent build. In the main
checkout the script is a no-op that removes stale override files, restoring
the plain Buzz identity. To enable push in direct Xcode builds and Runner tests, supply a
BUZZ_PUSH_GATEWAY_URL build setting in the gitignored
mobile/ios/Flutter/AppOverrides.xcconfig; the build phase validates and
passes it through as a Flutter Dart define. Since // begins an xcconfig
comment, spell the origin as BUZZ_PUSH_GATEWAY_URL = https:/$()/push.example.
For an Android debug build that must remain installed alongside other Buzz worktree builds, set an explicit launcher name and package suffix when invoking the generator or a recipe that invokes it:
BUZZ_PUSH_GATEWAY_URL="https://push.example" \
BUZZ_ANDROID_DEBUG_APP_NAME="Buzz Huddles" \
BUZZ_ANDROID_DEBUG_ID_SUFFIX=".huddles_829c" \
./bin/just mobile-build-android
This example produces the debug-only package
xyz.block.buzz.mobile.huddles_829c with the launcher label Buzz Huddles.
The suffix must start with a dot followed by a lowercase letter and may contain
only lowercase letters, digits, and underscores. Release and profile builds
ignore these overrides and retain the production package and name.
To remove leftover worktree-suffixed installs from booted iOS simulators and
connected Android emulators, run just mobile-clean (add --dry-run via
./scripts/mobile-worktree-clean.sh --dry-run to preview). Production
installs are never touched.
iOS push capability
Every iOS artifact builds and embeds the Notification Service Extension and
native push bridge. Runtime activation is fail-closed and scoped to the current
relay. After authenticated connectivity and a fully valid NIP-11 buzz-push-v1 push
descriptor, Buzz independently requests display permission and registers with
APNs. Display denial or request failure does not gate the device token, gateway
enrollment, or lease publication, so a later user opt-in can display pushes
without rebuilding transport authority. An absent, malformed, or unreachable
descriptor leaves push inactive without partial enrollment.
Mobile builds without a gateway origin succeed with push unavailable. To enable push, supply the gateway origin explicitly:
flutter build ios --dart-define=BUZZ_PUSH_GATEWAY_URL=https://push.example
flutter build apk --dart-define=BUZZ_PUSH_GATEWAY_URL=https://push.example
The iOS and Android build gates validate any supplied define, rejecting empty or malformed values. Release/profile builds require an HTTPS origin without an explicit port. An absent define disables permission requests, APNs registration, gateway enrollment, and lease publication; Settings shows push as unavailable. No production gateway is selected implicitly. Enrollment grants and crash-recovery journals are scoped to this origin. Push has not shipped to existing users, so there is no legacy-state or cross-gateway migration. Changing gateways requires fresh enrollment; old installations expire under their original gateway's lease policy. Current-gateway response loss is still retried from the exact journaled request.
Relay rollout remains an explicit deployment opt-in. Only deployments with
BUZZ_PUSH_ENABLED=true advertise the descriptor and process push. See
docs/push-gateway-deployment.md for the canonical gateway profile contract,
manual physical-device proof, measurements, and rollback procedure.
For local physical-device development, override the identity and sandbox
environments in the gitignored mobile/ios/Flutter/AppOverrides.xcconfig:
BUNDLE_IDENTIFIER = com.example.buzz.mobile
BUZZ_DEVELOPMENT_TEAM = YOUR_TEAM_ID
BUZZ_IOS_PUSH_ENVIRONMENT = development
BUZZ_APP_ATTEST_ENVIRONMENT = development
BUZZ_PUSH_GATEWAY_URL = https:/$()/push.example
Use your personal bundle ID and team above. Provision both the parent and its
.NotificationService extension. Configure an isolated gateway with the matching
App Attest application ID, APNs topic and sandbox certificate. Development
attestation requires the explicit personal-dev-app-attest gateway build feature
and BUZZ_PUSH_APP_ATTEST_ENVIRONMENT=development; ordinary gateway builds accept
production attestation only. See docs/push-gateway-deployment.md.
Validate distributed builds separately using a signed release candidate and
its matching gateway configuration.
Parent app identifiers require Apple's Communication Notifications capability and a regenerated app provisioning profile. The Notification Service Extension profile does not require that capability. Enable it on the personal development App ID for local rich-presentation validation. Enabling it on distribution App IDs is a release follow-up and is not performed by this repository change. Without a matching parent profile, source and unit validation still work, but the app cannot be signed for a physical device.
APNs and the gateway continue to carry only the constant opaque wake-up. The extension fetches the message from the scoped relay, verifies message, sender profile, and channel-metadata signatures, and uses a bounded App Group cache for names and app-rendered avatar thumbnails. It never fetches an avatar URL; missing, stale, or invalid enrichment falls back to the verified message with a short sender pubkey, community subtitle, and no image.
Checks
dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test --dart-define=BUZZ_PUSH_GATEWAY_URL=https://push.example
Or from the repo root: just mobile-check and just mobile-test.
Android release signing
Android release builds fail unless all upload-key inputs are supplied through the environment:
BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH: path to a CI-vended keystore fileBUZZ_ANDROID_UPLOAD_KEYSTORE_PASSWORDBUZZ_ANDROID_UPLOAD_KEY_ALIASBUZZ_ANDROID_UPLOAD_KEY_PASSWORD
The keystore path must be absolute, and the keystore must remain outside the repository. Development and debug builds do not require these variables.
Release pipelines that sign through the central APK Signer service instead of
a local upload keystore must set BUZZ_ANDROID_RELEASE_SIGNING=external. That
mode produces an unsigned release bundle and refuses to run if any
BUZZ_ANDROID_UPLOAD_* value is also set.
Architecture
lib/
├── main.dart # Entry point, Riverpod bootstrap
├── app.dart # MaterialApp with theme
├── shared/
│ └── theme/ # Catppuccin light/dark, spacing tokens, extensions
└── features/
└── home/ # Placeholder home surface
- State management: Riverpod + Hooks (
HookConsumerWidget) - Theme: Catppuccin Latte (light) / Macchiato (dark) — matches desktop
- Spacing:
Gridtokens for consistent spacing - Linting:
flutter_lints+riverpod_lintviacustom_lint - Feature isolation: No cross-feature imports except
shared/