Build one native target without pretending it is another.

Current development targets

The Android package currently has no native ABI payload; android-arm64 names its supported physical-device run profile. A published JavaScript provider does not establish that its matching native archive is available or that it has executed on the selected platform. See the Mac composition and host requirements.

1. Declare the exact target

Scaffold with the target, or add it to the canonical schema-2 app descriptor and validate it. A command-line target does not override a missing descriptor declaration.

npx arcane-os@latest new my-app --path ./my-app --target windows-x64 --git
cd my-app
npm install

Expected: the descriptor declares both browser and windows-x64 and includes the required raster application icon. Portable and Windows x64 use the installed SDK by default. Linux and Android retain their explicit compatible --arcane-root.

2. Diagnose the selected provider

native-doctor validates the selected provider and local prerequisites without creating a release artifact. Portable and Windows x64 select installed SDK providers by default. Windows assembly needs Node/npm and tar; execution needs Windows x64, .NET Framework 4.6.2 or later and WebView2 Runtime. Pass --arcane-root only when selecting a checkout-backed provider.

# Installed-SDK portable provider
npm exec -- arcane native-doctor --target portable

# Installed-SDK Windows provider
npm exec -- arcane native-doctor --target windows-x64

3. Build and run in one process

run owns the selected build and supported executable launch. The native provider retains the state required for that operation; tests and artifact verification remain explicitly selected work. Windows run cancellation closes input and waits for accepted service work and complete diagnostics to drain before exit. See the Windows artifact and lifecycle contract.

npm exec -- arcane run --target windows-x64 --output-root "../arcane-native-output"

# Linux x64
npm exec -- arcane run --target linux-x64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test

# Linux ARM64 on a compatible native ARM64 toolchain
npm exec -- arcane run --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test

# Android on a connected physical ARM64 device
npm exec -- arcane run --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development

4. Treat portable as a directory

The portable provider creates an app-scoped Core directory from the installed SDK. It intentionally has no executable run path, native bridge, product policy, or proof that an eventual composed host supplies the needed services.

npm exec -- arcane native-doctor --target portable
npm exec -- arcane build --target portable

Applications compose explicit services through the reusable Core runtime and host lifecycle. The browser Core client owns renderer transport and correlation, while the portable packaging contract defines the payload and the obligations of a real host.

5. Select the native services your app uses

The SDK supplies reusable services while the application owns its data and model choices. Use retained ONNX sessions for caller-selected graphs and complete named tensors, or Nemotron diarization for timed generic speaker labels from caller-fed mono audio. These APIs do not select a model or change browser AI defaults.

Local image generation retains a selected stable-diffusion.cpp model and returns every complete PNG through Core. Select the runtime and model in native.localAI; runtime installation, model preparation, loading and generation have separate lifetimes. The shared model-assets service projects complete stored files into native working files while preserving DBOPFS originals, then retains those files until the native engine actually releases them. The SDK composes both services for selected image requirements. CPU Windows/Linux and Mac Metal/CPU use their selected upstream runtime; actual execution and optional acceleration remain host-specific.

Whole-image editing uses that same selected context with the original PNG, complete prompt and explicit strength. The browser preserves the input and receives separate complete PNG results; the native model owns its documented preprocessing and alpha behavior. Applications retain originals and decide what to save.

The Core preferences service persists complete JSON values to an application-selected file and drains accepted writes. Git text snapshots read one fetched revision through a bare object cache without changing a working checkout. Compose services through native.services, include app-owned modules in package.nativeResources, and pass separate workspace/state locations at launch.

The built-in FLUX.2 Klein 4B selection prepares its diffusion model, complete VAE and Qwen text-conditioning resources together. Its four-step defaults advertise text-to-image generation; reference editing is a separate model/runtime capability. SDXL Base 1.0 selects one complete checkpoint with embedded text encoders and its original VAE, using the same retained generation lifecycle and a 1024-by-1024 default canvas.

The native speech service composes host-supplied STT and TTS engines with independent loading, role readiness and cancellation. It forwards complete requests and results and joins engine shutdown. Selecting whisper.cpp composes the SDK's persistent STT engine. Native assembly retains the matching helper, Whisper backend libraries, FFmpeg decoder and configured model files; the Windows helper includes its compiler/OpenMP runtime closure. Other platforms need their matching native resources. The selected model stays loaded across complete recordings, and an eligible accelerated failure can drain and retry the same recording once on the prepared CPU backend. Engine installation, actual model readiness and target-platform execution remain distinct.

Native repository workspaces resolve per-user ArcaneData/Repos locations and own an explicitly selected working checkout. Applications keep their chosen paths, remote and branch. Open, status, pull, push and joined shutdown preserve complete Git diagnostics and existing repository state; the shared module performs no user-data migration.

6. Keep app icons and window colors app-owned

The Windows launcher uses the app's displayName plus .exe, with a matching .exe.config; low-level compositions without a display name use the app ID. Windows filename substitutions preserve supported Unicode, case and spaces without changing the descriptor or title. Use manifest.host.executable for shortcuts and direct launch. Icon embedding, verification and the SDK runner use that recorded name; the generic downloaded host and internal Core executable remain unchanged.

The Windows provider uses native.icon from the app descriptor. PNG and ICO selections derive the copied app executable and its runtime icon while preserving the original asset and shared host cache. manifest.host.executableIcon and native.icon.completed/native.icon.unsupported report the actual assembly result. Other supported descriptor formats retain ordinary assembly; executable embedding and the host's image codecs have distinct capabilities. See the complete icon contract.

Shared ThemeBootstrap forwards the app's computed background and text colors through Arcane.window.setTheme(), independently of rendering and OS-user appearance. The host reports accepted and unsupported fields separately. Windows titlebar colors require the documented Windows version and matching host; ordinary browsers remain on their CSS path. npm availability, native archive delivery and actual host execution remain separate evidence.

7. Keep launch state and request cancellation explicit

The shared launch-context reader accepts --arcane-host-state-root as a stateRoot default for every service factory. Windows and Mac launchers forward the directory they actually selected. Every field in an explicit launch JSON object takes precedence unchanged, including stateRoot and an application-owned preferencesFile. The reader chooses no preference filename and performs no stored-data migration. Compiled launcher and matching archive delivery remain separate from this published JavaScript API.

The Core facade accepts Arcane.speech.synthesize(request, {signal}) and Arcane.speech.transcribe(request, {signal}) for per-request cancellation. Both preserve the complete request and existing timeout, release the cancelled request's correlation and leave unrelated calls active. AI.fetchTTS(payload, signal) and AI.fetchSTT(audio, signal) carry their signals through the native calls and report cancellation as AbortError with ARCANE_AI_REQUEST_ABORTED. Actual engine interruption belongs to the registered service. The shared native STT adapter correlates its already accepted request through unloaded recovery or pending error without treating either as readiness for another request. Genuine unload, close, replacement, transport loss and caller cancellation retain their owning lifetime.

Release-readiness principle

Verify the selected output at its actual boundary. A portable directory confirms payload assembly, not an executable host. A source check, browser package, or different architecture cannot substitute for the selected executable native artifact. Production installers, platform signing, and public release publication are separate release-system concerns.

• Descriptor target and command target match.
• Portable uses the installed SDK provider without --arcane-root.
• Windows and Mac assembly need the matching SDK host archive; Linux and Android use explicit compatible Arcane roots.
• Output root stays outside an integrated Arcane checkout.
• Build and run use the selected artifact and its owning provider.