Skip to content

Local-first stream: IndexedDB store, delta sync API, worker decode, and virtualized mobile list#390

Open
kojibai wants to merge 13 commits intomainfrom
codex/upgrade-performance-and-architecture-for-mobile
Open

Local-first stream: IndexedDB store, delta sync API, worker decode, and virtualized mobile list#390
kojibai wants to merge 13 commits intomainfrom
codex/upgrade-performance-and-architecture-for-mobile

Conversation

@kojibai
Copy link
Copy Markdown
Owner

@kojibai kojibai commented Feb 21, 2026

Motivation

  • Reduce main-thread work and initial render cost on mobile by moving expensive decode/graph work off the main thread and rendering a tiny preview model first.
  • Improve online sync efficiency by shipping tiny deltas instead of full payloads and preserve a strong offline-first experience via on-device persistence.
  • Provide conservative prefetch/warmup controls and preserve existing routes and offline shell behavior.

Description

  • Added a local-first, worker-backed stream data layer with IndexedDB persistence and preview model; new client APIs: streamStore.getFeedPage(cursor, limit), streamStore.getThread(token, depth), streamStore.applyDelta(delta), streamStore.getPreview(urlOrToken), and streamStore.prefetchAround(token) (new files: /workspace/PHI_NETWORK/src/lib/stream/streamStore.ts, /workspace/PHI_NETWORK/src/workers/streamWorker.ts).
  • Added compact delta-sync client/server flow: GET /api/stream/head, GET /api/stream/delta?after=<seal>&limit=<n>, and GET /api/stream/snapshot?compact=1, plus server helpers to compute row previews and a deterministic seal (new files: /workspace/PHI_NETWORK/api/stream/data.ts, /workspace/PHI_NETWORK/api/stream/head.ts, /workspace/PHI_NETWORK/api/stream/delta.ts, /workspace/PHI_NETWORK/api/stream/snapshot.ts).
  • Offloaded decode/preview projection to a Web Worker for main-thread relief, and provided a worker-fallback flag and pure-JS fallback when Workers are unavailable (changed: /workspace/PHI_NETWORK/src/lib/stream/streamStore.ts, /workspace/PHI_NETWORK/src/workers/streamWorker.ts).
  • Reworked stream UI for progressive/batched rendering and virtualization with a lightweight preview card that defers full payload decode until open/expand and performs local prefetch around an open token (changed: /workspace/PHI_NETWORK/src/pages/sigilstream/list/StreamList.tsx, /workspace/PHI_NETWORK/src/pages/sigilstream/list/virtualWindow.ts).
  • Integrated background delta sync into the Sigil Stream root to merge newly synced URLs into the local-first shown source list without forced reloads (changed: /workspace/PHI_NETWORK/src/pages/sigilstream/SigilStreamRoot.tsx, and added sync helper /workspace/PHI_NETWORK/src/lib/stream/streamSync.ts).
  • Tests and helper utilities added for deterministic behaviors and unit checks (new test: /workspace/PHI_NETWORK/tests/stream_upgrade.test.mjs).

Testing

  • Ran targeted unit/verification tests: npm test -- tests/stream_upgrade.test.mjs — all tests in that file passed (delta apply correctness, offline-first snapshot path, worker-fallback flag, virtualization bounds) ✅.
  • Built production artifacts: npm run build executed successfully (TypeScript compile + Vite build) ✅.
  • Exercised app in a headless browser to verify basic mobile layout: Playwright script visited http://127.0.0.1:4173/stream and produced a mobile screenshot at browser:/tmp/codex_browser_invocations/.../artifacts/artifacts/stream-mobile-upgrade.png (visual smoke check) ✅.

Files changed (absolute paths)

  • /workspace/PHI_NETWORK/src/lib/stream/streamStore.ts
  • /workspace/PHI_NETWORK/src/lib/stream/streamSync.ts
  • /workspace/PHI_NETWORK/src/workers/streamWorker.ts
  • /workspace/PHI_NETWORK/src/pages/sigilstream/SigilStreamRoot.tsx
  • /workspace/PHI_NETWORK/src/pages/sigilstream/list/StreamList.tsx
  • /workspace/PHI_NETWORK/src/pages/sigilstream/list/virtualWindow.ts
  • /workspace/PHI_NETWORK/api/stream/data.ts
  • /workspace/PHI_NETWORK/api/stream/head.ts
  • /workspace/PHI_NETWORK/api/stream/delta.ts
  • /workspace/PHI_NETWORK/api/stream/snapshot.ts
  • /workspace/PHI_NETWORK/tests/stream_upgrade.test.mjs

Commands run (selection) and outcomes

  • npm test -- tests/stream_upgrade.test.mjs — passed (targeted tests) ✅
  • npm run build — succeeded (TypeScript + Vite build) ✅
  • npm test — full test run started and many subtests passed during validation; targeted verification used for this PR (no regressions observed in the exercised areas) ⚠️ (long suite run observed; targeted tests used to validate changes)
  • Headless verification: Playwright screenshot of mobile viewport (artifact produced) ✅

Remaining risks & recommended next steps

  • Server delta endpoints currently derive rows from a static public/links.json scan; for large production feeds convert this to a persisted append-only index or change journal to make delta computation O(delta) rather than scanning.
  • Add cursor/pulse-based pagination for delta/snapshot for robust server-side pagination when dataset grows.
  • Add integration tests that run the full delta roundtrip against a running API to validate head→delta→apply end-to-end under network conditions.
  • Consider route-level code-splitting for very large chunks the bundler warned about to further improve initial mobile startup.

If you want, I can split the server endpoints into a separate service, add an HTTP integration test that runs a dev API and validates full delta synchronization, or add a small opt-in feature flag for aggressive prefetch tuning on high-end devices.


Codex Task

@vercel
Copy link
Copy Markdown

vercel Bot commented Feb 21, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
phi-network-5aii Ready Ready Preview, Comment Feb 22, 2026 4:15am

Request Review

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7235df2238

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread api/stream/delta.ts Outdated
Comment thread src/lib/stream/streamStore.ts Outdated
Comment thread src/pages/sigilstream/list/StreamList.tsx Outdated
…-returning-seal

Fix stream delta catch-up pagination, persisted baseline, and URL ingest churn
…visibility-change

Optimize StreamList ingestion to avoid repeated full URL processing
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant