🤖 Native chat feed (Mac first)

> Update 2026-07-25 — the takeover is COMPLETE on iOS too. NativeChatScreen > is the only chat surface (plain chats and app-thread Chat views alike); > ChatView — the per-thread webview feed this document plans around — is > deleted. Webviews on both native apps now carry only an app's own > interface (iOS AppThreadScreen/AppInterfacePane, Mac appInterfacePane); > chat never renders in a webview, by policy. The status note below is the > historical hand-off brief from the Mac takeover era — read it as history.

> Status: THE TAKEOVER SHIPPED (2026-07-07) — native chat is the Mac's > main surface: NativeChatView = native thread list (sidebar header with > search/new-chat/⋮, pin/close context menus, live via an instance-wide > socket) beside NativeFeedView (the former debug-pane feed, extracted). The > webview is the fallback (View ▸ Use Web App, ⌥⌘W) and still owns mini-apps, > admin, profile, joining; identity-less instances fall through to it. Feed > parity held from the pane era (all live-verified): every message type + > composer with typeahead, uploads/progress, actions (reply/edit/delete/react > via the Messages-style right-click NSMenu), Show Times gutter, drag in/out, > block formatting, link previews, click-to-play YouTube (iframe-shell embed; > plays in the lightbox), scroll-back with mid-viewport anchor restore + > 8-rows-early prefetch, and no-flash thread switching via > NativeFeedModelCache (parked live models + prewarm — the FeedWebCache rule, > now in LChatCore). iOS adoption started (2026-07-08 overnight): the > typeahead brain is native in ChatView (no JS round-trip), and > NativeChatScreen (shared pieces, phone container) ships behind the server > drawer's "Native chat (beta)" toggle — webview ChatView stays the default. > Cross-impl gates: thread-key, push-blob, message-payload, attachment-bytes, > native→web message, + format.js parity incl. blockTokens and youtubeId > (note: main's internal/e2ee Go port has its OWN vector corpus — unify in the > crypto-spec follow-up). Next: iOS parity (Show Times, file export, > pinch-zoom, jump wave, native thread list?), themes beyond classic, the > NSScrollView container (transactional scroll anchoring), retiring the > shell.js dead feed + ChatFeedWebView once the fallback is unneeded. > Branch native-mac-feed. This note is the handoff brief. > Everything below the top heading is 🤖-authored (see CLAUDE.md authorship).

Goal

Render the chat stream natively — bubbles, reactions, replies, message types — instead of hosting chat.js in a WKWebView. Start with the Mac app (LChatMac), prove each message type on-device, then bring iOS along. The payoff is a real Mac-assed feed (native scroll, selection, menus) with no webview emulation glue, and far more shared code between the Mac and iOS apps.

Non-goals for this branch: "App" (mini-app) views stay in WKWebView — unchanged. iOS feed migration comes after Mac reaches parity. The formal cross-language crypto spec is a separate follow-up (see Crypto: spec is a follow-up).

The load-bearing constraint (unchanged)

E2E encryption is load-bearing (CLAUDE.md §"The one rule"). Going native does not weaken it: crypto stays 100% client-side, the server still only ever sees ciphertext. If anything native crypto (CryptoKit + Keychain) is a stronger story than JS-in-a-webview.

The one property we must preserve is "a single auditable crypto implementation" → which becomes "two implementations (JS + Swift) that must never drift." The answer already exists: cross-impl test vectors (test/threadkey.test.mjs → ios/LChatTests/thread-key-vector.json, checked by ECIESVectorTest). The rule for this branch:

> Every crypto path that goes native ships with a JS↔Swift round-trip vector in > the same commit. Non-negotiable. The formal spec can wait; the vectors cannot. > A silently mis-decrypting client shows up as a garbled message, not a red test.

Where we are today (accurate — the framing "thin webview shell" is out of date)

Both apps already have native chrome; neither renders the feed natively — the message bubbles are chat.js in a webview on both.

iOS (LChat): native shell + native crypto, webview feed.

• LChatApp.swift: RootView → ThreadListView (native UICollectionView via ThreadListCollection + ThreadRow) → NavigationStack pushes ChatView.
• ChatView.swift (806 lines) hosts a per-thread WKWebView from FeedWebCache, seeded with one thread key via window.__lchatEmbed; chat.js renders in embed mode. Native crypto (Crypto.swift: ECIES + GroupKey) is used for previews, the push extension (LChatNSE), and thread-key unwrap. Identity is a native P-256 keypair in the Keychain (SavedInstance / InstancesStore). ThreadStore, SharedThreadKeys, LChatAPI, AvatarLoader are all native.

Mac (LChatMac): native SwiftUI shell (genuinely native, not Catalyst), webview feed, no native crypto at all.

• LChatMacApp.swift (SwiftUI, .hiddenTitleBar) → RootView.swift (server rail + ⌘K palette + NSMenus + Sparkle) → ChatFeedWebView.swift (531 lines) hosts a per-instance WKWebView running the full chat.js page. All crypto lives in the webview (MacInstance.swift header says so).
• MacInstance.swift deliberately forks identity: SavedChat/Session with the key living in the webview's storage — not iOS's native-keypair SavedInstance. project.yml confirms Mac compiles only Models.swift, LChatAPI.swift, InviteLink.swift — not Crypto.swift.
• ChatFeedWebView carries ~530 lines of "make the webview feel native" glue (window drag, Finder file-drops, NSMenu bridging, downloads, theme sync, confirm/alert panels, focus). This glue is exactly what native rendering deletes.

Shared today: almost nothing — Mac shares Models/LChatAPI/InviteLink; LChatNSE shares Crypto/Models/SharedThreadKeys. There is no shared package.

Test wiring gap (fix early): ios/LChatTests/ has ECIESVectorTest, PushBlobDecryptTest, InviteLinkTest + thread-key-vector.json, but project.yml defines no LChatTests target (only LChatUITests). Confirm whether these actually run under xcodebuild test; if not, add a unit-test target — they are the crypto safety net this whole plan leans on.

Decisions (locked — from the design discussion)

1. Schema = a data + action contract, not runtime SDUI. Formalize what a message is (fields) and what actions it affords, versioned. Do not build a runtime UI-description engine for the chat stream — the message-type set is small and closed; a native renderer per type is simpler and is the whole point (native fidelity). SDUI's only possible home is the mini-app / future native-app-view story, which is out of scope here.
2. Deploy tradeoff accepted for dev. We're iterating; each message type gets tested on the Mac app as it lands. The webview feed stays as the fallback until native reaches parity. Forward-compat for stale/un-updated native clients is deferred (dev-phase only) — revisit before any real release.
3. Mac stays native SwiftUI, not Catalyst. LChatMac is already more Mac-assed than a Catalyst build would be. Kill the Catalyst path (commit 1).
4. Crypto spec is a follow-up, written from the proven native implementation, not ahead of it — but the vectors land as we go (see the load-bearing rule above).
5. One branch, incremental commits. PR ≈ "switch the Mac chat feed from WebView to native." Squash-merge. Prefix commits by area (mac:, ios:, crypto:, docs:).

Target architecture (NetNewsWire, pushed one step further)

NetNewsWire shares a platform-neutral core (local Swift packages) and writes each UI natively per platform (AppKit on Mac, UIKit on iOS) — no Catalyst. It renders article bodies in a shared WKWebView + shared CSS while the timeline/ sidebar chrome is native. That "native chrome, webview content surface" split is exactly our current shape — and the model to keep for the app views.

We go one step further than NNW for the feed specifically (NNW predates mature SwiftUI, so it writes its timeline twice and shares no leaf views):

• Core (crypto, models, API, thread store, message→view-model logic) → shared Swift package. Pure NNW. No UIKit/AppKit imports.
• Bubble / reaction / reply leaf views → shared SwiftUI, which renders on both iOS and Mac.
• Chrome + scroll container → per-platform native, dropping to AppKit where SwiftUI can't hit Mac quality (below).

Where SwiftUI will bite (watch for these on Mac)

Build the feed in SwiftUI first; let bite points show themselves on-device; escape to AppKit reactively, not preemptively. Likely order:

1. Text selection across bubbles. SwiftUI Text selection is weak; Mac users expect NSTextView-grade select-and-copy across messages. This is the #1 "not a real Mac app" tell.
2. Scroll position control — staying pinned to the bottom, programmatic "jump to newest", no jump when images finish loading. SwiftUI's scroll APIs still stutter with variable-height content + images.

Escape hatch: an AppKit NSScrollView/NSTableView (or NSCollectionView) scroll container via NSViewRepresentable, hosting the shared SwiftUI leaf bubbles via NSHostingView. You already have NSViewRepresentable muscle memory in ChatFeedWebView. Sharing leaf views does not oblige sharing the container.

The commit sequence

Work these in order. Each should build (xcodebuild iOS + LChatMac) and keep the app working; a native message type is only "done" when tested on-device.

Commit 1 — kill the Catalyst build (pure deletion, no behavior change)

The confirmed cruft: the initial Mac approach was Catalyst (running the iOS LChat target on Mac), superseded by native LChatMac.

• project.yml: remove SUPPORTS_MACCATALYST: YES (and DERIVE_MACCATALYST_PRODUCT_BUNDLE_IDENTIFIER) from the LChat target.
• Delete ios/LChat/Views/MacTitlebar.swift (all #if targetEnvironment(macCatalyst); its type is MacWindowTitle).
• Remove the #if targetEnvironment(macCatalyst) branch in ChatView.swift:194 and the #if !targetEnvironment(macCatalyst) branches in JoinView.swift (keep the non-Catalyst side — e.g. the QR scanner stays).
• Keep the macCatalyst 16.4 bits in #available(...) checks (FeedWebCache.swift, JoinView.swift) — those are OS-version floors, not target guards.
• Verify: cd ios && xcodegen generate && xcodebuild -scheme LChat build and -scheme LChatMac build both succeed.

Commit 2 — extract the shared Swift core (behavior-preserving)

Pull the platform-neutral core into a package/group all targets depend on (iOS LChat, LChatMac, LChatNSE): Crypto, Models, LChatAPI, ThreadStore, SharedThreadKeys, InviteLink, Keychain, and the platform-neutral parts of AvatarLoader. No behavior change; this is the foundation and the "share more" win. Also wire up the LChatTests unit-test target here so the crypto vectors run in CI.

Commit 3 — Mac adopts native identity

Converge MacInstance's SavedChat/keys-in-webview onto iOS's SavedInstance (native P-256 keypair in the Keychain via InstancesStore). This is the load-bearing prerequisite: you cannot render the feed natively without native keys + native decrypt. Feed still webview at this point; nothing visible changes. This is where Mac gets its first full native crypto surface — the exact surface the eventual spec will describe.

Commit 4 — native WebSocket + decrypt → native view-model (behind a flag)

Native WS connection + native message decrypt (GroupKey.decryptJSON on the message blob) feeding a native view-model, rendered beside ChatFeedWebView behind a flag so you can diff native vs webview live. Add the JS↔Swift vector for message-body decrypt.

Commits 5+ — native bubbles, one message type per commit

Each type is its own commit, tested on Mac, with a crypto vector where it touches a new path:

1. Plain text bubble (own vs other, sender name, timestamp).
2. Reactions — remember these are separate react/unreact wire frames (not in the message blob), folded onto a message by (message id, emoji, user).
3. Replies — the reply { id, name, snippet } field; tap-to-scroll to source.
4. Images — attachments with w/h, blob download + decryptBytes, lightbox.
5. Files / video — file chips, downloads, video poster.
6. System / action lines — { sender, text, short, actions[] }; the /me-style action line and command-response chips.

Later (not this branch, or tail of it)

• Retire ChatFeedWebView once native is at parity; keep it reachable as a fallback until confident.
• Bring iOS along: ChatView/FeedWebCache → native, reusing the shared SwiftUI leaf views.
• App views stay WKWebView throughout.

The data + action contract (v1 — descriptive, formalize as we build)

The shape already exists implicitly; we're formalizing + versioning it, not inventing it. Sources of truth: web/static/apps/chat.js payload construction (~L264–283) and system lines (~L105); hub.go event switch (~L253); ios/LChat/Models.swift MessagePayload.

Encrypted message payload (inside the blob):

{ v, uid, name, text, ts,
  attachments: [{ id, name, type, w, h, poster? }],
  reply: { id, name, snippet } | null,
  edited, rev }

• System/notice line: { sender, text, short, actions: [{ label, id }] | null } — the /me-style action line and command-response chips.
• Reactions are NOT in the blob — they're separate react/unreact frames, keyed (message id, emoji, user), folded onto the message at render time.

Wire events (hub.go): msg (blob; may be ephemeral for private command replies), edit (blob, editedAt), delete (messageId), react / unreact, typing (ephemeral relay-only), plus active / ping (presence/keepalive).

Action catalog (consistent across platforms): reply · react · copy · edit (own message, within EDIT_WINDOW_MS) · delete (own message). System lines carry their own actions[] chips.

Versioning: stamp v and define a compat policy. Unknown type/field → graceful fallback (dev-phase: fall back to the webview for that thread rather than render wrong). Confirm the exact react frame shape (is the emoji encrypted?) from hub.go + chat.js before implementing reactions.

Crypto: spec is a follow-up (separate task)

Do not write the formal spec first. Build the native Mac client (which forces the complete native crypto surface into existence — commits 3–5), then write the spec as a description of code that already interops. But land vectors as you go (above). When it's time, the spec is three artifacts (see the design discussion):

1. Byte-level wire spec — AES-256-GCM (12-byte nonce, 16-byte tag, iv‖ct‖tag), ECDH P-256, X9.63 uncompressed pubkey (65 B), PKCS#8 private key, HKDF-SHA256 with empty salt and exact info constants (lchat-thread-wrap, lchat-invite-*), all base64url no-padding. Crypto operates on bytes; JSON is above the layer.
2. Language-neutral vector corpus — deterministic paths → golden byte vectors; randomized paths (fresh nonce / ephemeral key) → a decrypt-known-corpus + a referenceDecrypt(impl.encrypt(pt)) == pt check; optional deterministic- ephemeral hook (test-only) for byte-reproducible ECIES.
3. Conformance-runner protocol — a tiny per-impl CLI so one harness drives JS/Swift/Go/Rust identically.

Gotchas the spec must nail: base64url padding; PKCS#8 vs SEC1 vs raw; X9.63 uncompressed point; HKDF empty-salt semantics; GCM tag placement; exact info strings. This standard is for clients — the server stays key-blind and implements none of it. Keep spec + vectors in-repo (generated beside crypto.js) until an external impl forces a split; name it v1 with a compat policy (changing an info string or the KDF is data-orphaning).

Testing / verification each commit

• go build ./... && go test ./... (server contract unchanged).
• npm test (crypto/ui/format) + node --check web/static/*.js for any JS touched.
• cd ios && xcodegen generate && xcodebuild -scheme LChat build and -scheme LChatMac build.
• Run the crypto vector target (add it in commit 2 if missing).
• Run it on the Mac (the point of Mac-first): build Release LChatMac, exercise the new type against a real instance.

Conventions (CLAUDE.md — don't skip)

• Work in this worktree (../messenger-native-mac-feed, branch native-mac-feed) — not the shared main checkout.
• Incremental commits are fine (they squash); prefix by area; end messages with the Co-Authored-By: trailer for the assisting model.
• User-visible changes get a changelog/<date>-<slug>.md entry (first line 🤖). Retiring the webview feed / new native rendering is user-visible.
• Never innerHTML untrusted content; token-gate data endpoints; inline feedback, no floating toasts — but most of this branch is Swift, so mainly: keep the E2E posture (only ever hand the view-model decrypted data; never leak the user private key; only one thread's key per context).
• New Markdown prose is 🤖; don't rewrite any 👨/👤-marked block.
• Squash-merge + delete branch; deploy is unrelated (web/server unchanged).