Availability and normalization

Use this page to choose an API by capability. The compact labels tell you where it runs; the protocol guide contains the implementation detail.

Shared type predicates

SDK-owned JavaScript uses the declared strong-type dependency for type predicates. Node and managed renderer modules import Is from strong-type; browser providers and workers use their shipped relative dependency path. Component scripts import it within their own asynchronous component scope. Publication bootstrap tools import the shipped runtime dependency by relative path so they remain available before npm dependency installation. The dependency pin and both shipped projections use 2.0.1. Update them together through the published dependency workflow when another version is needed.

Reuse one non-throwing instance per module or component:

import Is from 'strong-type';

const is=new Is(false);

function requireText(value){
    if(!is.string(value))throw new TypeError('Text is required.');
    return value;
}

The predicates classify values without coercing them. Existing API owners keep their defaults, domain constraints, complete payloads, and public error behavior. Use number for primitive numbers, finite for finite numbers, and integer or safeInteger for the corresponding integer contract. object includes null; retain a contract's separate null and array handling. plainObject is narrower than a general non-array object check and must not silently reject previously accepted class instances.

Constructor identity checks, diagnostic type labels, foreign-language source, and isolated generated script bodies retain native operators where a replacement would change their contract or execution scope. DBOPFSWorker.js and SystemPlatformPresentation.js retain their few native predicates to preserve classic-script loading and synchronous availability. Upstream dependency source is consumed unchanged. Non-throwing strong-type array and constructor probes return false when a probe throws; SDK branching continues through its owning error path.

Availability labels

“Available” never means “authorized.” App grants, method allowlists, host policy, package-owned model policy, platform support, and dependency readiness are independent checks.

Windows x64 and macOS ARM64/x64 have SDK-owned provider and host composition source. Their assembly paths require the matching numeric release's native host archive; npm publication alone does not supply that archive or establish platform execution. The macOS provider composes AppKit, WebKit and the shared Node Core payload. Linux and Android retain their explicit checkout providers where listed. See native output and host requirements.

Capability-first matrix

The normalized application path

For ordinary cross-platform application code:

const runtime = globalThis.Arcane?.runtime?.current?.();

if (!runtime?.connected) {
    throw new Error('Open this application through an Arcane host.');
}

const access = await globalThis.Arcane.capabilities.list();

if (!access.methods.includes('localAI.status')) {
    throw new Error('This application is not admitted for local AI.');
}

const status = await globalThis.Arcane.localAI.status();
console.log(status.ready, status.models);

This code does not select WebView2, WebKitGTK, or an HTTP bridge. It calls one Arcane API. The host chooses its transport, and Core applies the bound application identity and method policy.

Normalization levels

Fully SDK-normalized

The Node toolchain uses ArcaneError, stable SDK error codes, structured arcane-cli-events/1 records, and normalized target descriptors. Platform providers can add complete target detail but cannot silently substitute a different target or artifact kind.

The central EventManager is also host-neutral JavaScript. Its synchronous live bus preserves listener argument identity, while its optional history owns a separate diagnostic normalization boundary: snapshots are complete, redact credentials and explicitly protected private fields, and are importable as arcane-event-stack/1. DOM instrumentation adds browser diagnostics only; it does not replay browser state. See EventManager and time-travel review.

Browser-local provider adapter

arcane-os/ai/browser-wasm exposes the same provider-neutral lifecycle used by createArcaneAI(), while its packaged Wllama engine and caller-supplied model run inside the browser. This surface does not require an Arcane Core method grant because it does not call a Core host. Browser Fetch, CORS, storage policy, secure-context behavior, and resource limits still apply.

The browser runtime defaults to full GPU offload (gpuLayers:99999). Explicit loadDefaults:{gpuLayers:0} or load({gpuLayers:0}) selects CPU and skips WebGPU requirements and adapter work; GPU failure never selects CPU implicitly. Both routes wait for Wllama to report the complete model loaded. navigator.gpu presence by itself is not readiness. On the GPU route, the provider emits the instrumented arcane.ai.browser-wasm.webgpu.adapter.selected capability event after adapter selection.

localOnly:true describes inference after load; it does not promise that load is offline. A normal cache miss downloads from the exact caller-supplied HTTPS URL. App, provider/model-binding, and load-operation options may use {security:{secure?:boolean}}. The SDK default is secure:false, and omitted security leaves ordinary model loading fully functional. Download byte counts, remaining bytes, rate, and ETA are observational progress only. Optional member bytes values may initialize progress and HTTP Range planning, but neither declared nor observed byte measures validate, admit, identify, hash, or decide cache reuse for model content. Completed split members and deterministic Range parts within any member are retained across an interrupted install so retry fetches only missing work. Exact part length is used only to recognize a completed HTTP transport frame. Zero-length whole entries and incomplete Range sets cannot become cache hits; failed or incorrectly framed active parts are removed. After a complete current representation exists, the store attempts to remove redundant Range fragments; cleanup failure is warned without hiding the usable model. Optional secure:true records intent only; historical checking remains disabled until a separately authorized user review. Successful Wllama model loading remains mandatory. load({offline:true}) permits only a compatible cache entry and otherwise rejects with ARCANE_AI_MODEL_OFFLINE_MISS. Tool calls are result data for application review and dispatch; every declaration and emitted call requires nonempty user-facing arguments.message, and the SDK never executes them. An ordered assistant call array remains pending until the application records exactly one matching executed, declined, cancelled, or not-executed role:'tool' result with nonblank user-facing content for every pending ID in one atomic batch. The direct browser provider and its v1-to-provider/2 adapter validate the same request history, declarations, and terminal structural-call contract. Structured completions contain exactly one top-level message or choices envelope, every choice is validated, and the ordinary stream iterator exposes complete content and reasoning projections from every choice in provider order while its private pump continues even when the terminal result is awaited first. Structural deltas remain private until validation; terminal-only calls are valid, while observed calls must preserve their choice, order, identity, exact arguments, and extension fields at settlement. Complete provider chunks and terminal envelopes remain available through explicit data, response, or inspection surfaces.

arcane-os/ai/browser-speech implements the sibling stt and tts provider/2 roles. Each caller-selected Whisper or Kokoro provider has its own load, use, cancellation, unload, dispose, cache, Worker, status, and error state. The SDK supplies neither speech adapter runtime nor model/voice content; every selected file is application-owned and stored through the SDK-created DBOPFS adapter.

Both speech roles default to device:'auto': try webnn-npu when navigator.ml.createContext exists, then exposed WebGPU, then WASM. A failed backend load releases its Worker/session pool before a fresh pool tries the same prepared model and precision on the next backend. Explicit webnn-npu, webgpu, or wasm selects only that backend. Whisper accepts exactly one Worker/session. Kokoro defaults to maxConcurrentRequests:4 and accepts one through four; its FIFO queue preserves later requests while those slots are occupied.

For high-level speech, read ai.providerRuntime.status(role, {execution:true}).execution for stt or tts after load. Both report requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount. selectedDevice is null while unloaded and identifies the successful session backend after load. WebNN may use WASM for unsupported operations, so that field does not establish that every operation ran on a physical NPU. The default status() remains the sticky lifecycle snapshot; execution is an explicit provider read, and inspection errors propagate. Neither state proves physical GPU kernel overlap. See the copyable speech quick start.

Materialized speech graphs use their file inventory as a routing table, not an admission policy. Known downloaded imports, fetches, Workers, and cache reads route to their materialized URLs; unmapped operations fall through to the native browser API with caller options preserved, and native cache writes are not disabled.

The projected AIProviderRuntime normalizes those browser providers and can admit an externally supplied native or cloud provider/2 adapter. AI.js also supplies built-in adapters for an already-selected TWiN Cloud LLM route, Ollama route, or admitted local Core speech route. Application-selected Web Speech recognition, Web Speech synthesis, and TWiN Cloud/FAL synthesis can be registered through ai.configureSpeechProvider(role,provider,{modelId}); configuration owns only the selected role and performs no network request. Saved selections remain application-owned, including selections waiting for provider registration. The SDK supplies reusable Core client/runtime/service-lifecycle primitives and portable payload composition; privileged execution stays in a native host. It supplies no application credential, selected model or product speech-service authority. Capability-only built-in adapters report their existing routes without probing, downloading, or changing providers. The sticky AIRuntimeState surface keeps application UI independent of transport. A selected route remains explicit: browser failure is not permission to invoke Core or cloud.

Arcane bridge-normalized

Core-backed calls return promises and reject with Arcane.Error. Transport selection, request correlation, JSON framing, capability denial, diagnostics, and public operation events are normalized at the bridge. Method data contracts remain authoritative; a method that documents platform-dependent fields is not silently widened into a fictional common shape.

Helper-normalized

Renderer helpers can deliberately collapse provider detail. For example, ollama.chatText() returns a string extracted from the final chat envelope and ollama.generateText() returns a string extracted from the final generation envelope. ollama.readiness() returns a frozen {ready, version, errorCode} snapshot.

Provider-native within an Arcane boundary

arcane-os/ai/twin-cloud accepts an explicit twinKey and model, with the same named fetchRequest import in Node and managed browsers. It preserves complete provider response JSON while mapping the supplied structured-output, tool, and reasoning options to the TWiN wire contract. The SDK adds no output cap or persisted context. Cancellation applies during request, body read, overload retry wait, and callback settlement. The existing profile-backed browser AI.js entry and its lifecycle remain separate.

Direct Arcane.ollama.chat(), generate(), show(), embed(), and lifecycle methods return complete Ollama-compatible envelopes. Arcane still owns error normalization, chunk correlation, and host transport, but it does not rename every provider response field. Feature-detect optional Ollama fields and use the high-level helpers when an application needs a smaller common contract.

Platform-dependent by design

Host service settings, machine evidence, permissions, installation state, and native build artifacts can differ between Microsoft NT, Linux, Android, and a development browser. Those methods provide a stable outer contract and mark platform-specific fields or unsupported states. supported: false is a valid result where documented; it is not permission to bypass the host from renderer code.

No implicit protocol or provider fallback

Arcane can expose the same method over different host transports, but it does not reinterpret a failed native call as authorization to send data to a cloud provider. Provider selection is explicit application/user profile state. A remote or development HTTP bridge transports an admitted Arcane call; it is not an automatic OpenAI fallback and does not turn a standalone browser into a native host.

Deep details: protocol selection and host boundaries.