Arcane OS SDK developer reference

This reference answers developer questions in this order:

1. What can the application or tool do?
2. What should I import or call?
3. What does a successful result look like?
4. Where does it run?
5. Only when needed: which transport, host, provider, or kernel boundary implements it?

The default path is capability-first. Transport and implementation detail is kept in the protocol and host architecture guide, and every high-level page links to the relevant deep section instead of repeating it.

Start with one working request

Install the SDK in your application:

npm pkg set dependencies.arcane-os=latest
npm install

The development declaration tracks the current latest channel. The lockfile and installed package record the exact version actually selected for the workspace.

For your first AI call, follow the TWiN Cloud quick start. For local models, native browser voices or cloud speech, follow the browser speech guide and the complete browser AI demo. Each guide names the application configuration you supply and shows the public call, response, cancellation, and error handling. Browser module imports use the SDK's managed import map; installing npm alone does not make bare module names resolve in a browser.

Reference map

Version scope and source ownership

This repository contains explicitly versioned surfaces with different owners:

Browser modules and reusable Core client/runtime/lifecycle source belong to the SDK. The portable provider uses this installed package by default and assembles an app payload with explicitly selected services; portable itself supplies no executable host. The Windows provider pairs that payload with the installed SDK version's precompiled WebView2/SEA release asset. Explicit Arcane OS provider overrides and integrated shared checks remain available. Arcane OS retains its product composition and policy. The historical Core reference snapshot describes a separate host contract; matching a protocol name or assembling a payload alone does not establish that a composed host supplies every required method or service.

See the Core reference source notes for the imported inventory and the distinction between a documentation snapshot and the selected runtime.

Installed documentation and release identity

The repository reference follows the current committed SDK capabilities. A documentation-only repository update can be newer than the text bundled in an already published package. The installed package includes the maintained docs/ tree and examples/wasm-ai-demo/ source alongside README and CHANGELOG. Open node_modules/arcane-os/docs/reference/README.md for the matching local reference. The generated website and test suites remain repository surfaces.

Read the installed version and current registry channel separately:

npm list arcane-os
npm view arcane-os@latest version

The changelog records changes by version; the GitHub releases identify the corresponding published package source. A newer website does not change the version installed in your application.

Generate the selected reference site

The existing node tools/build-reference-site.mjs --write command reads the live checkout. For release documentation while disjoint source work continues, select the reviewed documentation commit explicitly:

node tools/build-reference-site.mjs --write --source-ref <documentation-commit>

The same option is accepted by createReferenceSite({sourceRef}) and writeReferenceSite({sourceRef}). It reads the selected commit's package version, complete reference documents and inventories, the canonical docs/guides/native-whisper-openvino.md guide when present, inventory-selected runtime sources, and authored site inputs directly from Git in memory. It creates no checkout or export and leaves source drafts untouched. Rendering uses the current canonical generator and its authored semantic contracts; select a documentation commit whose contracts match the published package. Generated output still belongs to the canonical site/ tree and requires its usual coordinated output ownership. Generation does not publish hosted Pages.

For a selected release whose documentation correction lands after unrelated source, createReferenceSite({inputs}) and writeReferenceSite({inputs}) accept one explicit input owner with readText(relativePath) and listFiles(relativeDirectory). It is shared with the contract extractor. Keep package/runtime reads and document discovery on the release commit, and overlay only reviewed documentation records from the correction commit. In particular, preserve the selected inventory's member set instead of importing later public APIs. Omitted inputs preserves the live or sourceRef behavior above.

Historical 0.3.4 publication record

The following records describe that earlier release only. They do not identify the current registry channel or the package covered by this reference.

MDN-style page contract

Public reference entries follow the established Arcane documentation model:

• one canonical, mechanically readable inventory owns each public name;
• every public member or module has one guide entry headed by its exact name;
• each guide leads with an overview and the shortest safe working example;
• parameters, return values, errors, side effects, cancellation, and events are stated when they apply;
• availability is summarized near the call, while transport mechanics are folded into or deep-linked from the entry;
• normalized results are distinguished from provider- or platform-native envelopes;
• examples do not trigger destructive, privileged, expensive, or external actions merely by being copied.

Public runtime inventory

The public export map is maintained in package.json. It includes Node tooling, focused portable/browser entrypoints, direct runtime module and entity patterns, eight JSON Schemas and package metadata. The SDK member reference and package inventory describe focused functions; the runtime catalogs document the existing namespaces exposed through lowercase aliases and filename-based imports. Resolving a package name in Node does not supply browser, media, storage or Core capabilities. See the availability matrix.

The seven update-check records are explicit on-demand checks; they do not poll, download, install, or self-update.

The synchronized browser payload exposes:

• JavaScript modules under runtime/arcane/modules/, including ESM modules, classic vendor globals, one worker protocol, and one Node-oriented mail transport;
• shared entity modules under runtime/arcane/entities/;
• reusable HTML-import components under runtime/arcane/components/;
• shared CSS artifacts, images, optional physical-workspace security files where present, and the vendored strong-type dependency.

The module and component catalogs enumerate every shipped artifact, including vendor support files that are not ESM imports. The selected runtime directories and their current source inventories remain authoritative; the catalogs explain what those artifacts let a developer do.

Normalized AI

A speech-only interface explicitly passes null for both the first and fourth AI constructor arguments: new AI(null, 'LOCAL_SPEACH', 'LOCAL_SPEACH', null, ttsModel, sttModel). This leaves the LLM unselected from construction; omitted or empty arguments retain their historical defaults. See native speech startup.

Portable applications start with the provider-neutral runtime rather than an Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:

There is no automatic local-to-cloud, browser-to-Core, provider-to-provider, or storage fallback. Tool calls remain structural data until application-owned policy and code decide whether to execute them. App prompts, model defaults, profiles, tools, business policy, and private data remain app-owned.

An explicitly selected but unloaded model is not “ready.” chat.html keeps Send disabled and exposes a visible keyboard-operable LLM Start/Try again or Cancel loading control. speech.html and voice-transcription.html keep their recording operations unavailable and share the equivalent Start transcription/Try again/Cancel loading control for STT. Applications can override requestAIActivation(intent) or requestSTTActivation(intent), or cancel the corresponding activation-request event. Imports and state observation emit no lifecycle intent, and default startTranscription=false does not request an STT startup load or begin an automatic model download. It does not unload a role started independently. Reported availability never creates ready STT/TTS state without an admitted, loaded provider. Shared STT cancel/destroy propagates an owned signal, and TTS Mute/Unmute updates the shared lifecycle owner. The selected local TTS provider/model catalog owns its default voice; a saved OpenAI-route voice is not forwarded to Core or browser speech.

Authority and feature detection

The presence of a JavaScript function is not permission to use it. Native applications should inspect Arcane.capabilities.list() where available and then call the relevant status method. Android callers with system.read obtain the nested capability snapshot through Arcane.platform.status().

Do not infer local-AI readiness from Arcane.runtime.current().managedLocalAI, infer authorization from a transport name, or treat an Ollama model inventory as package admission. Each method rechecks native policy at invocation time.

Source and licensing

• SDK runtime source
• AGPL license
• Commercial-license notice
• Third-party and distribution notice