Upgrade to PowerSync JS SDK v2 with checkpoint-request refresh

[michaelbarnes]

Description

Upgrades the template from @powersync/web 1.34 / @powersync/react 1.9 to the v2 SDK line and adds a data refresh flow built on checkpoint requests, the new v2.3.0 API. Also migrates the cloud configuration path to Sync Streams and standardizes the repo on pnpm.

Work Done

SDK v2 upgrade

• Bumps @powersync/web to 2.3.0 and @powersync/react to 2.0.1.
• Rewrites src/powersync/System.ts for the v2 constructor: open options move under database: {...}, so WASQLiteOpenFactory and the flags wrapper are gone. The logger moves to createConsoleLogger.
• Removes the hand-rolled Safari, mobile, and multi-tab detection (from Updated practices for VFS #61 and fix: disable multi-tab on Safari regardless of mobile or desktop #63). The v2 SDK disables multi-tab on Safari by default, and OPFSCoopSyncVFS is stable on Safari. Only the runtime OPFS probe remains, because Safari Private Browsing exposes the OPFS API but rejects getDirectory().
• Updates SupabaseConnector for v2 types: CommonPowerSyncDatabase replaces AbstractPowerSyncDatabase, and fetchCredentials() now returns an expiresAt hint.
• Replaces the deprecated status.dataFlowStatus reads with status.uploading and status.downloading.
• Removes the direct @journeyapps/wa-sqlite dependency. It's now a regular dependency of @powersync/web.

Checkpoint requests (alpha API, requires PowerSync Service 1.24.0 or later)

• Connects with checkpointMode: "requests".
• Adds a Refresh button to App.tsx that calls powerSync.requestCheckpoint() and then checkpoint.waitForSync() with a 30 second abort signal. When the wait resolves, the local database reflects server state from the time of the request, and the existing watch query re-renders on its own.

Sync Streams for the cloud path

• Replaces the legacy sync-rules.yaml with sync-config.yaml (edition 3), matching the sync_config block in docker/powersync.yaml.
• Updates the README cloud setup for the current CLI flow: powersync login, powersync init cloud, powersync link cloud --create, powersync deploy.

Tooling

• Standardizes on pnpm: CI now uses pnpm/action-setup with the Node version from .nvmrc, packageManager is pinned in package.json, and package-lock.json is removed.
• Installs the PowerSync agent skill at .agents/skills/powersync (with a .claude/skills symlink and skills-lock.json), so coding agents in this repo pick up PowerSync best practices. ESLint ignores .agents/.
• Moves vite-plugin-wasm to devDependencies. Intentionally does not add vite-plugin-top-level-await: it breaks the v2 worker bundle under Vite 7 with Rollup 4, and Vite 7's default build target supports top-level await natively.
• Adds CLAUDE.md with repo guidance for Claude Code.

How to Test

1. Install dependencies: pnpm install.
2. Confirm the static checks pass: pnpm lint, pnpm type-check, and pnpm build.
3. Start the local stack: pnpm dev:supabase, then docker compose -f docker/compose.yaml pull (the service must be 1.24.0 or later for checkpoint requests), then pnpm dev:powersync and pnpm dev:ui.
4. At http://localhost:5173, confirm the status card shows connected: true and the console logs using VFS: OPFSCoopSyncVFS in Chrome.
5. Create and increment a counter, and confirm the row appears in Supabase Studio at http://localhost:54323.
6. Edit the counter's count directly in Supabase Studio, click Refresh in the app, and confirm the new value appears once the button returns from its refreshing state.
7. Optional: open a second tab to confirm multi-tab sync, and smoke-test Safari.

Lint, type-check, and build pass locally. The live end-to-end steps above have not been run against this branch yet, so please run them during review.

AI Disclosure

This PR was researched, written, and prepared by Claude Code (model: Claude Fable 5), directed and reviewed by @michaelbarnes. API usage was verified against the installed v2 package type definitions, the PowerSync docs, and the package changelogs rather than model memory. Please review with the usual scrutiny for AI-assisted changes, in particular the VFS selection in System.ts and the README cloud CLI flow.

🤖 Generated with Claude Code