Arcane OS SDK JavaScript API

The npm package exposes a Node.js ESM control plane, the portable arcane-os/event-manager, arcane-os/logging, arcane-os/mail, arcane-os/preference-store, arcane-os/speech-playback, arcane-os/websocket-client, arcane-os/speech-text, arcane-os/ai/tool-text-stream, arcane-os/ai/twin-cloud, and arcane-os/browser-device entrypoints, and the browser-only arcane-os/pwa, arcane-os/ai/browser-wasm, and arcane-os/ai/browser-decisions entrypoints. The arcane-os/ai/browser-speech entrypoint includes local and native browser providers plus a cloud TTS adapter usable in Node with Fetch and Blob. The arcane-os/modules/<filename> and arcane-os/entities/<filename> paths resolve directly to the existing runtime files, with their actual extension. They are public Node package exports and managed browser keys, without a wrapper. For example, import.meta.resolve('arcane-os/modules/WaitForComponent.js') retains the module directory needed to resolve ../components/modal.html. Lowercase runtime subpaths also expose existing module namespaces through both Node package exports and managed browser imports, as listed below. Established browser names such as arcane/AIProviderRuntime, arcane/AIRuntimeState, and arcane/ThemeBootstrap remain compatibility names in physical/nested maps; direct-installed root maps use the package namespace instead. Applications call globalThis.Arcane for capability-gated host behavior.

This page documents the focused package APIs. The same binding can appear at the root and a focused subpath; those entrypoints are listed together. Direct runtime-module aliases and filename patterns expose the complete namespaces in the runtime module and entity catalogs. The root workspace discoverApps and low-level packager discoverApps are separate functions with separate records.

Import map

This table is the Node package.json#exports map: it defines package entrypoints for SDK/tooling code. It is distinct from the generated browser import map that resolves application-facing arcane-os/* names for root/direct layouts and arcane/* compatibility names for physical/nested layouts. See browser runtime delivery for the shared browser destinations used by installed-package and physical runtime layouts.

These lowercase runtime-module entrypoints expose their existing exports; they do not duplicate the module implementations or change their platform and lifecycle requirements. Node resolves them inside the installed package, while the managed browser map resolves the same names to the selected runtime URLs. Node package resolution does not make browser-only operations available in Node: a module still needs its documented browser globals, storage, media, Worker, or host capabilities when its initialization or operation uses them. Use arcane-os/mail for the existing Mail aggregation rather than importing a private runtime file. Its package facade and managed browser entry both expose the canonical MailApi.mjs aggregation and the same Mail, outbox, and transport bindings.

Eight JSON schemas and package.json are data-only export subpaths. In Node ESM, import JSON with with {type: 'json'}, or resolve and read it explicitly.

Managed AI narration

Root applications import AI through arcane-os/ai in the managed browser map. ai.prepareTTSPlayback(payload,signal) silently prepares real Blob audio or a native speech descriptor for playback. Native browser voices expose no audio file; use this path or shared streaming/SpeechPlayback for native output. ai.prepareTTS({parts,storage,identity,textFormat,signal,onState}) prepares complete punctuation segments without playing them and optionally saves/reuses their audio through application-owned DBOPFS. Its immediate handle exposes ordered segments, preparation state, ready, getAudio(index), and cancel(). ai.playPreparedTTS(prepared,{signal,onState}) attaches ordered playback and returns state, error, finished, pause(), resume(), and stop(). Each preparation owns its pending activation interest. Cancelling the final interest aborts that activation; other preparation, playback or joining direct TTS-load interests preserve it. Cancelling after readiness leaves the model loaded, and complete cache hits start no model. Actual cleanup is provider-owned. Each AI has one playback lane; replacing playback preserves independent preparation. Fully cached replay does not load the speech model. See prepared narration for complete inputs, storage ownership, progress, errors, and cancellation, and AI.js for the managed runtime contract. These are AI instance methods, not new npm export names.

Complete synthesis calls can select textFormat:'plain' to preserve supplied speech text, including repeated formatting marks and surrounding whitespace. This applies to ai.fetchTTS(payload,signal), audio-file preparation through ai.prepareTTSPlayback(payload,signal), durable ai.prepareTTS(...), provider runtime TTS requests and direct Kokoro synthesis. The SDK consumes the control before engine dispatch; durable preparation retains the existing punctuation segmentation. Omitted or other values retain automatic speech cleanup. Streaming streamTTS, finishTTS and shared SpeechPlayback retain their automatic cleanup; this option does not change upstream engine capacity. See exact complete synthesis input.

Shared operation contract

High-level operations accept one options object. Common fields are workspaceRoot, appId, target, signal, and onEvent; only fields meaningful to that operation are consumed. Long work acknowledges first, owns its child tasks, keeps event delivery ordered and backpressured, emits progress or heartbeats, observes cancellation where safe, and rejects with ArcaneError on failure.

One invocation selects one workspace, app, operation, target, architecture, format, and output root. No API silently loops over all apps or targets.

Protocol mechanics are intentionally kept in the deep protocol guide. The compact availability and normalization sentence beneath each member is the normal application-facing view.

Canonical member inventory

memberCount in inventory/package-api.json counts the authored focused API records below. Shared bindings retain their entrypoints together. Runtime aliases and filename patterns are documented in Runtime modules and Runtime entities. The remaining data-only subpaths are eight JSON Schemas and package metadata.

Packaging and release bundles

APPBUNDLEDESCRIPTOR_NAME

Overview

Canonical descriptor filename stored in an external application release bundle.

Value and import

const APP_BUNDLE_DESCRIPTOR_NAME

Import it from arcane-os or arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_DESCRIPTOR_NAME} from 'arcane-os';

console.log(APP_BUNDLE_DESCRIPTOR_NAME);

APPBUNDLEEXTENSION

Overview

Required filename extension for deterministic external application release bundles.

Value and import

const APP_BUNDLE_EXTENSION

Import it from arcane-os or arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_EXTENSION} from 'arcane-os';

console.log(APP_BUNDLE_EXTENSION);

APPBUNDLEFORMAT

Overview

Canonical archive encoding used by external application release bundles.

Value and import

const APP_BUNDLE_FORMAT

Import it from arcane-os or arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_FORMAT} from 'arcane-os';

console.log(APP_BUNDLE_FORMAT);

APPBUNDLEKIND

Overview

Stable manifest kind identifying an Arcane application release bundle.

Value and import

const APP_BUNDLE_KIND

Import it from arcane-os or arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_KIND} from 'arcane-os';

console.log(APP_BUNDLE_KIND);

APPBUNDLEMANIFEST_NAME

Overview

Canonical bundle-envelope manifest filename.

Value and import

const APP_BUNDLE_MANIFEST_NAME

Import it from arcane-os or arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_MANIFEST_NAME} from 'arcane-os';

console.log(APP_BUNDLE_MANIFEST_NAME);

APPBUNDLERELEASE_PATH

Overview

Canonical path of the packaged release manifest inside a bundle payload.

Value and import

const APP_BUNDLE_RELEASE_PATH

Import it from arcane-os or arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_RELEASE_PATH} from 'arcane-os';

console.log(APP_BUNDLE_RELEASE_PATH);

APPBUNDLESCHEMA_VERSION

Overview

Current immutable bundle-envelope schema version.

Value and import

const APP_BUNDLE_SCHEMA_VERSION

Import it from arcane-os or arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_SCHEMA_VERSION} from 'arcane-os';

console.log(APP_BUNDLE_SCHEMA_VERSION);

APPBUNDLESUPPORTEDSDKVERSIONS

Overview

Exact SDK generations accepted by this bundle verifier.

Value and import

const APP_BUNDLE_SUPPORTED_SDK_VERSIONS

Import it from arcane-os/release-bundle. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_BUNDLE_SUPPORTED_SDK_VERSIONS} from 'arcane-os/release-bundle';

console.log(APP_BUNDLE_SUPPORTED_SDK_VERSIONS);

APPCONFIGNAME

Overview

Canonical schema-1 application package configuration filename used by the packager.

Value and import

const APP_CONFIG_NAME

Import it from arcane-os/packager. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {APP_CONFIG_NAME} from 'arcane-os/packager';

console.log(APP_CONFIG_NAME);

bumpVersion()

Overview

Updates the authored arcane-package.json version for one selected application. This is a development-time metadata operation. It never updates the Arcane SDK, the synchronized runtime, an installed application, or an Arcane OS host.

Signature, parameters, and result

async bumpVersion(options)

Import it from arcane-os/packager. options.workspaceRoot and options.appId select one configured app. Supply exactly one of bump ("major", "minor", "patch", or "prerelease") and exactVersion; preid customizes a prerelease bump and defaults to "rc". dryRun defaults to false.

The promise resolves to {app, currentVersion, version, bump, dryRun}. bump is null when an exact version was selected. A dry run validates and calculates the result without writing or acquiring the operation lock. A non-dry run acquires the selected app's packager lock under dist/, then atomically replaces only its arcane-package.json version through temporary and backup files.

This function has no signal, onEvent, or receipt parameter: once started it has no public cancellation or progress-event contract. It rejects invalid or unchanged versions, conflicting bump/exactVersion inputs, an invalid workspace/app, an active or stale packager lock, and filesystem failures. The lock is released in finally; an unrecoverable replacement failure can leave the documented backup file for manual recovery.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {bumpVersion} from 'arcane-os/packager';

async function previewNextPrerelease(workspaceRoot) {
    const result = await bumpVersion({
        workspaceRoot,
        appId: 'example-app',
        bump: 'prerelease',
        preid: 'beta',
        dryRun: true
    });

    console.log(`${result.currentVersion} -> ${result.version}`);
    return result;
}

createAppReleaseBundle()

Overview

Writes one deterministic USTAR+gzip external application bundle from the selected authored release state. Long or non-ASCII filenames use per-file POSIX PAX path extensions, preserving their complete UTF-8 spelling and file content. Ordinary USTAR entries remain unchanged. Metadata framing is excluded from the manifest's logical file inventory. Existing portable-path rules, schema 1, and the ustar+gzip format identifier remain unchanged.

Signature and result

async createAppReleaseBundle({releaseRoot, appDescriptor, outputPath, overwrite=false, signal, onEvent}={})

Import it from arcane-os or arcane-os/release-bundle. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {createAppReleaseBundle} from 'arcane-os';

async function usecreateAppReleaseBundle(...arguments_) {
    return createAppReleaseBundle(...arguments_);
}

createCanonicalUstarHeader()

Overview

Builds the exact 512-byte canonical USTAR header for one validated bundle entry. This low-level helper remains a single regular-file header with the USTAR field limits. Use createAppReleaseBundle() to encode complete long or Unicode paths; the bundle writer supplies PAX framing where needed.

Signature and result

createCanonicalUstarHeader(entryPath, size)

Import it from arcane-os or arcane-os/release-bundle. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {createCanonicalUstarHeader} from 'arcane-os';

async function usecreateCanonicalUstarHeader(...arguments_) {
    return createCanonicalUstarHeader(...arguments_);
}

discoverPackagerApps()

Overview

Root-entry alias for the packager-specific application discovery function.

Signature and result

async discoverPackagerApps({workspaceRoot:requestedWorkspaceRoot})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {discoverPackagerApps} from 'arcane-os';

async function usediscoverPackagerApps(...arguments_) {
    return discoverPackagerApps(...arguments_);
}

incrementSemver()

Overview

Returns a validated semantic version incremented by the requested bump and optional prerelease id.

Signature and result

incrementSemver(value, bump, preid)

Import it from arcane-os/packager. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {incrementSemver} from 'arcane-os/packager';

console.log(incrementSemver('1.2.3', 'minor'));

inspectApp()

Overview

Loads one validated packager app plan, including the shared directly navigable descriptor-selected browser document inventory.

Signature and result

async inspectApp({workspaceRoot, appId, signal, target, outputDirectory}={})

Import it from arcane-os or arcane-os/packager. The result includes the configured entry, include, and exclude values, the optional documents declaration when authored, and browserDocuments, the entry-first ordered .html/.htm paths shared by import-map refresh, development and packaging. package.documents in an authored descriptor, or documents in a schema-1 package, selects literal app-root-relative paths already included and not excluded. Other selected paths follow the entry in deterministic lexical order without duplicates. The authored documents declaration remains as supplied, including [], which selects only the entry. Omitting the property retains automatic discovery of the entry and included secondary pages with an active <base>. App identity meta tags do not select documents.

Selected pages retain their existing base requirements. Explicit selection leaves other included HTML documents unchanged, including iframe-referenced originals, while preserving package, serving and offline resource membership. Component processing and shared runtime-resource traversal retain their existing behavior. See application document selection.

entry and each app browser document's path stay relative to the app directory. Each browser document also reports packagePath, the emitted path such as apps/hello-world/index.html. The complete files inventory uses package-relative paths and includes the root index.html. Shared files retain their configured route destinations.

target defaults to 'browser'. A selected nonbrowser target adds the app's explicit nativeResources to files, without adding those native-only paths to browserDocuments. The optional normalized nativeResources record is returned when authored. This inspection copies or executes no resources.

output is the selected workspace-relative final package directory. An explicit operation outputDirectory wins. Otherwise, a nonbrowser target with a nonempty native include list uses dist/.native/<target>/<app-id>; the app's saved browser destination remains separate. Browser selection, omitted native resources and an empty native include list use the app's saved outputDirectory or dist/<app-id>. The SDK appends no app ID to an explicit destination. See native-only application resources.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {inspectApp} from 'arcane-os';

const plan=await inspectApp({workspaceRoot:process.cwd(),appId:'hello-world'});
console.log(plan.browserDocuments);

normalizeRelativePath()

Overview

Normalizes one portable repository-relative path and rejects traversal, aliases, links, and unsafe names.

Signature and result

normalizeRelativePath(value, label='path')

Import it from arcane-os/packager. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {normalizeRelativePath} from 'arcane-os/packager';

console.log(normalizeRelativePath('apps/example/index.html'));

packageApp()

Overview

Builds one complete selected application release through the low-level packager API, with browser selection by default. It does not run tests or checks automatically; verification occurs only when explicitly requested or when required for this selected release output.

Signature and result

async packageApp(options)

Import it from arcane-os or arcane-os/packager. Packaging consumes the saved source and managed import maps. Refresh maps through arcane import-map or ordinary arcane dev startup before selecting output that needs updated maps. The package preserves the complete selected content, applying the documented asset-version and enabled browser-PWA transformations to resource references. Malformed configuration or descriptors fail while preserving the prior output.

target defaults to 'browser'; supported target names are browser, portable, windows-x64, linux-x64, linux-arm64 and android-arm64. A nonbrowser target adds the app's explicit nativeResources selection and sets the effective browserPwa value to false. It does not compile or launch that platform. Browser calls preserve the existing browserPwa default and explicit setting. The app adapter's buildArcanePackage() context receives the actual target and effective browserPwa alongside its existing fields. copyBase() retains the browser/shared selection; native-only resources are copied afterward, outside browser rewriting and PWA processing.

moduleFormat controls browser module representation independently of target. In particular, moduleFormat:'native' alone remains a browser package and does not add native resources. The complete selection and separate-output rules are documented under native-only application resources.

moduleFormat defaults to 'import-map', preserving the ordinary browser package. Select 'native' to resolve saved document import maps into native module URLs in the package stage and emit executable inline scripts as external files. Static imports, re-exports, string-literal dynamic imports and string-literal import.meta.resolve() retain exact/prefix/scoped mappings. Imported HTML components use the shared HTMLImport externally executable script path, retaining their host binding and asynchronous lifecycle. No application-owned module loader is needed. Source HTML, saved data and the ordinary browser output remain unchanged. See native-module package output for resource handling and the static transformation boundary.

browserDecisions defaults to false. Explicit browserDecisions: true acquires the bundled Transformers.js 4.3.0 entry, matching ONNX Runtime 1.31.0-dev.20260914-8d85527a0 asyncify module/WASM and both licenses into the package stage beside the selected SDK ai/browser-decisions.mjs, under decisions-runtime/. Installed-package routes retain their configured dependency path, including aliases; source and installed dependencies remain unchanged, with no workspace-root arcane/ projection. The selected SDK decision module must be included in the package. Acquisition happens after native-module and asset rewriting, preserving upstream content unchanged in both module formats. The distribution joins the returned and release-manifest inventories and any enabled PWA's ordinary offline selection. The default and dry runs perform no optional acquisition; dry runs report selected inputs. Repeat this option on each package build that should acquire the closure. Cancellation and HTTP or observer failures abort/join acquisition before stage cleanup and preserve previous output. The existing workspace.decisions.started and workspace.decisions.progress events report file progress. See the extension-local decision guide for runtime.local: true, upstream versions and complete error details.

An operation may override outputDirectory without changing the saved app configuration. For example, package a complete application beneath an application-owned extension manifest and launcher:

const release = await packageApp({
    workspaceRoot,
    appId: 'moon-dashboard',
    outputDirectory: 'dist/extension/app',
    moduleFormat: 'native',
    browserPwa: false
});

The override uses the same workspace-relative destination and staged replacement rules as the saved field. It replaces only dist/extension/app, leaving its extension-root siblings and an existing browser output intact. browserPwa:false omits generated PWA artifacts and removes their active references from selected output documents before native-module processing. This removes SDK-marked data-arcane-pwa scripts and manifest relationships resolving to the package's arcane.webmanifest, preserving unrelated authored links and inactive HTML. It does not change source documents or the app's saved PWA configuration. The app owns extension metadata, permissions and toolbar launch behavior. This API builds the application directory, not an extension manifest or an operating-system launcher. Native-mode dry runs report selected input files; generated script/context files are included in the completed package's full returned inventory.

For browser selection, the app's optional schema-1 outputDirectory selects the final workspace-relative destination. For example, "ai" emits directly into <workspace>/ai; omission retains dist/<app-id>. The selected directory is wholly replaced through the existing staged swap, not merged. Changing the destination preserves the former output and siblings. Conflicting source, selected input, or required control paths fail before output writes. Source layout, app identity, OPFS scope, and internal package paths remain unchanged. See app-selected package output.

For a nonbrowser target with a nonempty native include list, the default is instead dist/.native/<target>/<app-id>, preserving a separately emitted browser output even when its saved destination is custom. An explicit operation outputDirectory still wins; choose a dedicated destination because packaging replaces that selected directory. Omitted or empty native resources retain the existing destination rules.

Root app files retain their paths at the output root; explicitly nested apps retain their apps/<id>/ paths. Shared files retain their configured route destinations. When the selected content supplies no root index.html, the SDK generates one that opens the selected app page. The result contains outputRoot, manifest, and the complete files inventory. manifest.app.entry stays app-relative, while manifest.app.start is the package launch URL, such as ./index.html for a root app or ./apps/hello-world/index.html for a nested app. Only when selected records supply an authored output-root index does the release add manifest.app.rootDocument: "./index.html". Preview serves that explicit document at /; without the field, older releases and generated-launcher packages retain the 302 redirect to app.start or the older app.entry fallback with the request query preserved. This generated release fact adds no app configuration or API option, changes no app.start, and requires no HTML content inference. Release schema 1, kind arcane-app-release, and packager identity arcane-app-packager-v1 remain unchanged. A dry run returns the planned output and file inventory without writing source or output.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {packageApp} from 'arcane-os';

const packaged = await packageApp({
    workspaceRoot: process.cwd(),
    appId: 'hello-world'
});

console.log(packaged.manifest.app.start, packaged.files);

PACKAGER_VERSION

Overview

Builder identity written into schema-1 application release manifests.

Value and import

const PACKAGER_VERSION

Import it from arcane-os/packager. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {PACKAGER_VERSION} from 'arcane-os/packager';

console.log(PACKAGER_VERSION);

packager.discoverApps()

Overview

Discovers packager application configurations and release boundaries beneath one workspace root.

Signature and result

async discoverApps({workspaceRoot:requestedWorkspaceRoot})

Import it from arcane-os/packager. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {discoverApps} from 'arcane-os/packager';

async function usediscoverApps(...arguments_) {
    return discoverApps(...arguments_);
}

parseSemver()

Overview

Parses one strict three-part semantic version with optional prerelease metadata.

Signature and result

parseSemver(value)

Import it from arcane-os/packager. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {parseSemver} from 'arcane-os/packager';

console.log(parseSemver('1.2.3'));

RELEASEMANIFESTNAME

Overview

Canonical packaged application release manifest filename.

Value and import

const RELEASE_MANIFEST_NAME

Import it from arcane-os/packager. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {RELEASE_MANIFEST_NAME} from 'arcane-os/packager';

console.log(RELEASE_MANIFEST_NAME);

ROOTCONFIGNAME

Overview

Canonical root packager configuration filename.

Value and import

const ROOT_CONFIG_NAME

Import it from arcane-os/packager. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {ROOT_CONFIG_NAME} from 'arcane-os/packager';

console.log(ROOT_CONFIG_NAME);

validateAppBundlePath()

Overview

Validates and normalizes one portable path selected inside an external app bundle.

Signature and result

validateAppBundlePath(value, label='bundle path')

Import it from arcane-os or arcane-os/release-bundle. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {validateAppBundlePath} from 'arcane-os';

console.log(validateAppBundlePath('payload/apps/example/index.html'));

validateAppConfig()

Overview

Validates one schema-1 packager app configuration and its relationship to the root config.

Optional nativeResources contains a required literal-path include array (which may be empty) and optional exclude array (default []). It selects additional app-owned resources only for a nonbrowser packaging target. Ordinary include, exclude, shared routes and document selection remain unchanged.

Optional outputDirectory is the saved workspace-relative browser package directory; omission preserves dist/<app-id>. Nonempty native selection uses the separate target-selected default described above. It is an app package field, not a change to the root configuration's distRoot or the schema-2 app identity. Packaging reports conflicting output/input selections with ARCANE_PACKAGE_INVALID before output writes. Authored-descriptor comparison treats the destination as package-local, and descriptor refresh preserves the existing setting.

Signature and result

validateAppConfig(value, appId, rootConfig, configPath=`apps/${appId}/${APP_CONFIG_NAME}`)

Import it from arcane-os/packager. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {validateAppConfig} from 'arcane-os/packager';

async function usevalidateAppConfig(...arguments_) {
    return validateAppConfig(...arguments_);
}

validateRootConfig()

Overview

Validates one root packager mapping and its fixed shared-route boundaries.

The schema-1 arcane-packager.json uses appsRoot: "." for standalone apps: each app's root is its repository root. Managed-map refresh, development serving, inspection and packaging use root app files and direct npm package paths without generated nested app redirects or duplicate PWA files. Installation identity and authored file selection remain unchanged. Explicit appsRoot: "apps" supports real multi-app workspaces. See standalone root applications.

Signature and result

validateRootConfig(value, configPath=ROOT_CONFIG_NAME)

Import it from arcane-os/packager. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {validateRootConfig} from 'arcane-os/packager';

async function usevalidateRootConfig(...arguments_) {
    return validateRootConfig(...arguments_);
}

verifyApp()

Overview

Reads one existing application release and compares its complete file inventory with its release manifest through the low-level packager API.

Signature and result

async verifyApp({workspaceRoot, appId, outputDirectory, signal, onEvent})

Import it from arcane-os or arcane-os/packager. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Optional outputDirectory selects the same workspace-relative override accepted by packageApp, without changing the app's saved destination. For a target-selected native input release, pass the returned release.output as this override. verifyApp has no target option and does not infer the native directory or execute the application, its services or a platform host.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {verifyApp} from 'arcane-os';

// release is the result of packageApp() for this app and workspace.
const inspected = await verifyApp({
    workspaceRoot,
    appId: 'moon-dashboard',
    outputDirectory: release.output
});
console.log(inspected.files);

verifyAppReleaseBundle()

Overview

Parses one deterministic app bundle without extraction and checks its structural manifest and complete logical file inventory. It supports ordinary USTAR entries and per-file POSIX PAX path extensions. The complete extended path is used by files and readFile(); the metadata and regular-header placeholder are not payload files. Malformed or orphaned PAX records produce ARCANE_BUNDLE_INVALID. Other PAX attributes and archive member types remain unsupported. The existing same-SDK-version condition remains unchanged. An older reader without PAX support must be updated before importing a bundle that requires these path extensions.

Signature and result

async verifyAppReleaseBundle({bundlePath, signal, onEvent}={})

Import it from arcane-os or arcane-os/release-bundle. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. Normalized SDK validation with complete canonical archive and release content. Deep protocol: SDK packager and deterministic bundle contract.

Example

import {verifyAppReleaseBundle} from 'arcane-os';

async function useverifyAppReleaseBundle(...arguments_) {
    return verifyAppReleaseBundle(...arguments_);
}

Runtime and app descriptors

APPDESCRIPTORNAME

Overview

Canonical schema-2 application descriptor filename.

Value and import

const APP_DESCRIPTOR_NAME

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {APP_DESCRIPTOR_NAME} from 'arcane-os';

console.log(APP_DESCRIPTOR_NAME);

APPDESCRIPTORSCHEMA_VERSION

Overview

Current authored application descriptor schema version.

Value and import

const APP_DESCRIPTOR_SCHEMA_VERSION

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {APP_DESCRIPTOR_SCHEMA_VERSION} from 'arcane-os';

console.log(APP_DESCRIPTOR_SCHEMA_VERSION);

generateDocumentImportMaps()

Overview

Writes SDK-managed inline browser import maps into explicitly selected HTML documents. Hosts can keep their existing page layout and use an already materialized Arcane runtime without an app descriptor, app discovery, or an apps/<id>/ directory. The existing app-scoped arcane import-map operation continues to own descriptor-selected application pages and its map artifact.

Signature and result

async generateDocumentImportMaps({
    documentRoot,
    runtimeRoot = path.join(documentRoot, 'arcane'),
    documents,
    version = SDK_VERSION,
    deploymentUrl,
    signal,
    onEvent
} = {})

Import it from arcane-os.

The resolved result contains:

{
    documentRoot,
    runtimeRoot,
    documentPaths,
    documentCount,
    documents: [{path, filePath, imports, scopes?}],
    committed: true
}

documentPaths and each filePath are absolute filesystem paths. Each path is relative to documentRoot; imports contains the global bindings rendered for that document. Optional scopes contains dependency-specific bindings; scope URLs and their targets are rebased with the same document base as global imports. The operation inventories the runtime once, builds the shared map once, and reads the selected documents with up to four concurrent readers. It renders every document before writing any of them, then writes in selected order. committed: true means all selected writes completed; the batch is not an atomic filesystem transaction.

Document URLs and authored content

The first <base> with an href determines each document's effective base. A target-only base, such as <base target="_blank">, does not change URL resolution. With no base, shell/home.html resolves the default runtime through ../arcane/. With <base href="../">, the same page resolves it through ./arcane/. Generated local URLs stay clean regardless of the retained version argument.

The host serves the runtime at the same relative location as runtimeRoot has to documentRoot. deploymentUrl supplies that directory's public URL when an authored base needs an origin or deployment path to resolve correctly. For example, https://example.com/control/ corresponds to documentRoot, so its default runtime is served at https://example.com/control/arcane/. Cross-origin bases produce absolute runtime map URLs. Without deploymentUrl, an absolute or root-relative base causes a TypeError before any document is written. A relative base that traverses above documentRoot also requires deploymentUrl, even if later path segments return into the physical directory: the filesystem's parent names do not establish public deployment paths. The two filesystem roots must share a volume.

The generator replaces only SDK-marked <script type="importmap" data-arcane-import-map> ranges, consolidating multiple SDK blocks into one. It preserves complete authored HTML around those ranges, including whitespace, resource URLs, custom import maps, and the attributes and order of classic, module, async, and defer scripts. Custom maps remain separate and are not merged into the SDK map. The managed block follows the effective base and precedes executable scripts and module preloads. An authored base that follows one of those loads is reported as ARCANE_IMPORT_MAP_INVALID before writes.

This operation writes only the selected HTML files. The caller owns runtime materialization, document selection, serving, and coordination with other document writers. It creates no map sidecar, copies no runtime content, and starts no build or browser.

Events, errors, and cancellation

If an event callback throws or rejects, generation continues. A successful return additionally reports eventDelivery: {status: 'degraded', errorCode: 'ARCANE_EVENT_DELIVERY_FAILED', message} for the first callback failure.

Invalid options can throw TypeError; document/map structure failures use ARCANE_IMPORT_MAP_INVALID, runtime inventory failures use ARCANE_RUNTIME_INVALID, and filesystem failures propagate. All started preparation reads settle before rejection; multiple failures are reported together in an AggregateError. Cancellation rejects with the signal's error reason when supplied, otherwise an operation cancellation error; an error lacking a code receives ARCANE_CANCELLED. Preparation failures occur before writes. Cancellation or a filesystem failure during writing can leave earlier completed files updated; the operation does not roll those files back. An in-flight filesystem write completes before the next cancellation boundary.

Availability and normalization

Node on Windows, Linux, and macOS. Filesystem paths are resolved with the host path API; browser import URLs use forward slashes and URL encoding. Deep protocol: Explicit host documents.

Example

A dragon observatory keeps its control page at shell/home.html, settings at settings.html, and its selected Arcane runtime at arcane/. Run this from that document root after materializing the runtime:

import {generateDocumentImportMaps} from 'arcane-os';

const controller = new AbortController();

function reportImportMapEvent(event) {
    console.log(event);
}

const result = await generateDocumentImportMaps(
    {
        documentRoot: process.cwd(),
        documents: ['shell/home.html', 'settings.html'],
        signal: controller.signal,
        onEvent: reportImportMapEvent
    }
);

for (const document of result.documents) {
    console.log(document.path, document.imports['arcane/AI']);
}

Change the explicit document list to update another host page. If either page uses <base href="/control/">, add deploymentUrl: 'https://example.com/control/' to the options. Both pages keep their authored layout and receive map URLs appropriate to their own base.

getSdkBrowserRuntimeRoot()

Overview

Returns the absolute SDK browser-runtime root selected by the installed package.

Signature and result

getSdkBrowserRuntimeRoot()

Import it from arcane-os. The return value is the default root accepted by the browser-runtime inventory and reader functions.

Availability and normalization

Node. Returns one absolute directory path. Deep protocol: Node ESM.

Example

import {getSdkBrowserRuntimeRoot} from 'arcane-os';

console.log(getSdkBrowserRuntimeRoot());

getSdkRoot()

Overview

Returns the absolute installed SDK package root.

Signature and result

getSdkRoot()

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {getSdkRoot} from 'arcane-os';

console.log(getSdkRoot());

loadAppDescriptor()

Overview

Loads an authored schema-2 descriptor or a complete package/registry projection with its source label.

Signature and result

async loadAppDescriptor({workspaceRoot, appRoot, appId, packageManifest})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {loadAppDescriptor} from 'arcane-os';

async function useloadAppDescriptor(...arguments_) {
    return loadAppDescriptor(...arguments_);
}

listRuntimeFiles()

Overview

Lists every regular file beneath one selected SDK runtime root as an ordered, slash-normalized relative path.

Signature and result

async listRuntimeFiles({runtimeRoot=path.join(sdkRoot, 'runtime'),signal}={})

The function traverses the selected directory, observes signal, and returns the complete sorted path list.

Availability and normalization

Node. Complete relative-path inventory. Deep protocol: Node ESM.

Example

import {listRuntimeFiles} from 'arcane-os';

const files=await listRuntimeFiles();

listSdkBrowserRuntimeFiles()

Overview

Lists every regular file beneath one selected SDK browser-runtime root as an ordered, slash-normalized relative path.

Signature and result

async listSdkBrowserRuntimeFiles({browserRuntimeRoot=defaultRoot,signal}={})

The function traverses the selected directory, observes signal, and returns the complete sorted path list.

Availability and normalization

Node. Complete relative-path inventory. Deep protocol: Node ESM.

Example

import {listSdkBrowserRuntimeFiles} from 'arcane-os';

const files=await listSdkBrowserRuntimeFiles();

loadRuntimeRelease()

Overview

Returns the selected runtime root, SDK version, and complete current file inventory derived directly from that directory.

Signature and result

async loadRuntimeRelease({runtimeRoot=path.join(sdkRoot, 'runtime'),signal}={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {loadRuntimeRelease} from 'arcane-os';

async function useloadRuntimeRelease(...arguments_) {
    return loadRuntimeRelease(...arguments_);
}

loadSdkBrowserRuntimeRelease()

Overview

Returns the selected browser-runtime root, SDK version, and complete current file inventory derived directly from that directory.

Signature and result

async loadSdkBrowserRuntimeRelease({browserRuntimeRoot=defaultRoot,signal}={})

Import it from arcane-os. The mutable result contains sdkVersion, browserRuntimeRoot, and ordered files.

Availability and normalization

Node. SDK-normalized inputs, errors, and documented result. Deep protocol: Node ESM.

Example

import {loadSdkBrowserRuntimeRelease} from 'arcane-os';

const release=await loadSdkBrowserRuntimeRelease();

materializeInstalledSdkRuntime()

Overview

Materializes the complete installed SDK runtime and browser-runtime content. After full runtime replacement, it writes or replaces semantic arcane.lock.json from the actual installed dependency name, package name, package version, alias source, and projected roots.

This operation remains available for physical workspace projections. External applications using installed-package routes read directly from their installed dependency and do not need to call it or create arcane.lock.json before serving, refreshing app import maps, or packaging.

Signature and result

async materializeInstalledSdkRuntime({workspaceRoot,sdkPackageSource,browserDecisions=false,workspaceOperationLease,signal,onEvent}={})

Import it through the exact dependency key declared by the workspace: normally arcane-os, or the alias name such as arcane-sdk when the declaration is npm:arcane-os@<version>. It resolves that declaration under the shared workspace-operation lock and replaces the complete projection by staged whole-tree replacement. The mutable result includes the installed-package location, materialized workspace runtime paths, and workspaceLock path and document. It does not install dependencies or merge application source.

Explicit browserDecisions: true also acquires the bundled Transformers.js 4.3.0 entry and matching ONNX Runtime 1.31.0-dev.20260914-8d85527a0 asyncify module/WASM and license files from their upstream distributions into arcane/sdk/ai/decisions-runtime/. It returns their directory, transformersVersion, onnxRuntimeVersion and files under workspaceRuntime.browserDecisions. The default false performs no optional acquisition. Select this option on each refresh that should retain those files. For applications with installed-package routes, use packageApp({workspaceRoot, appId, browserDecisions: true}) to place the distribution beside the actual deployed SDK module. This physical materializer continues to own only the separate arcane/ projection; it does not populate or modify node_modules. The extension-local decision guide describes runtime.local: true, complete resource ownership and MV3 usage.

Ordinary acquisition automatically recovers a workspace-operation lock when the recorded owner process is confirmed absent, without waiting solely for its six-hour expiry. Retry this public operation normally; workspaceOperationLease is for active nested SDK work and cannot be reconstructed from the lock JSON. Live or indeterminate owners remain ARCANE_WORKSPACE_BUSY; an indeterminate process-probe error is retained as the cause. Existing published lock documents remain readable. Recovery rechecks cancellation, the captured nonce and PID, and owner presence after asynchronous observation, preserving a replacement detected there. This cooperative read-then-remove protocol does not provide an atomic compare-and-delete across competing processes.

Replacement removes files absent from the selected runtime content and restores the prior tree if commit fails. signal and onEvent remain caller-owned before commit. Once the atomic replacement starts, it completes replacement or rollback without observing cancellation or invoking callbacks.

Availability and normalization

Node. Complete installed runtime content and a mutable materialization result. Deep protocol: Installed SDK runtime materialization.

Example

import {materializeInstalledSdkRuntime} from 'arcane-os';
// If package.json declares the SDK under the arcane-sdk alias, import from
// 'arcane-sdk' instead.

const result=await materializeInstalledSdkRuntime({workspaceRoot});

materializeWorkspaceRuntimeContent()

Overview

Replaces one workspace's complete projected runtime and browser-runtime content from selected source roots. It does not resolve a package declaration or write the installed-package lock document owned by materializeInstalledSdkRuntime().

Signature and result

async materializeWorkspaceRuntimeContent({workspaceRoot,runtimeRoot=path.join(getSdkRoot(), 'runtime'),browserRuntimeRoot=getSdkBrowserRuntimeRoot(),sdkVersion=SDK_VERSION,browserDecisions=false,signal,onEvent}={})

The operation stages the complete projection, replaces the prior tree at the commit boundary, restores it if commit fails, and removes paths absent from the selected sources.

browserDecisions: true acquires the same upstream executable closure described by materializeInstalledSdkRuntime() before replacement. Its result is at result.browserDecisions because this lower-level operation returns the workspace runtime directly. Full downloaded content remains unchanged; model and tokenizer data are not materialized. workspace.decisions.started and workspace.decisions.progress report completed files and the fixed total. Cancellation, HTTP failures and throwing/rejecting observers abort and join pending acquisitions before returning; the prior runtime remains in place. An HTTP failure retains its complete response in error.response, or in the corresponding member of AggregateError.errors when several operations fail.

Availability and normalization

Node. Complete workspace runtime content and a mutable materialization result. Deep protocol: Installed SDK runtime materialization.

Example

import {materializeWorkspaceRuntimeContent} from 'arcane-os';

const result=await materializeWorkspaceRuntimeContent({workspaceRoot});

PreferenceStore default export

Overview

Default binding for the canonical PreferenceStore runtime class. The static specifier arcane-os/preference-store works in Node package consumers and is mapped to the same runtime module in managed browsers. arcane/PreferenceStore is the direct browser runtime name generated into the managed import map.

Signature and result

default class PreferenceStore extends EventTarget

Availability and normalization

Node with injected adapters, or browser/native WebView storage. The package subpath and managed browser key both resolve directly to the canonical runtime module. Deep protocol: Browser runtime delivery.

The default adapter recognizes an absent optional preferences namespace only from the exact Core lookup tuple code:'METHOD_NOT_ALLOWED', reason:'core-namespace-unavailable', namespace:'preferences', and the matching method:'preferences.<operation>'. Single get, set, and delete operations then retry once through the existing app-scoped local adapter after checking disposal and cancellation, preserving complete values and operation context. The existing Android unsupported-capability route is unchanged. An advertised setMany batch rejected for that exact absence retains its original rejection and performs no serial retry; subsequent operations use the selected local adapter. Partial-service, permission, persistence, transport and cancellation failures remain errors. Explicit adapters retain their own behavior. See the complete PreferenceStore contract.

Example

import PreferenceStore from 'arcane-os/preference-store';
const store=new PreferenceStore({schema,adapter});

PREFERENCESTOREERROR_CODES

Overview

Frozen stable error-code vocabulary emitted by PreferenceStore.

Signature and result

const PREFERENCE_STORE_ERROR_CODES

Availability and normalization

Node and browser. Exact immutable values from the canonical runtime module.

Example

import {PREFERENCE_STORE_ERROR_CODES} from 'arcane-os/preference-store';
console.log(PREFERENCE_STORE_ERROR_CODES.disposed);

PREFERENCESTOREEVENT_TYPES

Overview

Frozen semantic event names published by PreferenceStore.

Signature and result

const PREFERENCE_STORE_EVENT_TYPES

Availability and normalization

Node and browser. Exact load, change, and reset names from the canonical runtime.

Example

import {PREFERENCE_STORE_EVENT_TYPES} from 'arcane-os/preference-store';
console.log(PREFERENCE_STORE_EVENT_TYPES.change);

Preference

Overview

Canonical Preference entity re-exported with the store namespace.

Signature and result

new Preference(data={})

Availability and normalization

Node and browser. Entity validation and serialization remain owned by the canonical runtime entity.

Example

import {Preference} from 'arcane-os/preference-store';
const record=new Preference({key:'theme',value:'system'});

preferenceSchema()

Overview

Builds the canonical Preference strong-type schema for a supplied definition set.

Signature and result

preferenceSchema(definitions=[])

Availability and normalization

Node and browser. Returns the canonical runtime schema for the supplied definitions.

Example

import {preferenceSchema} from 'arcane-os/preference-store';
const schema=preferenceSchema([]);

SpeechPlayback default export

Overview

Default binding for the canonical SpeechPlayback runtime class. The static specifier arcane-os/speech-playback works in Node package consumers and maps to the same runtime module in managed browsers. Physical/nested maps also retain the arcane/SpeechPlayback compatibility name.

When the supplied speech client has prepareTTSPlayback or fetchTTS and reports a positive providerRuntime.status('tts', {execution:true}).execution.maxConcurrentRequests, prepare() submits every complete part immediately. The provider owns its bounded FIFO queue (browser Kokoro defaults to four), while Blob audio or native playback descriptors remain in exact input order. Preparation prefers prepareTTSPlayback when available. Native playback owns pause, resume, stop and release without creating an audio-file URL. A native or custom client without that advertised capacity stays serialized with one lookahead. Replay keeps completed URLs and pending requests while retrying failed missing provider segments. The optional constructor onState(detail) callback runs synchronously after the canonical state occurrence is dispatched; callback failures are reported without replacing playback settlement.

prepare() keeps every nonblank stored part exact. At synthesis time, SpeechPlayback copies the part and automatically removes repeated formatting marks from only that outbound speech input. It passes SDK-internal preparation metadata so a downstream SDK speech boundary does not apply the filter again; applications do not supply that metadata. Original part objects, displayed or stored content, and every non-input payload field remain unchanged.

Signature and result

default class SpeechPlayback

Availability and normalization

Node with injected media adapters, or browser/native WebView media. The package subpath and managed browser key both resolve directly to the canonical runtime module; provider and media availability remain host-owned.

Example

import SpeechPlayback from 'arcane-os/speech-playback';

const audio=document.body.appendChild(document.createElement('audio'));
const playback=new SpeechPlayback({
  audio,
  speech:globalThis.ai,
  onState(detail) {
    console.log(detail.state);
  }
});
const button=document.body.appendChild(document.createElement('button'));
button.textContent='Speak';
button.addEventListener('click',async function speakCompleteSegments(){
  await globalThis.ai.setSpeechMuted(false);
  await playback.prepare({
    parts:['First complete segment.','Second complete segment.'],
    autoplay:true
  });
});

SPEECHPLAYBACKSTATE_EVENT

Overview

Canonical semantic event name for SpeechPlayback state transitions.

Signature and result

const SPEECH_PLAYBACK_STATE_EVENT

Availability and normalization

Node and browser. Exact immutable speech-playback-state name.

Example

import {SPEECH_PLAYBACK_STATE_EVENT} from 'arcane-os/speech-playback';
console.log(SPEECH_PLAYBACK_STATE_EVENT);

SPEECHVOICEALIASES

Overview

Mutable compatibility membership for the ten shared voice identifiers used by existing speech controls. SpeechPlayback does not select a voice from this set, and membership does not promise support from the selected provider.

Signature and result

const SPEECH_VOICE_ALIASES

Availability and normalization

Node and browser. Ordinary mutable Set, derived once in SPEECH_VOICE_OPTIONS order, containing alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, and shimmer.

Example

import {SPEECH_VOICE_ALIASES} from 'arcane-os/speech-playback';
console.log(SPEECH_VOICE_ALIASES.has('alloy')); // true

SPEECHVOICEOPTIONS

Overview

Mutable ordered compatibility records for existing speech voice controls. Each record has a lowercase value and matching title-case label. Provider support and voice selection remain caller-owned.

Signature and result

const SPEECH_VOICE_OPTIONS

Availability and normalization

Node and browser. Ordinary mutable array and mutable {value,label} records ordered as Alloy, Ash, Ballad, Coral, Echo, Fable, Nova, Onyx, Sage, and Shimmer.

Example

import {SPEECH_VOICE_OPTIONS} from 'arcane-os/speech-playback';
console.log(SPEECH_VOICE_OPTIONS[0]); // {value: 'alloy', label: 'Alloy'}

SpeechPlayback

Overview

Named binding for the same capability-aware, exact-order canonical class exposed as the speech-playback default. prepare() preserves each nonblank part's exact input string without trimming, splitting, or freezing that content. An optional onState(detail) constructor callback receives every state synchronously after the canonical occurrence is dispatched. Both surfaces expose the same public field values at dispatch time; object identity is not promised. Callback failures are reported through globalThis.reportError when available, otherwise console.error, and do not replace playback settlement. Only the outbound synthesis copy receives automatic repeated-formatting-mark cleanup; the original part and stored preparation record stay exact.

Signature and result

new SpeechPlayback({
  audio,
  speech?,
  model?,
  voice?,
  responseFormat?,
  speed=1,
  onState=()=>{},
  createObjectURL?,
  revokeObjectURL?,
  delay?,
  messages?
})

Availability and normalization

Node with injected media adapters, or browser/native WebView media. Binding identity equals the default export. Provider-advertised capacity enables eager submission while that provider owns its bound; native and custom speech stays serialized, and media availability remains host-owned.

Example

import SpeechPlayback,{SpeechPlayback as NamedSpeechPlayback} from 'arcane-os/speech-playback';

const audio=document.body.appendChild(document.createElement('audio'));
const playback=new NamedSpeechPlayback({
  audio,
  onState(detail) {
    console.log(detail.state);
  }
});
console.log(playback instanceof SpeechPlayback); // true

splitSpeechText()

Overview

Returns the caller's exact nonblank speech text as one segment.

Signature and result

splitSpeechText(value='')

Availability and normalization

Node and browser. Uses trimming only to detect blank input. A nonblank value is returned with its exact whitespace and content intact in one mutable array; it is not trimmed, split, or frozen. Blank or whitespace-only input returns an empty array.

Example

import {splitSpeechText} from 'arcane-os/speech-playback';
console.log(splitSpeechText('Hello world.'));

MarkdownSpeech

Overview

Streams the SDK's speech formatting cleanup across input chunk boundaries. append() removes runs of two or more identical *, #, _, backtick, or ~ marks while retaining single marks and every other character. It is a narrow speech filter, not a Markdown parser. Normal SDK TTS calls use this cleanup automatically; applications do not need to construct this class or opt in.

Signature and result

new MarkdownSpeech()

append(text='',end=false) returns only newly available narration. It retains one trailing candidate formatting mark across calls so a repeated run split between chunks is still removed. A terminal end:true append flushes any single pending mark and resets the instance. reset() discards pending state.

Availability and normalization

Node and browser. The implementation has no runtime dependency. Caller strings remain unchanged. Non-string input throws TypeError.

Example

import {MarkdownSpeech} from 'arcane-os/speech-text';

const speechText=new MarkdownSpeech();
console.log(speechText.append('*')); // '' (held for the next chunk)
console.log(speechText.append('*Hello.',true)); // 'Hello.'

stripSpeechFormatting()

Overview

Removes repeated same formatting marks from one complete speech text value. Single marks, ordinary punctuation, links, code contents, and every other character remain literal. Normal SDK TTS calls already apply this function to an outbound copy; the public helper is available when another speech-text owner needs the same one-pass result.

Signature and result

stripSpeechFormatting(text='')

Availability and normalization

Node and browser. Calls the supplied value's replace() method and returns its filtered result without modifying the supplied value. Pass a string; values without a callable replace() fail with the native TypeError.

Example

import {stripSpeechFormatting} from 'arcane-os/speech-text';

console.log(stripSpeechFormatting('**Hello**')); // 'Hello'

projectNativeDescriptor()

Overview

Projects the canonical app descriptor into the native registry shape consumed by paired builders.

Signature and result

projectNativeDescriptor(descriptor, {source}={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {projectNativeDescriptor} from 'arcane-os';

async function useprojectNativeDescriptor(...arguments_) {
    return projectNativeDescriptor(...arguments_);
}

projectPackageManifest()

Overview

Projects a schema-2 descriptor into the compatible schema-1 application package contract.

Optional package.documents becomes top-level documents. Omission stays omitted and an authored empty list stays [], so projection preserves automatic discovery versus entry-only selection. See application document selection.

Optional package.nativeResources becomes top-level nativeResources. Omission remains omitted, an empty include remains [], and an omitted exclude becomes []. Package-only descriptor synthesis preserves the same selection. This is a packaging contract; projectNativeDescriptor() keeps its existing registry shape and ordinary include list. See native-only application resources.

Signature and result

projectPackageManifest(descriptor)

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {projectPackageManifest} from 'arcane-os';

async function useprojectPackageManifest(...arguments_) {
    return projectPackageManifest(...arguments_);
}

readRuntimeFile()

Overview

Reads one complete contained file from a selected SDK runtime root.

Signature and result

async readRuntimeFile({runtimeRoot=path.join(sdkRoot, 'runtime'),relativePath,signal}={})

The relative path must identify a regular file contained by the selected root. The result is the complete file Buffer.

Availability and normalization

Node. Contained runtime file access with cancellation. Deep protocol: Node ESM.

Example

import {readRuntimeFile} from 'arcane-os';

const content=await readRuntimeFile({relativePath:'arcane/modules/AI.js'});

readSdkBrowserRuntimeFile()

Overview

Reads one complete contained file from a selected SDK browser-runtime root.

Signature and result

async readSdkBrowserRuntimeFile({browserRuntimeRoot=defaultRoot,relativePath,signal}={})

The relative path must identify a regular file contained by the selected root. The result is the complete file Buffer.

Availability and normalization

Node. Contained browser-runtime file access with cancellation. Deep protocol: Node ESM.

Example

import {readSdkBrowserRuntimeFile} from 'arcane-os';

const content=await readSdkBrowserRuntimeFile({relativePath:'ai/browser-wasm.mjs'});

validateAppDescriptor()

Overview

Strictly validates and freezes one schema-2 app descriptor, including runtime-only cross-field rules.

Signature and result

validateAppDescriptor(value, {appId}={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {validateAppDescriptor} from 'arcane-os';

async function usevalidateAppDescriptor(...arguments_) {
    return validateAppDescriptor(...arguments_);
}

Targets, native plans, and providers

ARCANEINTEGRATEDPROVIDERRELATIVEPATH

Overview

Frozen repository-relative path of Arcane OS's integrated shared-development provider.

Value and import

const ARCANE_INTEGRATED_PROVIDER_RELATIVE_PATH

Import it from arcane-os or arcane-os/integrated-provider. Treat arrays and records as immutable public values.

Availability and normalization

Node; selected browser/native target or provider as documented. Exact immutable SDK value. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {ARCANE_INTEGRATED_PROVIDER_RELATIVE_PATH} from 'arcane-os';

console.log(ARCANE_INTEGRATED_PROVIDER_RELATIVE_PATH);

ARCANENATIVEPROVIDER_PATHS

Overview

Target-to-provider path registry for explicitly selected Arcane OS checkout providers. The package-owned portable default resolves directly from the SDK module location and leaves this existing registry unchanged.

Value and import

const ARCANE_NATIVE_PROVIDER_PATHS

Import it from arcane-os or arcane-os/native-provider. The exported path arrays are ordinary copies; changing them does not change the loader's fixed paths.

Availability and normalization

Node. Checkout provider path metadata; it does not load a provider or report runtime readiness. Deep protocol: native provider protocols.

Example

import {ARCANE_NATIVE_PROVIDER_PATHS} from 'arcane-os';

console.log(ARCANE_NATIVE_PROVIDER_PATHS);

assertIntegratedNativeToolchain()

Overview

Requires an integrated workspace and explicitly selected checkout provider to use the same canonical Arcane checkout. The SDK-owned portable pairing uses its installed package root instead; other targets retain the existing requirement.

Signature and result

assertIntegratedNativeToolchain({workspaceMode, workspaceRoot, toolchainRoot, target, providerSource='arcane-checkout'}={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {assertIntegratedNativeToolchain} from 'arcane-os';

async function useassertIntegratedNativeToolchain(...arguments_) {
    return assertIntegratedNativeToolchain(...arguments_);
}

buildTarget()

Overview

Invokes one target adapter build with explicit app, target, and artifact inputs.

Signature and result

async buildTarget(options={})

Import it from arcane-os or arcane-os/targets. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {buildTarget} from 'arcane-os';

async function usebuildTarget(...arguments_) {
    return buildTarget(...arguments_);
}

createNativeBuildPlan()

Overview

Creates a native plan carrying the complete selected app release, dependency releases, toolchain, target request and output roots. Release inputs use {files, ...releaseFields} records; dependency inputs use {appId,releaseRoot,release}. Selected-file readers return the complete contents. Both nested CLI signing:{mode,profileId} and existing flat signing/signingProfileId inputs normalize to the same flat plan request. Optional selectedSdk:{packageRoot,packageSource} carries the app's actual installed SDK source through the plan and builder request. The high-level toolchain reads this from the workspace's existing installed SDK layout once per build. Direct callers composing services over a partial direct SDK projection supply the actual source; the builder does not infer it from the browser file inventory or substitute its own version.

Signature and result

async createNativeBuildPlan({ nativeBuilder, toolchainRoot, toolchain, appReleaseRoot, release, appDescriptor, selectedSdk, dependencyReleases, minimumCoreVersion, protectedRoots=[], outputRoot, targetRequest, signal, onEvent }={})

Import it from arcane-os or arcane-os/native. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {createNativeBuildPlan} from 'arcane-os';

async function usecreateNativeBuildPlan(...arguments_) {
    return createNativeBuildPlan(...arguments_);
}

createNativeTargetAdapter()

Overview

Adapts one validated native builder to the common target-adapter contract.

Signature and result

createNativeTargetAdapter({targetId, nativeBuilder}={})

Import it from arcane-os or arcane-os/targets. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {createNativeTargetAdapter} from 'arcane-os';

async function usecreateNativeTargetAdapter(...arguments_) {
    return createNativeTargetAdapter(...arguments_);
}

doctorNativeTarget()

Overview

Loads and diagnoses one explicit native provider and target without building an application.

Signature and result

async doctorNativeTarget(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {doctorNativeTarget} from 'arcane-os';

async function usedoctorNativeTarget(...arguments_) {
    return doctorNativeTarget(...arguments_);
}

executeNativeBuildPlan()

Overview

Invokes the plan's selected builder with complete app/dependency release records, their file readers, the flat target request and event/cancellation lifecycle.

Signature and result

async executeNativeBuildPlan(plan, { expectedNativeBuilder, expectedTarget, signal, onEvent }={})

Import it from arcane-os or arcane-os/native. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {executeNativeBuildPlan} from 'arcane-os';

async function useexecuteNativeBuildPlan(...arguments_) {
    return executeNativeBuildPlan(...arguments_);
}

getTargetAdapter()

Overview

Returns the registered adapter for one exact target id or fails for an unknown target.

Signature and result

getTargetAdapter(targetId)

Import it from arcane-os or arcane-os/targets. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {getTargetAdapter} from 'arcane-os';

async function usegetTargetAdapter(...arguments_) {
    return getTargetAdapter(...arguments_);
}

INTEGRATEDTOOLCHAINPROTOCOL

Overview

Protocol required from the fixed integrated shared-development provider.

Value and import

const INTEGRATED_TOOLCHAIN_PROTOCOL

Import it from arcane-os or arcane-os/integrated-provider. Treat arrays and records as immutable public values.

Availability and normalization

Node; selected browser/native target or provider as documented. Exact immutable SDK value. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {INTEGRATED_TOOLCHAIN_PROTOCOL} from 'arcane-os';

console.log(INTEGRATED_TOOLCHAIN_PROTOCOL);

listTargets()

Overview

Returns the frozen target descriptors without running an operation lifecycle.

Signature and result

listTargets()

Import it from arcane-os or arcane-os/targets. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {listTargets} from 'arcane-os';

console.table(listTargets());

loadArcaneIntegratedProvider()

Overview

Loads and authenticates the fixed Arcane-owned integrated development provider generation.

Signature and result

loadArcaneIntegratedProvider({ arcaneRoot, signal, onEvent, run=runProcess }={})

Import it from arcane-os or arcane-os/integrated-provider. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {loadArcaneIntegratedProvider} from 'arcane-os';

async function useloadArcaneIntegratedProvider(...arguments_) {
    return loadArcaneIntegratedProvider(...arguments_);
}

loadArcaneNativeProvider()

Overview

Loads the package-owned provider when arcaneRoot is omitted and target is portable or windows-x64. Portable produces a non-executable payload; Windows assembles the matching precompiled SDK host. An explicit root retains the fixed Arcane OS checkout provider route, including its errors; there is no silent fallback. Other native targets still require that root. Normal Node module resolution owns imports.

Signature and result

async loadArcaneNativeProvider({ arcaneRoot, target, inspect=lstat, canonicalize=realpath, importModule=specifier=>import(specifier), signal, onEvent }={})

The result retains arcaneRoot, toolchainRoot, providerPath and nativeBuilder, and adds providerSource. Package pairing returns providerSource:'sdk-package', arcaneRoot:null and the installed SDK root as toolchainRoot. Explicit checkout pairing returns providerSource:'arcane-checkout' with the selected root. Load completion means the builder interface was loaded, not that an app, native host or service is ready. For explicit service composition and host lifecycle, use the separate arcane-os/native/portable-provider and arcane-os/core/host guide.

Import it from arcane-os or arcane-os/native-provider. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {loadArcaneNativeProvider} from 'arcane-os';

async function useloadArcaneNativeProvider(...arguments_) {
    return loadArcaneNativeProvider(...arguments_);
}

NATIVEBUILDPLAN_PROTOCOL

Overview

Protocol identifier for native plans with complete selected release inputs.

Value and import

const NATIVE_BUILD_PLAN_PROTOCOL

Import it from arcane-os or arcane-os/native. Treat arrays and records as immutable public values.

Availability and normalization

Node; selected browser/native target or provider as documented. Exact immutable SDK value. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {NATIVE_BUILD_PLAN_PROTOCOL} from 'arcane-os';

console.log(NATIVE_BUILD_PLAN_PROTOCOL);

NATIVEBUILDERPROTOCOL

Overview

Protocol identifier required from injected native builders.

Value and import

const NATIVE_BUILDER_PROTOCOL

Import it from arcane-os or arcane-os/native. Treat arrays and records as immutable public values.

Availability and normalization

Node; selected browser/native target or provider as documented. Exact immutable SDK value. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {NATIVE_BUILDER_PROTOCOL} from 'arcane-os';

console.log(NATIVE_BUILDER_PROTOCOL);

prepareNativeTarget()

Overview

Runs one provider toolchain preparation and returns its process-owned result.

Signature and result

async prepareNativeTarget(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {prepareNativeTarget} from 'arcane-os';

async function useprepareNativeTarget(...arguments_) {
    return prepareNativeTarget(...arguments_);
}

resolveNativeBuildOutputRoot()

Overview

Resolves and validates one native output root, including integrated-checkout non-overlap.

Signature and result

resolveNativeBuildOutputRoot({target, workspaceMode, workspaceRoot, outputRoot}={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {resolveNativeBuildOutputRoot} from 'arcane-os';

async function useresolveNativeBuildOutputRoot(...arguments_) {
    return resolveNativeBuildOutputRoot(...arguments_);
}

runTarget()

Overview

Invokes one target adapter run method and fails honestly when the artifact kind is not runnable.

For the browser adapter, optional releaseRoot selects an existing packaged directory directly. Omission keeps the direct adapter's dist/<app-id> default, including callers with only a release workspace. The high-level runApplication() supplies the app-configured destination automatically.

Signature and result

async runTarget(options={})

Import it from arcane-os or arcane-os/targets. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {runTarget} from 'arcane-os';

async function userunTarget(...arguments_) {
    return runTarget(...arguments_);
}

TARGETADAPTERPROTOCOL

Overview

Protocol required from target adapter descriptors and implementations.

Value and import

const TARGET_ADAPTER_PROTOCOL

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node; selected browser/native target or provider as documented. Exact immutable SDK value. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {TARGET_ADAPTER_PROTOCOL} from 'arcane-os';

console.log(TARGET_ADAPTER_PROTOCOL);

TARGET_IDS

Overview

Frozen list of currently exposed target identifiers.

Value and import

const TARGET_IDS

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node; selected browser/native target or provider as documented. Exact immutable SDK value. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {TARGET_IDS} from 'arcane-os';

console.log(TARGET_IDS);

validateNativeBuilder()

Overview

Validates a native builder's protocol and required describe/doctor/prepare/build/verify/run methods.

Signature and result

validateNativeBuilder(provider)

Import it from arcane-os or arcane-os/native. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {validateNativeBuilder} from 'arcane-os';

async function usevalidateNativeBuilder(...arguments_) {
    return validateNativeBuilder(...arguments_);
}

verifyNativeArtifact()

Overview

Explicitly verifies one selected target artifact through the prepared provider and toolchain state.

Signature and result

async verifyNativeArtifact(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {verifyNativeArtifact} from 'arcane-os';

async function useverifyNativeArtifact(...arguments_) {
    return verifyNativeArtifact(...arguments_);
}

verifyTarget()

Overview

Invokes one target adapter's artifact verification boundary.

Signature and result

async verifyTarget(options={})

Import it from arcane-os or arcane-os/targets. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected browser/native target or provider as documented. Normalized complete plan and result; target-specific artifact detail preserved. Deep protocol: arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol.

Example

import {verifyTarget} from 'arcane-os';

async function useverifyTarget(...arguments_) {
    return verifyTarget(...arguments_);
}

Identity and protocol constants

ARCANEMACHINEBUNDLE_VERSION

Overview

Exact Arcane machine-bundle generation paired with this SDK runtime.

Value and import

const ARCANE_MACHINE_BUNDLE_VERSION

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {ARCANE_MACHINE_BUNDLE_VERSION} from 'arcane-os';

console.log(ARCANE_MACHINE_BUNDLE_VERSION);

ARCANE_PROTOCOL

Overview

Application-facing Arcane bridge protocol required by this SDK.

Value and import

const ARCANE_PROTOCOL

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {ARCANE_PROTOCOL} from 'arcane-os';

console.log(ARCANE_PROTOCOL);

ARCANEUPSTREAMREPOSITORY

Overview

Canonical upstream Arcane OS repository URL.

Value and import

const ARCANE_UPSTREAM_REPOSITORY

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {ARCANE_UPSTREAM_REPOSITORY} from 'arcane-os';

console.log(ARCANE_UPSTREAM_REPOSITORY);

CLIEVENTPROTOCOL

Overview

Version identifier for normalized CLI JSON and NDJSON event envelopes.

Value and import

const CLI_EVENT_PROTOCOL

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {CLI_EVENT_PROTOCOL} from 'arcane-os';

console.log(CLI_EVENT_PROTOCOL);

CLI_NAME

Overview

Primary command name presented by the SDK.

Value and import

const CLI_NAME

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {CLI_NAME} from 'arcane-os';

console.log(CLI_NAME);

OUTPUT_MODES

Overview

Frozen supported CLI output modes: human, JSON, and NDJSON.

Value and import

const OUTPUT_MODES

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {OUTPUT_MODES} from 'arcane-os';

console.log(OUTPUT_MODES);

RUNTIME_ROOT

Overview

Absolute installed SDK runtime directory for the current process.

Value and import

const RUNTIME_ROOT

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {RUNTIME_ROOT} from 'arcane-os';

console.log(RUNTIME_ROOT);

SDK_NAME

Overview

Published npm package name.

Value and import

const SDK_NAME

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {SDK_NAME} from 'arcane-os';

console.log(SDK_NAME);

SDK_ROOT

Overview

Absolute installed package root for the current process.

Value and import

const SDK_ROOT

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {SDK_ROOT} from 'arcane-os';

console.log(SDK_ROOT);

SDK_VERSION

Overview

Exact SDK package version.

Value and import

const SDK_VERSION

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {SDK_VERSION} from 'arcane-os';

console.log(SDK_VERSION);

Errors

ArcaneError

Overview

Normalized SDK error class carrying a stable code, human message, optional resolution details, cause, and exit status.

Signature and result

new ArcaneError(code, message, {details, cause, exitCode}={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. ArcaneError and JSON-safe error normalization. Deep protocol: Node ESM.

Example

import {ArcaneError, ERROR_CODES} from 'arcane-os';

const error = new ArcaneError(
    ERROR_CODES.usage,
    'Choose one documented target.'
);

console.log(error.code, error.message);

ERROR_CODES

Overview

Frozen registry of stable SDK error-code strings.

ERROR_CODES.updateCheckFailed is exactly 'ARCANE_UPDATE_CHECK_FAILED'. It identifies an update-check validation, registry, timeout, HTTP, or response failure; caller cancellation remains the separate ERROR_CODES.cancelled value.

The import-map operation also reports the stable operation-specific strings ARCANE_IMPORT_MAP_INVALID, ARCANE_IMPORT_MAP_UNRESOLVED, and ARCANE_IMPORT_MAP_COLLISION; package assembly can additionally report ARCANE_IMPORT_MAP_CLEANUP_FAILED. They are normalized ArcaneError.code values, but are not properties added to this general registry in SDK 0.5.14.

Value and import

const ERROR_CODES

Import it from arcane-os. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM.

Example

import {ERROR_CODES} from 'arcane-os';

console.log(ERROR_CODES.updateCheckFailed); // ARCANE_UPDATE_CHECK_FAILED

errorRecord()

Overview

Projects an error into the JSON-safe normalized public error record.

Signature and result

errorRecord(error)

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. ArcaneError and JSON-safe error normalization. Deep protocol: Node ESM.

Example

import {errorRecord} from 'arcane-os';

console.log(errorRecord(new Error('Example failure.')));

fail()

Overview

Synchronously throws an ArcaneError with the supplied code, message, and optional diagnostic context. It never returns a value or a promise.

Signature, parameters, and error

fail(code, message, options)

Import it from arcane-os. code is normally one of ERROR_CODES; a falsy code becomes ARCANE_OPERATION_FAILED. message is the public error message. options can contain details, cause, and exitCode. details is preserved for structured recovery, cause is attached through the standard Error cause, and an integer exitCode is preserved; otherwise the exit code is 1.

Calling fail() has no filesystem, event, cancellation, or receipt side effect. Catch the thrown ArcaneError synchronously, or let it reject the surrounding asynchronous operation naturally. Do not wrap it merely to make it look asynchronous.

Availability and normalization

Node. ArcaneError and JSON-safe error normalization. Deep protocol: Node ESM.

Example

import {ERROR_CODES, fail} from 'arcane-os';

function requireSelectedApp(appId) {
    if (typeof appId !== 'string' || appId.length === 0) {
        fail(ERROR_CODES.usage, 'Select one application.', {
            details: {field: 'appId'}
        });
    }

    return appId;
}

normalizeError()

Overview

Converts an unknown thrown value into an ArcaneError while preserving an existing normalized error.

Signature and result

normalizeError(error, fallbackCode=ERROR_CODES.operationFailed)

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. ArcaneError and JSON-safe error normalization. Deep protocol: Node ESM.

Example

import {normalizeError} from 'arcane-os';

console.log(normalizeError(new Error('Example failure.')));

throwIfAborted()

Overview

Throws the signal reason or a normalized cancellation error when an AbortSignal is already aborted.

Signature and result

throwIfAborted(signal)

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. ArcaneError and JSON-safe error normalization. Deep protocol: Node ESM.

Example

import {throwIfAborted} from 'arcane-os';

const controller = new AbortController();
throwIfAborted(controller.signal);

Workspace, doctor, repository, and server

assessArcaneOllama()

Overview

Performs a read-only Microsoft NT assessment of the managed ArcaneOllama service and reports unsupported hosts honestly.

Signature and result

async assessArcaneOllama({ signal, onEvent, platform=process.platform, run=runProcess, fileExists=exists }={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; Microsoft NT managed-service assessment. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {assessArcaneOllama} from 'arcane-os';

async function useassessArcaneOllama(...arguments_) {
    return assessArcaneOllama(...arguments_);
}

createWorkspace()

Overview

Scaffolds one new external repository-shaped workspace and one selected application.

Signature and result

async createWorkspace({ targetPath, appId, displayName, target='browser', initializeGit=false, signal, onEvent })

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {createWorkspace} from 'arcane-os';

async function usecreateWorkspace(...arguments_) {
    return createWorkspace(...arguments_);
}

doctorApplication()

Overview

Runs the read-only SDK/runtime/workspace and optional local-AI diagnostic operation.

Signature and result

async doctorApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {doctorApplication} from 'arcane-os';

async function usedoctorApplication(...arguments_) {
    return doctorApplication(...arguments_);
}

initializeApplication()

Overview

Initializes missing Arcane files for one app in an existing external or integrated workspace.

Signature and result

async initializeApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {initializeApplication} from 'arcane-os';

async function useinitializeApplication(...arguments_) {
    return initializeApplication(...arguments_);
}

initWorkspace()

Overview

Adds one application scaffold to an existing workspace without overwriting incompatible files.

Signature and result

async initWorkspace({ workspaceRoot=process.cwd(), appId, displayName, target='browser', signal, onEvent })

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {initWorkspace} from 'arcane-os';

async function useinitWorkspace(...arguments_) {
    return initWorkspace(...arguments_);
}

inspectWorkspaceProfile()

Overview

Classifies one canonical workspace as external or integrated and reports its fixed layout.

Signature and result

async inspectWorkspaceProfile(workspaceRoot=process.cwd())

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {inspectWorkspaceProfile} from 'arcane-os';

async function useinspectWorkspaceProfile(...arguments_) {
    return inspectWorkspaceProfile(...arguments_);
}

repositoryPull()

Overview

Runs one fast-forward-only pull after proving the selected repository worktree is clean.

Signature and result

async repositoryPull({ workspaceRoot=process.cwd(), target, signal, onEvent, run=runProcess }={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Optional target:{remote,ref,remoteBase?} captures the exact nonempty native-representable remote and ref strings before any wait and selects git pull --ff-only -- <remote> <ref>:. The current clean branch receives a fast-forward-only integration; the SDK never switches branches, resets or changes configuration. Without a target, the existing configured pull and result remain unchanged. Targeted results add target, complete stdout and stderr to the existing pull result.

Supplying target.remoteBase explicitly selects a local filesystem locator: only the Git remote argument becomes path.resolve(remoteBase, remote), captured once at acceptance before status work. Relative bases, including '', use the working directory at that moment. The returned target retains the original remote, ref and supplied base text. Omission preserves Git remote names, URLs, SCP-like addresses and remote-helper strings without guessed parsing. Unrepresentable base text reports TypeError without transformation. See checkout configuration and selected targets.

Availability and normalization

Node; network-assisted Git. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {repositoryPull} from 'arcane-os';

async function userepositoryPull(...arguments_) {
    return repositoryPull(...arguments_);
}

repositoryPush()

Overview

Pushes the selected attached branch through the repository's configured remote and credentials.

Signature, parameters, and result

async repositoryPush({ workspaceRoot=process.cwd(), target, signal, onEvent, run=runProcess }={})

Import it from arcane-os. workspaceRoot selects the Git worktree. signal cancels the owned Git process tree. The awaited onEvent callback receives the ordered process.* events for the three status probes and the push. run is an injectable process runner intended for deterministic tests; ordinary callers should keep the default.

Before pushing, the SDK runs git rev-parse --show-toplevel, git branch --show-current, and git status --short --branch in order. It rejects a detached HEAD, then, without target, runs plain git push; the repository's current branch, configured upstream/remote, Git credentials, hooks, and server policy remain authoritative. Unlike repositoryPull(), this function does not require a clean worktree. It does not create a commit or choose an application destination. Optional target:{remote,ref,remoteBase?} captures the original nonempty native-representable remote and ref strings before any wait and runs git push --no-follow-tags -- <remote> HEAD:<ref>. This publishes current HEAD to the caller-selected ref without force or implicit configured tag following. It changes no branch or Git configuration; credentials, URL interpretation, hooks and remote rejection remain Git-owned.

Supplying target.remoteBase explicitly selects a local filesystem locator: only the Git remote argument becomes path.resolve(remoteBase, remote), captured once at acceptance before status work. Relative bases, including '', use the working directory at that moment. Later directory or target-object changes do not redirect accepted work. Omission preserves Git remote names, URLs, SCP-like addresses and remote-helper strings without guessed parsing. Unrepresentable base text reports TypeError without transformation.

The promise resolves to {action:'push', repositoryRoot, branch, output}. output is trimmed stdout, or trimmed stderr when stdout is empty. A missing Git executable, failed status probe, rejected/nonzero push, cancellation, or event-callback failure rejects with the normalized process error. Cancellation stops the local process tree; it cannot prove that a remote accepted no objects before the interruption. Targeted results also contain the captured target, retaining original remote, ref and any supplied remoteBase, and complete stdout/stderr; omitting the target preserves the existing result shape. See checkout configuration and selected targets.

Availability and normalization

Node; network-assisted Git. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {repositoryPush} from 'arcane-os';

// Call only after the user has chosen to publish the attached branch.
async function pushAttachedBranch(workspaceRoot, signal) {
    const result = await repositoryPush({
        workspaceRoot,
        signal,
        onEvent(event) {
            if (event.type === 'process.stderr') console.error(event.message);
        }
    });

    console.log(`Pushed ${result.branch} from ${result.repositoryRoot}`);
    return result;
}

repositoryStatus()

Overview

Reads one repository's branch and short worktree status through an owned child process.

Signature and result

async repositoryStatus({ workspaceRoot=process.cwd(), signal, onEvent, run=runProcess }={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {repositoryStatus} from 'arcane-os';

async function userepositoryStatus(...arguments_) {
    return repositoryStatus(...arguments_);
}

resolveWorkspace()

Overview

Resolves one workspace profile and selected app into canonical SDK paths.

Signature and result

async resolveWorkspace({workspaceRoot=process.cwd(), appId}={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {resolveWorkspace} from 'arcane-os';

async function useresolveWorkspace(...arguments_) {
    return resolveWorkspace(...arguments_);
}

discoverApps()

Overview

Discovers application ids in one external or integrated workspace without selecting one.

Signature and result

async discoverApps(workspaceRoot=process.cwd())

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {discoverApps} from 'arcane-os';

async function usediscoverApps(...arguments_) {
    return discoverApps(...arguments_);
}

runDoctor()

Overview

Runs the underlying read-only doctor checks and returns their normalized report.

Signature and result

async runDoctor({ workspaceRoot, appId, arcaneRoot, requireLocalAI=false, signal, onEvent, platform=process.platform, run=runProcess }={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {runDoctor} from 'arcane-os';

async function userunDoctor(...arguments_) {
    return runDoctor(...arguments_);
}

runRepositoryAction()

Overview

Selects and runs one repository action by name.

Signature and result

async runRepositoryAction(action, options={})

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {runRepositoryAction} from 'arcane-os';

async function userunRepositoryAction(...arguments_) {
    return runRepositoryAction(...arguments_);
}

selectApp()

Overview

Selects one exact app id, or requires an unambiguous single discovered application.

Signature and result

async selectApp(workspaceRoot=process.cwd(), appId)

Import it from arcane-os. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {selectApp} from 'arcane-os';

async function useselectApp(...arguments_) {
    return selectApp(...arguments_);
}

WS

Import WS as the default or named binding from arcane-os/websocket-client, or as a named binding from the Node root arcane-os. new WS(uri,protocols?) returns the exact native socket from published ws-share, sharing a connecting or open socket for the same exact URI string and ordered protocol list. await WS.observe() exposes one event-pubsub observer with created/open/error/close lifecycle records; WS.getConnections() returns current managed-connection snapshots. Each physical connection has its own ID, including replacements at the same address.

The shared-client guide covers complete record fields, subscribe-then-snapshot ordering, listener cleanup, shared close ownership, native per-socket behavior and the per-loaded-module/realm boundary. This client entry does not change the server-side acceptWebSocket contract.

acceptWebSocket()

Overview

Accepts one caller-selected RFC6455 HTTP/1.1 Upgrade using Node's native duplex stream. The caller owns HTTP routing, TLS, listeners, application messages and shutdown. Use the raw server returned by startDevServer, or the public .server / .secureServer of node-http-server. There is no listener creation, default port, application envelope, message persistence, client sharing, reconnect loop or third-party WebSocket runtime.

Clients may use native WebSocket directly or the separate shared WS client. Node's global WebSocket is also a client, not a server. This server adapter supports version 13 over an HTTP/1.1 upgrade event, including HTTP/1.1 negotiated on an HTTPS listener. It does not implement HTTP/2 extended CONNECT or negotiate extensions such as compression. TLS setup remains with the existing server owner.

Signature, modes, and result

acceptWebSocket({request,socket,head,protocol,signal})

Import from arcane-os/websocket or arcane-os. Supply the exact request, socket and head from the selected Node upgrade event. Do not substitute request.socket for that event's stream. head defaults to an empty buffer. Optional protocol is one exact client-offered token; the default empty string selects no subprotocol. A browser that offers subprotocols expects one to be selected. Optional signal owns this connection's lifetime.

The synchronous result is a native EventTarget with:

Register listeners synchronously after acceptance. The handshake write and initial head processing begin in a microtask so those listeners receive buffered messages. head is processed once, before later stream chunks.

These are transport-local native events, not an application bus or retained event history. Native EventTarget owns listener exceptions; an async listener must observe its own promises. Listen for errors or inspect closed.error. Ping receives a matching Pong internally; Pong is not an application message. Text decoding preserves a leading U+FEFF and validates UTF-8 across the complete fragmented message. Binary data is never interpreted or wrapped as JSON.

Errors and cancellation

Before changing the socket, an invalid handshake throws ARCANE_WEBSOCKET_HANDSHAKE_INVALID with statusCode:400,headers:{}; an unsupported WebSocket version throws ARCANE_WEBSOCKET_VERSION_UNSUPPORTED with statusCode:426 and headers:{'Sec-WebSocket-Version':'13'}. The host owns sending that HTTP response and ending the rejected stream. Invalid socket, data or close arguments report TypeError / RangeError; a failed send rejects its promise without changing the payload. An unpaired UTF-16 surrogate cannot be represented as UTF-8: sending such text rejects with ARCANE_WEBSOCKET_TEXT_INVALID, and using it as a close reason throws that error before changing connection state. Valid strings remain exact.

After acceptance, invalid framing reports ARCANE_WEBSOCKET_PROTOCOL_INVALID and close status 1002; invalid text reports ARCANE_WEBSOCKET_TEXT_INVALID and 1007. Complete platform errors remain observable. Framing lengths, masking, the handshake's SHA-1 accept calculation and control-frame bounds are RFC transport requirements only. There are no application message limits, byte progress, content identities, or optional security controls.

A pre-aborted signal throws before taking ownership. Later abort destroys the stream with an AbortError coded ARCANE_WEBSOCKET_ABORTED, preserving the signal reason as its cause. Closing rejects new sends with ARCANE_WEBSOCKET_CONNECTION_CLOSED (or the existing failure). No timer silently terminates a slow close handshake; use the caller's signal or terminate() when that owner decides to stop. Server listener closure alone, including Node closeAllConnections(), does not own upgraded sockets. Track connections or provide a shared lifetime signal, then await their closed promises separately. None of this changes chat storage or persist:false.

Example

This example attaches to an already-owned listener and returns a separate connection cleanup function. Its route and echo policy belong to the caller. Call it with publicServer.server, publicServer.secureServer, or an SDK development server's returned server; it creates no additional HTTP server.

import {acceptWebSocket} from 'arcane-os/websocket';

function attachEcho(server,signal){
    const connections=new Set();
    function upgrade(request,socket,head){
        if(request.url!=='/socket'){
            socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
            return;
        }
        let connection;
        try{connection=acceptWebSocket({request,socket,head,signal});}
        catch(error){
            console.error(error);
            const status=error.statusCode??400;
            const version=status===426?'Sec-WebSocket-Version: 13\r\n':'';
            socket.end(`HTTP/1.1 ${status} Upgrade rejected\r\n${version}Connection: close\r\n\r\n`);
            return;
        }
        connections.add(connection);
        connection.addEventListener('error',function failed(event){console.error(event.detail);});
        connection.addEventListener('message',function echo(event){
            connection.send(event.data).catch(function sendFailed(error){console.error(error);});
        });
        connection.addEventListener('close',function remove(){connections.delete(connection);});
    }
    server.on('upgrade',upgrade);
    return async function detach(){
        server.off('upgrade',upgrade);
        await Promise.all([...connections].map(function stop(connection){return connection.terminate();}));
    };
}

// In browser code, after the host has selected its ws: or wss: URL:
function connectEcho(url){
    const client=new WebSocket(url);
    client.addEventListener('open',function greet(){client.send('The moon needs a coffee break.');});
    client.addEventListener('message',function received(event){console.log(event.data);});
    return client;
}

Protocol references: RFC6455, Node upgrade event, and native browser WebSocket. Work is connection-local and linear in actual framing/content. Input is assembled once per complete message; advertised lengths do not preallocate payloads. Outbound framing snapshots each submitted message and uses native writable backpressure. Callers await send when producing a sustained stream. There is no history scan, app loop, diagnostic payload store or automatic retry. The authored test/websocket.test.mjs fixtures cover this boundary; source inspection is distinct from executing them or verifying a browser deployment.

resolvePwaRetirementResponse()

async resolvePwaRetirementResponse({workspaceRoot=process.cwd(), appId}={})

Import from arcane-os. This Node API supplies the shared disabled-PWA worker response to an application's existing server without starting or replacing it. It reads the current standalone workspace configuration and root authored descriptor, using the package descriptor only when the authored file is absent. The optional appId must match the selected descriptor. It uses the existing configuration contracts, performs no writes and rereads current configuration on each call; there is no retained cache, timer, subscription or dispose handle.

It returns null for a non-standalone workspace, omitted or enabled PWA, an omitted pwa.enabled field, or an existing root arcane-sw.js entry. The author's explicit pwa.enabled:false choice plus an ENOENT root worker produces {statusCode:200, headers, body}, with the existing JavaScript content type, Cache-Control: no-cache, and the complete retirement script. Configuration/JSON errors and other filesystem failures reject. The result carries no prior worker Last-Modified validator.

The caller owns its exact GET/HEAD /arcane-sw.js route and applies the supplied status, headers and body through its existing node-http-server public serve() path. A null result leaves normal routing intact. There is no request payload transformation, server listener, generated file, cache/storage cleanup, client enumeration or reload. The worker skips waiting on installation and unregisters its own registration on activation; existing-page controller timing remains browser-owned. The custom-host PWA guide shows the complete hook and preservation contract. The Node filesystem path is portable across Windows, Linux and macOS; Android needs its normal Node host adaptation, and browser retirement requires native service-worker support.

startDevServer()

Overview

Starts one owned browser development server with exact runtime/app route mappings and a caller-selected bind address.

Source callers may pass core, a handle returned by createDevelopmentCore(). The server delegates the Core HTTP routes and closes that owner during shutdown. The existing internal localAI handle remains accepted; core takes precedence when explicitly supplied.

HTTP and HTTPS serving use published node-http-server 10.0.0. The SDK selects source routes and supplies generated representations; the module owns static-file conditional GET/HEAD handling and response delivery. The SDK retains modification dates for its generated representations. Unchanged resources can return 304 with no body while changed resources return their complete current representation. PEM-path listeners use module deployment and negotiate HTTP/2 or HTTP/1.1 on the same HTTPS port. Explicit raw tls options retain native HTTPS transport with the same module response and static-file operations.

Static files retain the module's complete built-in MIME map, including PDF, Markdown, audio and video. Generated representations use the same published node-http-server/mime-types map. Existing text charsets and the application/octet-stream fallback for unknown extensions remain unchanged; supported document and media types need no application override.

Signature, modes, and result

async startDevServer(options={})

Import it from arcane-os. Source mode accepts {workspaceRoot=process.cwd(), appId, mode='source', host='127.0.0.1', port=0, httpPort=0, http=false, certPath, keyPath, tls, signal, onEvent} and serves one validated workspace application plus its complete SDK or integrated runtime. Packaged mode uses {mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, http=false, certPath, keyPath, tls, signal, onEvent} and serves the complete selected release files. External source mode accepts both the installed-package route layout and the existing physical runtime layout. Installed-package mode serves the configured SDK resources directly from node_modules at their logical browser URLs; it does not create a workspace arcane/ directory or require arcane.lock.json.

For a standalone appsRoot:'.' source application with explicit pwa.enabled:false and an absent root arcane-sw.js, the exact worker URL returns a small retirement worker. Its native install requests skipWaiting(); activation unregisters only its own registration, without a fetch handler, storage/cache changes, client claiming or page reload. The browser owns update timing and an open page may retain the neutral controller until its lifetime ends. An existing authored worker, omitted/enabled PWA, multi-app source routes and packaged mode stay unchanged. See the complete disabled-worker lifecycle.

host defaults to 127.0.0.1 and accepts an explicit network address or hostname. Use 0.0.0.0 for all IPv4 interfaces or :: for the platform's IPv6 wildcard listeners. port selects the HTTPS application port, and httpPort selects the paired HTTP redirect port. Each defaults to 0, which asks the operating system for an available port. The SDK request hook returns 308 for HTTP with a Location pointing to the actual HTTPS port while preserving the original request path and query. Both listeners use the selected host.

Source servers and packaged browser previews default to HTTPS, including localhost. The existing https option is accepted; https:false and tls:false alone do not disable HTTPS. HTTPS startup reads .arcane/dev/server-cert.pem and .arcane/dev/server-key.pem relative to workspaceRoot unless explicit certPath and keyPath are supplied together; relative paths resolve from the workspace. A direct tls object instead supplies Node HTTPS server options, including cert and key, without reading certificate files. Keep private material server-side. Missing PEM files and Node certificate/key parse errors reject startup without falling back to HTTP. Node owns TLS option handling and the handshake; browser trust and address matching are evaluated when a client connects. The CLI's --public selects the wildcard bind; the API's host option alone changes only the bind address.

Explicit http:true selects one HTTP content listener in source or packaged mode and skips certificate loading. port selects that listener's port, including 0 for an available port. Source mode keeps the same application, runtime and generated PWA routes. Packaged mode serves the complete selected releaseRoot; pass the artifact's web-root directory, not its enclosing native package directory. Its declared application start path, query and fragment are preserved. A caller requiring a stable origin must reuse its selected host and port; a bind conflict rejects startup rather than silently choosing another port. http must be boolean; http:true rejects https:true, explicit certificate/key paths, a tls value other than undefined, null or false, and a nonzero httpPort. Browser secure-context and installation requirements remain browser-owned; see explicit HTTP development.

The promise settles after all selected listeners are ready and resolves to {server, protocol, mode, workspaceRoot, appId, host, port, origin, cleanUrl, url, networkUrls, httpPort, httpOrigin, httpUrl, close, closed, lifecycle}. server is the raw Node server for application content: Http2SecureServer for PEM-backed HTTPS, https.Server for explicit raw tls options, or http.Server for explicit HTTP mode. HTTP/2 uses Node's compatibility request/response APIs; callers accessing the raw server must account for its native type. protocol describes the URL scheme: 'https:' for either negotiated HTTPS protocol or 'http:' with explicit HTTP mode. url and cleanUrl are the same application URL. Wildcard listeners use localhost in that local URL; host retains the actual bound address. httpPort is the actual HTTP listener port, httpOrigin is its HTTP origin, and httpUrl combines that origin with the application start path. These fields identify the redirect endpoint in HTTPS mode; origin, url, cleanUrl, and networkUrls identify application endpoints. In HTTP mode, httpPort, httpOrigin, and httpUrl equal port, origin, and url; they identify the single content listener, with no redirect listener. networkUrls lists application URLs for applicable non-loopback interface addresses discovered once at startup. These URLs are connection candidates, not evidence of reachability from another device. The server adds no session capability or authentication. In packaged mode, workspaceRoot and appId are null.

PEM-path startup reads the selected pair. The server does not create certificates or modify trust stores. Each client must trust the issuing CA and open an address covered by the server certificate. Lifecycle events and CLI summaries exclude TLS options and private key contents. See development HTTPS setup.

Starting the server opens the selected listener or listeners and emits awaited, backpressured server.starting and server.started events. server.started includes the selected protocol, httpPort, httpOrigin, and httpUrl alongside the application endpoint. Request failures emit server.request.failed; shutdown emits server.stopped after owned requests and event delivery drain. Call await result.close() in a finally block, or abort signal; close() is idempotent and returns the same settlement represented by both closed and lifecycle. Closing the operation closes every selected listener once. A listener error or an event-callback failure closes the operation and rejects the lifecycle. Invalid mode/host/port/httpPort, malformed workspace or release content, an occupied port, or an already-aborted signal rejects startup.

Availability and normalization

Node control plane; browser data plane. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {startDevServer} from 'arcane-os';

async function inspectSourceServer(workspaceRoot, signal) {
    const running = await startDevServer({
        workspaceRoot,
        appId: 'example-app',
        mode: 'source',
        host: '127.0.0.1',
        port: 0,
        signal
    });

    try {
        // Hand running.url directly to the intended development browser.
        console.log(`Serving on ${running.origin}`);
        return {origin: running.origin, port: running.port};
    } finally {
        await running.close();
    }
}

startSourceExampleServer()

Overview

Starts a generic server for examples that consume live source trees. The caller explicitly maps URL prefixes to directories, so an example can serve its own small wrapper, SDK src, browser-runtime, and runtime trees, and an external model directory without copying those files or owning a static-server implementation.

Signature, options, and result

async startSourceExampleServer(options={})

Import it from arcane-os. Options are {mounts, startPath='/', host='127.0.0.1', port=0, tls, crossOriginIsolated=false, signal, onEvent}. mounts is a nonempty array of {urlPath, root, index?, include?} records:

• urlPath is an absolute URL path. Nested mounts are allowed and the longest matching URL path owns the request.
• root is a filesystem path or file: URL. It is resolved when the server starts, but the directory does not need to exist until a file is requested.
• index optionally names the relative file used for a mount or directory URL.
• include optionally lists exact relative files and directory prefixes ending in /. When omitted, every regular file under the mount is addressable.

startPath is returned in the public URL and receives a redirect from / when it is not /. host and port are passed to the owned Node listener; an explicit 0.0.0.0 or :: host allows LAN access. tls, when supplied, is the ordinary options object passed to node:https.createServer. Set crossOriginIsolated:true when a browser-WASM example needs Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp; otherwise those headers are absent. The helper adds no Content Security Policy.

GET and HEAD stream the complete selected regular file. A single HTTP Range is handled automatically, including open-ended and suffix ranges. Content length, content range, and range offsets exist only as required HTTP transport framing; they are not size limits, admission rules, progress values, or product policy. Missing mounts remain lazy and return 404 until their files exist. Unsupported methods return 405 and an invalid range returns 416.

The promise settles after the listener is ready and resolves to {server, protocol, host, port, origin, url, close, closed}. server is the raw Node HTTP or HTTPS server, close() is idempotent, and closed settles when the listener closes. It rejects with an operational server failure after the listener closes. An abort signal closes the listener. Optional onEvent receives source-server.starting, source-server.started, source-server.request.failed, and source-server.failed records; an event listener failure is logged without replacing the request outcome.

Availability and normalization

Node control plane; browser data plane. Explicit URL mounts, complete file streaming, protocol-local HTTP ranges, and a closeable server result. Deep protocol: Node ESM.

Example

import {startSourceExampleServer} from 'arcane-os';

async function serveSourceExample(signal) {
    const running = await startSourceExampleServer({
        mounts: [
            {
                urlPath: '/examples/chat',
                root: new URL('./', import.meta.url),
                index: 'index.html',
                include: ['index.html', 'app.js', 'assets/']
            },
            {
                urlPath: '/src',
                root: new URL('../../src/', import.meta.url)
            },
            {
                urlPath: '/browser-runtime',
                root: new URL('../../browser-runtime/', import.meta.url)
            },
            {
                urlPath: '/runtime',
                root: new URL('../../runtime/', import.meta.url)
            },
            {
                urlPath: '/examples/chat/models',
                root: process.env.ARCANE_EXAMPLE_MODEL_ROOT
                    || new URL('./models/', import.meta.url)
            }
        ],
        startPath: '/examples/chat/',
        host: '127.0.0.1',
        port: 8444,
        crossOriginIsolated: true,
        signal
    });

    console.log(`Serving on ${running.url}`);
    return running;
}

validateWorkspace()

Overview

Runs canonical workspace, runtime, descriptor, and selected-app validation with progress events.

Signature and result

async validateWorkspace({
    workspaceRoot=process.cwd(),
    appId,
    allowMissingManagedImportMap=false,
    signal,
    onEvent
}={})

Import it from arcane-os. It resolves to a validation result with valid, workspaceMode, workspaceRoot, appId, appRoot, the selected configuration/application, lock data where the layout uses it, and completed checks. External installed-v1 selection reads package metadata directly and does not require a workspace arcane.lock.json or runtime projection. For an external workspace the result additionally includes the installed package:

const result = {
  sdkInstallation: {
    dependencyName,
    packageSource,
    canonicalPackageRoot,
    packageName: 'arcane-os',
    packageVersion,
    runtimeRoot,
    browserRuntimeRoot
  }
};

The dependency can be named arcane-os or use an npm alias for the selected arcane-os version. The configured package source must match that declaration; packageVersion reports the installed package's version. Duplicate canonical/alias declarations reject. allowMissingManagedImportMap is an internal packaging/development seam. An ordinary caller should leave it false.

Availability and normalization

Node. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Node ESM.

Example

import {validateWorkspace} from 'arcane-os';

const validation = await validateWorkspace({
    workspaceRoot: process.cwd(),
    appId: 'hello-world'
});

console.log(validation.sdkInstallation?.dependencyName);
console.log(validation.sdkInstallation?.packageVersion);

Headless toolchain operations

buildApplication()

Overview

Builds one explicitly selected target through its adapter. A paired native builder packages the selected app and its explicit bundled-app closure, then passes those complete releases to the provider. Provider verification and host launch remain separate operations.

The selected target reaches each app's packager, so every app's own nativeResources and separate native input directory apply consistently to both copying and output-overlap calculations. The provider receives the actual release roots, manifests and complete file readers. An explicit nativeBuilder retains its existing identity and contract. See portable Core packaging.

Signature and result

async buildApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {buildApplication} from 'arcane-os';

async function usebuildApplication(...arguments_) {
    return buildApplication(...arguments_);
}

bundleApplication()

Overview

Creates one deterministic external application bundle from one authenticated packaged release.

The high-level operation reads the app's selected package directory. Its default archive is placed beside that directory; an explicit artifact path retains the existing output-path contract.

Signature and result

async bundleApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {bundleApplication} from 'arcane-os';

async function usebundleApplication(...arguments_) {
    return bundleApplication(...arguments_);
}

checkApplication()

Overview

Runs the selected application or integrated shared validation boundary.

Signature and result

async checkApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {checkApplication} from 'arcane-os';

async function usecheckApplication(...arguments_) {
    return checkApplication(...arguments_);
}

createApplication()

Overview

Creates one new external application workspace through the shared headless toolchain.

Signature and result

async createApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {createApplication} from 'arcane-os';

async function usecreateApplication(...arguments_) {
    return createApplication(...arguments_);
}

createToolchain()

Overview

Returns a frozen convenience object that applies shared defaults to every headless application operation.

The object includes importMap(options), which merges defaults with explicit call options and refreshes every directly navigable descriptor-selected browser document for one selected app. The equivalent generic route is execute('import-map', options). For a standalone root app with pwa.enabled:false, ordinary refresh removes marked SDK-generated PWA references from selected documents. An explicit importMap({retireGeneratedPwa:true}) also retires the four standard root PWA outputs and matching older manifest references after the application owner confirms they are generated. See disabled-PWA retirement for the required source-selection adjustment and preserved content. It also includes upgrade(options), which performs the explicit installed-SDK consumer upgrade described by upgradeApplication(), and updateCheck(options), which invokes checkSdkUpdate() once. Constructing the toolchain does not check, poll, schedule, download, install, regenerate, or mutate anything.

Signature and result

createToolchain(defaults={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {createToolchain} from 'arcane-os';

const toolchain = createToolchain({
    workspaceRoot: process.cwd(),
    appId:'hello-world',
    onEvent(event) {
        console.info(event.type);
    }
});

// Only this explicit call refreshes the managed map and selected HTML documents.
const result = await toolchain.importMap();
console.log(Object.keys(result.importMap.imports).length);
console.log(result.importMap.documentPaths, result.importMap.documentCount);

describeTargets()

Overview

Returns the normalized target catalog through the headless operation lifecycle.

Signature and result

async describeTargets(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {describeTargets} from 'arcane-os';

async function usedescribeTargets(...arguments_) {
    return describeTargets(...arguments_);
}

developApplication()

Overview

Starts one owned browser development server for the selected application.

The selected descriptor's native.services composes application Core services independently of local AI. Programmatic serviceModules:[{module,options}] replaces that list; services adds constructed service definitions and context supplies app-owned launch fields. The result adds core when composed and retains localAI for selected native local AI. Page rendering and the listener do not wait for service readiness. See source-development Core for explicit /arcane-core.js loading, cancellation and current-state replay.

http, https, certPath, keyPath, and tls follow the startDevServer() transport contract, alongside host, port, and httpPort. By default, port selects HTTPS and httpPort selects the HTTP 308 redirect listener; each defaults to an available port. Explicit http:true selects one source HTTP content listener at port, without certificate loading. The operation refreshes the selected authored descriptor's arcane-package.json projection and managed import maps under one development-refresh lock, then releases that lock before opening the selected source listener or listeners. It returns their application endpoints and shared shutdown lifecycle. Package-only apps remain unchanged. The operation generates no packaged output; enabled PWA manifests are served directly from the selected source resources.

The source listener also supplies the disabled-worker retirement lifecycle for explicit disabled standalone PWA configuration when the root worker is absent. This does not grant filesystem retirement authority or change the refresh operation's preservation of authored files. Browser activation and unregistration proceed through the native lifecycle without clearing saved data or reloading an open page.

Signature and result

async developApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {developApplication} from 'arcane-os';

async function usedevelopApplication(...arguments_) {
    return developApplication(...arguments_);
}

executeOperation()

Overview

Dispatches one named headless SDK operation with normalized acceptance, events, cancellation, and failure.

The exact command 'import-map' dispatches one app-scoped refresh across the .html/.htm documents selected by package.documents or automatic discovery, and returns {workspaceRoot, workspaceMode, appId, importMap}. The importMap value reports the generated imports and complete ordered documentPaths. This route mutates the map artifact and selected managed HTML documents through sequential writes and has no supported dry-run or all-file transaction. An error or cancellation can leave completed writes in place; rerun the operation after resolving the cause.

For a standalone appsRoot:'.' app with pwa.enabled:false, ordinary refresh removes active generated registration scripts and matching manifest relationships marked data-arcane-manifest. Unmarked references and existing PWA files remain. Set retireGeneratedPwa:true only after confirming generated ownership of the matching root manifest references and all four standard outputs: arcane.webmanifest, arcane-offline.json, arcane-sw.js and arcane-pwa.mjs. Remove those generated outputs from required package.include entries first, and confirm that unselected documents no longer need them. The operation writes selected reference changes before deleting these files; its import-map.root-files.completed event reports actual removed paths in retiredPwa. Repeated retirement accepts already-absent output.

An omitted PWA record selects no retirement; an enabled record keeps normal generation. The option belongs only to this explicit import-map API route. Ordinary development refresh does not forward file-retirement authority, and there is no new CLI flag. Other files, unselected/inactive HTML, authored content and browser registrations, caches and saved data keep their existing ownership. See the complete source PWA contract.

The exact command 'upgrade' dispatches upgradeApplication(options). It is external-workspace-only and runs that application's ordinary npm upgrade command. It does not independently reconcile the installed SDK projection, semantic Arcane lock, or managed import map; npm retains authority for dependency selection and network behavior.

The exact command 'update-check' dispatches one checkSdkUpdate(options) call. Dispatch never installs a recurring task, polls application state, or causes another command to check for updates implicitly. There is no exported importMapApplication() or generateImportMap() binding and no arcane-os/import-map package subpath.

Signature and result

async executeOperation(command, options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {executeOperation} from 'arcane-os';

const result = await executeOperation('import-map', {
    workspaceRoot:process.cwd(),
    appId:'hello-world'
});
console.log(result.importMap.committed, Object.keys(result.importMap.imports).length);
console.log(result.importMap.documentPaths, result.importMap.documentCount);

packageApplication()

Overview

Runs the high-level package operation for one selected application. It reads the installed SDK/runtime selection and packages the saved source and managed import maps through packageApp(). Map generation remains the explicit arcane import-map operation and the ordinary arcane dev startup refresh. Root app files retain their paths at the output root, while explicitly nested apps retain apps/<id>/ paths alongside the shared routes and any root launcher described by packageApp().

The same low-level operation resolves the app's optional outputDirectory; there is no separate high-level destination override. release.outputRoot names the resulting complete release directory, with omitted configuration retaining dist/<app-id>. Browser preview and bundle creation use that selected root. This ordinary package operation retains browser selection; paired native assembly through buildApplication() separately passes its actual target and applies each app's native-resource output selection.

Packaging does not automatically run tests or checks. Verification occurs only when explicitly requested or when required for the selected release output. A failure leaves the prior distribution untouched. Success returns the selected workspace and app identity plus release, containing the low-level package result, manifest, and complete file inventory. ARCANE_APP_RELEASE.json records that inventory and the distinct app-relative app.entry and package-relative app.start; it remains package metadata rather than an application route.

Signature and result

async packageApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {packageApplication} from 'arcane-os';

const result = await packageApplication({
    workspaceRoot: process.cwd(),
    appId: 'hello-world'
});

console.log(result.release.manifest.app.start, result.release.files);

planApplication()

Overview

Creates one authenticated native build plan without executing the provider build.

Signature and result

async planApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {planApplication} from 'arcane-os';

async function useplanApplication(...arguments_) {
    return planApplication(...arguments_);
}

repositoryApplication()

Overview

Dispatches one selected repository status, pull, or push operation through the headless lifecycle.

Signature and result

async repositoryApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {repositoryApplication} from 'arcane-os';

async function userepositoryApplication(...arguments_) {
    return repositoryApplication(...arguments_);
}

runApplication()

Overview

Runs a browser app or performs the selected native build/launch lifecycle for one target. It does not run tests or checks automatically; selected release-output verification remains explicit to that release operation.

Browser runs resolve the app's current outputDirectory, defaulting to dist/<app-id>, and preview that existing release without repackaging it. Native artifact output remains separately selected by its target contract.

Signature and result

async runApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {runApplication} from 'arcane-os';

async function userunApplication(...arguments_) {
    return runApplication(...arguments_);
}

testApplication()

Overview

Runs the selected application's exact test boundary or one integrated shared test. For external and modern integrated apps, app-scope testing authenticates the existing managed import-map artifact against the selected runtime and each selected HTML document before launching isolated files. The child loader maps only exact entries such as arcane/SpeechPlayback, preserves arcane-os/testing, resolves supported URL-like compatibility keys, and rejects an unmapped arcane/* or #arcane/* specifier. The compact map locator is removed from the child environment before application test code is imported.

Signature and result

async testApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {testApplication} from 'arcane-os';

async function usetestApplication(...arguments_) {
    return testApplication(...arguments_);
}

upgradeApplication()

Overview

Runs the selected external installed-SDK application's ordinary npm upgrade command without adding a separate lock, runtime, import-map, authentication, or reconciliation workflow. npm retains authority for dependency selection and network behavior.

Signature and result

async upgradeApplication(options={})

The mutable arcane-application-upgrade result includes workspaceRoot, workspaceMode, appId, and the normal process result (command, args, cwd, code, stdout, and stderr).

Availability and normalization

Node; external installed-SDK workspaces only. SDK-normalized inputs, errors, events, and documented process results.

Example

import {upgradeApplication} from 'arcane-os';

const upgraded=await upgradeApplication({
    workspaceRoot:process.cwd(),
    appId:'hello-world'
});
console.log(upgraded.command,upgraded.args,upgraded.code);

verifyApplication()

Overview

Runs the high-level verification operation for one selected browser release.

Signature and result

async verifyApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {verifyApplication} from 'arcane-os';

async function useverifyApplication(...arguments_) {
    return verifyApplication(...arguments_);
}

verifyBundleApplication()

Overview

Runs the high-level external bundle verification operation.

Signature and result

async verifyBundleApplication(options={})

Import it from arcane-os or arcane-os/toolchain. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node; selected operation may produce browser or native output. SDK-normalized inputs, errors, events, and documented result. Deep protocol: Shared headless operation API + arcane-cli-events/1.

Example

import {verifyBundleApplication} from 'arcane-os';

async function useverifyBundleApplication(...arguments_) {
    return verifyBundleApplication(...arguments_);
}

Events, processes, and testing

createReporter()

Overview

Creates the ordered CLI reporter that normalizes accepted, progress, terminal, JSON, and NDJSON event delivery.

Signature, state, and output

createReporter({ command, output='human', stdout=process.stdout, stderr=process.stderr, operationId=randomUUID(), clock=()=>new Date() }={})

Import it from arcane-os or arcane-os/events. This function returns synchronously. output must be "human", "json", or "ndjson". stdout and stderr are writable streams; operationId and clock can be injected for deterministic tests.

The returned object is {operationId, output, accept, emit, forward, complete, reject, accepted, terminal}. accepted and terminal are live getters. Call accept(data) before emit(type, data, message) or forward(value, data). Acceptance happens once; later accept() calls return null. complete(result) and reject(error) are mutually terminal, and later progress or terminal calls return null. Each emitted event contains arcane-cli-events/1, the operation id, a strictly increasing sequence, an ISO timestamp, the command, type, status, and JSON-safe data. Circular members and unsupported JSON values are omitted; errors are reduced through errorRecord().

Human mode writes work events to stderr, readable results to stdout, and a completion line to stderr. JSON mode writes work events to stderr and exactly one final success/error envelope to stdout. NDJSON mode writes every event to stdout. Reporter methods write synchronously to the supplied streams; they do not provide backpressure promises, cancellation, or receipts. An unsupported mode, emit() before acceptance, an invalid clock result, or a stream write failure throws synchronously.

Availability and normalization

Node. SDK event/error/report normalization. Deep protocol: arcane-cli-events/1.

Example

import {createReporter} from 'arcane-os';

const reporter = createReporter({command: 'check', output: 'human'});

reporter.accept({appId: 'example-app'});
reporter.emit(
    'workspace.validate.check',
    {name: 'descriptor', ok: true},
    'Validated the application descriptor.'
);
reporter.complete({ok: true});

default()

Overview

Default-export alias of the public test registration function.

Signature and result

default(name, optionsOrCallback, maybeCallback)

Import it from arcane-os/testing. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK event/error/report normalization. Deep protocol: Node ESM / owned process or test lifecycle.

Example

import test from 'arcane-os/testing';

test('adds two values', () => {
    if (1 + 1 !== 2) throw new Error('Unexpected result.');
});

DEFAULTTESTTIMEOUT_MS

Overview

Default timeout applied by the public isolated test API.

Value and import

const DEFAULT_TEST_TIMEOUT_MS

Import it from arcane-os or arcane-os/testing. Treat arrays and records as immutable public values.

Availability and normalization

Node. Exact immutable SDK value. Deep protocol: Node ESM / owned process or test lifecycle.

Example

import {DEFAULT_TEST_TIMEOUT_MS} from 'arcane-os';

console.log(DEFAULT_TEST_TIMEOUT_MS);

registeredTestCount()

Overview

Returns the number of tests registered in the current isolated test realm.

Signature and result

registeredTestCount()

Import it from arcane-os or arcane-os/testing. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK event/error/report normalization. Deep protocol: Node ESM / owned process or test lifecycle.

Example

import {registeredTestCount} from 'arcane-os';

console.log(registeredTestCount());

createGitTextSnapshot()

Overview

Reads complete application-selected UTF-8 text from one fetched revision using a dedicated bare Git cache. It does not create or alter a working checkout.

Signature, lifecycle, and result

createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,allowUnborn=false,gitIdentity,onEvent,run=runProcess}={})

Import from arcane-os. The application owns the cache location, remote, ref, path predicate and service factory. The returned refresh({signal}={}) returns {revision,files:[{path,content}]} in Git tree order. Concurrent calls share work; unchanged fetched revisions reuse completed text retrieval. Caller cancellation ends only that wait. close(), drain() and dispose() stop acceptance and await accepted refresh/process cleanup. Errors remain observable instead of returning stale or partial success. See Git text snapshots for complete inputs, text semantics, errors, events and Core service composition.

Optional allowUnborn:true observes the complete remote advertisement on every acquisition. Only successful empty output returns {revision:null,files:[],unborn:true}; committed results add unborn:false and retain the actual commit even for an empty tree. Any advertised HEAD, branch or tag continues through ordinary selected-ref fetch; missing refs and actual Git failures remain errors. Omitted/false preserves the prior result and commands. See unborn remotes.

Optional remoteBase explicitly selects remote as a local filesystem locator. Only its Git fetch argument is derived using path.resolve(remoteBase, remote), once at construction, independently of the cache location and later changes to the working directory. Relative bases, including '', use the construction-time working directory. Original locator/options remain unchanged. Omission preserves Git remote names, URLs, SCP-like addresses and remote-helper strings without guessed parsing. Unrepresentable base text reports TypeError without transformation; actual Git failures retain their existing error behavior. See relative local repository locators.

Optional gitIdentity:{name?,email?,username?} captures a child-process-only selection for init/fetch and subsequent Git commands, preserving shared refresh cancellation and complete content. See Git identity configuration for author precedence, scoped defaults and credential username semantics.

Example

import {createGitTextSnapshot} from 'arcane-os';

const dispatches = createGitTextSnapshot({
    cacheDirectory: applicationCacheDirectory,
    remote: applicationRepository,
    ref: applicationRef,
    selectPath: function selectDispatch(filename) {
        return filename.startsWith('dispatches/') && filename.endsWith('.md');
    }
});
const snapshot = await dispatches.refresh({signal});
await dispatches.close();

runProcess()

Overview

Runs one shell-free child command with complete stdout and stderr, ordered stream events, heartbeats, and explicitly selected process cancellation behavior.

Signature, parameters, and result

async runProcess(command, args=[], { cwd, env, signal, onEvent, onOutput, captureOutput=true, emitOutputEvents=true, outputEncoding='utf8', heartbeatMs=5000, terminationGraceMs=DEFAULT_TERMINATION_GRACE_MS, allowNonzero=false, input, cancellationMode='terminate-tree' }={})

Import it from arcane-os. command is executed directly with shell:false; args must be a fixed array of strings, so shell expansion, pipelines, and redirection never occur. cwd selects the child directory. env is shallowly merged over process.env. In the default cancellationMode:'terminate-tree', supplied input is written once and stdin is closed; otherwise stdin closes immediately. With cancellationMode:'close-input', optional input is written once and stdin remains open until cancellation or a callback/input failure requests shutdown. On Microsoft NT, npm and npx are normalized to their Node CLI entrypoints.

For the literal git command on Windows, the default runner reads Git for Windows' registered InstallPath in the current-user and machine registry views. When that installation's cmd/git.exe exists, its cmd directory is appended only to this child's effective PATH. Existing entries and native command lookup retain priority; duplicate Path/PATH spellings follow Node's lexical selection. Other environment fields, explicit executable paths, custom process adapters, other commands and other platforms keep their existing behavior. No global environment or registry setting is changed, and no Git download, installation or command retry occurs.

One successful location is retained in memory for this process while its executable remains present. A removed executable triggers fresh discovery; absent, failed and cancelled lookups are not retained. Concurrent cold callers own independent discovery and cancellation. The standard Windows registry helper uses the existing process owner; its lifecycle callbacks have process.git.discovery.* event names, and its captured metadata is separate from the requested command's output. Missing registration leaves ordinary lookup unchanged. Discovery failure emits process.git.discovery.unavailable with the complete error before ordinary lookup continues. Cancellation or an event-callback failure stops the operation before Git starts. Normal Git errors and missing-working-directory errors remain actual command failures.

An AsyncIterable input instead feeds stdin with awaited writes and closes it when the producer finishes. Its return() must cooperate with cancellation of an outstanding next(); the process owner drains both input and output work. onOutput({stream,chunk}) receives complete ordered chunks and is awaited with backpressure for each stream. UTF-8 decoding retains split characters. The default capture and nonempty-line events remain unchanged; line events are not a substitute for lossless chunk delivery.

captureOutput and emitOutputEvents accept booleans or per-stream selections, for example {stdout:false} while stderr retains its default. A stream with capture disabled returns null and requires an onOutput consumer. outputEncoding defaults to 'utf8'; explicitly selecting null, globally or per stream such as {stdout:null}, delivers native Buffer chunks unchanged. A raw stream requires capture and line events explicitly disabled for that stream plus an onOutput owner. It is never decoded or sent as text implicitly. Complete failed chunks, original callback failures, process diagnostics and exit results remain available through the normal error record after drain.

onEvent is awaited in order for process.starting, nonempty process.stdout/process.stderr lines, coalesced process.heartbeat, and the terminal process event. Stream delivery pauses the corresponding child stream while the callback owns that chunk. heartbeatMs defaults to 5 seconds; the timer applies a 1-second floor to ordinary numeric values. terminationGraceMs defaults to 1,500 ms and must be an integer from 100 through 30,000. allowNonzero:false rejects a nonzero exit; true returns it as data.

The promise resolves to {command, args, cwd, code, signal, stdout, stderr}. Here signal is the child's terminating signal name or null, not the input AbortSignal. args is copied, cwd defaults to the current process directory, and each captured text stream preserves its complete content. A missing executable rejects with ARCANE_PREREQUISITE_MISSING; invalid arguments, a disallowed nonzero exit, and spawn/runtime failures use the normalized SDK error boundary, with the nonzero result retained in error details.

Aborting signal emits cancellation-requested state. The default mode terminates the owned process tree and escalates after the grace interval. close-input instead closes only the child's stdin, with no forced termination or deadline; the selected child must own EOF shutdown. This lets a native host finish accepted service work before exiting. Both paths continue observing output and drain event delivery before rejection with ARCANE_CANCELLED and exit code 130. An abort after the child's close event does not cancel already completed work.

An onEvent failure requests shutdown through the same selected mode. The close-input failure retains the child's complete result in details and additional failures in errors, with the original primary error as cause when wrapping is needed. A cancellation rejection can therefore contain a successful child exit code 0; that is the child's drained result, distinct from the cancelled caller operation. Cancellation cannot reverse external effects already performed by the command.

Availability and normalization

Node. SDK event/error/report normalization. Deep protocol: Node ESM / owned process or test lifecycle.

Example

import {runProcess} from 'arcane-os';

const result = await runProcess(process.execPath, ['--version'], {
    cwd: process.cwd(),
    onEvent(event) {
        if (event.type === 'process.stderr') console.error(event.message);
    }
});

console.log(result.stdout.trim(), result.code);

runRegisteredTests()

Overview

Executes the current isolated realm's registered tests once and returns the normalized Vanilla Test report.

Signature, lifecycle, and result

async runRegisteredTests({signal, requireTests=true, onPhase}={})

Import it from arcane-os or arcane-os/testing. Register every top-level test with test() before this call. One module realm can run its registry only once; a second call rejects with ReferenceError. With requireTests:true, an empty registry becomes one failed report outcome. Set it to false only when an empty suite is intentional.

Tests run sequentially. A test callback receives {signal, after(callback), test(name, options?, callback)} for cooperative cancellation, FIFO cleanup, and owned nested tests. Each test uses its declared timeout or DEFAULT_TEST_TIMEOUT_MS; test timeouts can abort the remainder of the run, cleanup and report phases have their own bounded timeouts, and cleanup is skipped after fatal timeout or cancellation because JavaScript promises cannot be preempted safely. The awaited onPhase callback receives started and completed records for test, cleanup, and report phases. A phase-callback failure is authoritative and can reject the run.

The promise resolves to the frozen Vanilla Test snapshot {passed, failed, total, failureCount, ok, report}. passed and failed are frozen description arrays and report is the rendered text. Ordinary assertion failures produce ok:false; invalid API use, cancellation, a fatal timeout, or an authoritative phase/report failure rejects. Aborting signal propagates to the currently owned test and stops later tests, but test callbacks must observe their supplied signal to stop host work cooperatively.

Availability and normalization

Node. SDK event/error/report normalization. Deep protocol: Node ESM / owned process or test lifecycle.

Example

import {runRegisteredTests, test} from 'arcane-os/testing';

test('normalizes an application id', () => {
    const value = 'example-app'.trim();
    if (value !== 'example-app') throw new Error('Unexpected id.');
});

const report = await runRegisteredTests({
    onPhase(phase) {
        if (phase.status === 'started') console.log(phase.name);
    }
});

if (!report.ok) process.exitCode = 1;

test()

Overview

Registers one public test, optional timeout, callback, nested cases, and FIFO cleanup in the isolated runner.

Signature and result

test(name, optionsOrCallback, maybeCallback)

Import it from arcane-os or arcane-os/testing. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.

Availability and normalization

Node. SDK event/error/report normalization. Deep protocol: Node ESM / owned process or test lifecycle.

Example

import {test} from 'arcane-os';

test('adds two values', () => {
    if (1 + 1 !== 2) throw new Error('Unexpected result.');
});

Explicit SDK update checks

This is an on-demand Node.js control-plane and CLI maintainer surface. It never runs from renderer application code automatically. One call can make one ordinary HTTP or HTTPS GET to the selected npm registry and reads the complete response subject only to unavoidable HTTP framing; there is no polling, recurrence, interval, background agent, download, install, dependency mutation, runtime replacement, or self-update. The only timer is the timeout owned and cleared by that one request.

SDKUPDATEREGISTRY

Overview

Default npm registry root for an explicit SDK update check.

Value

const SDK_UPDATE_REGISTRY = 'https://registry.npmjs.org/'

The request builder appends the fixed -/package/arcane-os/dist-tags endpoint only after validating the root.

Availability and normalization

Node; on-demand CLI or maintainer check only. Exact default HTTPS origin string. Importing it performs no request and starts no timer.

Example

import {SDK_UPDATE_REGISTRY, validateUpdateRegistry} from 'arcane-os';

const registry = validateUpdateRegistry(SDK_UPDATE_REGISTRY);
console.log(registry.origin);

SDKUPDATETIMEOUT_MS

Overview

Default timeout for the single registry request owned by an explicit update check.

Value

const SDK_UPDATE_TIMEOUT_MS = 2500

Availability and normalization

Node; on-demand CLI or maintainer check only. Exact default millisecond integer. Accepted per-call timeouts are positive safe integers.

Example

import {SDK_UPDATE_TIMEOUT_MS} from 'arcane-os';

console.log(`Update-check timeout: ${SDK_UPDATE_TIMEOUT_MS} ms`);

checkForSdkUpdate()

Overview

Performs exactly one complete registry read and reports whether the npm dist-tag selected for the installed SDK is newer. It only checks metadata; it does not download, install, mutate, or schedule anything.

Signature and parameters

async checkForSdkUpdate({
    packageName=SDK_NAME,
    currentVersion=SDK_VERSION,
    registry=SDK_UPDATE_REGISTRY,
    timeoutMs=SDK_UPDATE_TIMEOUT_MS,
    fetchImpl=globalThis.fetch,
    signal,
    onEvent,
    clock=()=>new Date()
}={})

packageName must be exactly arcane-os. currentVersion must be strict semantic version text: prereleases select npm dev, while stable versions select latest. registry must pass validateUpdateRegistry(); ordinary HTTP and HTTPS npm registries, including caller-selected local or corporate paths, remain functional. fetchImpl and clock are explicit injection points. timeoutMs is a positive safe integer. signal provides caller cancellation, and each supplied onEvent callback is awaited.

The request is one ordinary GET accepting JSON and follows the selected runtime's normal registry behavior. The response must return HTTP 200 and JSON media type, be valid UTF-8, and decode to a nonempty dist-tag object whose string values are strict semantic versions.

Result, events, and errors

The promise resolves to a mutable object:

{
    packageName,
    currentVersion,
    registryVersion,
    tag,                 // 'dev' or 'latest'
    status,              // 'update-available', 'current', or 'ahead'
    updateAvailable,
    registry,            // normalized origin
    checkedAt            // clock().toISOString()
}

After initial validation it emits awaited update.check.started. Success emits update.check.completed; a non-cancellation request or response failure emits update.check.failed with the normalized failure code. Registry, timeout, HTTP, content, JSON, dist-tag, version, or clock failures reject with ARCANE_UPDATE_CHECK_FAILED. Caller cancellation rejects with ARCANE_CANCELLED; it is distinct from the per-request timeout. Event callbacks are awaited, and a callback rejection can reject or replace the operation's normal settlement; it is never ignored. The owned timeout is cleared in finally.

Availability and normalization

Node; on-demand CLI or maintainer check only. Registry data is reduced to one mutable status result. No provider payload becomes installation authority, and applications never invoke this function automatically.

Example

import {checkForSdkUpdate} from 'arcane-os';

// Defined for an explicit maintainer action; this function is not scheduled.
async function checkInstalledSdkOnce(signal) {
    const result = await checkForSdkUpdate({
        signal,
        onEvent(event) {
            console.info(event.type, event.message);
        }
    });

    console.log(result.status, result.registryVersion);
    return result;
}

checkSdkUpdate()

Overview

High-level toolchain/CLI wrapper for exactly one checkForSdkUpdate() call.

Signature and result

async checkSdkUpdate(options={})

Import it from arcane-os or arcane-os/toolchain.

It forwards the options unchanged and preserves the direct result, events, errors, cancellation, timeout, and security boundary. executeOperation() routes the exact command 'update-check' here, and createToolchain() exposes it as updateCheck(options). Neither route polls or schedules a later call.

Availability and normalization

Node; on-demand CLI or maintainer check only. Same normalized contract as checkForSdkUpdate() with no additional request or mutation.

Example

import {checkSdkUpdate} from 'arcane-os';

async function runRequestedUpdateCheck(signal) {
    const result = await checkSdkUpdate({signal});
    return result.updateAvailable;
}

compareSdkVersions()

Overview

Synchronously compares two strict semantic SDK versions without network access.

Signature and result

compareSdkVersions(leftValue, rightValue)

Returns -1 when the left version has lower precedence, 0 when precedence is equal, and 1 when it is higher. Major, minor, patch, then semantic prerelease identifiers are compared. A stable version outranks a prerelease at the same core version; build metadata does not affect precedence. Invalid input throws the packager's semantic-version validation error synchronously.

Availability and normalization

Node; on-demand CLI or maintainer check only. Pure in-process comparison; no request, timer, event, mutation, or cancellation contract.

Example

import {compareSdkVersions} from 'arcane-os';

console.log(compareSdkVersions('0.1.0-dev.4', '0.1.0-dev.5')); // -1
console.log(compareSdkVersions('1.0.0+local', '1.0.0+registry')); // 0

updateTagForVersion()

Overview

Selects the one npm dist-tag appropriate for an installed SDK version.

Signature and result

updateTagForVersion(value)

Returns 'dev' when the strict semantic version contains any prerelease identifier and 'latest' otherwise. Invalid input synchronously throws ARCANE_UPDATE_CHECK_FAILED with the semantic-version error as its cause.

Availability and normalization

Node; on-demand CLI or maintainer check only. Pure dev/latest normalization; no registry request or state change.

Example

import {updateTagForVersion} from 'arcane-os';

console.log(updateTagForVersion('0.1.0-dev.4')); // dev
console.log(updateTagForVersion('1.0.0'));       // latest

validateUpdateRegistry()

Overview

Synchronously validates one ordinary HTTP or HTTPS registry URL.

Signature and result

validateUpdateRegistry(value)

The URL must use HTTP or HTTPS. Caller-selected credentials, ports, paths, queries, and normal redirects remain under the selected registry and Fetch runtime. The function returns the normalized URL object and performs no DNS lookup or request.

Invalid syntax or an unsupported scheme throws synchronously with ARCANE_UPDATE_CHECK_FAILED.

Availability and normalization

Node; on-demand CLI or maintainer check only. URL normalization only; no request, polling, or mutation.

Example

import {SDK_UPDATE_REGISTRY, validateUpdateRegistry} from 'arcane-os';

const registry = validateUpdateRegistry(SDK_UPDATE_REGISTRY);
console.log(registry.href); // https://registry.npmjs.org/

Central events, time travel, and DOM instrumentation

ARCANEEVENTSTACK_PROTOCOL

Overview

The exact discriminator for serialized Arcane event-stack documents and every record they contain. Use it to reject incompatible diagnostic files before review or playback.

Value and use

const ARCANE_EVENT_STACK_PROTOCOL = 'arcane-event-stack/1'

This is a data-format version, not the Core arcane/1 RPC protocol and not a network transport. parseEventStack() enforces it on the document and each retained record. Full operational guidance: central events, DOM instrumentation, and time-travel review.

Availability and normalization

Node and browser/bundler. Exact host-neutral protocol string; it grants no capability or authority.

Example

import {ARCANE_EVENT_STACK_PROTOCOL} from 'arcane-os/event-manager';

if (document.protocol !== ARCANE_EVENT_STACK_PROTOCOL) {
    throw new Error('Unsupported event stack.');
}

DEFAULTDOMEVENT_TYPES

Overview

The mutable default list of 44 capture-phase browser interaction names observed by DOM instrumentation. Pass a smaller eventTypes array when a debugger needs only a focused interaction class.

Value and use

const DEFAULT_DOM_EVENT_TYPES

The list is configuration, not an event source. Observation begins only after a controller starts, normally because time travel is enabled on a manager with attached DOM instrumentation. Full operational guidance: central events, DOM instrumentation, and time-travel review.

Availability and normalization

Node and browser/bundler; meaningful to browser DOM instrumentation. The array contains the exact event-name strings; live host event objects are never stored in this value.

Example

import {DEFAULT_DOM_EVENT_TYPES} from 'arcane-os/event-manager';

console.log(DEFAULT_DOM_EVENT_TYPES.includes('click'));

DOMINTERACTIONEVENT

Overview

The event name used for complete diagnostics of captured clicks, keys, pointer actions, form activity, and the other configured DOM interactions. Its payload describes the target and path without retaining DOM nodes and preserves readable event details and target values.

Value and use

const DOM_INTERACTION_EVENT = 'arcane.dom.interaction'

Listen on the EventManager to update a debugger in real time. DOM instrumentation records complete readable interaction details and target values. Full operational guidance: central events, DOM instrumentation, and time-travel review.

Availability and normalization

Browser DOM or a DOM-compatible test host; constant imports in Node. Target, path, flags, and enabled details are normalized diagnostics, not replayable browser event objects.

Example

import {DOM_INTERACTION_EVENT, arcaneEvents} from 'arcane-os/event-manager';

arcaneEvents.on(DOM_INTERACTION_EVENT, diagnostic => {
    console.log(diagnostic.eventType, diagnostic.target?.selector);
});

DOMMUTATIONEVENT

Overview

The event name used for normalized attribute, character-data, and child-list mutation diagnostics. It lets review tools correlate observable DOM changes with the interaction that preceded them.

Value and use

const DOM_MUTATION_EVENT = 'arcane.dom.mutation'

Mutation capture uses MutationObserver and is enabled by default when DOM instrumentation starts. Complete markup, text, selectors, URLs, and attribute values are preserved. Full operational guidance: central events, DOM instrumentation, and time-travel review.