Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
ca9df4a
feat(web): add shadcn drawer, components.json and scoped neutral tokens
danditomaso Nov 15, 2026
d161ac6
feat(web): Connections drawer shell replaces the Connections page
danditomaso Nov 15, 2026
b817e50
feat(web): restyle Connections drawer, in-drawer Add view, container …
danditomaso Nov 15, 2026
26b00be
feat(web): resizable Connections drawer with remembered width
danditomaso Nov 15, 2026
5ac0e96
feat(web): inline delete confirmation in the Connections drawer
danditomaso Nov 15, 2026
da21dc1
build(sdk-kmp): add the Kotlin meshtastic-sdk compiled to JavaScript
danditomaso Nov 15, 2026
e0b6ab0
feat(web): connect over HTTP through the Kotlin SDK behind a flag
danditomaso Nov 15, 2026
3aa33b2
refactor(web): take connection state and reconnects from the Kotlin SDK
danditomaso Nov 15, 2026
1091b75
refactor(web): import Protobuf and Types through core/protobuf
danditomaso Nov 15, 2026
a735d46
feat(sdk-kmp): expose admin, telemetry, routing, nodes and sends on t…
danditomaso Nov 15, 2026
f21603f
refactor(web): port ConfigEditor and its hooks into core/kmp
danditomaso Nov 15, 2026
8f50a17
refactor(web): own firmware, logger and admin-size helpers instead of…
danditomaso Nov 15, 2026
7c06ea3
feat(sdk-kmp): Web Serial and Web Bluetooth transports for the Kotlin…
danditomaso Nov 15, 2026
3779663
feat(web): connect Serial and Bluetooth through the Kotlin SDK
danditomaso Nov 15, 2026
189074b
feat(sdk-kmp): send handles, lockdown admin and a host storage provider
danditomaso Nov 15, 2026
12a9370
refactor(web): own the sqlocal repositories and the Types namespace
danditomaso Nov 15, 2026
dc1bd8a
refactor(web): run the app on the Kotlin SDK session, ending the TS r…
danditomaso Nov 15, 2026
659f3c1
feat(web): the Kotlin SDK's storage over the sqlocal database
danditomaso Nov 15, 2026
620c857
chore: lockfile for the web app's storage dependencies
danditomaso Nov 15, 2026
71e6fb0
build(sdk-kmp): compile the Kotlin SDK from a pinned submodule
danditomaso Nov 15, 2026
a725f7a
fix(web): connection lifecycle over the Kotlin SDK
danditomaso Nov 15, 2026
ca51600
fix(sdk-kmp): transport hygiene for reconnects
danditomaso Nov 15, 2026
b4d85d1
refactor(web): drawer and facade cleanup after the SDK review
danditomaso Nov 15, 2026
dcffadd
fix(web): reuse the permitted port or device found on drawer refresh
danditomaso Nov 15, 2026
5819b23
fix(web): drop dead device handles and pick before switching radios
danditomaso Nov 15, 2026
ec7168f
fix(kmp): keep reconnecting after a serial drop and surface the SDK's…
danditomaso Nov 15, 2026
80f8d01
fix(web): keep the live session through an SDK reconnect
danditomaso Nov 15, 2026
86aa110
feat(web): allow only one tab to run the app
danditomaso Nov 15, 2026
7f31adb
fix(web): take the own node from the SDK when its handshake frame was…
danditomaso Nov 15, 2026
1cfdb04
fix(web): enable immer Map support before the device store rehydrates
danditomaso Nov 15, 2026
835653e
fix(web): release the database on tab takeover and bound SDK storage …
danditomaso Nov 15, 2026
ec70d23
fix(web): stop an in-flight connect on handover and harden the tab lock
danditomaso Nov 15, 2026
9a00a59
fix(kmp): drop the bytes a serial device queued before the port opened
danditomaso Nov 15, 2026
b8a79aa
chore: remove the hand-written TypeScript SDK and transport packages
danditomaso Nov 15, 2026
40347b9
chore: clean up references to the removed SDK packages
danditomaso Nov 15, 2026
efad996
perf(sdk-kmp): stop forwarding packet frames on the raw FromRadio stream
danditomaso Nov 15, 2026
dea253d
perf(web): publish node updates once per task
danditomaso Nov 15, 2026
898eb0d
build(sdk-kmp): pin meshtastic-sdk with the browser storage target
danditomaso Nov 16, 2026
b079c15
feat(sdk-kmp): bounded SQLDelight browser storage for the SDK
danditomaso Nov 16, 2026
ee32e32
feat(web): bundle the SDK's SQLite worker
danditomaso Nov 16, 2026
c4b420e
feat(web): the SDK keeps its device state in its own SQLite database
danditomaso Nov 16, 2026
ba7eef5
fix(web): keep the node list's own table current until the SDK serves it
danditomaso Nov 16, 2026
1f25fe2
fix(sdk-kmp): stay degraded across activations and warn once
danditomaso Nov 16, 2026
20c9a7f
build(sdk-kmp): re-pin meshtastic-sdk with the bind-failure fix
danditomaso Nov 16, 2026
5bd291b
chore(web): lint override and storage wiring test
danditomaso Nov 16, 2026
4ac6a5e
fix(web): drop the toast after disconnecting a connection
danditomaso Nov 16, 2026
dd087b9
perf(sdk-kmp): read every queued frame per HTTP poll
danditomaso Nov 16, 2026
66956d7
fix(web): stop the sidebar crashing when a connection drops
danditomaso Nov 16, 2026
85f9acc
build(sdk-kmp): pin the SDK to the pushed storage branch
danditomaso Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
16 changes: 15 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ jobs:
steps:
- name: Checkout code
uses: actions/checkout@v7
with:
submodules: true

- name: Setup pnpm
uses: pnpm/action-setup@v6
Expand All @@ -32,13 +34,25 @@ jobs:
pnpm fetch
pnpm install --frozen-lockfile --offline

- name: Setup JDK 21 (for @meshtastic/sdk-kmp)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21

- name: Setup Gradle
uses: gradle/actions/setup-gradle@v5

- name: Build @meshtastic/sdk-kmp
run: pnpm --filter @meshtastic/sdk-kmp build

- name: Build All Packages (with exclusions)
shell: bash
run: |
set -euo pipefail

# List packages to exclude (full paths under repo root)
EXCLUDED_DIRS=("packages/protobufs" "packages/transport-deno" "packages/ui" "packages/web")
EXCLUDED_DIRS=("packages/protobufs" "packages/sdk-kmp" "packages/ui" "packages/web")

is_excluded() {
local dir="$1"
Expand Down
14 changes: 14 additions & 0 deletions .github/workflows/e2e.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ jobs:
CI: "true"
steps:
- uses: actions/checkout@v7
with:
submodules: true

- uses: pnpm/action-setup@v6

Expand All @@ -32,6 +34,18 @@ jobs:
- name: Install workspace deps
run: pnpm install --frozen-lockfile

- name: Setup JDK 21 (for @meshtastic/sdk-kmp)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21

- name: Setup Gradle
uses: gradle/actions/setup-gradle@v5

- name: Build @meshtastic/sdk-kmp
run: pnpm --filter @meshtastic/sdk-kmp build

- name: Install Chromium
run: pnpm exec playwright install --with-deps chromium

Expand Down
14 changes: 14 additions & 0 deletions .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ jobs:
steps:
- name: Checkout code
uses: actions/checkout@v7
with:
submodules: true

- name: Setup pnpm
uses: pnpm/action-setup@v6
Expand All @@ -33,6 +35,18 @@ jobs:
- name: Install dependencies (root)
run: pnpm install --frozen-lockfile

- name: Setup JDK 21 (for @meshtastic/sdk-kmp)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21

- name: Setup Gradle
uses: gradle/actions/setup-gradle@v5

- name: Build @meshtastic/sdk-kmp
run: pnpm --filter @meshtastic/sdk-kmp build

- name: Run tests
run: pnpm run test

Expand Down
14 changes: 14 additions & 0 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ jobs:
steps:
- name: Checkout code
uses: actions/checkout@v7
with:
submodules: true

- name: Setup pnpm
uses: pnpm/action-setup@v6
Expand All @@ -47,6 +49,18 @@ jobs:
- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Setup JDK 21 (for @meshtastic/sdk-kmp)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21

- name: Setup Gradle
uses: gradle/actions/setup-gradle@v5

- name: Build @meshtastic/sdk-kmp
run: pnpm --filter @meshtastic/sdk-kmp build

- name: Run linter
run: pnpm run lint

Expand Down
20 changes: 17 additions & 3 deletions .github/workflows/release-packages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,24 @@ jobs:
run: |
set -euo pipefail
if [ "${{ github.event.inputs.packages }}" = "all" ] || [ -z "${{ github.event.inputs.packages }}" ]; then
mapfile -t TARGETS < <(ls -d packages/*)
mapfile -t ALL < <(ls -d packages/*)
else
IFS=',' read -ra TARGETS <<< "${{ github.event.inputs.packages }}"
TARGETS=("${TARGETS[@]/#/packages/}")
IFS=',' read -ra ALL <<< "${{ github.event.inputs.packages }}"
ALL=("${ALL[@]/#/packages/}")
fi
# Only publish packages that are not marked "private": true
# (protobufs, sdk-kmp and ui are all private workspace packages).
TARGETS=()
for dir in "${ALL[@]}"; do
if [ -f "$dir/package.json" ] && [ "$(node -p "require('./$dir/package.json').private === true")" = "false" ]; then
TARGETS+=("$dir")
else
echo "Skipping $dir (private or no package.json)"
fi
done
if [ "${#TARGETS[@]}" -eq 0 ]; then
echo "::error::No publishable (non-private) packages selected."
exit 1
fi
printf '%s\n' "${TARGETS[@]}" | paste -sd, - > targets.txt
echo "list=$(cat targets.txt)" >> "$GITHUB_OUTPUT"
Expand Down
13 changes: 13 additions & 0 deletions .github/workflows/release-web.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ jobs:
uses: actions/checkout@v7
with:
ref: ${{ inputs.ref != '' && inputs.ref || github.ref }}
submodules: true

- name: Setup pnpm
uses: pnpm/action-setup@v6
Expand All @@ -50,6 +51,18 @@ jobs:
- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Setup JDK 21 (for @meshtastic/sdk-kmp)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21

- name: Setup Gradle
uses: gradle/actions/setup-gradle@v5

- name: Build @meshtastic/sdk-kmp
run: pnpm --filter @meshtastic/sdk-kmp build

- name: Build web package
working-directory: apps/web
run: pnpm run build
Expand Down
4 changes: 4 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[submodule "packages/sdk-kmp/vendor/meshtastic-sdk"]
path = packages/sdk-kmp/vendor/meshtastic-sdk
url = https://github.com/danditomaso/meshtastic-sdk.git
branch = feat/storage-sqldelight-js
2 changes: 1 addition & 1 deletion .oxfmtrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
"useTabs": false,
"tabWidth": 2,
"printWidth": 80,
"ignorePatterns": ["*.md"]
"ignorePatterns": ["*.md", "packages/sdk-kmp/vendor/**"]
}
117 changes: 27 additions & 90 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,83 +1,41 @@
# Meshtastic Web Monorepo

[![CI](https://img.shields.io/github/actions/workflow/status/meshtastic/web/ci.yml?branch=main&label=Web%20CI&logo=github&color=yellow)](https://github.com/meshtastic/web/actions/workflows/ci.yml)
[![CI](https://img.shields.io/github/actions/workflow/status/meshtastic/js/ci.yml?branch=master&label=JS%20CI&logo=github&color=yellow)](https://github.com/meshtastic/js/actions/workflows/ci.yml)
[![CLA assistant](https://cla-assistant.io/readme/badge/meshtastic/web)](https://cla-assistant.io/meshtastic/web)
[![Fiscal Contributors](https://opencollective.com/meshtastic/tiers/badge.svg?label=Fiscal%20Contributors&color=deeppink)](https://opencollective.com/meshtastic/)
[![Vercel](https://img.shields.io/static/v1?label=Powered%20by&message=Vercel&style=flat&logo=vercel&color=000000)](https://vercel.com?utm_source=meshtastic&utm_campaign=oss)

## Overview

This monorepo consolidates the official [Meshtastic](https://meshtastic.org) web
interface, the domain-driven JavaScript SDK that drives it, and a set of
runtime-specific transport packages. Everything you need to read state from or
send commands to a Meshtastic device lives here.
This monorepo contains the official [Meshtastic](https://meshtastic.org) web
client, the shared UI library it uses, the generated protobuf stubs, and
`sdk-kmp`, a thin JavaScript facade over the Kotlin
[meshtastic-sdk](https://github.com/meshtastic/meshtastic-sdk) that handles
device connections and mesh state.

> [!NOTE]
> You can find the main Meshtastic documentation at https://meshtastic.org/docs/introduction/.

## Packages

Libraries live under `packages/`; the reference web client lives under `apps/`.

| Package | Purpose |
| --- | --- |
| `packages/sdk` | Framework-agnostic TypeScript SDK. Domain-driven feature slices (device, chat, nodes, channels, config, telemetry, position, traceroute, files) built around a `MeshClient` orchestrator with `@preact/signals-core` reactive state. |
| `packages/sdk-react` | React hooks + `MeshProvider` on top of `@meshtastic/sdk`. Wraps signals in `useSyncExternalStore` for concurrent-safe renders. |
| `apps/web` | Reference React web client. Hosted at [client.meshtastic.org](https://client.meshtastic.org). |
| `packages/sdk-kmp` | Wraps the Kotlin Multiplatform [meshtastic-sdk](https://github.com/meshtastic/meshtastic-sdk), compiled to JavaScript with Gradle (JDK 21), behind a small `@JsExport` facade plus browser transports. The web client's connection and mesh behaviour comes from here. The SDK source is pinned as a git submodule at `packages/sdk-kmp/vendor/meshtastic-sdk`. |
| `packages/ui` | Shared Radix + Tailwind component library. |
| `packages/protobufs` | Generated TypeScript stubs from [`meshtastic/protobufs`](https://github.com/meshtastic/protobufs), produced via `buf generate`. Source of truth for every wire-level type. |
| `packages/transport-http` | HTTP transport for devices exposing a network interface. |
| `packages/transport-web-bluetooth` | Web Bluetooth transport for BLE-capable devices (browsers). |
| `packages/transport-web-serial` | Web Serial transport for USB-serial devices (browsers). |
| `packages/transport-node` | TCP transport for Node.js. |
| `packages/transport-node-serial` | Serial transport for Node.js. |
| `packages/transport-deno` | TCP transport for Deno. |
| `packages/transport-mock` | In-memory transport for tests. |

All publishable packages ship to both [JSR](https://jsr.io/@meshtastic) and [NPM](https://www.npmjs.com/org/meshtastic).
All packages under `packages/` are private workspace packages; none are
published to npm or JSR from this repository.

## Architecture

`@meshtastic/sdk` organises its source by feature slice. Each slice follows the
same DDD layout:

```
features/<slice>/
domain/ # entities & value objects — pure TypeScript types
application/ # use-cases (SendTextUseCase, FavoriteNodeUseCase, …)
infrastructure/ # protobuf ↔ domain mappers, admin-message adapters
state/ # signals-backed reactive stores
<Slice>Client.ts # public facade exposing readable signals + command methods
index.ts
```

The shared kernel under `packages/sdk/src/core/` owns:

- **`client/`** — `MeshClient`, the thin orchestrator that owns the transport, queue, event bus, and one instance of every slice client.
- **`transport/`** — the `Transport` interface every `transport-*` package implements.
- **`event-bus/`** — typed pub/sub channels populated by the packet codec.
- **`packet-codec/`** — frame parser (0x94 0xC3), `FromRadio` decoder, portnum router.
- **`queue/`**, **`xmodem/`** — packet ack/timeout pipeline and file-transfer protocol.
- **`signals/`** — signal and keyed-collection helpers consumed by every slice.
- **`logging/`** — `tslog` factory used consistently by every class.
- **`identifiers/`**, **`errors/`** — small primitives shared across slices.

The protobuf boundary is strict: wire messages enter through the packet codec,
get mapped into domain entities inside `features/*/infrastructure/*Mapper.ts`,
and signals only ever expose the domain shape.

```
Transport ─▶ Packet codec ─▶ EventBus ─▶ Slice infrastructure
│
▼
Signals (state) ─▶ sdk-react hooks ─▶ UI
▲
│
Slice application (use-cases) ─▶ MeshClient.sendPacket ─▶ Queue ─▶ Transport
```

Expected domain errors are returned as `Result<T, E>` via [`better-result`](https://www.npmjs.com/package/better-result); exceptions are reserved for programmer errors and truly exceptional conditions.
The web client never speaks the Meshtastic protocol itself. `apps/web` calls
the facade in `packages/sdk-kmp`, which drives the Kotlin SDK (framing, packet
queue, state, persistence) over a browser transport (Web Serial, Web Bluetooth,
or HTTP). Wire-level types come from `packages/protobufs`. See
`packages/sdk-kmp/README.md` for the facade surface and how the SDK version is
pinned.

## Getting Started

Expand All @@ -89,11 +47,20 @@ Expected domain errors are returned as `Result<T, E>` via [`better-result`](http
`pnpm -r build`, since it runs `buf generate`). If you only want to run
the web client in dev, `pnpm --filter meshtastic-web dev` does not need
Buf as long as the protobuf stubs are already generated.
- [JDK 21](https://adoptium.net/) — required to build `@meshtastic/sdk-kmp`,
the Kotlin meshtastic-sdk compiled to JavaScript that the web client
connects through. `pnpm --filter meshtastic-web dev` builds it on first
run (its `predev` hook); on macOS `brew install openjdk@21` and
`export JAVA_HOME=/opt/homebrew/opt/openjdk@21`. Until the SDK's `js`
artifacts are released, it compiles from the `packages/sdk-kmp/vendor/meshtastic-sdk`
git submodule (clone with `--recurse-submodules`, or let the build run
`git submodule update --init`). See `packages/sdk-kmp/README.md` for how
the SDK version is pinned and how to switch to the release.

### Setup

```bash
git clone https://github.com/meshtastic/web.git
git clone --recurse-submodules https://github.com/meshtastic/web.git
cd web
pnpm install
```
Expand All @@ -120,8 +87,7 @@ not sequenced against workspace peers, so run `pnpm --filter
@meshtastic/protobufs build` first if you are iterating on generated
stubs consumed via a non-workspace protocol.

If you only need the web client, build it and its dependency graph without
touching every publishable package:
If you only need the web client, build it and its dependency graph:

```bash
pnpm --filter meshtastic-web... build
Expand All @@ -142,39 +108,10 @@ pnpm check:fix

## Developing

### Adding a new feature slice to `@meshtastic/sdk`

1. Create `packages/sdk/src/features/<slice>/` with `domain/`, `application/`, `infrastructure/`, `state/` subdirectories plus an `index.ts` barrel.
2. Implement a signals-backed store in `state/`.
3. Subscribe to the relevant `EventBus` channel(s) inside a `<Slice>Client.ts` class and write mapped domain entities to the store.
4. Wire the new client into `MeshClient` and re-export types from `packages/sdk/mod.ts`.
5. Add vitest coverage: domain invariants, use-cases against `createFakeTransport()`, and round-trip mapper fixtures.
6. If the slice has React callers, add a matching hook under `packages/sdk-react/src/hooks/`.

### Adding a new transport

Implement the `Transport` interface exported from `@meshtastic/sdk/transport`:

```ts
interface Transport {
toDevice: WritableStream<Uint8Array>;
fromDevice: ReadableStream<DeviceOutput>;
disconnect(): Promise<void>;
}
```

The SDK does the framing and decoding — transports only supply raw bytes.

### Testing

Vitest is wired at the repo root and picks up `packages/*` projects. The SDK
ships `@meshtastic/sdk/testing` with `createFakeTransport()` for wiring tests
without real hardware.

## Publishing

Each publishable package has `build:npm` / `publish:npm` / `prepare:jsr` /
`publish:jsr` scripts. See each package's `package.json` for details.
Vitest is wired at the repo root (`pnpm test`) and picks up the `packages/*` and
`apps/*` projects. See `TESTING.md` for the testing strategy.

## Repository activity

Expand Down
Loading
Loading