[softnationz]

Changes

Realtime subscription intents previously disappeared during socket outages, and the client dispatched unbound payloads without owning route subscription lifetimes. This adds one desired-state registry and reconciliation path for offline changes, authenticated reconnect/resume, wildcard interests, and route owners.

• Queue final subscribe/unsubscribe intent in order, authenticate before flushing, reconcile against the server resume set, bound queue/registry growth with diagnostics, and discard state on wallet logout or explicit teardown. Delayed route snapshots cannot resurrect subscriptions after logout.
• Declare public topic sets for /, /cover, /provide and nested segments. Fetch bounded initial snapshots without blocking rendering, retain shared interests, debounce rapid navigation, release departing interests, and optionally prefetch same-origin link intent with a five-second lifetime. Unmapped routes retain independent hook-owned subscriptions.
• Compile and validate dot-separated exact, *, and terminal ** patterns. Negotiate server wildcard support or enumerate a configured concrete catalog. Deduplicate wire interests and deliver once per registration.
• Validate endpoint scheme/host/port and explicit origin allowlists. Require a versioned challenge handshake, authenticated session binding on every event, monotonic sequence numbers, and ±60s timestamp tolerance. Expose bounded reason-only diagnostics without payloads or secrets.
• Document protocol, ordering/overflow behavior, backend responsibilities, catalog limitations, and threat model in docs/realtime.md.

Security / integration contract

Uses issue #270's authenticated-session binding option, not application-layer signatures. TLS authenticates the allowed endpoint; session binding rejects unsigned legacy envelopes, cross-session events, forged bindings, and replay. It cannot independently authenticate events from a compromised trusted backend. No runtime verification bypass exists, including in mock mode.

The original frontend documented an unimplemented backend transport contract. The backend must implement the documented v1 handshake/resume/envelope contract before streaming succeeds; incompatible feeds fail closed and REST remains available. Default fallback enumeration covers the three public flat topics; hierarchical variants require a complete configured catalog or negotiated server wildcard capability.

Validation

• 34 new tests pass: npx vitest run --config vitest.config.mts src/lib/realtime/client.test.ts src/lib/realtime/topics.benchmark.test.ts.
• Covers disconnect/mutate/reconnect ordering, canceled toggles, resume deduplication, ref counts, send failures, queue overflow convergence, logout and stale snapshot cleanup, origins, production mock-bypass rejection, forged/unsigned/replayed session envelopes, clock tolerance, exact/wildcard routing, route navigation and prefetch lifetime.
• Matcher benchmark: 256,000 comparisons in 23.33ms locally; no machine-dependent timing assertion.
• Focused TypeScript compilation of all new realtime modules, provider, hook, route registry, and tests passes.
• Changed-file ESLint passes with the existing invalid no-restricted-syntax selector disabled on the command line; no lint configuration changed.
• git diff --check passes; one commit on current upstream 8260266, authored and committed by authenticated account softnationz, with no co-author trailers.

Existing upstream verification blockers

Verified against an isolated checkout of upstream main with the same installed dependencies; the full failure listings are identical:

upstream main, valid .mts config: 10 failed suites / 46 failed tests / 105 passed tests
this branch, valid .mts config: 10 failed suites / 46 failed tests / 139 passed tests

• npm ci fails because upstream package-lock.json contains invalid JSON at line 1459. Local validation used npm install --package-lock=false --ignore-scripts --legacy-peer-deps because upstream also has a Vite/plugin peer conflict; manifests and lockfile are unchanged.
• Default npm test loads upstream's empty vitest.config.ts; the existing vitest.config.mts supplies the required alias/include configuration.
• Full npm run typecheck and npm run build fail on existing malformed JSX in src/app/cover/page.tsx; build also reports the malformed lockfile.
• Full npm run lint fails on the existing Literal[value=1e7] selector in .eslintrc.json.
• Several upstream route/component files, including the root layout, are empty. Browser screenshots and application E2E cannot be meaningfully validated while the baseline does not build. This transport change has no visual design changes; executable test output is provided above.

These unrelated files are intentionally excluded from this PR. CI cannot be represented as passing until baseline issues are repaired. Maintainer review and approval remain required.

Closes #271
Closes #268
Closes #270
Closes #269

[drips-wave]

@softnationz Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits