Universal PowerSync Diagnostics (POC) by khawarizmus · Pull Request #1094 · powersync-ja/powersync-js

khawarizmus · 2026-09-09T14:55:31Z

This PR implements a live-attach diagnostics tool built once and reused across different hosts.

New packages

@powersync/diagnostics-ui — the shared UI (contains six tabs: Sync Status, Data, Buckets, Streams, Config, Logs).
@powersync/diagnostics-core — the host-side client and the PostMessageTransport.
tools/diagnostics-extension — a Chrome DevTools extension (using WXT).

@powersync/common

Add the diagnostics subpath: the protocol, the agent, and the state mappers.
Add schema serialization: Schema.serialize() and fromSerialized(), with tests.
Promote connector and connectionOptions to the public database interface.
Add the diagnostics sync option.

@powersync/web

Add the BroadcastChannel transport and event source.
Add enableDiagnostics(db).

shared-internals

Fix the connector getter to persist for the connection lifetime.
Wire the core diagnostics event stream (HandleDiagnostics) into the JS SDK.

@powersync/nuxt

Replace the old inspector with the shared UI over the protocol.
Delete the interceptor, the schema inference, and the dead inspector code.

Notes

Draft PR for review.
The extension ships here for review. We may move it to its own repository later.

Claude code was used to steer the discovery and development. The code was reviewed and modified manually.

…lient implementations

…ge with components and playground

…ync diagnostics

…d indexes; add SchemaTab to diagnostics UI

…line module imports and setup

…ding columns, indexes, and table options

…ream, UI components, and schema inspection features

…for a cleaner separation

…ion alongside currentOptions

…t and enhance connection handling in extension

…ostMessageTransport, enhance package metadata, and add Chrome types

…nents with icons and status bar

…play and integrate virtual scrolling for upload queue

…t detail component, and improved data handling features

…sizable columns, and theme synchronization

changeset-bot · 2026-09-09T14:55:36Z

🦋 Changeset detected

Latest commit: 9c6336a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
@powersync/diagnostics-ui	Minor
@powersync/web	Minor
@powersync/shared-internals	Minor
@powersync/diagnostics-core	Minor
@powersync/diagnostics	Minor
@powersync/nuxt	Minor
@powersync/common	Minor
@powersync/adapter-sql-js	Patch
@powersync/tanstack-react-query	Patch
@powersync/diagnostics-app	Patch
@powersync/capacitor	Patch
@powersync/node	Patch
@powersync/react-native	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…ted the protocol

simolus3

To share more context here (I've also shared that offline with more context @khawarizmus). I think the idea is awesome, my initial architectural complaints are:

It's not clear whether we need a browser extension, so remove that from this PR which is already very big (you can open a follow-up PR for that separately).
I think a JSON-based protocol over "any two way channel" is the wrong abstraction here. It e.g. forces us to re-invent an RPC protocol when some implementations we'll use (say the Dart VM service protocol) are already RPC based.
None of this should require any changes to an existing SDK package (aside from forwarding core diagnostics events, but even that should likely be a separate PR to validate that the basic integration can work without SDK changes). We can likely inject an agent by writing a vite devtools package instead. Or initially, we could also expose it as a seperate package a user would depend on to expose the channel (e.g. a enablePowerSyncDiagnostics(port: MessagePort, db: BasePowerSyncDatabase)).
Related to 2 and 3, the interface the diagnostics tool expects an SDK to provide should be an actual TypeScript interface with async methods and event listeners. It is the responsibility of each integration (vite, postMessage iframe, Dart) to figure out how to implement that interface by doing the serialization itself.

Add dependency-free `shapes.ts` and `integration.ts` as the tool-owned protocol; move PROTOCOL.md into diagnostics-core and rewrite it to interface + shapes.

…add Vite plugin.

simolus3

I didn't take a look at the UI yet, but the architecture of how devtools are served and integrated looks pretty good at this point. I'll also try to scaffold a Dart integration over the vm service protocol.

simolus3 · 2026-09-16T07:30:42Z

+ */
+
+/** The shape exposed over comlink: `observeEvents` takes a proxied callback instead of a function. */
+type Remote = Omit<SdkIntegration, 'observeEvents'> & {


Let's just make observeEvents return a promise on SdkIntegration, or a Promise<void> | void.

This was addressed

simolus3 · 2026-09-16T07:44:19Z

+// The JavaScript integration (runs in the app page) and the structural database it reads.
+export * from './live-database.js';
+export * from './agent.js';
+export * from './state.js';
+
+// Moving an integration across an iframe boundary, and deriving UI state from its events.
+export * from './bridge.js';
+export * from './store.js';


Relying on structural typing to avoid pulling in the JS SDK here is clever, but also feels somewhat fragile.

Given that these files are still only useful when providing diagnostics for JavaScript SDKs, maybe they shouldn't be part of the default export. I think putting them into a separate package is overkill, but maybe they should be exported from a separate entrypoint (say @powersync/diagnostics-core-js-web).

(and then if they're separate exports, I wouldn't mind this package having an optional dependency on @powersync/common and defining the JS agent on BasePowerSyncDatabase).

The JS-specific code now lives in @powersync/diagnostics-core/js. I kept the structural type instead of adding an optional @powersync/common dependency. The Vite client can now pass WebPowerSyncDatabase directly, and only the Playground UI mock needs to implement that small interface.

simolus3 · 2026-09-16T07:46:00Z

+
+The tool never carries a wire format of its own. Request/response correlation, connection and reconnection are the implementation's concern.
+
+## 2. The interface


Having the overview here is helpful, but it could also be part of the readme. Sections 2-5 of this document should be tsdoc comments instead.

This was addressed. The relevant parts are now in the README, and the rest has been ported to tsdocs comments

simolus3 · 2026-09-16T07:48:38Z

+
+/**
+ * Emitted by the core extension when diagnostics are enabled on the sync stream (see
+ * {@link https://github.com/powersync-ja/powersync-sqlite-core diagnostics}). Reports detailed


Should probably link to https://github.com/powersync-ja/powersync-sqlite-core/blob/main/crates/core/src/sync/diagnostics.rs directly?

This is done

…l arguments

…ors, support several app tabs

… 7 and build behaviour in the README

…the Nuxt changeset breaking

…rd, fast refusal; drop the stdio mcp command

khawarizmus added 16 commits September 2, 2026 17:07

feat(diagnostics-core): add core diagnostics package with agent and c…

ef5771d

…lient implementations

chore(diagnostics-ui): update pnpm lockfile, add diagnostics UI packa…

d857087

…ge with components and playground

feat(diagnostics-extension): add Chrome DevTools extension for PowerS…

e8a9689

…ync diagnostics

feat(schema): implement serialization for schema, tables, columns, an…

d6c8a26

…d indexes; add SchemaTab to diagnostics UI

refactor(inspector): remove unused components and composables; stream…

f135b47

…line module imports and setup

test(schema): add comprehensive tests for Schema serialization, inclu…

d8eb81d

…ding columns, indexes, and table options

feat(diagnostics): enhance diagnostics capabilities with new event st…

4f38dc8

…ream, UI components, and schema inspection features

feat(diagnostics): introduce DiagnosticsAgent and related components …

a682157

…for a cleaner separation

fix(connection-manager): add currentConnector to track active connect…

5195084

…ion alongside currentOptions

fix(diagnostics): implement resync functionality for DiagnosticsClien…

d8533a7

…t and enhance connection handling in extension

feat(diagnostics): update diagnostics core and UI packages with new P…

01f9cb4

…ostMessageTransport, enhance package metadata, and add Chrome types

feat(diagnostics-ui): integrate theme management and enhance UI compo…

3c4c652

…nents with icons and status bar

feat(diagnostics-ui): add new components for enhanced diagnostics dis…

2fd21c9

…play and integrate virtual scrolling for upload queue

feat(diagnostics-ui): enhance diagnostics UI with new logs tab, bucke…

5822ec7

…t detail component, and improved data handling features

feat(diagnostics-ui): improve diagnostics UI with tab persistence, re…

66095e3

…sizable columns, and theme synchronization

chore: revert some unrelated changes

b03e9f3

khawarizmus requested review from simolus3 and stevensJourney September 9, 2026 14:55

refactored(diagnostics): dropped public interface changes and documen…

8048c3a

…ted the protocol

simolus3 requested changes Sep 10, 2026

View reviewed changes

khawarizmus added 3 commits September 14, 2026 19:29

feat(diagnostics-core): define the SdkIntegration and protocol shapes

115dd4f

Add dependency-free `shapes.ts` and `integration.ts` as the tool-owned protocol; move PROTOCOL.md into diagnostics-core and rewrite it to interface + shapes.

refactor(diagnostics): move the protocol to the diagnostics package; …

eed750a

…add Vite plugin.

refactor(diagnostics): add package READMEs, drop NuxtPowerSyncDatabase

8714f7b

github-advanced-security Bot found potential problems Sep 15, 2026

View reviewed changes

Comment thread packages/diagnostics-ui/playground/mockDatabase.ts Fixed

simolus3 reviewed Sep 16, 2026

View reviewed changes

khawarizmus added 3 commits September 16, 2026 16:01

fix(diagnostics): stream subscription timestamps, PowerSync dock icon

9993733

refactor(diagnostics): address review on the protocol package

b228e75

feat(diagnostics): ship PowerSync DevTools as a devframe definition

cb770ae

bean1352 added this pull request to stack #1110 September 17, 2026 10:58

khawarizmus added 7 commits September 18, 2026 13:44

fix(diagnostics): Nuxt devtools now mounts on Vite devtools properly

95e0b73

feat(diagnostics): MCP origin knob for node and CLI and spell out too…

3a3bc42

…l arguments

fix(diagnostics): announce source attach and detach, surface tool err…

188a0a1

…ors, support several app tabs

fix(diagnostics): keep the Nuxt plugin quiet in production, note Vite…

b275f4e

… 7 and build behaviour in the README

chore(diagnostics): trim traces, type the Nuxt runtime options, mark …

5331d84

…the Nuxt changeset breaking

feat(diagnostics): CLI --token for connectAgent clients, location gua…

a8bb921

…rd, fast refusal; drop the stdio mcp command

build: make CI green for the diagnostics packages

9c6336a

Navigation Menu

Universal PowerSync Diagnostics (POC) - #1094

Universal PowerSync Diagnostics (POC)#1094
khawarizmus wants to merge 30 commits into
mainfrom
diagnostics-poc

khawarizmus commented Sep 9, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

simolus3 left a comment

Uh oh!

Uh oh!

simolus3 left a comment

Uh oh!

simolus3 Sep 16, 2026

Uh oh!

khawarizmus Sep 16, 2026

Uh oh!

simolus3 Sep 16, 2026

Uh oh!

khawarizmus Sep 16, 2026

Uh oh!

simolus3 Sep 16, 2026

Uh oh!

khawarizmus Sep 16, 2026

Uh oh!

simolus3 Sep 16, 2026

Uh oh!

khawarizmus Sep 16, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		The tool never carries a wire format of its own. Request/response correlation, connection and reconnection are the implementation's concern.

		## 2. The interface

Conversation

khawarizmus commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

simolus3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

simolus3 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

khawarizmus commented Sep 9, 2026 •

edited

Loading

changeset-bot Bot commented Sep 9, 2026 •

edited

Loading