Both packages publish to npm with `files: [..., "README.md", ...]` so the
README is the landing page. Old versions were one-line stubs.
- @meshtastic/sdk: explain feature-client surface, subpath exports
(/transport, /protobuf, /testing), the fake transport for tests, and
the migration story from @meshtastic/core (one SDK, separate transport
packages, framework-agnostic core).
- @meshtastic/sdk-react: single-client + registry quickstarts, grouped
hook reference, and why the React bindings split out of core.
Shim note carried forward in the sdk README: legacyMeshDevice export
stays until the web client finishes migrating; new code should target
MeshClient directly.
Surfaces what the connection handshake is doing in real time. Per DDD,
the predicate + counters live in the SDK; the web overlay is a thin
consumer of the signal.
SDK
- New `MeshClient.progress: ReadonlySignal<ConnectionProgress>` with the
state machine `idle → configuring → configured`. Counters
(config / modules / channels / nodes + boolean myInfo / metadata)
tally inbound packets each `configure()` cycle.
- `configure()` resets to `configuring` with empty counters.
`onConfigComplete` flips to `configured`.
- `ConnectionProgress` + `ConnectionProgressCounters` exported from the
package surface.
- 6 new tests in `MeshClient.progress.test.ts`.
sdk-react
- `useConnectionProgress()` hook reads the active client's signal,
returns `{ phase: "idle" }` when there is no active client so the
caller can render unconditionally.
apps/web
- `ConnectingOverlay` redesigned as a terminal-style streaming log:
- macOS-window-style header (red/yellow/green dots) with a live
`phase` indicator pulse.
- Monospace event lines with `→` (active) / `✓` (done) / `•` (info)
glyphs and a relative-seconds timestamp column.
- Auto-scrolls to the latest entry; blinking caret on the trailing
active line.
- Lines derive from `device.connectionPhase` transitions and per-
counter bumps on `MeshClient.progress`. Resets on each fresh
connect cycle.
- Mounted at the top of the device tree (outside the device-conditional
branch) so it shows during a first-time connect from the Connections
screen as well as reconnects from inside the app.
- i18n strings under `connections.overlay.log.*`.
Mirrors Meshtastic-Android's `regionUnset` flow. A freshly-flashed device
boots with `Config.LoRa.region == UNSET` and won't transmit at all until
the user picks one. Web now surfaces this:
- `ConfigClient.isRegionUnset: ReadonlySignal<boolean>` — computed from
the radio config signal, false until the first LoRa packet arrives so
consumers don't flash the prompt during the connect handshake.
- `useIsRegionUnset()` hook in sdk-react, re-exported from the package's
public surface.
- `RegionSetupReminder` mounts inside the connected-device branch of
App.tsx. While the SDK reports `isRegionUnset == true`, a persistent
toast offers a "Set region" CTA that deep-links into the LoRa tab
(`/settings/radio`). Toast auto-dismisses the moment a real region is
committed.
Predicate matches Android exactly (single check, no owner/name/setupComplete
heuristics). Lives in the SDK config slice — UI is a thin consumer.
3 new SDK tests; SDK 64 / sdk-react 8 / web 236.
Sweep covering several unrelated cohorts:
- Delete dead `NewDeviceDialog.tsx` (commented-out in App.tsx, imports point at
non-existent `@components/PageComponents/Connect/*`).
- Add `better-result` to sdk-react deps so `useChat`/`useDirectChat`/
`useFavoriteNode`/`useIgnoreNode` resolve.
- Fix `test-utils.tsx`: route at `routeTree.gen.ts` was never generated;
re-export the existing `routeTree` constant from `routes.tsx` and pass
the missing router context + DeviceWrapper deviceId.
- Pre-existing `noUncheckedIndexedAccess` violations in `pskSchema.test.ts`,
`x25519.ts`, `Table/index.tsx` + test, `useCopyToClipboard` (Timeout vs
number) — non-null asserts where the index is guaranteed by the
surrounding code, plus a defensive `if (!cell) return 0` in the table sort.
- Immer `WritableDraft<T>` mismatches against SDK's `MeshDevice`/`Device`
classes — cast through `Draft<X>` where the inferred recursive draft type
can't represent SDK class internals.
- `deviceStore.mock` updated for the `connectionPhase`/`connectionId` +
setters added when the connection lifecycle was extracted.
- `HeatmapLayer` accepts the `isVisible` prop everyone else's layer accepts.
- `SNRTooltipProps.to` widened to `string | undefined` (single-node hover
has no `to`).
- Zod resolver returns `Record<string, never>` for the error-path values
shape that react-hook-form expects.
- Mock `NodeInfo` in `useFilterNode.test.ts` gains the `isMuted` proto
field that landed upstream.
- Drop bogus `dts.isolatedDeclarations` field from SDK (not a real tsdown
option; tsdown was silently ignoring it).
- Make every package explicit about the perf-relevant flags rather than
relying on defaults that drift between tsdown versions: target=esnext
(no syntax downleveling), sourcemap=false, minify=false, treeshake=true,
report=false, splitting=false.
- Modest wall-clock wins: SDK 1020→752ms, transports ~720→~600ms.
`isolatedDeclarations: true` in tsconfig would unlock the bigger oxc-dts
fast path but the codebase isn't ID-clean yet — left as future work.
The legacy `@meshtastic/core` package is gone. The six transport-*
packages and the web app no longer depend on it; everything routes
through `@meshtastic/sdk`.
Transport packages (transport-deno, transport-http, transport-node,
transport-node-serial, transport-web-bluetooth, transport-web-serial):
- package.json deps swap `@meshtastic/core: workspace:*` for
`@meshtastic/sdk: workspace:*`.
- src/transport.ts + src/transport.test.ts imports point at
`@meshtastic/sdk` (the `Types` and `Utils` namespaces are still
exported from the SDK so source code is otherwise unchanged).
- README.md examples updated to import from `@meshtastic/sdk`.
apps/web:
- Drops the leftover `@meshtastic/core` workspace dep; nothing in
apps/web/src imports from it.
@meshtastic/sdk:
- README description loses the "Replaces @meshtastic/core" suffix —
there's nothing left to replace.
- Three legacy shim files keep their re-exports but their docstrings
drop the "Phase-A shim, removed in Phase C" framing. The MeshDevice
facade survives because the web app's `connection.factoryResetDevice()`
/ `connection.reboot()` / etc. callsites still go through it; new
consumers should reach into `client.config` / `client.chat` / etc.
- New scripts/rename-dts.mjs is a postbuild step that renames tsdown's
hashed entry-point dts outputs (`mod-<hash>.d.ts` etc.) back to their
canonical names so package.json `types` and downstream dts-bundlers
can find them. Internal chunk dts files (e.g. `Transport-<hash>.d.ts`)
are intentionally NOT renamed because mod.d.ts imports them by path.
- build:npm runs tsdown then the rename script.
Version bumps (signal: now require @meshtastic/sdk):
- @meshtastic/sdk 0.1.0 -> 1.0.0
- @meshtastic/sdk-react 0.1.0 -> 1.0.0
- @meshtastic/sdk-storage-sqlocal 0.1.0 -> 1.0.0
- @meshtastic/transport-http 0.2.5 -> 1.0.0
- @meshtastic/transport-web-serial 0.2.5 -> 1.0.0
- @meshtastic/transport-web-bluetooth 0.1.5 -> 1.0.0
- @meshtastic/transport-deno 0.1.1 -> 1.0.0
- @meshtastic/transport-node 0.0.2 -> 1.0.0
- @meshtastic/transport-node-serial 0.0.2 -> 1.0.0
Workflows: nothing referenced packages/core directly (only the
release-packages.yml glob which already collapsed in the apps/web
move). README packages table loses the legacy `packages/core` row.
Verified: web build clean, all four package suites green
(web 236, sdk 65, sdk-react 8, storage 30).
The transport packages' dist build is currently blocked by a tsdown
cross-chunk dts resolution glitch where the `Types` namespace import
can't follow `mod.d.ts`'s reference to the internal `Transport-<hash>`
chunk. Runtime is fine — only the published-types path is affected,
and transport packages publish via their own release flow. Logged as
follow-up.
ChatClient gains a `chat.unread` namespace mirroring `chat.drafts`:
- byKey: ReadonlySignal<Map<conversation-key-string, number>>
- total: ReadonlySignal<number>
- count(key): ReadonlySignal<number>
- markRead(key): void
Increments happen in the existing onMessagePacket subscriber when
packet.from !== client.myNodeNum (so the outbound echo of our own send
doesn't bump anything). Uses the same ConversationKey shape the rest
of the chat slice already keys by, so direct messages keyed by peer
and broadcasts by channel can never collide.
Counts are in-memory only — persistence will come later if needed
(would require tracking a lastReadAt timestamp per conversation in the
message repository and computing unread on hydrate).
sdk-react: new useTotalUnread / useUnreadCount(key) / useUnreadByKey
hooks. All fall back to safe empty values when no client is active.
Web migration:
- Sidebar reads useTotalUnread instead of summing
deviceStore.unreadCounts.
- MessagesPage: per-channel SidebarButton counts read from
useUnreadByKey()'s `channel:N` keys; per-direct-message counts from
`direct:N` keys. Click handlers call meshClient.chat.unread.markRead
with the typed ConversationKey instead of resetUnread.
- subscriptions.ts: drops onMessagePacket -> incrementUnread mirror
(SDK now owns it). myNodeNum local goes away too — nothing else
consumed it.
- deviceStore: removes unreadCounts field + incrementUnread /
resetUnread / getUnreadCount / getAllUnreadCount methods. The mock
+ test block in deviceStore.test.ts also drop their unread coverage.
- deviceStore.mock.ts: also strips the dead changeRegistry / setChange
/ hasConfigChange / etc. methods that survived from the earlier
changeRegistry deletion.
Tests: SDK 61 -> 65 (+4 ChatClient.unread.test), sdk-react 8, web 236.
Build clean.
Replaces the (broken) web changeRegistry with a section-grain editor that
lives on the SDK. Per-connection state, signal-backed, exposed via
client.config.editor.
ConfigEditor (domain):
- baseline = what the device most recently sent. Updated automatically
from onConfigPacket / onModuleConfigPacket / onChannelPacket.
- working = UI edits. setRadioSection / setModuleSection / setChannel.
- dirtyRadioSections / dirtyModuleSections / dirtyChannels signals plus
an aggregate isDirty signal.
- Inbound baseline updates do NOT discard pending working changes — if a
section is already dirty, the new baseline is recorded but working stays
put; dirty bookkeeping recomputes against the updated baseline.
- reset() restores working = baseline.
- commit() wraps beginEditSettings → setConfig per dirty radio variant +
setModuleConfig per dirty module variant + setChannel per dirty channel
→ commitEditSettings, then optimistically promotes working to baseline.
- Disconnect clears both baseline and working so a stale working copy can
never leak across reconnects.
Domain types:
- RadioConfig and ModuleConfig are now derived directly from the proto
Config / ModuleConfig payloadVariant union (Extract<{case: V}> shape) so
new variants stay typed without manual list maintenance. This adds
deviceUi (radio) and statusmessage (module) automatically.
sdk-react:
- New useConfigEditor() hook returns the editor for the active client, or
undefined when no client is active. Components subscribe to the editor's
signals via the existing useSignal helper.
Tests:
- 5 new ConfigEditor tests covering: clean start, dirty tracking, multi-
section dirty, reset, mid-edit baseline update preservation, and
disconnect-clears-state. SDK suite 49 passing.
This commit is scaffolding only — no web settings page rewires yet. The
~25 settings pages move to editor.set* / editor.commit() in follow-up
commits, replacing setChange / commitEditSettings call sites and unblocking
deletion of changeRegistry from the device store.
Phase one of the channels-slice migration (PR #8 in plan). Moves the
non-changeRegistry-coupled consumers off the legacy deviceStore.channels
Map onto the SDK signal-backed ChannelsClient.
- sdk-react useChannels: switch from useClient to useActiveClient and
fall back to an empty signal when no client is active. Matches the
no-throw pattern already used by useNodes / useNodeErrors so isolated
component tests and pre-connect renders don't throw.
- Messages.tsx reads channels via useChannels(); filteredChannels is
derived with useMemo, currentChannel via .find(). The SDK Channel
shape (index/role/settings) matches everything this page touches.
- QRDialog reads channels directly via useChannels(); the channels Map
prop is dropped from QRDialogProps + DialogManager.
- getChannelName loosens its parameter type to the SDK-compatible
subset { index, settings?: { name? } } so it accepts both proto
Channel and SDK Channel without conversion.
Channels.tsx, ImportDialog and Settings/index.tsx still read from the
deviceStore — they are coupled to changeRegistry / setChange and will
move with PR #9 (ConfigEditor).
Moves PKI mismatch / duplicate-key validation and routing-error tracking
out of the legacy Zustand nodeDBStore and into the SDK NodesClient so
every consumer reads the same source of truth. Validates Android's gap
analysis: Meshtastic-Android does not track per-node PKI errors at all,
so the SDK must own this concern client-side.
packages/sdk
- New NodeError + NodeErrorType (Routing_Error | "MISMATCH_PKI" |
"DUPLICATE_PKI"). Mirrors the previous web-only types.
- New nodeValidation infrastructure mapper (pure): byte-equal compare on
publicKey, returns ValidatedNodeInfo { accepted?, error? }. Ports the
detection rules verbatim from
packages/web/src/core/stores/nodeDBStore/nodeValidation.ts.
- NodesClient gains an errors signal + errorFor / hasError / setError /
clearError / clearAllErrors API. handleIncoming runs validation before
upserting; conflicts skip the store write and record an error. A clean
refresh of a previously-flagged node clears the error.
- handleRoutingPacket records PKI_UNKNOWN_PUBKEY / PKI_FAILED /
PKI_SEND_FAIL_PUBLIC_KEY / NO_CHANNEL against packet.from.
- 5 new vitest cases covering MISMATCH_PKI, DUPLICATE_PKI, error-clear-on-
refresh, routing-error capture, clearError / clearAllErrors. SDK total:
44 tests, all green.
packages/sdk-react
- New useNodeErrors / useNodeError(num) / useHasNodeError(num) hooks.
All resolve through useActiveClient() and fall back to empty when no
client is present.
packages/web
- pages/Nodes/index.tsx, pages/Messages.tsx, components/PageComponents/
Map/Layers/NodesLayer.tsx swap useNodeDB().hasNodeError for the SDK
useNodeErrors hook + a memoised Set lookup.
- components/Dialog/RefreshKeysDialog/RefreshKeysDialog.tsx reads the
current error from useNodeError(activeChat); useRefreshKeysDialog.ts
drives meshClient.nodes.clearError + meshClient.nodes.remove instead
of the legacy store. The companion test still passes through the
empty-MeshRegistry render path because useNodeError tolerates a
missing active client.
- core/subscriptions.ts no longer calls nodeDB.setNodeError on PKI /
no-channel routing packets — the SDK records those itself. The dialog
open trigger stays here.
- pages/Nodes/index.tsx drops the now-dead NODEDB_DEBOUNCE_MS constant.
Web tests: 295 still green; production Vite build clean. The legacy
nodeDB still runs its internal validation but its error map is now a
dead end — removal queued in the plan-file follow-up alongside the rest
of the nodeDB cleanup.
Moves per-conversation draft text out of the legacy Zustand messageStore
into the SDK chat slice so drafts share the same persistence + signal
machinery as messages. MessageInput now binds directly to the SDK; the
legacy `useMessages().getDraft/setDraft/clearDraft` API is no longer
called from the input.
packages/sdk
- New DraftRepository port + InMemoryDraftRepository default.
- ChatClient.drafts namespace: get(key) returns a ReadonlySignal<string>;
set/clear keyed by ConversationKey.
- ChatClient.send auto-clears the draft for the resolved conversation on
success (parity with prior Zustand clearDraft-on-send behavior).
- Lazy hydrate from the DraftRepository on first read of a conversation.
- 3 new tests in ChatClient.drafts.test.ts.
packages/sdk-react
- New useDraft(conversation) hook returning { text, setText, clear }.
packages/sdk-storage-sqlocal
- New `drafts` table (device_id + conversation_key composite PK, text,
updated_at). Drizzle schema in src/schema/drafts.ts.
- Migration v2 in src/schema/migrations.ts creates the table on first
open of an existing v1 DB.
- SqlocalDraftRepository implementing DraftRepository: load/save/clear/
loadAll, scoped by device_id, upsert on conflict, delete on empty save.
- 6 new tests covering save/load round-trip, empty-string deletion,
upsert, multi-device isolation, loadAll.
packages/web
- useConnections wires the SqlocalDraftRepository alongside the existing
SqlocalMessageRepository per registered MeshClient.
- MessageInput accepts `conversation: ConversationKey` instead of the
prior `to: Types.Destination` — fixes the legacy bug where every
broadcast channel shared a single draft slot.
- MessagesPage passes the appropriate ConversationKey for direct/
broadcast chats.
- MessageInput.test.tsx rewritten to mock useDraft from sdk-react.
Test counts: sdk 39 (+3), sdk-storage-sqlocal 18 (+6), web 294 unchanged.
Production Vite build clean.
Adds an adapter hook that bridges sdk-react's `useChat` and `useDirectChat`
to the legacy `Message` shape MessagesPage / ChannelChat / MessageItem
expect. The page now renders messages directly from the OPFS-backed
SqlocalMessageRepository — page reload hydrates lazily (last 50 per
conversation) instead of pulling 1000+ rows from IndexedDB into memory.
packages/sdk-react
- useChat() gains loadOlder(before, limit) for paginated backfill.
- New useDirectChat(peer) hook covering DM conversations.
packages/web
- src/core/hooks/useChatLegacy.ts: maps SDK `Message` → legacy
`messageStore/types.ts` Message shape, including state translation
(SDK Pending → legacy Waiting).
- MessagesPage flips broadcast and direct chat reads to useChatLegacy.
getMessages call sites removed; setMessageState retained on the legacy
store for outbound bookkeeping until the next migration step.
Drafts, unread counts, activeChat / chatType continue to live in the
Zustand messageStore — they are UI-only state and stay where they are
per the locked architecture decision. The legacy store's saveMessage,
getMessages, setMessageState, and persistence path remain in place for
now; PR cleanup follow-up will retire them once outbound state and
"delete all messages" flows are switched to the SDK.
Web test suite: 294 still green. Production Vite build clean.
Adds TESTING.md documenting six tiers (unit / slice / client / storage /
hook / E2E), per-package coverage gates, and the audit of where we
currently sit.
Slice tests in @meshtastic/sdk
- NodeMapper proto round-trip; NodesClient list signal updates.
- ChannelsClient indexes by channel number.
- ConfigClient merges Config + ModuleConfig variants.
- TelemetryClient latest + history per node.
- PositionClient byNode + list.
- ChatClient persistence: hydrate on first subscribe, paginate via
loadOlder, persist inbound messages through the repository. Fixes a
reverse-iteration bug in loadOlder discovered by the new test.
Hook tests in @meshtastic/sdk-react
- New tests/hooks.registry.test.tsx covers useMeshDevice, useNodes,
useNode, useChannels under <MeshRegistryProvider>, plus an active-
client switch round-trip.
Storage tests in @meshtastic/sdk-storage-sqlocal
- migrations.test.ts validates v1 DDL creates messages/nodes/telemetry/
_schema and indexes; CREATE IF NOT EXISTS is idempotent.
- MultiTabCoordinator.broadcast.test.ts proves cross-tab BroadcastChannel
delivery between two coordinators in the same process.
- New vitest.browser.config.ts + tests/sqlocal-opfs.browser.test.ts run
under @vitest/browser (Playwright provider) for real OPFS round-trip
verification. Wired as `pnpm test:browser`. Browser test files end in
`.browser.test.ts` and are excluded from the Node runner.
E2E / firmware-simulator tier (TESTING.md §"E2E / simulator") is scoped
for a follow-up — needs CI Docker for meshtasticd.
Totals after this change:
- @meshtastic/sdk: 36 tests (was 25)
- @meshtastic/sdk-react: 8 tests (was 2)
- @meshtastic/sdk-storage-sqlocal: 12 tests (was 8)
- meshtastic-web: 294 tests (unchanged)
Prevents collision with packages/web's own useDevice() Zustand hook. All
internal exports + tests updated; no behavior change.
Callers migrating off @meshtastic/core should use useMeshDevice() from
@meshtastic/sdk-react going forward.
Phase B prep for web migration. Web holds multiple simultaneous device
connections keyed by ConnectionId, so per-slice hook migrations need a
registry-aware provider.
packages/sdk
- MeshRegistry: Map<ConnectionId, MeshClient> with signals for list/active/activeId.
create()/get()/has()/remove()/setActive().
- First-created client auto-activates.
- remove() disconnects the client and rotates active to another entry.
- 4 vitest cases covering create, auto-activate, duplicate rejection, and remove.
packages/sdk-react
- MeshRegistryProvider + MeshRegistryContext.
- useMeshRegistry, useOptionalMeshRegistry, useActiveClient, useClientById(id).
- useClient now falls back to the registry's active client when no direct
<MeshProvider> is present, so existing hooks work unchanged under a
registry-backed app.
No web-facing changes in this commit; used by follow-up slice migrations.
