Skip to content

LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.

8.8 KB
Raw Blame

LordOS apps

Each app is a folder apps/<id>/ with two files. Apps don't depend on the theme: any theme shows them with its own colors (via useTheme()).

apps/quicknotes/
├── manifest.json
└── index.jsx

manifest.json

{
  "id": "quicknotes",
  "version": "1.0.0",
  "name": "Quick Notes",
  "description": "Quick notes",
  "size": [500, 400],
  "dock": true,
  "permissions": []
}

version is required: the app's own version, in semver (major.minor.patch, optionally with a -beta.1 or ~rc1 suffix). The build refuses an app without one (tools/build-theme.mjs), and the Store shows it next to the app (Installed: "LordOS app · 0.8.5"). The native apps started at 0.8.5, the LordOS version they first shipped in; from then on an app's version changes when the app changes, apart from LordOS's, so the apps can later live in repositories of their own.

Optional fields: "transparent": true (the theme paints no background under the content; the app draws its own, e.g. the Terminal with transparency) and "minSize": [width, height].

index.jsx

import { View, Text, useTheme, TextInput } from '@lordos/sdk';
import { useState } from 'react';

export function Icon({ size }) {          // icon for the dock, app launcher, taskbar
  return <View style={{ width: size, height: size, borderRadius: size * 0.22, backgroundColor: '#ffd60a' }} />;
}

export default function QuickNotes() {    // the window's content
  const t = useTheme();
  const [text, setText] = useState('');
  return (
    <View style={{ flex: 1, padding: 16, gap: 10 }}>
      <Text style={{ fontSize: 18, fontWeight: 700, color: t.text }}>Quick Notes</Text>
      <TextInput value={text} onChange={setText} placeholder="Write…" />
    </View>
  );
}

(Real apps don't hard-code visible text like this: see "Texts and languages" below.)

npm run build rebundles every theme with every app. To distribute an app without touching the themes, it is packaged as an .lpk with node tools/lpk.mjs <folder> and installed from the Store (see docs/NATIVE-APPS.md).

Available API (@lordos/sdk)

Area API
UI View, Text (with fontFamily: 'monospace' for JetBrains Mono), Image, ScrollView, TextInput (with onKeyDown), Button, Toggle, Segmented, Stepper, Slider, SidebarItem, SectionTitle, Terminal
Theme useTheme() → text, textDim, accent, windowBg, sidebarBg, separator, hover, control, inputBg, mode
Windows wm.open(app, { new, instance, frame, args }), wm.close(id), wm.focus(id), wm.setTitle(id, t), wm.setMenus(id, menus), wm.setCloseGuard(id, fn), useAppWindow() → { id, focused, args }
Terminal term.create/close/configure/key/paste/search/... (see docs/TERMINAL.md), clipboard.get/set, clipboardHistory
Keyboard useKeyboard(fn) (only with the window in front), TextInput; keyboard.list/configured/active/next/set (XKB layouts)
Language t('namespace.key', vars), useLocale(), appName(app), formatDate, formatTime, formatNumber, languages(), setLanguage(id), direction(), textDirection(text) — see docs/LANGUAGES.md
Input methods TextInput already uses them; for a custom field, ime.attach(token, caret) / ime.detach(token) and useIme()
Administration admin.run('locale-gen' | 'system-locale' | 'timezone' | 'langpack', arg, onLog) → promise; admin.busy (progress)
Files useDirectory(path), fs.list, fs.read(path, { binary }) (max. 8 MB), fs.write(path, text | ArrayBuffer) (atomic, max. 32 MB), fs.mkdir, fs.rename, fs.copy/fs.move (in the background: fs.jobs()), fs.trash/trashList/restore/removeFromTrash/emptyTrash (freedesktop Trash), fs.stat, fs.du, fs.free, fs.search, fs.recent, fs.volumes, fs.join, fs.parent, fs.basename — only in the home folder and on the user's mounted disks (/media/$USER, /run/media/$USER); writing to ~/.local/share/applications, ~/.config/autostart, ~/.local/share/lordos/apps or the settings is not allowed, and deleting is only possible inside the Trash (see docs/FILES.md)
Fonts lord.fonts.list({ rescan }) → { family, style, ps, weight, italic, mono, color } of the installed fonts
Touchpad onWheel with e.precise, e.deltaX/deltaY in pixels and e.phase ('momentum' = inertia); onPinch({ scale, rotation, x, y, phase }); onSwipe({ dx, dy, fingers, phase, system }); useTrackpads(), trackpad.config()/set(changes), registerGestureActions({ up, down, left, right }) (themes) — see docs/TRACKPAD.md
System useSystemInfo(), useCpuUsage(), useServerStats(), formatBytes, formatDuration
Settings useSettings() → [settings, update], stored in ~/.config/lordos/settings.json
Session session.quit(), themes.list(), themes.use(id)
Apps useLauncherApps() (LordOS, packages and Linux apps), launchApp(id), packages.*, windowIcon(w) — see docs/NATIVE-APPS.md
Clipboard clipboard.get/set(text, { secure })/use/pin/remove/clear, clipboardHistory and clipboardKind (saved history; ❖V and ❖⇧V panels) — see docs/SPOTLIGHT.md
Search spotlight.open/close/toggle (❖Space); spotlightCalc(text) and spotlightConvert(text)
Sound useSound(), sound.setVolume/setMute/setDefault/setPort/move/meter/play, defaultSink(s), microphones(s) — see docs/SOUND.md
WebAssembly the standard WebAssembly global (docs/WASM.md); in installed apps, loadWasm(id, path)
Canvas <Image pixels={{ width, height, data }} />: RGBA pixels (for example, computed in WASM)
Media media.play/image/thumb/probe/poster/edit/transcode/screenshot/annotate/saveImage/copyImage/screenRecord/audioRecord/camera/photo/cameraRecord, usePlayer(id), <MediaView media={id} />, nowPlaying, NowPlayingTile, useThumb(path), userDirs() — decoded by lord-media, sandboxed (see docs/MEDIA.md)
Windows (media) wm.setProtected(id, on) (black in screenshots, recordings and remote desktop), wm.setFullscreen(id, on), wm.setPip(id, frame), useWindowState(key, initial), useAppWindow().mode ('window', 'fullscreen' or 'pip')
Markdown <Markdown source base width onLink onToggleTask />, markdownHeadings(text), toggleTask — see docs/NOTES.md
Desktop registerWidgetType(type, Component), setWidgets(type, [{ id, x, y, w, h, pinned }]): widgets between the wallpaper and the windows
Notifications (M9) notify({ app, title, body, actions: [{ id, label, primary, run }], sound, sticky, timeout, onClose }) → id, dismissNotification(id), useNotifications(), notifyHistory; registerStatusItem(id, Component) (status icons in the theme's bar) — see docs/SYSTEM.md
Clock and Help (M9) clockAlarms, clockTimer/timerStart…, stopwatch/swStart… (keep running with the app closed); lord.time.zoneOffset(zone, t); help.list/read/search/open/startTour; registerSpotlightSource(id, fn); weekdayName(d)
Documents (M9) pdf.open(path | { blob }) (page, search, outline, links, forms, annotations, save a copy), <DocImage image>, archive.list/extract/create, fontInfo/fontSample/fontGrid, pdfThumb, makeTextPdf/makeImagePdf: all in the sandboxed helper lord-doc — see docs/DOCUMENTS.md
Printing (M9) print.open({ title, path | doc | text | image }) opens the system dialog; print.printers/jobs/cancel/add/remove/setDefault/discover/scanCaps/scan — see docs/PRINTING.md
Emoji (M9) emoji.open() (❖.), emoji.search/name/withTone/insert, EmojiGrid, EmojiToneBar
Custom text focus takeTextFocus(token, onKey, onChange) / releaseTextFocus(token): a custom field receives keys like a TextInput

Texts and languages

Visible texts aren't written in the code: they go through t('myapp.key') with their translations in assets/locales/{es,en,pt}/myapp.json ({ "key": "Text" }). The app's name is translated in apps.json ("myapp": "My app"). Lists containing texts are built at render time, not as module constants, because the UI is remounted when the language changes. node tools/i18n-check.mjs warns if any key is missing.

Permissions

permissions in the manifest is declarative for now: it documents what the app uses, but all apps run in the same JS context as the theme. Real isolation (one context or process per app, with permissions checked by the server) is pending work. What is real today: the server runs without root, fs doesn't leave the home folder and there is no API to run commands (the terminal can only open the user's shell).

fs only writes inside the home folder and never to the folders the system uses to launch or install things (.desktop, autostart, installed apps), so an app can't turn a write into running a command.