@vizcrush/core

The entry point. @vizcrush/core initializes the library, detects what the runtime can do, picks the compute backend, and exposes the kernel machinery the algorithm packages build on.

You only need to call init() once per page — most other packages call it implicitly the first time you use them.

Install & import

import { init, detectCapabilities, selectBackend } from "@vizcrush/core";

init()

const ctx = await init();
// {
//   preferredBackend: "wasm" | "js", // preferred from runtime capability
//   backend: "wasm" | "js",          // deprecated compatibility alias
//   capabilities: {
//     webgpu: boolean,        // raw probes, for reporting only
//     wasmSimd: boolean,
//     wasm: boolean,
//     sharedArrayBuffer: boolean,
//   },
// }

preferredBackend is "wasm" when WebAssembly is available and "js" otherwise. It is a capability-based preference, not proof that a particular operation used that path: automatic size thresholds, per-call overrides, and package WASM loading still participate in dispatch. Use a kernel's withBackend() result when you need the requested mode, actual backend, and decision reason for a completed call.

backend remains as a deprecated alias for compatibility with 2.x callers. New code should use preferredBackend; the alias is scheduled for removal in the next major release.

The capabilities object reports the raw WebGPU/SIMD/SharedArrayBuffer probes, but those probes do not name distinct selectable default backends. The opt-in WebGPU path on @vizcrush/bin’s bin2d is requested per call, not selected here (ADR 0004).

detectCapabilities()

Probe the runtime without committing to a backend:

const caps = await detectCapabilities();
if (!caps.wasm) {
  console.warn("WebAssembly unavailable — vizcrush will run on the pure-JS core");
}

Note that webgpu, wasmSimd, and sharedArrayBuffer are informational probes only — they do not change the default capability preference. Passing +simd128 does not prove that a hot loop was vectorized: ADR 0002 found byte-identical SIMD/scalar LTTB binaries, differing aggregate binaries, and no measured speedup for either tested operation.

Detection is cheap and runs the same checks as init() internally. Use it if you want to gate UI features on backend availability before committing to load any algorithms.

selectBackend(capabilities)

Pick the best backend from a capability set:

const backend = selectBackend(caps);
// "wasm" if caps.wasm, else "js"

You rarely need this directly — init() does it for you. It's exported so you can audit the selection.

Typed arrays at the WASM boundary

vizcrush APIs operate on Float64Array (and Uint32Array for indices). wasm-bindgen performs one bulk copy into WebAssembly linear memory. Typed arrays avoid per-element boxing; they do not make a one-shot call zero-copy. See ADR 0001.

Type re-exports

For convenience, @vizcrush/core re-exports the result types used by other packages:

import type {
  Backend,
  Capabilities,
  VizcrushContext,
  DownsampleResult,
  BinResult,
  Bin2dResult,
  StatsResult,
} from "@vizcrush/core";

Each describes a typed-array result shape (for example, DownsampleResult = { x: Float64Array; y: Float64Array }).

When to call init()

• In a top-level module for vanilla apps: await init() once at startup, then call algorithm packages without worrying about backend.
• In a React app: use the useVizcrush hook — it caches the context across renders.
• In a Node script: same as vanilla apps — Node supports WebAssembly, so init() reports a wasm preference; individual calls can still select JS.

See also

• Backends & Capabilities — selection rules and how to override per call
• useVizcrush hook — React wrapper