#webnn-mbt

• add / sub / mul / div
• reduce_mean / gather / slice / concat
• matmul (rank 2 or higher, with batch-dimension broadcasting)
• conv2d (NCHW/OIHW and NHWC/HWIO)
• max_pool2d / average_pool2d
• sigmoid / tanh / gelu (the exact erf definition from the WebNN specification)
• layer_normalization
• clamp / relu
• softmax
• reshape
• transpose

#Quick start

moon add mizchi/webnn

import {
  "mizchi/webnn",
}

supported_targets = "js"

pub async fn add_bias() -> Array[Float] {
  let graph = @webnn.WebNNGraphBuilder::new(
    @webnn.DevicePreference::Npu,
  )
  let input = graph.input("input", @webnn.Shape::new([1, 2]))
  let bias = graph.constant(@webnn.Shape::new([1, 2]), [10.0, 20.0])
  let output = input.tensor().add(bias)
  let program = graph.compile_program_single(input, "output", output)
  defer program.destroy()
  program.run([1.0, 2.0])
}

#Requirements

• MoonBit 0.10.3 or later
• Node.js 24 or later
• pnpm
• just
• Google Chrome Canary

--enable-features=WebMachineLearningNeuralNetwork

#Running

just install
just check

just unit
just build
just e2e
just fixture-bert
just bench
just bench-mnist
just bench-mnist-cache
just bench-mnist-pool
just bench-named-io
just bench-tiny-cnn
just bench-transformer
just bench-attention
just bench-encoder
just bench-encoder-stack
just bench-bert-encoder
just bench-litert
just bench-tflite
just bench-tflite-runner-cache
just bench-mobilenet-v2

#Workspace

• . is the mizchi/webnn library module. Its packages live under src/.
• examples/playground is the repository-local mizchi/webnn-examples application module. It depends on the workspace copy of mizchi/webnn, owns benchmark and MNIST fixture code, and exposes the browser API used by Playwright.

import {
  "mizchi/webnn",
}

#CI

• MoonBit contracts: CI configuration contracts, moon fmt --check, moon check, 117 unit tests, and a release build
• WebNN Canary E2E: 72 WebNN end-to-end tests on Ubuntu 24.04 with Playwright's chromium-tip-of-tree distribution (Chrome Canary for Testing headless shell)

pnpm exec playwright install --only-shell chromium-tip-of-tree
WEBNN_BROWSER_CHANNEL=chromium-tip-of-tree just ci-e2e

just bench 64,128,256 10 30
just bench-mnist 1,16,100 10 30
just bench-mnist-cache 1,16,100 10 30
just bench-mnist-pool 1,2,4,8 256 10 30
just bench-named-io 64,1024,16384 10 30
just bench-tiny-cnn 1,2,4,8,16,32,64 10 30 nchw,nhwc
just bench-transformer 32,64,128,256 16 10 30
just bench-attention 32,64,128,256 16 4 causal 10 30
just bench-encoder 32,64,128,256 2 16 4 causal-padding 10 30
just bench-encoder-stack 1,2,4 2 16 64 4 causal-padding 10 30
just bench-bert-encoder 1,2,4 2 16 64 4 padding 10 30
just bench-litert 10 30
just bench-tflite 10 30
just bench-tflite-runner-cache 10 30
just bench-mobilenet-v2 3 10

#Design

model/Linear
    |
    v
tensor/TensorOps
    |---------------------|
    v                     v
backend/cpu          backend/webnn
eager execution      builds MLOperands
                          |
                          v
                    compile / dispatch / read

• mizchi/webnn: curated public facade for the primary inference contracts
• shape: shape validation and result-shape inference
• tensor: backend-neutral operation contracts
• model: backend-independent model definitions
• bert: Hugging Face named-tensor validation, dense-weight transposition, and conversion to BERT parameters
• backend/cpu: eager CPU implementation for differential testing
• webnn/raw: thin FFI over the WebNN JavaScript API
• webnn/compat: compatibility between Chrome's current deviceType API and the newer accelerated contract
• backend/webnn: symbolic tensors, compilation, program cache, execution pools, and tensor lifecycle
• examples/playground/src/app: focused consumer-side browser API adapters called from Playwright
• examples/playground/src/benchmark: setup and steady-state measurements with CPU/WebNN correctness comparisons
• litert: source-neutral IR for named tensors, float32 constants, and operation sequences, plus a TensorOps lowerer
• examples/playground/src/mnist: trained MLP weights, IDX loading, and CPU/WebNN evaluation and benchmarks

SelfAttentionConfig / TransformerEncoderConfig / TransformerEncoderStackConfig
                         + Parameters (owned float32 arrays per layer)
                         + AttentionMask
                                     |
                    |----------------|----------------|
                    v                                 v
@cpu.materialize_transformer_encoder_stack   builder.materialize_transformer_encoder_stack
                    |                                 |
                    v                                 v
TransformerEncoderStack[CpuTensor]     TransformerEncoderStack[WebNNTensor]

#BERT encoder loader

#Real TFLite fixtures

• micro_speech_quantized.tflite (18,800 bytes) is a real quantized RESHAPE → DEPTHWISE_CONV_2D → FULLY_CONNECTED → SOFTMAX model. Canary E2E covers raw INT8 I/O, INT32 bias, flattening from rank 4, and runtime caching.
• person_detect.tflite (300,568 bytes) is a quantized 96×96 grayscale person-detection CNN. It exercises normalization of rank-1 per-channel INT32 bias metadata that retains producer axis 3, zero-input raw INT8 I/O, and the compiled runtime cache.
• mobilenet_v2_1.0_224_inat_bird_quant.tflite (3,531,296 bytes) is a quantized MobileNet V2 classification model from Coral Edge TPU. Canary E2E covers parse/lower/compile without a delegate, raw UINT8 I/O, and cache hits.
• audio_preprocessor_int8.tflite (8,772 bytes) is a negative fixture containing the SignalWindow custom operator. It currently locks in the rejection message unsupported TFLite custom operator: SignalWindow.

#Browser API

• compatibilityMode()
• supportedOperators()
• probeWebnnCapabilities()
• runCpuLinear()
• runAdd()
• runConcat()
• runLinear()
• runLiteRtLinear()
• runTfliteAdd()
• runTfliteSub()
• runTfliteAddRelu6()
• runTfliteFullyConnected()
• runTfliteFullyConnectedRelu6()
• runTfliteConv2d()
• runTfliteReshape()
• runTfliteTranspose()
• runTfliteDepthwiseConv2d()
• runTfliteAveragePool2d()
• runTfliteMaxPool2d()
• runTfliteLogistic()
• runTfliteTanh()
• runTfliteQuantizedAdd()
• runTfliteQuantizedAddRaw()
• runTflitePerAxisInt8Raw()
• runTfliteReluN1To1()
• runTfliteRelu6()
• benchmarkLiteRtLinear(warmup, iterations)
• benchmarkTfliteFullyConnected(warmup, iterations)
• benchmarkTfliteSub(warmup, iterations)
• benchmarkTfliteDepthwiseConv2d(warmup, iterations)
• benchmarkTfliteMaxPool2d(warmup, iterations)
• benchmarkTflitePerAxisInt8Raw(warmup, iterations)
• runTfliteRunnerCachePerAxisInt8Raw()
• runTfliteRuntimeCachePerAxisInt8Raw()
• runTfliteCpuPerAxisInt8Raw()
• runTfliteRuntimeCpuFallbackPerAxisInt8Raw()
• probeTfliteRuntimePolicy()
• runMicroSpeechFixture()
• runPersonDetectionFixture()
• probeMobileNetV2Fixture()
• runMobileNetV2Fixture()
• benchmarkMobileNetV2Fixture(warmup, iterations)
• probeAudioPreprocessorFixture()
• probeTfliteRunnerCacheConcurrency()
• runTfliteRunnerNamedAdd()
• runTfliteRunnerTwoInputTwoOutput()
• benchmarkTfliteRunnerCachePerAxisInt8Raw(warmup, iterations)
• runTransformPipeline()
• benchmarkMatmul(size, warmup, iterations)
• benchmarkTransformerBlock(tokens, width, warmup, iterations)
• benchmarkSelfAttention(tokens, width, heads, maskMode, warmup, iterations)
• benchmarkTransformerEncoder(batchSize, tokens, width, heads, maskMode, warmup, iterations)
• benchmarkTransformerEncoderStack(layers, batchSize, tokens, width, heads, maskMode, warmup, iterations)
• benchmarkBertEncoder(layers, batchSize, tokens, width, heads, maskMode, warmup, iterations)
• runBertSafetensorsFixture()
• evaluateMnist(count)
• benchmarkMnist(batchSize, warmup, iterations)
• clearMnistCache()
• runMnistCached(batchSize)
• benchmarkMnistCache(batchSize, warmup, iterations)
• probeConcurrentProgram() (E2E probe for concurrent runs and deferred destruction)
• probeExecutionPool() (E2E probe for multi-slot assignment)
• benchmarkMnistPool(poolSize, requestCount, warmup, iterations)
• runNamedMultiIo()
• benchmarkNamedIo(size, warmup, iterations)
• runConvSoftmax()
• benchmarkTinyCnn(batchSize, warmup, iterations)
• benchmarkTinyCnnLayout(inputLayout, batchSize, warmup, iterations)
• runPreferredLayoutConv()

#Limitations

• Not every WebNN operator, data type, or dynamic shape is supported.
• The .tflite parser is limited to a single subgraph and ADD/SUB/MUL/DIV/MEAN/GATHER/SLICE/CONCATENATION/RELU/RELU_N1_TO_1/RELU6/LOGISTIC/TANH/SOFTMAX/FULLY_CONNECTED/CONV_2D/DEPTHWISE_CONV_2D/AVERAGE_POOL_2D/MAX_POOL_2D/RESHAPE/TRANSPOSE. GELU and layer_normalization are available in the generic IR/API but are not yet emitted by the TFLite parser. CONCATENATION supports negative axes, two or more inputs, and fused activations. UINT8 and INT8 require positive scales and zero points; constants are statically dequantized to float32 using either scalar per-tensor or shape-compatible per-axis quantization. Quantized INT32 is supported only for bias constants; int32 computation and runtime inputs are not supported. Fused activations are limited to NONE, RELU, RELU_N1_TO_1, RELU6, and TANH; SIGN_BIT is not supported. INT16 and FLOAT16 are not supported. Multiple subgraphs, control flow, and custom operators such as SignalWindow are not supported.
• conv2d supports NCHW inputs with OIHW filters and NHWC inputs with HWIO filters. Padding, stride, dilation, and groups are supported. Bias is expressed as an add with [1,C,1,1] for NCHW or [1,1,1,C] for NHWC. WebNNGraphBuilder.preferred_input_layout() reads opSupportLimits().preferredInputLayout to guide layout selection.
• The accelerated contract distinguishes only CPU from accelerated execution, so Npu maps to accelerated: true.
• Even when the current Canary implementation accepts deviceType: "npu", the WebNN API cannot confirm that Apple Neural Engine was selected.
• A native backend is intentionally outside this implementation. It may be added later as a Core ML or ONNX Runtime backend.
• The BERT loader covers encoder layers only. Embeddings, poolers, task heads, ONNX, and gelu_new are unsupported. The SafeTensors parser accepts only a single file containing F32 tensors with positive fixed shapes; F16/BF16, sharded indexes, and zero-sized tensors are unsupported.
• Execution pools share the same browser thread and WebNN context. Increasing pool size cannot exceed the concurrency available in the hardware/backend and increases per-slot tensor memory.
• In Canary 152, passing the same MLOperand directly under two output names caused the build to fail with Context is lost. Creating a distinct operand with reshape avoids the issue.

• WebNN specification
• SafeTensors format
• MoonXi Net
• Playwright browser channels