@desert-ant-labs/core

Shared JavaScript runtime for Desert Ant Labs on-device model SDKs. The per-model node packages (@desert-ant-labs/shapes, @desert-ant-labs/emo, @desert-ant-labs/redact, ...) build their browser and Node entries on these model-agnostic pieces, so each model ships only its payload codecs and its public class - both entry points are a couple of lines of wiring.

Not meant to be used directly; it is the common core the model packages depend on.

What it provides

Browser-safe entry (@desert-ant-labs/core, no node:*):

• createWasmSdk({ platform, packageName }) - the whole browser/WebAssembly half of a model package: instantiate the core through the package's #platform seam, set up the LiteRT.js session, then open(options) either downloads the model from Hugging Face or adopts the files a modelBaseUrl serves, and returns a ready LoadedModel.
• LoadedModel - a loaded model behind an opaque core handle: run(text, options, { deviceId }) returning an FfiReader, plus isDownloaded, flushTelemetry, and dispose. The same object on both runtimes, so a package writes its public class once. flushTelemetry waits for the license requests in flight. withCallGroup and the group call option are still accepted and have no effect.
• makeModelHostSeam() / makeLiteRtHost(...) - the model host a wasm core is instantiated with (dalModelHost in its generated Imports, from Sources/JSHost/Host.swift) and the LiteRT.js implementation of it: named-tensor createSessionFrom* / run with the correct dtype marshalling and LiteRT.js manual memory management. The seam is late-bound, so a core can instantiate before its session exists, and nothing is installed on globalThis.
• loadLiteRt(...) / assertBrowserRuntime(...) - load @litertjs/core once per process (with an install hint) and guard against running the wasm runtime in plain Node.
• fetchSelfHostedModel(baseUrl, files) - fetch the files a modelBaseUrl serves: sidecars keyed by catalog name, artifact bytes for the host to compile.
• browserSetup / browserWasmDir / browserReadModelSource / browserCacheRoot - the browser half of a model's #platform seam.
• The wasm ABI itself (create, createSelfHosted, isDownloaded, download, run, endCallGroup, destroy, flushTelemetry), the twin of the native dal_* symbols, is what BridgeJS generates from the @JS entry points in the model's Web/main.swift; its types live in the package's own generated dist/bridge-js.d.ts. Both setups return it, so a model package writes no wasm glue: options and results cross as FFIBuffer payloads it encodes with the codecs it already needs for the native entry.
• FfiReader / FfiWriter - big-endian cursor over the length-prefixed FFIBuffer payloads both cores speak (the JS counterpart of Kotlin's FfiReader).

Node entry (@desert-ant-labs/core/node, uses node:* + koffi):

• createNativeSdk({ here, packageName, modelId, coreName }) - the native half of a model package, mirroring createWasmSdk: binds the prebuilt core and returns an SDK whose open(options) yields the same LoadedModel.

• loadNative({ here, packageName, coreName, modelId }) - the loader under it: resolves the prebuilt Swift core under native/<platform>-<arch>, loads the LiteRT runtime first, binds the C ABI with koffi (generic dal_* calls plus the model's own <modelId>_create), and returns callAsync + decodeResult + cache-path helpers. SSR-safe node seam (@desert-ant-labs/core/platform-node, uses node:*, no koffi):

• nodeSetup / nodeWasmDir / nodeReadModelSource / nodeCacheRoot - the Node half of the #platform seam, reached when a framework renders the universal wasm entry in Node (Next.js's Client-Component SSR pass).

The two node entries stay apart on purpose. koffi ships native .node addons, and bundlers statically trace the require("koffi") inside the loader even though it only runs lazily, so a package's #platform seam importing /node makes an SSR build fail with Turbopack's "non-ecmascript placeable asset" (or webpack's equivalent). A model package imports /node from its /native entry only, and /platform-node from platform-node.js.

Audio models use the separate @desert-ant-labs/core/audio browser entry or @desert-ant-labs/core/audio/node on Node. Text-model imports never traverse the audio host or WAV codec.

@litertjs/core and koffi are optional peer dependencies: the browser path needs @litertjs/core, the native Node path needs koffi, and neither is required just to import the package.

Tests

mise run test:js        # unit tests + the SSR module-graph guard (no network)
mise run test:bundles   # the bundle matrix: real bundlers, real tarballs

The packages are isomorphic, so most of what can break lives in a bundler rather than in a function. Two layers cover it:

• test/ssr-graph.test.mjs walks the static import graph the way a bundler does and fails if the browser or SSR seam reaches koffi or a node: builtin. Fast, offline, runs on every change.
• test/bundle/ packs the core and every model package and builds them with esbuild, vite, webpack, and Next (Turbopack + webpack), plus plain Node imports of both entries. It reproduces consumer build failures exactly; see js/test/bundle/README.md.

License

Desert Ant Labs Source-Available License. Free for most apps, and a commercial license is required at scale. Full terms are at the link. Licensing: [email protected].

Third-party notices for the SDK: THIRD_PARTY_NOTICES.md.