acde: modules
Every module has both named exports and a default export:
import { fs } from 'acde:fs'import fs from 'acde:fs'Types are in @dopame/acde-api: @dopame/acde-api/app declares the modules an app can import, @dopame/acde-api/shell adds the shell modules, and the package root declares all of them. For how capabilities are requested and approved, see Capabilities.
Who can import what. "App" is an app of its own package; a "system app" ships in a desktop's package (the apps of a desktop config). A name in a cell is the capability the app must declare:
| Module | App | System app | Desktop page |
|---|---|---|---|
acde:window |
✓ | ✓ | |
acde:capabilities |
✓ | ✓ | ✓ |
acde:apps |
✓ | ✓ | ✓ |
acde:open |
✓ (opening an app needs open) |
✓ (same) | ✓ |
acde:fs |
fs |
fs |
✓ |
acde:terminal |
terminal |
terminal |
✓ |
acde:network |
network |
network |
✓ |
acde:system |
system |
system |
✓ |
acde:bluetooth |
bluetooth |
bluetooth |
✓ |
acde:audio |
audio |
audio |
✓ |
acde:devices |
devices |
devices |
✓ |
acde:power |
power |
power |
✓ |
acde:input |
input |
input |
✓ |
acde:display |
display |
display |
✓ |
acde:office |
office |
office |
✓ |
acde:openPath acde:handlers |
openFiles |
openFiles |
✓ |
acde:launch |
launch or slots |
launch or slots |
✓ |
acde:windows acde:packages acde:session acde:desktops acde:inspect acde:desktop acde:setDefault acde:permissions (shell modules) |
The module's name: "windows": true |
✓ | |
acde:<service> |
The service's name in services |
The same | ✓ |
A module the platform lacks is missing for everyone there (see Platform support). An import that is not allowed fails with an AcdeError (code: 'forbidden', status: 403, module without acde:) whose message names the missing declaration, such as acde:terminal needs "terminal" in the capabilities of Notes; when the service that provided the module stopped, the code is service_not_running and the status 503. See Errors. Desktop services cannot import acde: modules; a service that the desktop grants shell modules gets them from ctx.import(); see Service API.
Events are subscribed with on(type, handler), which returns an unsubscribe function. on() throws a TypeError for an event type the module does not have, such as acde:window has no nosuch event (activate, deactivate, …). acde:terminal takes a callback instead (subscribe); acde:network has on('changed') and also takes a callback with watch.
Errors
Section titled “Errors”The system modules (acde:network, acde:system, acde:bluetooth, acde:audio, acde:devices, acde:power, acde:input, acde:display) fail with one kind of error, whether a method throws or its promise rejects: an Error with name === 'AcdeError' and status, code and module (the module's name without acde:). The cause is in cause, and a code of its own, when it has one, in the optional reason. The types are AcdeError and AcdeErrorCode in @dopame/acde-api; tell the error by error.name === 'AcdeError'. The codes:
code |
status |
When |
|---|---|---|
bad_request |
400 | A wrong argument, such as a host name, a time zone, a power setting, a brightness or a device id |
forbidden |
403 | The app was not given the module or the call (not in its capabilities) |
unsupported |
501 | This runtime or platform cannot do it |
service_not_running |
503 | The system service or bus it needs is not there (NetworkManager, BlueZ, UPower, fcitx5 and the like) |
failed |
500 | Anything else |
try { await network.connect('Home', 'secret')} catch (error) { if (error.name === 'AcdeError' && error.code === 'service_not_running') showOffline() else throw error}An import of a module the app was not given fails with the same error, code: 'forbidden' (see above).
acde:window
Section titled “acde:window”interface AcdeWindow { readonly id: number readonly state: WindowState readonly output: WindowOutput readonly hostControls: boolean readonly minimizable: boolean readonly host: WindowHost mount(app: WindowApp): void setTitle(title: string): void setMenus(menus: readonly AppMenu[]): void close(): Promise<boolean> minimize(): Promise<void> requestAttention(): Promise<void> requestState(state: WindowState): void requestMode(mode: WindowMode): void setGrabHint(rect: WindowRect, edges?: readonly ('top' | 'bottom' | 'left' | 'right')[]): void setBackdrop(rect: WindowRect | null, effect?: { radius?: number; blur?: number; saturate?: number; brightness?: number }): void requestActivate(): void requestGrab(kind: 'pointer' | 'keyboard'): void releaseGrab(kind: 'pointer' | 'keyboard'): void shortcut(combo: string): Promise<void> unshortcut(combo: string): Promise<void> on(name: 'beforeclose', handler: () => boolean | void | Promise<boolean | void>): () => boolean on<R extends AppRequest = AppRequest>(name: 'request', handler: (request: SystemRequest | R) => void): () => boolean on(name: 'activate' | 'deactivate', handler: () => void): () => boolean on(name: 'state', handler: (event: { readonly state: WindowState; readonly previous: WindowState }) => void): () => boolean on(name: 'output', handler: (output: WindowOutput) => void): () => boolean on(name: 'hostcontrols', handler: (hostControls: boolean) => void): () => boolean on(name: 'minimizable', handler: (minimizable: boolean) => void): () => boolean on(name: 'shortcut', handler: (event: ShortcutEvent) => void): () => boolean on(name: 'grab', handler: (event: { readonly kind: 'pointer' | 'keyboard'; readonly granted: boolean }) => void): () => boolean on(name: 'grablost', handler: (event: { readonly kind: 'lost'; readonly reason: 'esc' | 'other_window' | 'focus_lost' | 'denied' }) => void): () => boolean on(name: 'suspend' | 'resume', handler: () => void): () => boolean}
type WindowState = 'normal' | 'minimized' | 'filled' | 'fullscreen'type WindowMode = 'free' | 'fixed' | 'pinned'
interface WindowRect { x: number; y: number; width: number; height: number }interface WindowOutput { width: number; height: number; scale: number; workArea: WindowRect }
interface ShortcutEvent { type: 'shortcut'; window: number; key: string; title: 'session' | 'desktop' | 'app' }
interface AppMenu { id: string label: string items: ({ type: 'separator' } | AppMenuItem)[]}interface AppMenuItem { id: string label: string shortcut?: string checked?: boolean disabled?: boolean onSelect?(): void | Promise<void>}
interface WindowApp { mount(element: Element, host: WindowHost): () => void}interface WindowHost { setTitle(title: string): void setMenus(menus: readonly AppMenu[]): void}- Full screen is a state:
requestState('fullscreen').requestMode('fullscreen')throws aTypeError, and so does an unknown state.requestStatehas no result; follow thestateevent. See Window state. close()closes the window without askingbeforeclose.minimize()rejects withstatus: 409,code: 'unavailable'for a window that cannot be minimized (minimizableisfalse):window 1048576 cannot be minimized: it fills the host window, which only the host window's own controls minimize herefor the app's window in a session that runs a single app, on macOS and headless.requestState('minimized')changes nothing there.suspendandresumeare declared, but the runtime does not send them yet.- Coordinates are logical pixels of the page (the content area). Shortcut combos are written like
ctrl+alt+t: keys are xkb keysym names, the key names X11 and Wayland use (t,return,escape,f5,space; case doesn't matter), and Shift is part of the combo.
acde:capabilities
Section titled “acde:capabilities”interface AcdeCapabilities { readonly level: number readonly platform: 'linux' | 'win32' | 'darwin' readonly mode: 'session' | 'desktop' | 'standalone' readonly window: { readonly backdrop: 'full' | 'approximated' | 'unsupported' } get(name: string): CapabilityStatus list(): CapabilityStatus[] request(name: string): Promise<CapabilityStatus>}
interface CapabilityStatus { name: string kind: 'system' | 'service' state: 'available' | 'not-asked' | 'asking' | 'not-declared' | 'unsupported' | 'service-not-running' | 'shell-only' | 'denied' reason: string optional: boolean}level is the contract level (1). request(name) asks the user for a capability that needs approval and resolves with its status after the answer; for anything else it resolves at once. A capability that needs approval is available only once the user allowed it: not-asked before the prompt, asking while it waits, denied after a denial or after the approval was taken back. A call that the approval stops fails with status: 403, the capability, and one of the codes not_asked, asking, denied. Names are capability names, fs.<place> for a shared place (fs.downloads), service names, and notifications (the standard Notification API: available, or unsupported where this way of running has no notifications). See Capabilities.
acde:fs
Section titled “acde:fs”interface AcdeFs { roots(): Promise<FinderRoot[]> list(root: string, path?: string, hidden?: boolean): Promise<{ root: FinderRoot; path: string; entries: FinderEntry[]; truncated: boolean; skipped?: number }> stat(root: string, path: string): Promise<FinderEntry & { path: string }> readText(root: string, path: string): Promise<{ text: string; modifiedMs: number; size: number; version: string }> readBytes(root: string, path: string): Promise<{ data: Uint8Array; modifiedMs: number; size: number; version: string }> readRange(root: string, path: string, offset: number, length: number, options?: { ifVersion?: string }): Promise<{ data: Uint8Array; offset: number; size: number; modifiedMs: number; version: string }> writeFile(root: string, path: string, data: string | Uint8Array, options?: { create?: 'always' | 'new' | 'never' ifVersion?: string ifModifiedMs?: number mkdirs?: boolean }): Promise<FinderEntry> openWrite(root: string, path: string, options?: { keepExistingData?: boolean create?: 'always' | 'new' | 'never' ifVersion?: string mkdirs?: boolean }): Promise<{ id: string; size: number }> writeChunk(id: string, offset: number, data: string | Uint8Array): Promise<void> truncateWrite(id: string, size: number): Promise<void> commitWrite(id: string): Promise<FinderEntry> abortWrite(id: string): Promise<void> mkdir(root: string, path: string, options?: { recursive?: boolean }): Promise<FinderEntry> rename(root: string, from: string, to: string): Promise<FinderEntry> delete(root: string, path: string): Promise<{ status: 'deleted'; path: string }> copy(fromRoot: string, fromPath: string, toRoot: string, toDir: string): Promise<FinderEntry & { path: string }> preview(root: string, path: string): Promise<FinderPreview> download(root: string, path: string): Promise<{ name: string; contentType: string; data: Uint8Array }> revoke(root: string): Promise<void> locate(path: string): Promise<{ root: string; path: string }> openPath(root: string, path: string): Promise<{ root: string; path: string; file: string }>}
interface FinderRoot { id: string label: string source: 'private' | 'place' | 'granted' | 'desktop' | 'downloads' | 'default' place?: 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos' path?: string mode: 'writable' | 'read_only' | 'unavailable' reason: string | null exists: boolean}
interface FinderEntry { name: string kind: 'directory' | 'file' | 'symlink' | 'other' size: number modifiedMs: number target?: string version?: string inPlace?: true}
interface FinderPreview { path: string name: string size: number modifiedMs: number kind: 'text' | 'image' | 'binary' | 'too_large' content?: string truncated?: boolean}rootis theidof an item ofroots():private, a shared place's name, orfolder-…for a picked folder; never a path. An app's roots havesourceprivate,place(withplace), orgranted, and nopath.pathis there only for system apps that name shared places, and for the desktop page.locateandopenPathwork only for them; in other apps they reject withEACCES.- The desktop page's roots are folders by path (
sourcedesktop,downloads,default, orgranted), and theiridis the path. listleaves hidden entries out unlesshiddenistrue;skippedcounts entries whose names are not valid Unicode.copycopies a file or a folder from one root into the foldertoDirof another; a taken name gets a number (todo 2.md), andpathis where the copy is intoRoot.revokegives back a folder the user picked.versionis an opaque string for one state of a file; pass it asifVersionand a write (or areadRange) of a file that changed since fails withECONFLICT.inPlacemarks a write that could not go through a temporary file. See Safe writes.openWritestarts a write in parts:writeChunkat any offset,truncateWrite, thencommitWriteputs the file in place (orabortWrite). A write left alone for 10 minutes is given up. See Large files.- Limits:
readText/readBytes/writeFile64 MiB;readRange/writeChunk16 MiB a call;list5000 entries (truncated);previewtext 256 KiB. downloadanswers the type the system knows for the file's name ascontentType:text/markdownfornote.md,image/pngforshot.png, andapplication/octet-streamfor a name it knows no type for (data.xyz). The types come from the system, as described under Files and links.- Errors have
codeandstatus; see Files and folders.
acde:open
Section titled “acde:open”interface AcdeOpen { (app: string, request?: null, options?: OpenWindowOptions): Promise<{ window: number }> <R extends AppRequest>(app: string, request: R, options?: OpenWindowOptions): Promise<{ window: number }> (app: string, request: SystemRequest): Promise<Opened> (request: SystemRequest): Promise<Opened>}
type AppRequest<K extends string = string, Fields extends object = Record<never, never>> = { readonly kind: K } & { readonly [P in keyof Fields]: Fields[P] }
type SystemRequest = | { kind: 'open-file'; handle?: FileSystemFileHandle | FileSystemDirectoryHandle; url?: string; root?: string; path?: string; file?: string | null } | { kind: 'open-link'; url: string }
interface OpenWindowOptions { parent?: number; modal?: boolean }interface Opened { kind: 'acdev' | 'native'; id: string; window?: number }open(app)andopen(app, request)need theopencapability to allowapp. A request to an app must have akindthat the target lists in itsrequests(400untyped_request, 409not_accepted).open(request)with a system request and no app needsopenFiles: the system picks the app. With an app, the target must declare the file's type (mimeTypes) or the link's scheme (schemes).- A receiving app gets a file as
{ kind: 'open-file', handle }; a system app that names shared places also getsurl. Send a file withhandle(one this page got from a picker, a drop, or a request) or, where the caller knows paths, withurl. - A receiver types its own requests with
AppRequest<K, Fields>:type ShowImage = AppRequest<'show-image', { image: string }>, thenself.on<ShowImage>('request', …)narrows bykind.SystemRequestandAppRequestare also inacde:window'srequestevent (above).
See Opening apps.
acde:apps
Section titled “acde:apps”interface AcdeAppList { list(): Promise<DesktopApp[]> open: AcdeOpen on(type: 'changed', handler: (event: { type: 'appschanged'; apps: readonly DesktopApp[] }) => void): () => boolean}
interface DesktopApp { id: string; label: string; icon: string; script: string }list() gives the apps that can run here; open is the function of acde:open. changed fires with the new list when it changes. A denied camera or microphone keeps the app in the list. Installing packages and native programs are in acde:packages.
acde:openPath / acde:handlers / acde:setDefault
Section titled “acde:openPath / acde:handlers / acde:setDefault”function openPath(path: string, options?: { app?: string; select?: boolean }): Promise<{ kind: 'acdev' | 'native'; id: string; window?: number }>function handlers(path: string): Promise<{ mime: string; association: string | null; handlers: OpenHandler[] }>function setDefault(association: string, handler: string): Promise<string>
interface OpenHandler { kind: 'acdev' | 'native' id: string label: string icon: string default: boolean system?: boolean}path can be a path or a URI. openPath and handlers need openFiles; for an app the file must be inside one of its roots (404 outside_roots). setDefault is a shell module. association is the key a choice is remembered under: the MIME type, or on Windows the file's extension (.md); mime is '' when the system knows no type for the file. system marks the program that is the system's own default (Windows).
acde:launch
Section titled “acde:launch”Needs launch (for start) or slots (for embed).
interface AcdeLaunch { start(argv: readonly string[], options?: LaunchOptions): Promise<number> embed(argv: readonly string[], options?: LaunchOptions): Promise<number> close(window: number): Promise<boolean> list(): NativeWindow[] on<K extends WindowsEventType>(type: K, handler: (event: WindowsEventMap[K]) => void): () => boolean}
interface LaunchOptions { cwd?: string; env?: Record<string, string> }start runs a native program and embed runs one embedded in the app's own window (Dopame OS only). close closes a window the app started; any other window is rejected with 403 forbidden. The events are those of acde:windows.
acde:terminal
Section titled “acde:terminal”Needs terminal.
interface AcdeTerminals { open(cols: number, rows: number): Promise<{ id: string }> subscribe(id: string, callback: (events: TerminalEvent[]) => void): Promise<void> input(id: string, data: string): Promise<{ ok: true }> resize(id: string, cols: number, rows: number): Promise<{ cols: number; rows: number }> close(id: string): Promise<{ closed: string }>}
type TerminalEvent = | { type: 'output'; data: string } | { type: 'cwd'; path: string } | { type: 'exit'; code: number | null; signal: number | null }acde:network
Section titled “acde:network”Linux only (Dopame OS, or any Linux with NetworkManager). Needs network.
interface AcdeNetwork { state(): Promise<NetworkState> networks(scan?: boolean): Promise<WifiNetwork[]> connect(ssid: string, password?: string): Promise<void> activate(iface: string): Promise<void> disconnect(iface: string): Promise<void> setWifiEnabled(on: boolean): Promise<void> on(type: 'changed', handler: (state: NetworkState) => void): () => boolean watch(callback: (state: NetworkState) => void): void}
interface NetworkState { wifiEnabled: boolean connectivity: 'full' | 'limited' | 'portal' | 'none' | 'unknown' primary: 'wifi' | 'ethernet' | string | null devices: NetworkDevice[]}
interface NetworkDevice { iface: string type: 'wifi' | 'ethernet' state: 'connected' | 'connecting' | 'disconnecting' | 'disconnected' | 'unavailable' | 'unmanaged' | 'failed' connection: string | null ip4: string | null ssid?: string strength?: number carrier?: boolean speed?: number}
interface WifiNetwork { ssid: string strength: number secure: boolean band: '2.4GHz' | '5GHz' active: boolean saved: boolean}acde:system
Section titled “acde:system”Linux only. Needs system. Its errors are AcdeErrors.
interface AcdeSystem { info(): Promise<SystemInfo> storage(): Promise<SystemVolume[]> time(): Promise<SystemTime> timezones(): Promise<string[]> setTimezone(zone: string): Promise<void> setNtp(on: boolean): Promise<void> setHostname(name: string): Promise<void> user(): Promise<SystemUser> on(type: 'changed', handler: (change: SystemChange) => void): () => boolean}The computer: info() (the host name and other facts), storage() (its volumes), time() (with timezone and ntp), timezones(), the settings setTimezone, setNtp and setHostname, and user(). changed gives {storage, hostname, timezone, ntp}, the whole set each time, when one of these changes; it is checked every 30 seconds while someone listens, and right after this page sets one of them. The state types are in @dopame/acde-api.
acde:bluetooth
Section titled “acde:bluetooth”Linux only. Needs bluetooth. Its errors are AcdeErrors.
interface AcdeBluetooth { state(): Promise<BluetoothState> setPowered(on: boolean): Promise<void> setDiscoverable(on: boolean, timeout?: number): Promise<void> setName(name: string): Promise<void> scan(on: boolean): Promise<void> pair(id: string): Promise<void> answer(id: string, accept: boolean, pin?: string): Promise<void> connect(id: string): Promise<void> disconnect(id: string): Promise<void> forget(id: string): Promise<void> setTrusted(id: string, on: boolean): Promise<void> setBlocked(id: string, on: boolean): Promise<void> rename(id: string, name: string): Promise<void> setOnLogin(mode: 'remember' | 'on' | 'off'): Promise<void> on(type: 'changed', handler: (state: BluetoothState) => void): () => boolean on(type: 'pairing', handler: (request: BluetoothPairing) => void): () => boolean}The Bluetooth adapter and its devices (BlueZ). changed gives the whole BluetoothState; pairing asks the page to confirm a pairing, show or enter a PIN or passkey, or authorize a service, and the page answers with answer(id, accept, pin?). The state types are in @dopame/acde-api.
acde:audio
Section titled “acde:audio”Linux only. Needs audio. Its errors are AcdeErrors.
interface AcdeAudio { state(): Promise<AudioState> setDefault(id: string): Promise<void> setVolume(id: string, volume: number): Promise<void> setMuted(id: string, muted: boolean): Promise<void> setBalance(id: string, balance: number): Promise<void> setPort(id: string, port: string): Promise<void> setProfile(card: string, profile: string): Promise<void> moveStream(id: string, device: string | null): Promise<void> on(type: 'changed', handler: (state: AudioState) => void): () => boolean}The sound cards, outputs, inputs and playing streams: the default device, volume, mute, balance, port and card profile, and which device a stream plays on. changed gives the whole AudioState. The state types are in @dopame/acde-api.
acde:devices
Section titled “acde:devices”Linux only. Needs devices. Its errors are AcdeErrors.
interface AcdeDevices { state(): Promise<DevicesState> mount(id: string): Promise<string> unmount(id: string): Promise<void> eject(id: string): Promise<void> setAutomount(patch: Partial<Pick<Automount, 'onLogin' | 'onAttach' | 'unknown'>>): Promise<void> setDeviceAutomount(id: string, patch: Partial<Pick<AutomountDevice, 'login' | 'attach'>>): Promise<void> forgetDevice(id: string): Promise<void> setDefaultPrinter(id: string): Promise<void> pausePrinter(id: string): Promise<void> resumePrinter(id: string): Promise<void> jobs(printer: string): Promise<PrintJob[]> cancelJob(printer: string, job: number): Promise<void> on(type: 'changed', handler: (state: DevicesState) => void): () => boolean on(type: 'added', handler: (drive: Drive) => void): () => boolean}Drives (USB sticks, cards, discs, phones, disks: mount, unmount, eject, and the automount settings) and printers (the default one, pause, resume, jobs). changed gives the whole DevicesState; added gives a drive when one is plugged in. The state types are in @dopame/acde-api.
acde:power
Section titled “acde:power”Linux only. Needs power. Its errors are AcdeErrors.
interface AcdePower { state(): Promise<PowerState> setProfile(profile: PowerProfile): Promise<void> configure(patch: PowerSettingsPatch): Promise<void> setScreenOff(seconds: number | null): Promise<void> setSleep(seconds: number | null): Promise<void> suspend(): Promise<void> hibernate(): Promise<void> setBrightness(value: number): Promise<void> setChargeLimit(percent: number | null): Promise<void> on(type: 'changed', handler: (state: PowerState) => void): () => boolean on(type: 'prompt', handler: (event: PowerPromptEvent) => void): () => boolean on(type: 'critical', handler: (event: PowerCriticalEvent) => void): () => boolean}Batteries, the power profile, what the lid, the power button and being idle do (on AC, on battery and on low battery), screen-off and sleep timers, suspend and hibernate, the backlight, and the charge limit. changed gives the whole PowerState; prompt ({type: 'prompt'}) asks the page to offer the power choices, and critical ({type: 'critical', action, seconds}) says the battery is critically low and what happens in how many seconds. The state types are in @dopame/acde-api.
acde:input
Section titled “acde:input”Linux only. Needs input. Its errors are AcdeErrors.
interface AcdeInput { state(): Promise<InputState> set(patch: InputPatch): Promise<void> catalog(): Promise<InputCatalog> on(type: 'changed', handler: (state: InputState) => void): () => boolean}Keyboard (model, layouts, options, Num Lock), mouse and touchpad settings, and the input methods. set() takes the parts to change; catalog() lists the models, layouts, options and input methods to choose from. changed gives the whole InputState. The state types are in @dopame/acde-api.
acde:display
Section titled “acde:display”Linux only. Needs display. Its errors are AcdeErrors.
interface AcdeDisplay { state(): Promise<DisplayState> configure(id: string, patch: DisplayPatch): Promise<void> setBrightness(id: string, value: number): Promise<void> setNightLight(patch: Partial<NightLight>): Promise<void> on(type: 'changed', handler: (state: DisplayState) => void): () => boolean}The displays (mode, scale, rotation and the rest, set with configure), their brightness, and the night light. changed gives the whole DisplayState. The state types are in @dopame/acde-api.
acde:session
Section titled “acde:session”Shell module: only the desktop page and the system apps of its package (with "session": true in their capabilities) can import it; an ordinary app cannot, even if it declares session.
interface AcdeSession { own(): boolean logout(): Promise<void> reboot(): Promise<void> poweroff(): Promise<void> setLanguage(tag: string): Promise<void>}own(): whether this is a real Dopame OS session (false in the host window of acdev dev). After setLanguage, pages receive languagechange.
acde:desktops
Section titled “acde:desktops”Shell module.
interface AcdeDesktops { list(): Promise<{ desktops: DesktopInfo[]; current: string }> choose(id: string, remember?: boolean): Promise<void>}
interface DesktopInfo { kind: 'acdev' | 'session' id: string name: string description: string | null package: string | null}kind: 'session' is another Wayland session on the system (GNOME, KDE, ...).
acde:packages
Section titled “acde:packages”Shell module.
interface AcdePackages { refresh(): Promise<DesktopApp[]> install(dir: string): Promise<{ id: string; dir: string; apps: DesktopApp[] }> natives(): Promise<NativeApp[]> runNative(id: string): Promise<number> on(type: 'changed', handler: (event: { type: 'appschanged'; apps: readonly DesktopApp[] }) => void): () => boolean}
interface NativeApp { id: string name: string comment: string | null icon: string keywords: string[] wmClass: string | null}natives() lists the system's native programs (.desktop files, Linux only).
acde:windows
Section titled “acde:windows”Shell module: every window of the session.
interface AcdeWindows { on<K extends WindowsEventType>(type: K, handler: (event: WindowsEventMap[K]) => void): () => boolean list(): NativeWindow[] close(id: number): void requestState(id: number, state: WindowState): Promise<void> kill(id: number): Promise<boolean> focus(id: number): Promise<void> hide(id: number): Promise<void> show(id: number): Promise<void> invokeMenu(id: number, menu: string, item: string): Promise<void> stats(): Promise<Record<string, number>> animate(id: number, options: { opacity?: number; scale?: number; dx?: number; dy?: number duration?: number; delay?: number easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' }): Promise<void> shortcut(combo: string, scope?: 'session' | 'desktop'): Promise<void> unshortcut(combo: string, scope?: 'session' | 'desktop'): Promise<void> launch(argv: string[], options?: { cwd?: string; env?: Record<string, string>; slot?: boolean }): number | Promise<number>}
interface NativeWindow { id: number; appId: string | null; title: string | null; web?: boolean; state: WindowState }WindowsEventType: open close title state activate minsize parent menus crash hang responsive attention ready show animated. Every event is { type: 'window<name>', window: number, … }:
| Event | Extra fields |
|---|---|
open |
appId, title, web, icon |
title |
appId, title |
state |
state, previous |
minsize |
width, height |
parent |
parent |
menus |
menus: the app's menus, each item with action: boolean instead of onSelect |
crash |
reason |
- A window's state changes are reported by
state; full screen and minimizing have no events of their own.requestStaterejects an unknown state with aTypeError. close(id)asks the app (beforeclose);kill(id)ends the window without asking.animatemay finish at once where the runtime cannot animate;animatedstill fires.- Every row of
list()has the window's currentstate, andlist()has every window, also in a system app that started after a window opened. - An app starts native programs with
acde:launch, not withlaunchhere.
acde:desktop
Section titled “acde:desktop”Shell module.
interface AcdeDesktop { apps(): Promise<{ apps: DesktopApp[] }> pin(element: Element, options?: { margin?: number; reserve?: PanelReserve }): PinnedPanel setDoubleClick(action: 'fill' | 'minimize' | 'none'): void setFrameTheme(theme: FrameTheme | null): void on(type: 'notification', handler: (e: NotificationEvent) => void): () => boolean on(type: 'download', handler: (e: DownloadEvent) => void): () => boolean on(type: 'screenshot', handler: (e: { type: 'screenshot'; path: string; width: number; height: number } | { type: 'screenshot'; path: string; error: string }) => void): () => boolean on(type: 'shortcut', handler: (e: ShortcutEvent) => void): () => boolean on(type: 'edge', handler: (e: { type: 'screenedge'; edge: 'top' | 'right' | 'bottom' | 'left'; entered: boolean; output: string }) => void): () => boolean}
interface PanelReserve { edge: 'top' | 'bottom' | 'left' | 'right'; thickness?: number }interface PinnedPanel { update(): void unpin(): void reserve(reserve: PanelReserve | null): void}
interface FrameTheme { active?: FrameColors inactive?: FrameColors light?: { active?: FrameColors; inactive?: FrameColors } buttonStyle?: 'dots' | 'glyphs' buttonSide?: 'left' | 'right' titleAlign?: 'center' | 'start'}interface FrameColors { background?: string; title?: string; line?: string; buttons?: string }
interface NotificationEvent { type: 'notification' window: number app: string | null label: string | null title: string body: string icon: string tag: string}
interface DownloadEvent { type: 'download' window: number app: string | null path: string name: string size: number}edgefires when the pointer reaches (entered: true) or leaves an edge of the screen, once per edge (twice in a corner);outputis the screen's name,hostin a host window. It takes no focus, for a desktop that shows its hidden menu bar or Dock.light: the title bar colors for windows whose page does not declare dark support (color-schemewithoutdark);active/inactiveare then for pages that do. EverysetFrameThemecall gives the whole theme; a bad value throws aTypeError, and an unknown key is ignored with a warning in the log.- A system app that declares
"desktop": truegetsapps(),setDoubleClick,setFrameTheme, and thenotification,downloadandedgeevents;pin,screenshotandshortcutare the desktop page's only.
See Desktops.
acde:permissions
Section titled “acde:permissions”Shell module: the approval prompts and the decisions about them.
interface AcdePermissions { pending(): Promise<PermissionPrompt[]> answer(id: number, allow: boolean): Promise<void> list(app?: string): Promise<PermissionDecision[]> revoke(app: string, capability: string): Promise<boolean> on(type: 'prompt', handler: (event: PermissionPrompt & { type: 'permissionprompt' }) => void): () => boolean on(type: 'answered', handler: (event: { type: 'permissionanswered'; id: number; app: string; capability: string; allowed: boolean }) => void): () => boolean}
interface PermissionPrompt { id: number app: string label: string capability: string reason: 'request'}
interface PermissionDecision { app: string label: string | null capability: string decision: 'granted' | 'denied' folder?: { label: string; exists: boolean }}A prompt's capability is camera, microphone or idleDetection, the only capabilities that ask; in a decision it can also be fs.folder-…, a folder the user picked for the app (with folder). revoke resolves to false when there was no decision. Every prompt comes on first use, with reason: 'request'. See Desktops.
acde:inspect
Section titled “acde:inspect”Shell module, also given to desktop services as ctx.inspect. Turns the screen into a text semantic tree and acts on it by ref; meant for AI agents. acdev inspect / acdev act and MCP are built on it.
interface AcdeInspect { snapshot(options?: { window?: string; ref?: string; all?: boolean; diff?: boolean limit?: number; find?: string; tree?: boolean; offscreen?: boolean }): Promise<{ text: string; windows: InspectWindow[]; trees: Record<string, InspectNode[]> }> act(ref: string, action: InspectAction, arg?: string | number | readonly string[] | null): Promise<{ ok: boolean; text: string }> run(steps: readonly { ref: string; action: InspectAction; text?: InspectArg }[]): Promise<{ ok: boolean; text: string }> open(name: string): Promise<{ ok: boolean; text: string }> query(options: { selector: string; window?: string; ref?: string; limit?: number; attributes?: readonly string[] }): Promise<{ window: string; count: number; nodes: InspectMatch[] }>}
type InspectAction = 'click' | 'double' | 'right' | 'hover' | 'drag' | 'type' | 'settext' | 'select' | 'key' | 'scroll' | 'focus' | 'close' | 'minimize' | 'restore' | 'fill' | 'fullscreen'Window refs are w0 (the desktop), w1, ...; element refs look like w3.12. The text form has one node per line:
- button "New Folder" [pressed] [w1.52]acde:office
Section titled “acde:office”Linux only. An editing service for office documents (text, spreadsheets, presentations), used by Dopame's bundled office apps; the API is still subject to change.