Advanced: split-package build target

For nearly all consumers the canonical install is the single @honua/sdk-js package described in INSTALL.md. The repository also carries an opt-in build target that produces five focused npm packages from the same source tree, for downstream packagers and organizations that only want a subset of the surface.

Packages produced by the split build

Package	Subpath equivalent	What it contains
`@honua/sdk`	`@honua/sdk-js/honua` + most stable subpaths	Core client, shared contract, query planner, offline-region contract, and plan-bound MapLibre adapter
`@honua/sdk-esri-compat`	`@honua/sdk-js/esri-compat`	Esri ArcGIS JS compatibility layer (incl. the `geometryEngine` shim)
`@honua/react`	`@honua/sdk-js/react`	React provider, hooks, and map components (optional `react` / `react-dom` peers)
`@honua/geometry`	`@honua/sdk-js/geometry`	Curated turf/proj4 client-side geometry ops + reprojection
`@honua/app-platform`	(evicted from `@honua/sdk-js`)	Application-platform surfaces — app-shell/workspace/scene state, studio + generated-app builder contracts, operator controllers, native controls / web components, and hosted-product clients (control-plane, collaboration, share, operate, replica-sync). See `decisions/scope-split-and-1.0.md`.

Companion packages that carry a copy of the contract declare the exact @honua/sdk version as a required peer. Their local contract forwards capability-profile recognition to that peer, so an immutable profile created by the core SDK remains valid across React, app-platform, geometry, and Esri-compat boundaries without exposing the profile-registration authority.

The migration package is no longer a generated SDK split. It is built from the honua-migrate repository, while @honua/sdk-js/migration remains a temporary forwarder. See the transition policy.

Optional gRPC-Web runtime

REST and open-protocol consumers do not install the Buf/Connect runtime. A consumer that selects transport: "grpc-web" must install the optional peers alongside the split SDK:

npm install @honua/sdk @bufbuild/protobuf @connectrpc/connect @connectrpc/connect-web

npm run verify:split-packages installs the generated package into a fresh consumer, opts into those peers, and executes a unary QueryFeatures call through the packed SDK's real protobuf adapter and Connect gRPC-Web transport. The deterministic in-process protocol fixture verifies request serialization, authentication headers, response framing, and response decoding without an external service. It does not replace live Honua Server conformance testing.

How to build the split tarballs

# from the repo root
npm install
npm run build
npm run build:split-packages
# tarballs land in dist/packages/* — npm pack each as needed
npm run pack:split-packages

Why the split exists

Some enterprise registries cap individual package size; the split keeps each tarball under that cap.
A downstream team can install only the focused SDK surface it uses.

When not to use it

If you are writing an application that consumes the Honua server directly, install @honua/sdk-js instead. The split packages are not the recommended consumer install — they exist for packaging workflows, not for end users.

The monolithic package root is a reviewed common workflow, not an alias for all split-package surfaces. Advanced imports use the focused subpaths in INSTALL.md; every transition-era root symbol has an exact replacement in the generated root import migration table.