Capabilities
Pages only get the standard Web APIs. There is exactly one way into system capabilities: the built-in acde: modules, imported the same way as node:fs:
import { fs } from 'acde:fs'import { window } from 'acde:window'import fs2 from 'acde:fs' // the default export is the same objectThere is no acdev global, and the runtime never attaches anything non-standard to window.
Talking to other hosts needs no capability: fetch, WebSocket, and the other standard APIs work as usual, through the system's proxy when one is set. See Web compatibility.
Requesting capabilities
Section titled “Requesting capabilities”The capabilities in your config decide which modules an app can import:
{ "capabilities": { "fs": true, "openFiles": true, "open": ["notes", "viewer"] }}| Capability | Grants |
|---|---|
fs |
acde:fs. true: the app's private folder and the folders the user picks for it. { "roots": ["downloads", … ] } adds shared places; see Files and folders |
terminal |
acde:terminal: pseudo-terminals |
network |
acde:network: network settings, Wi-Fi (Linux only, including Dopame OS) |
system |
acde:system: host name, time zone and clock sync, storage, the user (Linux only) |
bluetooth |
acde:bluetooth: the adapter, pairing and devices (Linux only) |
audio |
acde:audio: sound devices, volume, streams (Linux only) |
devices |
acde:devices: drives (mount, eject, automount) and printers (Linux only) |
power |
acde:power: batteries, power profiles and settings, suspend, brightness (Linux only) |
input |
acde:input: keyboard layouts, mouse and touchpad, input methods (Linux only) |
display |
acde:display: display modes, scale, rotation, brightness, night light (Linux only) |
office |
acde:office: office document service (Linux only) |
open |
Opening other apps with acde:open. true for any app, or a list of app ids |
openFiles |
acde:openPath / acde:handlers, and open(request) without a target app: a file or a link goes to its default app |
launch |
start in acde:launch: start native programs |
slots |
embed in acde:launch: native programs embedded in your own window (Dopame OS only) |
camera / microphone |
navigator.mediaDevices.getUserMedia() video / audio (not on Windows); the user is asked, see below |
idleDetection |
IdleDetector (Linux only); the user is asked when the page calls IdleDetector.requestPermission() |
Every app can import these without requesting anything: acde:window (its own window), acde:capabilities (what it has, see below), acde:apps (list() and open()), and acde:open (opening another app still needs open).
A name that is not in the table is an error in acdev check:
- Desktop services are listed under
services, not undercapabilities:"services": ["clock"], thenimport { clock } from 'acde:clock'. The app then starts only in a desktop that runs the service. See Services. - Shell modules (
acde:windows,acde:packages,acde:session,acde:desktops,acde:inspect,acde:desktop,acde:setDefault,acde:permissions) belong to the desktop. Only the desktop page, its services, and the apps bundled with a desktop (system apps) get them; see Desktops.
Importing a module the app has no right to fails with an AcdeError (an Error with name === 'AcdeError', code: 'forbidden', status: 403, and module, the name without acde:) whose message names the missing declaration; a module whose service stopped fails the same way with code: 'service_not_running' and status: 503 (see Errors). acdev check and acdev build report the same thing for every import in your source before anything runs:
error: app "notes": capability "clock" is not a system capability; list desktop services under serviceserror: src/main.js:1: app "notes": acde:terminal needs "terminal" in the capabilities of Noteserror: src/main.js:2: app "notes": acde:windows is a shell module: only the desktop, its services and system apps may import it, and Notes is not a system appCalling a method the app has no right to is rejected with status: 403 (code: 'forbidden'), for example open('mail') when open lists only other apps.
Camera and microphone
Section titled “Camera and microphone”Declaring a capability is what gives the app access to it: nothing is asked, also for shared places in fs.roots, terminal, network, launch and slots. Only the camera and the microphone ask the user, and idle detection (idleDetection, when the page calls IdleDetector.requestPermission()), which asks the same way. The apps bundled with a desktop (system apps) are not asked.
- When: the first time a page calls
navigator.mediaDevices.getUserMedia()(orrequest(), below); the call waits for the answer. This holds for a camera or microphone the app requires too. - Allowed: the decision is stored per app (
$XDG_CONFIG_HOME/acde/permissions.json) and the user is not asked again. - Denied:
getUserMedia()rejects withNotAllowedError, as in a browser. The app keeps running and stays in the app list, also when it requires the one denied. - Who asks: in a desktop, the desktop shows the prompt (see Desktops). In the host window of a single app, Windows asks in a dialog, a macOS host window in a sheet (
Allow/Don't Allow) and a Linux host window in a desktop notification with Allow and Deny (without a notification service, nothing shows). - In a Dopame OS session: the camera and the microphone are not available yet, also when declared:
getUserMedia()rejects at once withNotAllowedErrorand nothing asks. - In a dev session: answer with
acdev alloworacdev deny(also when nothing shows, and headless), take a decision back withacdev revoke; see Debugging. Tests answer withacde.allow()(see Testing).
Optional capabilities
Section titled “Optional capabilities”Everything in capabilities is required by default: if the platform lacks one, the app does not start. List the ones the app can run without in optional:
{ "capabilities": { "terminal": true }, "optional": ["terminal"]}- The app also starts on a platform that lacks the capability.
- An optional module must not be imported statically (
acdev check:acde:terminal is optional ("terminal" is in optional): import it dynamically, await import('acde:terminal'), which rejects where this platform lacks it). Import it dynamically; the promise rejects while the module is unavailable. cameraandmicrophonehave no module to load: the page callsnavigator.mediaDevices.getUserMedia(), which asks the user the first time. See Web compatibility.
const terminal = await import('acde:terminal').then((m) => m.default, () => null) // null where this platform lacks itMaking fs optional makes its shared places optional too.
acde:capabilities
Section titled “acde:capabilities”import { capabilities } from 'acde:capabilities'
capabilities.level // 1: the contract level of the runtimecapabilities.platform // 'linux' | 'darwin' | 'win32'capabilities.mode // 'session' (Dopame OS) | 'desktop' (a desktop in the host window) | 'standalone' (a single app in the host window)capabilities.get('terminal') // { name, kind: 'system' | 'service', state, reason, optional }capabilities.list() // the same for every system capability and shell module, notifications, and each fs.<place> and service the app declaresawait capabilities.request('camera') // asks the user for the camera or microphone; resolves with the statusstate |
Meaning |
|---|---|
available |
Declared and this platform has it (camera, microphone: and the user allowed it) |
not-asked |
Camera or microphone, and the user was not asked yet: request() asks |
asking |
The camera or microphone prompt waits for the user's answer |
not-declared |
Not in the app's capabilities / services |
unsupported |
This platform, or this way of running, lacks it |
service-not-running |
The desktop service is not running |
shell-only |
A shell module, and the app is not a system app |
denied |
Camera or microphone: the user denied it, or the decision was taken back |
request() of any other capability, or of one the user already answered, resolves at once with the current status.
notifications is the standard Notification API, which needs no declaration: it is available, or unsupported where this way of running shows no notifications (a single app on Windows).
Types for every module ship in the SDK, @dopame/acde-api. Reference the entry point that fits the project and your editor understands the acde:* modules it can import:
/// <reference types="@dopame/acde-api/app" />@dopame/acde-api/app: the modules of an app (acde:fs,acde:window,acde:open, ...).@dopame/acde-api/shell: those plus the shell modules, for a desktop and its bundled apps.@dopame/acde-api: all of them.
In a browser
Section titled “In a browser”To preview the same code in an ordinary browser:
- Import
acde:modules dynamically and fall back when the import rejects (a browser has noacde:modules):
const fs = await import('acde:fs').then((m) => m.default, () => null)Modules
Section titled “Modules”| Module | Purpose | Docs |
|---|---|---|
acde:window |
Your own window: title, menus, closing, state, shortcuts, events | Windows |
acde:capabilities |
What the app has, asking for optional capabilities | Above |
acde:fs |
Files | Files and folders |
acde:apps acde:open acde:openPath acde:handlers |
Other apps, opening files and links | Opening apps |
acde:launch |
Native programs | Reference |
acde:terminal |
Pseudo-terminals | Reference |
acde:network |
Networking | Reference |
acde:windows acde:packages acde:desktop acde:inspect acde:permissions acde:session acde:desktops acde:setDefault |
Shell modules: the desktop and system apps | Desktops |
For full signatures, see Reference: acde: modules.