From 4b308aa7a13ff79bf7a7f085151a6cccefbf1dca Mon Sep 17 00:00:00 2001 From: Nidish Date: Fri, 4 Sep 2026 18:11:40 +0530 Subject: [PATCH 1/3] chore(make): add a debugger target that builds the host in dev mode --- Makefile | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 880f1ff2a..ff426992a 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,7 @@ # Run `make help` for the list of targets. .DEFAULT_GOAL := help -.PHONY: help setup build codegen test check check-generated clean playground wasm wasm-crypto-test uniffi uniffi-kotlin android-check provider-android-check ios-build ios-run ios-chat-run ios-chat-host-playground-run ios-chat-all android-jni android-publish-local dotli-link dev dev-cli dev-bootstrap dev-link-check e2e-dotli e2e-cli-diagnosis e2e-signing-cli e2e-pairing-cli e2e-chat-cli e2e-cli-update headless install cli-runner cli-dist matrix explorer xcframework +.PHONY: help setup build codegen test check check-generated clean playground wasm wasm-crypto-test uniffi uniffi-kotlin android-check provider-android-check ios-build ios-run ios-chat-run ios-chat-host-playground-run ios-chat-all android-jni android-publish-local dotli-link dev dev-cli dev-bootstrap debugger dev-link-check e2e-dotli e2e-cli-diagnosis e2e-signing-cli e2e-pairing-cli e2e-chat-cli e2e-cli-update headless install cli-runner cli-dist matrix explorer xcframework CARGO ?= cargo TRUAPI_PKG := js/packages/truapi @@ -25,6 +25,8 @@ DOTLI_TRUAPI_LINK := $(DOTLI_NODE_MODULES)/@parity/truapi DOTLI_HOST_WASM_LINK := $(DOTLI_NODE_MODULES)/@parity/truapi-host DOTLI_UI_TRUAPI_SHADOW := $(DOTLI_UI)/node_modules/@parity/truapi DOTLI_UI_HOST_WASM_SHADOW := $(DOTLI_UI)/node_modules/@parity/truapi-host +DEBUGGER_PKG := $(JS_PACKAGES)/truapi-debugger +DEBUGGER_PORT ?= 9231 VITE_NETWORKS ?= paseo-next-v2,previewnet export VITE_NETWORKS @@ -396,6 +398,24 @@ dev: dev-bootstrap ## Start dotli host (:5173) + playground (:3000) together; op ( until curl -fsS http://localhost:3000/ >/dev/null 2>&1; do sleep 1; done; curl -fsS http://localhost:3000/diagnostics >/dev/null 2>&1 || true ) & \ wait +debugger: dev-bootstrap ## Wire debugger (:9231) + a DEV-MODE dotli host (:5173) + playground (:3000). Open http://127.0.0.1:9231 + # `make dev` cannot drive the debugger: dotli ships only `build` and `preview`, + # both production builds, and the dial sits behind `import.meta.env.DEV`, which + # a production bundle replaces with `false`. The host then never dials and the + # board stays empty with no error - so build the host in dev mode here. + cd $(DOTLI)/apps/host && NODE_ENV=development VITE_APP_DEBUG=true bunx --bun vite build + @printf '\n Debugger: http://127.0.0.1:$(DEBUGGER_PORT)\n' + @printf ' Host: http://localhost:5173/localhost:3000\n\n' + @printf ' One-time, in the browser console on http://localhost:5173 (the realm that\n' + @printf ' creates the host runtime - localStorage is per-origin AND per browser profile):\n\n' + @printf ' localStorage.setItem("truapi:debugger", "ws://127.0.0.1:$(DEBUGGER_PORT)"); location.reload()\n\n' + @printf ' The host logs `wire debugger: dialling ...` once it connects.\n\n' + @trap 'kill 0' EXIT; \ + ( cd $(DEBUGGER_PKG) && TRUAPI_DEBUGGER_PORT=$(DEBUGGER_PORT) bun run src/server.ts ) & \ + ( cd $(DOTLI) && bun scripts/preview-server.ts ) & \ + ( cd $(PLAYGROUND) && yarn dev ) & \ + wait + e2e-dotli: ## Fully automated dotli + playground diagnosis e2e using the local signing-host CLI. @$(MAKE) dev-bootstrap cargo build -p truapi-host-cli From d5161c9c761c0c10c285371c75fdcec2757e63ea Mon Sep 17 00:00:00 2001 From: Nidish Date: Mon, 7 Sep 2026 14:28:31 +0530 Subject: [PATCH 2/3] docs(readme): describe the wire debugger package and the debugger target --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index c7b032e4f..125f5574d 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,28 @@ host owns where the bytes live. The crate stores nothing itself: a host implemen `StorageClient` over storage it already owns, on web and native alike, so it keeps control of quota and of whether the bytes are backed up or encrypted. +### Wire debugger + +[`@parity/truapi-debugger`](js/packages/truapi-debugger) is the consumer for the +payload-blind frame tap in `truapi-server`. The core streams raw SCALE frames out +of two choke points; the debugger correlates them into per-operation traces, +decodes envelopes and values behind a `TRUAPI_WIRE_SCHEMA_HASH` match, and renders +them through one of two mounts: + +- `startDebugServer(...)` is a standalone Bun WS+HTTP server on `127.0.0.1:9231` + that hosts dial into, so frames from any host reach one inspector. +- `createInAppDebugger(...)` mounts the same engine inside the host page, with no + server and no dial. + +All decoding lives in this package; `@parity/truapi` has no debug seam. Its +[README](js/packages/truapi-debugger/README.md) carries the endpoint list and the +per-host enablement recipe. + +`make debugger` brings up the inspector on `:9231` alongside a dot.li host and the +playground. It builds the host with `NODE_ENV=development` on purpose: the dial +sits behind `import.meta.env.DEV`, which a production bundle replaces with `false`, +so `make dev` leaves the board empty with no error. + ## How it works 1. The protocol is defined as Rust traits in [`rust/crates/truapi/`](rust/crates/truapi/), with each method tagged `#[wire(id = N)]` for a stable byte-level dispatch table. Every method's doc comment must carry a ` ```ts ` example, which codegen extracts into the playground's EXAMPLE tab; the build fails if any method is missing one. From 2d1ea80a95aafb1736e592e4e8b2d73abb688e31 Mon Sep 17 00:00:00 2001 From: Nidish Date: Mon, 7 Sep 2026 17:15:56 +0530 Subject: [PATCH 3/3] chore(make): pass the debugger dial URL to the host build --- Makefile | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index ff426992a..1947e4f63 100644 --- a/Makefile +++ b/Makefile @@ -403,11 +403,15 @@ debugger: dev-bootstrap ## Wire debugger (:9231) + a DEV-MODE dotli host (:5173) # both production builds, and the dial sits behind `import.meta.env.DEV`, which # a production bundle replaces with `false`. The host then never dials and the # board stays empty with no error - so build the host in dev mode here. - cd $(DOTLI)/apps/host && NODE_ENV=development VITE_APP_DEBUG=true bunx --bun vite build + cd $(DOTLI)/apps/host && NODE_ENV=development VITE_APP_DEBUG=true \ + VITE_TRUAPI_DEBUGGER=ws://127.0.0.1:$(DEBUGGER_PORT) bunx --bun vite build @printf '\n Debugger: http://127.0.0.1:$(DEBUGGER_PORT)\n' @printf ' Host: http://localhost:5173/localhost:3000\n\n' - @printf ' One-time, in the browser console on http://localhost:5173 (the realm that\n' - @printf ' creates the host runtime - localStorage is per-origin AND per browser profile):\n\n' + @printf ' The dial URL is passed to the host build. A dotli revision that reads\n' + @printf ' VITE_TRUAPI_DEBUGGER seeds it into localStorage for every browser profile;\n' + @printf ' the revision this repo pins does not, so until that pin moves, set it once\n' + @printf ' in the browser console on http://localhost:5173 (the realm that creates the\n' + @printf ' host runtime - localStorage is per-origin AND per browser profile):\n\n' @printf ' localStorage.setItem("truapi:debugger", "ws://127.0.0.1:$(DEBUGGER_PORT)"); location.reload()\n\n' @printf ' The host logs `wire debugger: dialling ...` once it connects.\n\n' @trap 'kill 0' EXIT; \