Roadmap: v4.2 parity push — catch up to the nostr-article-capture userscript

[bryanmatthewsimonson]

Context

X-Ray was originally ported from the nostr-article-capture userscript at v1.8.0. Since then, the userscript has been rewritten twice and is at v4.2.0 — a substantially different architecture with real crypto, platform handlers, claims, entity sync, and a reader/capture-panel dual UI. X-Ray lags on all of that and, more critically, inherited v1's broken crypto stub (unconditional-true signature verification, fake bech32).

See docs/project-history-and-migration.md on the userscript repo for the full history and data model. That document was written as an explicit migration guide toward a browser extension — we're following it.

Strategic decisions (locked in)

1. Extension-native, not userscript-translated. Every workaround the userscript had because it was stuck in a page context becomes a non-issue:
   • Relay client moves to the background service worker (no more page-CSP WebSocket blocks).
   • declarativeNetRequest strips page CSP (no more Trusted Types policy gymnastics).
   • Reader view becomes a real extension page (no more DOM takeover).
   • Settings / entity browser become side panels (no more injected overlays).
   • Article cache uses IndexedDB + unlimitedStorage (no more 3MB GM cap).
   • chrome.notifications, chrome.commands, proper ES modules via esbuild.
2. Pragmatic subset first. Substack + YouTube + Twitter/X + generic articles cover the high-value, low-maintenance 80% of real usage. Facebook / Instagram / TikTok are deferred to a later phase with their own per-platform implementation sub-issues.
3. v1-era features (URL metadata UI, annotation highlights, debunk banner, kinds 32123–32144) are scrapped. Clean-sheet catch-up to v4.2.

Phases

• Phase 0 — Teardown + infrastructure rebuild (Phase 0 — Teardown + infrastructure rebuild #11)
• Phase 1 — Real NOSTR crypto (secp256k1 / BIP-340 / bech32 / NIP-44) (Phase 1 — Real NOSTR crypto (secp256k1 / BIP-340 / bech32 / NIP-44) #12)
• Phase 2 — Capture parity for article-shaped content (Phase 2 — Capture parity for article-shaped content #13)
• Phase 3 — Easy-tier platform handlers: Substack / YouTube / Twitter / generic (Phase 3 — Easy-tier platform handlers (Substack, YouTube, Twitter/X, generic) #14)
• Phase 4 — Entity system (Phase 4 — Entity system (types, tagger, browser, aliases, kind-0 profiles) #15)
• Phase 5 — Claims + evidence linking (Phase 5 — Claims + evidence linking #16)
• Phase 6 — Entity sync over NIP-78 + NIP-44 v2 (Phase 6 — Entity sync over NIP-78 with NIP-44 v2 encryption #17)
• Phase 7 — Archive reader (IndexedDB + paywall detection + relay reconstruction) (Phase 7 — Archive reader (IndexedDB cache + paywall detection + relay reconstruction) #18)
• Phase 8 — Hard-tier platforms (Facebook / Instagram / TikTok) with anti-obfuscation stack (Phase 8 — Hard-tier platforms (Facebook, Instagram, TikTok) with anti-obfuscation stack #19, will likely split into sub-issues at work-start)

Ordering rationale

• Phases 0 and 1 both labeled P0 and must land before any feature code. They're quick.
• Phase 2 is the biggest single deliverable (reader view as an extension page ≈ 2k LOC of UI code).
• Phase 3 piggy-backs on Phase 2's platform-handler hook points.
• Phases 4 → 5 → 6 build the knowledge-graph stack in dependency order.
• Phases 7 and 8 are independent of the knowledge-graph stack; Phase 7 can slot in anywhere after Phase 2 opportunistically.

Non-goals (for this push)

• Chrome Web Store / AMO submission (tracked separately in Release pipeline: CHANGELOG, version bump, tagged releases #8).
• User-defined plugins.
• Mobile support.
• Keystone (the browser) — X-Ray is and will remain an extension. Keystone is a separate project that will eventually embed X-Ray's content-script stack natively.

Abandonment criteria

If, at any phase boundary, the cost to continue exceeds the marginal value of reaching parity (for example, if the platforms we care about simply don't use NOSTR at all and nothing we build sees users), it's reasonable to stop. Nothing about this roadmap is a commitment to shipping all phases — it's a commitment to doing them in this order when we do them.