mobile bluesky app made with flutter
lazurite.stormlightlabs.org/
mobile
bluesky
flutter
doc: lists and starter pack spec + tasks
+255
+196
docs/specs/phase-4.md
+196
docs/specs/phase-4.md
···
402
402
header on all outgoing requests. The header value is a comma-separated list of
403
403
labeler DIDs from the user's `labelersPref`. This should be set once on login
404
404
and updated whenever preferences change.
405
+
406
+
## Lists
407
+
408
+
Lists let users organise accounts into named collections. There are two
409
+
user-facing list types: **curation lists** (curated feeds of member posts) and
410
+
**moderation lists** (mute or block every member at once). A third type,
411
+
**reference lists**, exists only as the backing store for starter packs.
412
+
413
+
### API
414
+
415
+
| Endpoint | Purpose |
416
+
| --------------------------------------- | ---------------------------------------- |
417
+
| `app.bsky.graph.getList` | Paginated list view with member profiles |
418
+
| `app.bsky.graph.getLists` | Lists created by an actor |
419
+
| `app.bsky.graph.getListsWithMembership` | User's lists with membership info |
420
+
| `app.bsky.graph.getListMutes` | Mod lists the user has muted |
421
+
| `app.bsky.graph.getListBlocks` | Mod lists the user is blocking |
422
+
| `app.bsky.feed.getListFeed` | Feed of posts from list members |
423
+
| `app.bsky.graph.muteActorList` | Mute all accounts on a list |
424
+
| `app.bsky.graph.unmuteActorList` | Unmute a previously muted list |
425
+
426
+
List records, list items, and list blocks are managed through
427
+
`com.atproto.repo.createRecord`, `putRecord`, and `deleteRecord` with the
428
+
appropriate collection (`app.bsky.graph.list`, `app.bsky.graph.listitem`,
429
+
`app.bsky.graph.listblock`).
430
+
431
+
### List Purposes
432
+
433
+
| Purpose | Constant | Usage |
434
+
| --------------- | ----------------------------------- | --------------------------------------- |
435
+
| Curation list | `app.bsky.graph.defs#curatelist` | User-curated, viewable as a feed |
436
+
| Moderation list | `app.bsky.graph.defs#modlist` | Mute or block all members at once |
437
+
| Reference list | `app.bsky.graph.defs#referencelist` | Internal backing list for starter packs |
438
+
439
+
### List Record
440
+
441
+
| Field | Type | Notes |
442
+
| ------------------- | --------- | --------------------------------- |
443
+
| `purpose` | string | One of the list purpose constants |
444
+
| `name` | string | 1–64 graphemes |
445
+
| `description` | string? | Max 300 graphemes / 3000 bytes |
446
+
| `descriptionFacets` | facets[]? | Rich text facets for description |
447
+
| `avatar` | blob? | PNG or JPEG, max 1 MB |
448
+
| `createdAt` | datetime | Required |
449
+
450
+
### List Item Record
451
+
452
+
| Field | Type | Notes |
453
+
| ----------- | -------- | ------------------------- |
454
+
| `subject` | string | DID of the account to add |
455
+
| `list` | string | AT-URI of the parent list |
456
+
| `createdAt` | datetime | Required |
457
+
458
+
Duplicate list items for the same subject are ignored by the AppView.
459
+
460
+
### List Views
461
+
462
+
`listView` includes: `uri`, `cid`, `creator` (profileView), `name`,
463
+
`purpose`, `description?`, `avatar?`, `listItemCount?`, `labels?`,
464
+
`viewer?` (listViewerState with `muted?` and `blocked?`), `indexedAt`.
465
+
466
+
`listItemView` includes: `uri` (of the listitem record), `subject`
467
+
(profileView).
468
+
469
+
### List Feed
470
+
471
+
`getListFeed` returns `feedViewPost` items — posts and reposts from list
472
+
members. Only curation lists support feeds. The existing feed rendering
473
+
infrastructure can be reused.
474
+
475
+
### Screens
476
+
477
+
**My Lists screen** (accessible from profile or settings): shows lists the
478
+
user has created, separated by curation and moderation tabs. Each row shows
479
+
name, avatar, member count, and purpose badge. FAB to create a new list.
480
+
481
+
**List detail screen**: shows the list header (name, avatar, description,
482
+
creator, member count) and two tabs — **Feed** (for curation lists, using
483
+
`getListFeed`) and **Members** (paginated member profiles). The overflow
484
+
menu includes: edit list, delete list, add/remove members, and for mod
485
+
lists — mute list / block via list.
486
+
487
+
**Add/remove members**: a screen with a search field using
488
+
`searchActorsTypeahead` to find users, plus a list of current members with
489
+
remove buttons. Adding creates a `listitem` record; removing deletes it.
490
+
491
+
**Create/edit list dialog**: name, description, avatar picker, and purpose
492
+
selector (curation or moderation — reference lists are not user-created
493
+
directly).
494
+
495
+
### Bloc Architecture
496
+
497
+
Build a `ListBloc` with events: `ListRequested`, `ListRefreshed`,
498
+
`ListItemAdded`, `ListItemRemoved`, `ListMuted`, `ListUnmuted`,
499
+
`ListBlocked`, `ListUnblocked`.
500
+
501
+
Build a `MyListsCubit` that loads the user's lists via `getLists`.
502
+
503
+
Build a `ListFeedBloc` reusing the feed pagination pattern from the home
504
+
feed, backed by `getListFeed`.
505
+
506
+
### Profile Integration
507
+
508
+
On profile screens, add a "Lists" tab that shows lists created by that
509
+
actor via `getLists`. Also add an "Add to list" option in the profile
510
+
overflow menu that shows `getListsWithMembership` and lets the user toggle
511
+
membership.
512
+
513
+
## Starter Packs
514
+
515
+
Starter packs are curated bundles of recommended accounts and feeds,
516
+
designed to help new users bootstrap their experience. Each starter pack is
517
+
backed by a reference list that holds the recommended accounts.
518
+
519
+
### API
520
+
521
+
| Endpoint | Purpose |
522
+
| ---------------------------------------------- | ----------------------------------------- |
523
+
| `app.bsky.graph.getStarterPack` | Detailed view of a single starter pack |
524
+
| `app.bsky.graph.getStarterPacks` | Batch-fetch up to 25 starter packs by URI |
525
+
| `app.bsky.graph.getActorStarterPacks` | Starter packs created by an actor |
526
+
| `app.bsky.graph.getStarterPacksWithMembership` | User's starter packs with membership info |
527
+
| `app.bsky.graph.searchStarterPacks` | Search starter packs by query string |
528
+
529
+
Starter pack records are managed through `com.atproto.repo.createRecord`,
530
+
`putRecord`, and `deleteRecord` with collection
531
+
`app.bsky.graph.starterpack`.
532
+
533
+
### Starter Pack Record
534
+
535
+
| Field | Type | Notes |
536
+
| ------------------- | ----------- | -------------------------------- |
537
+
| `name` | string | 1–50 graphemes |
538
+
| `list` | string | AT-URI to a reference list |
539
+
| `description` | string? | Max 300 graphemes / 3000 bytes |
540
+
| `descriptionFacets` | facets[]? | Rich text facets for description |
541
+
| `feeds` | feedItem[]? | Up to 3 feed generator URIs |
542
+
| `createdAt` | datetime | Required |
543
+
544
+
`feedItem` contains a single `uri` field pointing to a feed generator
545
+
record.
546
+
547
+
### Starter Pack Views
548
+
549
+
`starterPackView` (full): `uri`, `cid`, `record`, `creator`
550
+
(profileViewBasic), `list?` (listViewBasic), `listItemsSample?` (up to 12
551
+
listItemView), `feeds?` (up to 3 generatorView), `joinedWeekCount?`,
552
+
`joinedAllTimeCount?`, `labels?`, `indexedAt`.
553
+
554
+
`starterPackViewBasic` (compact): `uri`, `cid`, `record`, `creator`
555
+
(profileViewBasic), `listItemCount?`, `joinedWeekCount?`,
556
+
`joinedAllTimeCount?`, `labels?`, `indexedAt`.
557
+
558
+
### Creation Flow
559
+
560
+
1. Create a reference list via `com.atproto.repo.createRecord` with
561
+
collection `app.bsky.graph.list` and purpose `referencelist`.
562
+
2. Add members to the reference list by creating `listitem` records.
563
+
3. Create the starter pack record pointing to the reference list.
564
+
565
+
Updating the people in a starter pack means adding/removing `listitem`
566
+
records on its backing reference list. Updating the name, description, or
567
+
feeds means updating the starter pack record itself.
568
+
569
+
### Screens
570
+
571
+
**Starter pack detail screen**: shows name, description, creator profile,
572
+
join stats (`joinedWeekCount`, `joinedAllTimeCount`), a sample of members
573
+
(up to 12 from `listItemsSample`), and recommended feeds. A "See all
574
+
members" button navigates to the full member list via the backing reference
575
+
list. A "Follow all" button follows every member in the pack.
576
+
577
+
**Actor starter packs screen**: shows starter packs created by a specific
578
+
user, accessible from their profile. Uses `getActorStarterPacks` with
579
+
pagination.
580
+
581
+
**Create/edit starter pack screen**: name (max 50 graphemes), description,
582
+
member search (using `searchActorsTypeahead`), and feed picker (up to 3
583
+
feeds from `getActorFeeds` or `getSuggestedFeeds`). On save, the app
584
+
creates the reference list, adds members, then creates the starter pack
585
+
record.
586
+
587
+
### Bloc Architecture
588
+
589
+
Build a `StarterPackBloc` with events: `StarterPackRequested`,
590
+
`StarterPackCreated`, `StarterPackUpdated`, `StarterPackDeleted`,
591
+
`MemberAdded`, `MemberRemoved`.
592
+
593
+
Build a `ActorStarterPacksCubit` that loads starter packs for a given
594
+
actor via `getActorStarterPacks`.
595
+
596
+
### Profile Integration
597
+
598
+
On profile screens, add a "Starter Packs" section or tab showing packs
599
+
created by that actor. Starter pack cards show the pack name, creator,
600
+
member count, and join stats.
+59
docs/tasks/phase-4.md
+59
docs/tasks/phase-4.md
···
82
82
- [ ] Self-label support — render self-labels embedded in posts and profiles
83
83
- [ ] Labeler detail screen: show labeler creator, policies, and custom label definitions with localised names
84
84
- [x] Drift table: `labeler_cache` (labeler_did, policies_json, fetched_at) for offline label definition lookup
85
+
86
+
## M18 — Lists
87
+
88
+
### Core
89
+
90
+
- [ ] `ListBloc` — events: `ListRequested`, `ListRefreshed`, `ListItemAdded`, `ListItemRemoved`, `ListMuted`, `ListUnmuted`, `ListBlocked`, `ListUnblocked`
91
+
- [ ] `MyListsCubit` — load user's lists via `getLists`
92
+
- [ ] `ListFeedBloc` — paginated feed via `getListFeed`, reuse existing feed pattern
93
+
94
+
### List CRUD
95
+
96
+
- [ ] Create list — name, description, avatar, purpose selector (curation/moderation) via `com.atproto.repo.createRecord`
97
+
- [ ] Edit list — update name, description, avatar via `com.atproto.repo.putRecord`
98
+
- [ ] Delete list via `com.atproto.repo.deleteRecord`
99
+
- [ ] Add members — search via `searchActorsTypeahead`, create `listitem` records
100
+
- [ ] Remove members — delete `listitem` records
101
+
102
+
### Moderation Actions
103
+
104
+
- [ ] Mute list via `muteActorList` / unmute via `unmuteActorList`
105
+
- [ ] Block via list — create `listblock` record; unblock — delete `listblock` record
106
+
107
+
### Screens
108
+
109
+
- [ ] My Lists screen — curation and moderation tabs, FAB to create new list
110
+
- [ ] List detail screen — header (name, avatar, description, creator, member count), Feed tab (curation lists), Members tab
111
+
- [ ] Add/remove members screen — search field + current members with remove buttons
112
+
- [ ] Create/edit list dialog — name, description, avatar picker, purpose selector
113
+
114
+
### Profile Integration
115
+
116
+
- [ ] "Lists" tab on profile screens via `getLists`
117
+
- [ ] "Add to list" option in profile overflow menu using `getListsWithMembership`
118
+
119
+
## M19 — Starter Packs
120
+
121
+
### Core
122
+
123
+
- [ ] `StarterPackBloc` — events: `StarterPackRequested`, `StarterPackCreated`, `StarterPackUpdated`, `StarterPackDeleted`, `MemberAdded`, `MemberRemoved`
124
+
- [ ] `ActorStarterPacksCubit` — load starter packs for an actor via `getActorStarterPacks`
125
+
126
+
### Viewing
127
+
128
+
- [ ] Starter pack detail screen — name, description, creator, join stats, member sample (up to 12), recommended feeds (up to 3)
129
+
- [ ] "See all members" — navigate to full member list via backing reference list
130
+
- [ ] "Follow all" button — follow every member in the pack
131
+
- [ ] Actor starter packs screen — paginated list via `getActorStarterPacks`
132
+
133
+
### Creation & Editing
134
+
135
+
- [ ] Create starter pack — name (max 50 graphemes), description, member search, feed picker (up to 3)
136
+
- [ ] Creation flow: create reference list → add `listitem` records → create starter pack record
137
+
- [ ] Edit starter pack — update name/description/feeds via `putRecord`, add/remove members via `listitem` CRUD
138
+
- [ ] Delete starter pack and its backing reference list
139
+
140
+
### Profile Integration
141
+
142
+
- [ ] "Starter Packs" section on profile screens showing packs created by actor
143
+
- [ ] Starter pack cards — name, creator, member count, join stats