add zig atproto sdk wishlist doc

docs/zig-atproto-sdk-wishlist.md

···
+# zig atproto sdk wishlist
+
+notes from building a bluesky feed generator in zig. what would make life easier.
+
+## the pain points
+
+### 1. json navigation is brutal
+
+every single field access looks like this:
+
+```zig
+if (record.get("embed")) |embed_val| {
+    if (embed_val == .object) {
+        if (embed_val.object.get("external")) |external_val| {
+            if (external_val == .object) {
+                if (external_val.object.get("uri")) |uri_val| {
+                    if (uri_val == .string) {
+                        // finally, the actual value
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+this is 6 levels of nesting to get `embed.external.uri`. it's error-prone, hard to read, and easy to mess up.
+
+**wish**: typed structs generated from lexicons. just give me:
+
+```zig
+const post = try Post.fromJson(data);
+if (post.embed) |embed| {
+    if (embed.external) |ext| {
+        doSomething(ext.uri);
+    }
+}
+```
+
+### 2. no lexicon types at all
+
+we're working blind. the at-protocol has a full lexicon system with typed schemas, but in zig we get raw `json.Value` and have to know the structure from memory or docs.
+
+**wish**: codegen from lexicons. run a build step that reads `app.bsky.feed.post.json` and outputs `Post`, `Facet`, `Embed`, `ExternalEmbed`, etc. with proper zig types.
+
+even better: ship pre-generated types for the core `app.bsky.*` and `com.atproto.*` namespaces.
+
+### 3. no xrpc client
+
+making api calls means manually:
+- constructing urls
+- handling auth headers
+- parsing responses
+- dealing with rate limits
+- cursor pagination
+
+**wish**: typed xrpc client:
+
+```zig
+const client = try AtProto.init(allocator);
+try client.login("handle", "password");
+
+// typed request, typed response
+const feed = try client.call(.app_bsky_feed_getFeed, .{
+    .feed = "at://did:plc:.../app.bsky.feed.generator/my-feed",
+    .limit = 50,
+});
+
+for (feed.posts) |post| {
+    // post is already typed
+}
+```
+
+### 4. no firehose/jetstream client
+
+we had to build our own websocket handler from scratch:
+- tls connection setup
+- websocket frame parsing
+- reconnection logic
+- backpressure handling
+- cursor management for resumption
+
+**wish**: built-in stream client:
+
+```zig
+const stream = try Jetstream.connect(allocator, .{
+    .collections = &.{"app.bsky.feed.post"},
+    .cursor = saved_cursor,
+});
+
+while (try stream.next()) |event| {
+    switch (event) {
+        .commit => |commit| {
+            // commit.record is already typed based on collection
+        },
+        .identity => |id| { ... },
+        .account => |acc| { ... },
+    }
+}
+```
+
+### 5. tid parsing is non-obvious
+
+tids encode timestamps in base32-sortable format. we had to figure out the algorithm and implement it:
+
+```zig
+pub fn parseTidTimestamp(tid: []const u8) ?i64 {
+    if (tid.len < 13) return null;
+    var timestamp: u64 = 0;
+    for (tid[0..13]) |c| {
+        const val: u64 = switch (c) {
+            '2'...'7' => c - '2',
+            'a'...'z' => c - 'a' + 6,
+            else => return null,
+        };
+        timestamp = (timestamp << 5) | val;
+    }
+    return @intCast(timestamp / 1000);
+}
+```
+
+**wish**: `Tid` type with utilities:
+
+```zig
+const tid = Tid.parse("3jui7...") orelse return error.InvalidTid;
+const created_at = tid.timestamp(); // returns i64 milliseconds
+const clock_id = tid.clockId();
+
+// also: generate tids
+const new_tid = Tid.now();
+```
+
+### 6. at-uri parsing
+
+at-uris are everywhere: `at://did:plc:xyz/app.bsky.feed.post/abc123`
+
+we need to extract did, collection, rkey constantly. currently doing string splits manually.
+
+**wish**: `AtUri` type:
+
+```zig
+const uri = try AtUri.parse("at://did:plc:xyz/app.bsky.feed.post/abc123");
+uri.did      // "did:plc:xyz"
+uri.collection // "app.bsky.feed.post"
+uri.rkey     // "abc123"
+
+// construct
+const new_uri = AtUri.init("did:plc:xyz", "app.bsky.feed.post", "abc123");
+new_uri.toString() // "at://did:plc:xyz/app.bsky.feed.post/abc123"
+```
+
+### 7. feed generator scaffolding
+
+building a feed generator requires:
+- http server for xrpc endpoints
+- `describeFeedGenerator` endpoint
+- `getFeedSkeleton` endpoint with cursor handling
+- well-known did document serving
+
+we built all this from scratch.
+
+**wish**: feed generator framework:
+
+```zig
+const FeedGenerator = @import("atproto").FeedGenerator;
+
+const MyFeed = struct {
+    pub fn filter(post: Post) bool {
+        // return true to include in feed
+        return post.hasLink("soundcloud.com");
+    }
+
+    pub fn sort(posts: []Post) void {
+        // custom sort, or use default chronological
+    }
+};
+
+pub fn main() !void {
+    var generator = try FeedGenerator.init(allocator, .{
+        .did = "did:web:my-feed.example.com",
+        .feeds = &.{
+            .{ .name = "my-feed", .handler = MyFeed },
+        },
+    });
+    try generator.serve(3000);
+}
+```
+
+### 8. did resolution
+
+resolving `did:plc:*` and `did:web:*` to did documents requires http calls and json parsing. needed for verifying identities, getting service endpoints.
+
+**wish**: did resolver:
+
+```zig
+const resolver = DidResolver.init(allocator);
+const doc = try resolver.resolve("did:plc:xyz");
+doc.alsoKnownAs  // ["at://handle.bsky.social"]
+doc.service      // pds endpoint, etc.
+```
+
+### 9. cbor/dag-cbor support
+
+the actual at-proto repo format uses dag-cbor. if you want to verify signatures or work with raw repo data, you need cbor.
+
+**wish**: cbor codec, at least for reading commit data from firehose.
+
+### 10. labeler integration
+
+reading and applying labels (nsfw, etc.) from labeler services.
+
+**wish**: label types and utilities:
+
+```zig
+const labels = post.labels orelse &.{};
+if (Label.hasAny(labels, &.{"porn", "sexual", "nudity"})) {
+    // exclude
+}
+```
+
+### 11. facet helpers
+
+facets (links, mentions, tags in post text) have a specific structure. extracting links means navigating:
+
+```zig
+for (facets) |facet| {
+    for (facet.features) |feature| {
+        if (feature.type == .link) {
+            // feature.uri
+        }
+    }
+}
+```
+
+**wish**: facet utilities:
+
+```zig
+const links = post.extractLinks();     // [][]const u8
+const mentions = post.extractMentions(); // []Did
+const tags = post.extractTags();       // [][]const u8
+```
+
+### 12. rich text building
+
+creating posts with links/mentions requires building facet byte ranges correctly.
+
+**wish**: rich text builder:
+
+```zig
+var rt = RichText.init(allocator);
+rt.text("check out ");
+rt.link("this track", "https://soundcloud.com/...");
+rt.text(" by ");
+rt.mention("@artist.bsky.social");
+
+const post = rt.toPost(); // has .text and .facets set correctly
+```
+
+## summary
+
+the ideal sdk would have:
+
+1. **typed lexicons** - generated zig structs for all at-proto record types
+2. **xrpc client** - typed api calls with auth, pagination, rate limiting
+3. **stream client** - jetstream/firehose with reconnection, typed events
+4. **primitives** - Tid, AtUri, Did, Cid types with parsing/generation
+5. **feed generator framework** - scaffolding for common feed patterns
+6. **facet utilities** - extract/build links, mentions, tags
+7. **label handling** - read and apply moderation labels
+8. **did resolution** - resolve did:plc and did:web
+
+basically: let me focus on the feed logic, not the protocol plumbing.