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.
C cdebiandesktop-environmentebpffirewalllandlocklinuxlinux-distributionopen-sourceprivacyquickjsraspberry-pi-5reactsecuritywaylandwayland-compositor
Theme guide (docs/THEMES-GUIDE.md) and a minimal example theme (examples/theme-minimal); the theme switch keeps the last theme that loaded as the fallback after a refusal (two refused switches could leave no theme)
Federico Pereiraeaf139dee22c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 839822f..b907bf4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,6 +12,12 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),### Added+- **A guide to building an appearance.** `docs/THEMES-GUIDE.md` explains, for a React developer new to+ LordOS, what a theme is, its parts (theme.json, tokens, the shell, window frames, menus, layers),+ right-to-left, light and dark, several displays and the performance rules, how to build and test one,+ and a checklist; `examples/theme-minimal/` is a small working theme to start from. It also says+ plainly what is missing: a theme LordOS didn't sign doesn't load on a release build yet (no theme+ package format or user trust decision exists).- **Settings → Displays: numbers, Identify and snapping.** With more than one display each one has anumber (the main display is 1); clicking a display in the arrangement, or Identify, shows its numberbig on that monitor for a moment, so you know which screen is which. Dragging a display snaps it edge@@ -120,6 +126,9 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),### Fixed+- **Two failed theme switches in a row could leave the session without a theme.** After a theme was+ refused, the server still took it as the current one, so a second refused switch fell back to it.+ Now the last theme that loaded stays the fallback.- **Apps whose launcher file has a space in its name didn't appear in Apps.** A package may name its`.desktop` file freely (the LordOS Imager's is `LordOS Imager.desktop`), but the launcher skipped anyname with a space or another unusual character. Such a name now gets an id with those charactersdiff --git a/docs/README.md b/docs/README.mdindex a887eed..73fc440 100644--- a/docs/README.md+++ b/docs/README.md@@ -40,6 +40,7 @@ Website: [lordos.org](https://lordos.org) · Brand kit: [LORDOS-BRAND.md](LORDOS| [DISPLAYS.md](DISPLAYS.md) | Several displays and HiDPI || [GPU.md](GPU.md) | GPU composition, dmabuf and the CPU path || [DOCK.md](DOCK.md) | Dock and taskbar |+| [THEMES-GUIDE.md](THEMES-GUIDE.md) | How to build a LordOS appearance (theme): anatomy, tokens, frames, building, verified code, testing || [LAYERS.md](LAYERS.md) | The desktop's stacking order: what is drawn and clicked above what || [SPOTLIGHT.md](SPOTLIGHT.md) | Search and the advanced clipboard || [TRACKPAD.md](TRACKPAD.md) | Touchpads, gestures and touchscreens |diff --git a/docs/THEMES-GUIDE.md b/docs/THEMES-GUIDE.mdnew file mode 100644index 0000000..2296a75--- /dev/null+++ b/docs/THEMES-GUIDE.md@@ -0,0 +1,538 @@+# How to build a LordOS appearance (theme)++This guide is for a React developer who has never seen LordOS. It explains what a theme is, what it+must provide, the SDK pieces it builds on, how it is built and loaded, and what to check before+sharing it. Everything here is checked against the current code; file references point to where+each piece lives. A small working starting point is in [`examples/theme-minimal/`](../examples/theme-minimal/).++Read first, if you can: [`themes/README.md`](../themes/README.md) (the short reference: components,+events and the supported style subset), [DESIGN.md](DESIGN.md) (tokens and the shared controls),+[LAYERS.md](LAYERS.md) (stacking order) and [WINDOWS.md](WINDOWS.md) (moving and resizing).++> **Today a theme only runs on a development build of LordOS.** A release build loads only JavaScript+> that is listed in LordOS's signed code manifest, and a theme you build yourself is not in it. See+> [Verified code](#verified-code-what-happens-to-a-theme-that-lordos-did-not-sign) for exactly what happens and what+> would be needed.++## 1. What a theme is++A theme is **the whole desktop, written in React**: wallpaper, menu bar or taskbar, Dock, app+launcher, panels, menus and every window frame. It is not a style sheet and it does not run in a web+engine. `lord-server` (the display server and Wayland compositor, in C) evaluates the theme's bundle+with QuickJS; a React reconciler (`runtime/index.js`) turns the tree into native nodes+(`lord.setStyle`, `appendChild`…) that `lord-server` lays out (flexbox) and paints itself, on the+CPU or the GPU. So you write ordinary function components with hooks, but with `<View>`, `<Text>`,+`<Image>` instead of DOM elements, and a CSS subset as React Native-style style objects+(`themes/README.md`, "Supported styles").++**What the SDK (`@lordos/sdk`, `sdk/`) gives a theme:**++- the native components and events (`View`, `Text`, `Image`, `Terminal`, `addListener`, gestures);+- the window manager: the window list, open/focus/minimize/maximize/snap, the work area, moving and+ resizing done in C (`sdk/windows.js`, `sdk/windowshell.jsx`);+- `AppHost`, which draws an app inside a window; the native apps themselves come from `apps/`+ (`@lordos/apps`) and Linux (Wayland and X11) windows arrive on their own (`sdk/wayland.js`);+- the token contract and the shared controls apps use (`ThemeProvider`, `useTheme`,+ `sdk/theme.js`, `sdk/components.jsx`, `sdk/controls.jsx`);+- the layers that order everything above the windows (`Layer`, `Overlay`, `sdk/layers.js`);+- the models behind the desktop pieces, without their look: the Dock and taskbar (`sdk/dock.js`),+ app menus and the Window menu (`useAppMenus`, `appMenuItems`, `windowMenuItems`), notifications,+ status items, search, sound, battery, Bluetooth, Night Light, displays, the clock, translations;+- the surfaces that look the same in every theme, placed by `startShell`: search, notification+ banners, permission and keyring prompts, the file chooser, the print dialog, the input method's+ candidate window, fullscreen and picture-in-picture windows.++**What the theme must provide:** the colors and shapes (tokens), the window frame, the desktop+around the windows (bars, Dock, launcher, panels), where menus open, and the keyboard shortcuts of+its own layout (for example what the Super key alone does).++**The two built-in themes are the references:**++| Theme | Folder | Layout |+|---|---|---|+| Lord Flow | `themes/default` | menu bar on top (with the app's menus), magnifying Dock, app launcher, Control Center |+| Lord Classic | `themes/classic` | taskbar (bottom, top or a side), start menu with search, quick settings, notification panel, menus in each window, snapping and a task view |++`themes/greeter` is the login and lock screen: it is a separate program, not a desktop theme (see+[The login and lock screen](#the-login-and-lock-screen-are-not-your-theme)).++**Switching.** The user switches themes live from **Settings → Appearance → Desktop style**, which+since 0.8.5 lists every installed theme (the only place to choose one; `StylePicker` in+`apps/settings/index.jsx`). Lord Flow and Lord Classic come first, the others by name; a theme with+`"hidden": true` in its `theme.json` is not listed. Switching discards the JavaScript context and+loads the new bundle (`themes.use` in `sdk/index.js`, `lord.themes.use` in `server/src/ui/js_sys.c`,+`switch_theme` in `server/src/main.c`): the LordOS app windows that were open (up to 8) reopen in+the new theme with their frames, and Linux windows stay connected and get the new frame. The+choice is stored as `theme` in `~/.config/lordos/settings.json`.++How a session starts: `lord-sessiond` always starts `lord-server` with+`--theme <LordOS folder>/themes/default/theme.bundle.js` (`server/src/remote/sessiond.c`,+`sess.c`); the default theme's `startShell()` sees that the user chose another one and switches to+it at once. If the chosen theme can't be loaded, the session stays on the theme it came from.++## 2. Anatomy of a theme++```+themes/<id>/+ theme.json name, description, hidden+ index.jsx the entry point: puts the desktop together, ends with startShell(<App />)+ tokens.js the colors and shapes (by convention; the bundled themes use makeTheme())+ components/ the frame, bars, Dock, menus… (by convention)+ assets/ images the theme loads (<Image src="assets/…">)+ theme.bundle.js the build output (generated)+```++The theme's **id is its folder name**: letters, digits, `-` and `_`, at most 64 characters+(`valid_id` in `js_sys.c`). A folder is listed as a theme when it holds a readable+`theme.bundle.js`.++### `theme.json`++```json+{ "name": "Minimal", "description": "One sentence for Settings.", "hidden": false }+```++- `name` and `description` are what Settings shows, unless the `shell` catalog has+ `shell.theme.<id>.name` / `shell.theme.<id>.description` (the bundled themes translate theirs+ that way; `themes.list` in `sdk/index.js`). A missing or invalid `theme.json` shows the id.+- `hidden: true` keeps it out of Settings (the login screen uses it).+- It is read as text of at most 4 KB. It is data, not code, so it is not in the code manifest.++### `tokens.js`: the contract with the apps++Every app reads its colors with `useTheme()` (`sdk/theme.js`), so it looks right in any theme. The+theme passes its tokens to `<ThemeProvider tokens={…}>`; whatever it leaves out falls back to+`DEFAULT_TOKENS` (Lord Flow's dark colors), and its own extra keys pass through untouched. Isolated+apps (their own processes) receive the same tokens through the broker, and Linux apps get the mode,+the accent and the title-bar button order through the settings portal (`publishTokens` and+`syncPortal` in `sdk/theme.js`). So the tokens must be plain JSON values (no functions).++**Base tokens (required in practice: apps use all of them):**++| Token | Meaning | Used by |+|---|---|---|+| `mode` | `'dark'` or `'light'`: apps pick icons, shadows and contrast from it | 67 places in `apps/` |+| `accent` | the accent color (`#rrggbb`): selection, focus, toggles, primary buttons | 118 |+| `text` | primary text | 281 |+| `textDim` | secondary text: labels, hints, captions | 446 |+| `windowBg` | the window's content background | 28 |+| `sidebarBg` | sidebars and secondary panes | 17 |+| `separator` | hairlines and borders between areas (usually a translucent `rgba`) | 101 |+| `hover` | the fill of a hovered row or button (translucent) | 18 |+| `control` | neutral control fills (buttons, tracks, segmented controls) | 44 |+| `inputBg` | text fields | the SDK's `TextInput`, `SearchField` |++(The counts are uses of `t.<token>` in `apps/**/*.jsx` on 2026-10-26.)++**Optional tokens apps and the SDK read:**++- `accents`: a map name → color. Settings → Appearance shows these swatches and stores the chosen+ *name* (`settings.accent`). Use the same names as the bundled themes (`azul`, `violeta`, `rosa`,+ `naranja`, `verde`, `grafito`) so the user's choice survives a switch; `syncPortal` maps them to+ the portal's accent names.+- `wallpapers`: `[{ id, nameKey, name, src, thumb?, category?, variants? }]` for Settings →+ Wallpaper; `lordosWallpapers` from the SDK is the LordOS collection+ (`assets/wallpapers/README.md`).+- Shape tokens for the shared controls: `controlRadius`, `controlRadiusSmall`, `groupRadius`,+ `menuRadius`, `menuItemRadius`, `menuHighlight` (`'accent'`|`'subtle'`), `selection`+ (`'fill'`|`'indicator'`), `inputFocus` (`'ring'`|`'underline'`), `buttonBorder`, `popupBg`. They+ restyle `Button`, `TextInput`, `GroupBox`, `SidebarItem`, menus… in every app without touching+ the apps ([DESIGN.md](DESIGN.md#theme-tokens-for-the-shared-controls)).+- Scroll bars: `scrollThumb`, `scrollThumbHover`, `scrollRadius`, `scrollThumbBorder`.+- `gtkButtons`: the GTK title-bar button order sent to Linux apps (`':minimize,maximize,close'` for+ buttons on the right; by default `'close,minimize,maximize:'`).+- `radius`: a general corner radius (default 8).++`ThemeProvider` adds two tokens from the user's settings: `scrollBars` and `reduceMotion`. The+user's choices that a theme turns into tokens itself are in `settings` (`sdk/settings.js`): `mode`,+`accent` (a name), `effects` (transparency with blur), `wallpaper`. Both bundled themes do it with a+`makeTheme({ mode, accent, effects })` in `tokens.js`, called on every render with+`useSettings()`, so a change in Settings → Appearance applies at once.++### `index.jsx`: what it does and how the shell starts it++There is no exported component: `index.jsx` is a script that runs once when the bundle is+evaluated. The order the bundled themes follow:++```jsx+import { startShell, configureWindows, ThemeProvider, useSettings, useWindows, getApp, Layer } from '@lordos/sdk';+import { apps } from '@lordos/apps'; // every native app in apps/, added by the build+import { makeTheme } from './tokens.js';++// 1. At module level: the apps, the work area and the frame size (before startShell)+configureWindows({ apps, workArea: (d) => areaFor(d), chrome: { w: 2, h: TITLE_H + 2 } });++function App() {+ const [s] = useSettings();+ const t = makeTheme(s);+ const { windows, visible, focused } = useWindows();+ return (+ <ThemeProvider tokens={t}>+ {/* wallpaper, <DesktopWidgets layer="below" />, the windows, <DesktopWidgets layer="above" /> */}+ {/* <Layer name="dock">…</Layer>, <Layer name="menubar">…</Layer>, popovers, modals */}+ </ThemeProvider>+ );+}++// 2. Last: the SDK starts the desktop+startShell(<App />);+```++**`configureWindows({ apps, workArea, chrome, snap })`** (`sdk/windows.js`):++- `apps`: always the `apps` from `@lordos/apps`.+- `workArea`: a function `display → { x, y, w, h }`, the free area for windows on that display+ (without the bar and the Dock). Maximize, snapping, new windows and `wm.beginMove`'s top limit use+ it. An object is still accepted and means the main display's area. Call it again when the bar or+ Dock changes (both themes do it in a `useEffect` on the Dock settings and the screen size).+- `chrome: { w, h }`: how much the frame adds around the content (borders plus title bar), so a+ Linux window opens at the size it asked for.+- `snap: true`: window snapping (drag to the edges, `wm.snap`, `wm.snapKey`, the `snapPreview`+ store to draw the preview; [WINDOWS.md](WINDOWS.md#snapping-083)). Lord Classic turns it on.++**`startShell(element)`** (`sdk/index.js`): switches to the user's theme if it isn't this one, turns+the layers on, reopens the windows after a theme switch, renders your element inside a root that+remounts on a language change, and adds the SDK's own surfaces in their layers (search,+clipboard and emoji panels, print dialog, notification banners, prompts, Identify displays,+fullscreen windows, the input method). It also starts the background services every theme gets:+alarms, mail and reminder notifications, hardware (Night Light, idle, battery), disk health,+browser video, the network item, and the "modified component" notice.++The window objects (`useWindows()`: `windows` all of them bottom to top, `visible` without+minimized/fullscreen/picture-in-picture, `focused` the id in front) carry `id`, `app`, `title`,+`args`, `x`, `y`, `w`, `h`, `minimized`, `maximized`, `snapped`, `fullscreen`, `pip`, `protected`+and, for Linux windows, `windowMenu`. Use `wm.frame(w)` for the effective geometry (a maximized+window takes the work area), `windowTitle(w)` for the title, `windowIcon(w)` for its icon, and+`getApp(w.id)` for the app (`transparent`, `minSize`, `name`…). The `wm` object has `open`, `close`,+`focus`, `minimize`, `toggleMaximize`, `snap`, `center`, `moveToDisplay`, `arrange`, `move`,+`resize`, `setFrame`, `beginMove`, `beginResize` and more (`sdk/windows.js`).++Both bundled themes open windows at start (`wm.open('files')`, `wm.open('about')`); that is a+choice, not a requirement.++### Window frames++Build every frame on **`<WindowShell win={w} style={…} onMouseDown={() => wm.focus(w.id)}>`**+(`sdk/windowshell.jsx`). It positions the window, marks the node for the C side (`wm.frameRef`), and+adds invisible resize edges on 4 sides and 4 corners (6 px outside, 3 px inside) with their cursors.+Inside it:++- a title bar whose `onMouseDown` calls **`wm.beginMove(w.id)`**. Moving and resizing are then done+ by `lord-server` in C (`server/src/ui/grab.c`): React gets no event per frame, and the moving+ window is painted from a cached layer ([WINDOWS.md](WINDOWS.md)). `beginMove` returns `false` when+ it can't (a maximized window, no button held); Lord Classic then drags out of the maximized place+ in JS with `wm.move`;+- **`<AppHost id={w.id} focused={…} />`** for the content, in a `flex: 1` box;+- no background under the content when `getApp(w.id).transparent` (the Terminal). Such a window has+ nothing behind its border either: draw the border with `solidOver(line, titleBg)` so it stays+ opaque (both themes do);+- the title with `windowTitle(w)` (apps change it, for example the Terminal);+- buttons that `stopPropagation()` on mouse down, so pressing them doesn't start a move.++**Linux windows** enter as windows of the internal app `linux` (`sdk/wayland.js`). When+**`w.args.csd`** is true the app draws its own title bar: render only `<WindowShell>` ++`<AppHost>` (with your shadow) and no frame. `args.csd` can change while the window is open (the+browsers' "tabs in the title bar" switch), so decide on every render. When such an app asks for the+window menu (a right click on its own bar), `w.windowMenu` is `{ x, y }`: draw your window menu there+and call `wm.closeWindowMenu(w.id)` when it closes ([WAYLAND.md](WAYLAND.md)). With `chrome`+declared in `configureWindows`, server-side-decorated windows open at the size they requested.++### Menus++The SDK gives menus as **item lists**; the theme draws them. An item is+`{ label, onClick, hint, disabled, checked, submenu, header }` or `'-'` for a separator.++| Source | What it is |+|---|---|+| `useAppMenus(winId)` | the app's own menus (`[{ label, items }]`, e.g. the Terminal's Shell, Edit, View); `null` if it has none. Isolated apps' menus come through the broker and arrive the same way |+| `appMenuItems(winId)` | the app menu: About *app*, Settings…, Hide, Hide Others, Show All, Quit (`sdk/appcontrol.js`) |+| `windowMenuItems(winId)` | the Window menu, the same in every theme: Minimize, Zoom, Fill, Center, Move & Resize (halves, quarters, thirds, arrangements), Move to *display*, Bring All to Front, the window list (`sdk/windowmenu.js`) |+| `dockMenu(entry)` | a Dock or taskbar item's context menu |+| `trashMenu({ onEmpty })` | the Trash's menu |+| `recentItems(n)`, `storeUpdates()`, `runningApps()`, `forceQuit(key)`, `appGroup(winId)` | for a system menu like Lord Flow's crown menu |++Where they go is the theme's choice: Lord Flow shows the app menus in its top menu bar+(`themes/default/components/MenuBar.jsx`), Lord Classic in a strip under each window's title bar+(`themes/classic/components/Window.jsx`). A theme without either must still give the app's menus a+place, or the apps lose commands. Each bundled theme has its own `components/Menu.jsx` that puts the+menu in the `popover` layer.++### Layers++`zIndex` only orders siblings. Everything above the windows goes into a named **layer**:+`<Layer name="dock|menubar|overlay|popover|modal|notification|tooltip|drag">` (the full order, with+`floating`, `system` and `input` reserved for the SDK, is in `sdk/layers.js` and+[LAYERS.md](LAYERS.md)). The layer, not the tree, decides what is drawn and clicked on top, so a menu+is never under the Dock. A popover anchored to a control is `<Overlay anchor={ref} onClose={…}>`.+While something is in `overlay`, `modal` or `system`, Linux apps don't get the keyboard; `popover`+keeps it.++### The Dock or taskbar++`sdk/dock.js` is the model; the theme draws it ([DOCK.md](DOCK.md)):++```js+const entries = useDockEntries(['files', DOCK_LAUNCHER, 'terminal', 'settings'], { launcher: { Icon, onOpen }, recents: 0 });+// entry = { id, kind, name, Icon, windows, pinned, running, focused, locked, movable, … }+dockActivate(entry); // click: launch, or bring up (cycle) its windows+dockMenu(entry); // context menu items+dock.pin(id, i) · dock.move(id, i) · dock.unpin(id) · dock.reset()+```++Pinned items are typed ids (`app:`, `lpk:`, `desktop:`, `shell:launcher`; `sdk/dockmodel.js`);+Files is always first and the Trash last. `dockPrefs(settings)` gives the user's position, size,+magnification and auto-hide (and `taskbarPosition` for a taskbar). Dragging uses+`beginDockDrag`, `registerDockTarget`, the `dockDrag` and `dockPoof` stores (the theme draws the+drag image and the "poof"). The Trash: `useTrash()`, `openTrash()`, `emptyTrash()` (ask first with+`ConfirmDialog`).++### Panels: launcher, Control Center, quick settings, notifications++There are no ready-made panels in the SDK: each theme draws its own from SDK stores and controls.++- **App launcher / start menu:** `useLauncherApps()` (LordOS apps and installed Linux apps, sorted by+ name, with `name`, `Icon`, `kind`), `launchApp(id)`, `appCategory(app)`, `APP_CATEGORIES`;+ system-wide search results from `searchEverything` (Lord Classic's start menu).+- **Control Center / quick settings:** `Toggle`, `Slider`, `Segmented`; `useSound`, `sound`,+ `defaultSink`; `useBluetooth`; `useBattery`, `BatteryGlyph`; `nightActive`, `setNightManual`;+ `notifyPrefs`, `dndActive` (Do Not Disturb); `NowPlayingTile`; `useCpuUsage`, `useSystemInfo`;+ `keyboard.label(keyboard.active())`, `keyboard.next()`. See+ `themes/default/components/ControlCenter.jsx` and `themes/classic/components/QuickSettings.jsx`.+- **Status area:** `<StatusItems color={…} />` (items apps register with `registerStatusItem`, such+ as the network item) and `<PrivacyIndicators />` (camera, microphone, screen in use).+- **Notifications:** banners are drawn by the SDK (`NotificationBanner`, placed by `startShell`);+ `setBannerPlacement('bottom')` puts them above a bottom taskbar. A notification centre reads+ `notifyHistory` (and `useNotifications()` for what is on screen), with `dismissNotification(id)`+ and `clearNotifyHistory()` (`themes/classic/components/NotificationCenter.jsx`).+- **Search:** the SDK's search panel opens with ❖Space or Ctrl+Space by itself; a button calls+ `spotlight.toggle()` ([SPOTLIGHT.md](SPOTLIGHT.md)).+- **Session:** `session.quit()`, `session.lock()`, `session.switchUser()` (with `session.managed()`),+ `session.restart()`, `session.shutdown()` (60 s confirmations; render `<PowerDialog />` in the+ `modal` layer, inside your `ThemeProvider`, so it takes your colors).+- **Gestures:** `registerGestureActions({ up, down, left, right })` in a `useEffect` (it returns the+ function that removes them; [TRACKPAD.md](TRACKPAD.md)).+- **Desktop widgets:** `<DesktopWidgets layer="below" />` between the wallpaper and the windows and+ `<DesktopWidgets layer="above" />` after them (the Notes app's notes, [NOTES.md](NOTES.md)).++Keyboard shortcuts of the layout are the theme's own (`addListener('keydown', …)`): both bundled+themes open their launcher or start menu with Super pressed and released alone, and Lord Classic+adds Super+arrows, Super+Tab, Alt+F4. The SDK already handles ❖Space (search) and ❖L / ❖Ctrl+Q (lock).++### The login and lock screen are not your theme++`themes/greeter` is loaded by `lord-sessiond` with `lord-server --greeter`, as the system user+`lordos-greeter`, from a fixed path (`server/src/remote/sessiond.c`). It is also the lock screen+(mode `lock`) and the user switcher. It calls `render()` itself instead of `startShell()`, and it never+sees passwords being checked: it sends them with `lord.greeter.send()` and the root process answers+([SESSIONS.md](SESSIONS.md)). A desktop theme can't replace or restyle it; the first frame of a+boot (the hand-off from the boot splash) is the greeter's, or the default theme's with autologin.++### Right to left++With Arabic or Hebrew the engine flips rows and alignment by itself. Your part+([LANGUAGES.md](LANGUAGES.md)):++- text that follows the language uses `textAlign: 'start'`/`'end'`, never `'left'`/`'right'`;+- use the logical edges (`paddingStart`, `marginInlineEnd`, `insetInlineStart`,+ `borderTopStartRadius`…) instead of physical ones;+- anything positioned from the mouse x (a magnifying Dock) is laid out with `direction: 'ltr'` or+ takes `direction()` into account; drop-down menus open towards the inside (`direction() === 'rtl'`);+- physical things stay physical: Super+Left snaps to the left in any language, and the Dock's+ `left`/`right` positions are screen sides.++### Light, dark, accent, transparency and motion++- Build every color from `mode` (both themes switch the whole palette in `makeTheme`).+- The accent comes as a name (`settings.accent`) mapped through your `accents`.+- `settings.effects === false` means "no transparency": draw opaque bars and `blur: 0`.+- **Reduce motion** (`settings.reduceMotion`, also `useTheme().reduceMotion`): skip decorative+ animation (both themes skip the Dock's "poof" when an item is removed, Lord Flow also the Dock's+ reorder glide; `ScrollView` stops fading).++### Several displays++Use `screenDisplays()` (`[{ id, name, x, y, w, h, scale, main }]`), `mainDisplay()`,+`displayAt(x, y)`, `displayFor(rect)` and `screen.mirror` ([DISPLAYS.md](DISPLAYS.md#the-theme-and-the-sdk)).+The bundled themes draw a wallpaper per display at its pixel size+(`wallpaperSrc(w, d.w * d.scale / 100, d.h * d.scale / 100)`), and put the bar and the Dock on the+main display (Lord Flow also on the others with "Show menu bar on all displays",+`settings.menuBarAllDisplays`). Your `workArea` function receives each display; `workAreaOf(d)` and+`pointerWorkArea()` read it back. New windows open on the display under the pointer, or the one the+user assigned the app to from the Dock. The window list is global: windows are not per display.++### Performance rules++Everything runs on `lord-server`'s main thread, which also composites the screen and serves the+Linux apps. A slow theme makes the whole desktop slow.++- **No React render per frame.** Moving and resizing windows is already in C. To animate, change one+ style with **`lord.setStyle(ref.current.id, 'opacity' | 'transform' | …, value)`** from a timer or+ `requestAnimationFrame` (the `ScrollView` thumb fade in `sdk/components.jsx`, the fans in+ `sdk/cooling.jsx`); stop the loop when the animation ends or the surface is hidden, and don't start+ it with reduce motion.+- **`transform` scale and rotate are cheap**: the subtree is painted once into a cached raster and+ composited (Lord Flow's minimize effect scales a whole window).+- **Blur costs**: `backdropFilter: blur(r)` reads a margin of 2×r around the surface, and any change+ touching it repaints the whole surface ([LAYERS.md](LAYERS.md#blurred-surfaces-and-partial-repaints)).+ Keep blurred surfaces few and small, and turn blur off with `effects: false`.+- **Subscribe narrowly**: `useStore(store, selector)` re-renders only when the selected value changes;+ a clock that renders every second should only re-render its own text.+- **Don't poll** when a store exists (sound, battery, Bluetooth and displays arrive as events). Lord+ Classic's network glyph polls every 5 s; that is the upper bound to aim for.+- The style subset has no CSS animations, dashed borders, skew or 3D (`themes/README.md`). An+ unknown style key is logged as `js: unsupported style '<key>'`.++### Images, fonts and other files++`<Image src="assets/x.png">` is resolved against the theme's folder; `asset:wallpapers/…` against+LordOS's `assets/`; an absolute path as is (`server/src/ui/js.c`). PNG and JPEG. Text uses the+bundled Inter (400/500/600/700). The `.deb` packaging copies only `theme.json`, `theme.bundle.js`+and `assets/` of each theme (`tools/iso/mkdeb.sh`), so keep your files there.++### Translations++Visible text goes through `t('namespace.key')` ([LANGUAGES.md](LANGUAGES.md)); app names through+`appName(app)`, dates and times through `formatDate`/`formatTime`. The bundled themes' strings are in+the `shell` catalog (`assets/locales/{en,es,pt}/shell.json`). A theme of your own can reuse existing+`shell.*` keys (the example does) or bring its own namespace: `lord.locale.catalog` reads+`<lang>/<namespace>.json` from `~/.local/share/lordos/locales/` first and then LordOS's+`assets/locales/` (`f_locale_catalog` in `js_sys.c`). A missing key shows the key itself. Inside the+LordOS tree, `node tools/i18n-check.mjs` checks every `t()` key in `themes/` against the English+catalog and every language against English.++## 3. Building it++`npm install` once (React, the reconciler and esbuild), then:++```sh+npm run build # every theme, the isolated-app host and the system apps+node tools/build-theme.mjs <id> # only themes/<id>+```++`tools/build-theme.mjs` bundles `themes/<id>/index.jsx` with esbuild into+**`themes/<id>/theme.bundle.js`** (one minified IIFE, ES2020, JSX automatic). React, the reconciler,+`@lordos/runtime` (`runtime/index.js`) and `@lordos/sdk` (`sdk/index.js`) are **bundled into it**, and+so is every native app: the virtual module `@lordos/apps` imports `apps/<id>/index.jsx` and+`manifest.json` for each app (and checks that each has a semver `version`). That is why a theme+bundle is 1.5–1.8 MB and why every theme carries the same apps. Apps with `"process": "isolated"`+(Passwords, Mail…) run as their own processes; in the theme they are only a starter+(`isolatedApp` in `sdk/packages.js`).++The tool only builds folders under `themes/` of the tree it lives in: there is no option for a theme+elsewhere, so a theme is developed inside a LordOS development tree (copy it to `themes/<id>`).++After building, it rewrites **`code-manifest.json`** at the tree's root (`tools/code-manifest.mjs`):+the size and SHA-256 of every `themes/*/theme.bundle.js`, `assets/app-host.bundle.js` and+`assets/sysapps/*/app.js`. If the manifest changed, a `code-manifest.sig` next to it is deleted (it+signed the old one).++### Verified code: what happens to a theme that LordOS did not sign++LordOS's own JavaScript is checked before it runs ([SIGNING.md](SIGNING.md#verified-system-code-082)).+Every bundle goes through `codesig_load` (`server/src/sec/codesig.c`, called from `load_code` in+`server/src/ui/js.c`): once per process `lord-server` reads `code-manifest.json` and+`code-manifest.sig` from the LordOS folder (`/usr/lib/lordos` installed, the repository root in a+development tree) and verifies the signature with the release key compiled into it. Then, per+bundle:++| `lord-server` build | Manifest in the LordOS folder | A `themes/<id>/theme.bundle.js` that is not listed |+|---|---|---|+| **Release** (`make -C server RELEASE=1`; the published images and `.deb`) | signed by LordOS | **refused**: `code: REFUSED themes/<id>/theme.bundle.js: not listed in the manifest` |+| Release | missing, unsigned, or a bad signature | **everything is refused** (state "invalid"): the recovery screen |+| Development (`make -C server`) | none | **loads** (About says "Development build") |+| Development | unsigned (what `npm run build` writes) | **refused unless listed**: the hashes are still checked, so rebuild with `npm run build` / `build-theme.mjs` to list it |+| Development | signed | refused unless listed |++So on an installed release system, copying a theme into `/usr/lib/lordos/themes/<id>/` (which needs+root anyway) makes it **appear** in Settings → Appearance → Desktop style (the list only looks for a+readable `theme.bundle.js`), but choosing it does nothing visible except a notice: the switch is+refused, `lord-server` reloads the theme it was on (`switch_theme`), the session shows the sticky+notification "This LordOS component was modified and was not loaded" naming the file+(`sdk/codesig.js`), and choosing it again in that session does nothing (`ui.theme_failed`). Because `theme` was already+saved in the settings, the same happens once at every login. **Do not** try to make it load by+regenerating the installed manifest: on a release build an unsigned or changed manifest invalidates+all of LordOS's code and leaves only the recovery screen.++A bundle outside the LordOS folder (for example `lord-server --theme /home/me/x/theme.bundle.js`)+is run only when the state is "development" (a development build with no manifest or an unsigned+one), logged as `code: … loaded unchecked (outside …, development build)`; otherwise it is refused+with "not part of LordOS's system code".++**Third-party themes can't run on release builds today.** That is deliberate for now: a theme is not+sandboxed. It runs inside `lord-server`, in the same JavaScript context as every native app, with+the whole `lord.*` API of the session (files, the terminal, the network, administrator requests),+and it sees the desktop's keyboard and pointer input. It also carries its own copy of the SDK,+including the code that shows the permission prompts and records the answers (`lord.perms.set`,+`server/src/ui/js_sec.c`), so a theme decides what those prompts do. Supporting+them would need, at least: a theme package format and a separate, user-confirmed trust decision+(signed like `.lpk` packages, [SIGNING.md](SIGNING.md), not the LordOS release key), a place for+user-installed themes that the code check knows about, and probably a narrower API for theme code+than what built-in code gets. None of that exists yet.++## 4. Installing and testing++**Where themes live.** Installed: `/usr/lib/lordos/themes/<id>/` (`theme.json`, `theme.bundle.js`,+`assets/`), next to `/usr/lib/lordos/code-manifest.json`; the development VMs also use+`/usr/local/lib/lordos` ([VM-SETUP.md](VM-SETUP.md), step 22). The list of themes is the folder that+holds the running theme's folder (`themes_root` in `js_sys.c`); there is no per-user themes folder.++**Trying one in a development session** (a development build of `lord-server`, see the table+above):++1. Put the theme in `themes/<id>` of your LordOS tree and run `node tools/build-theme.mjs <id>` (or+ `npm run build`).+2. Copy the tree to the VM and build `lord-server` as in [VM-SETUP.md](VM-SETUP.md), step 6 (`themes/`+ and `assets/` with `server/`). Copy `code-manifest.json` too, or none at all: a stale manifest+ refuses the new bundle.+3. Start it and choose the theme in **Settings → Appearance → Desktop style**. Passing+ `--theme ../themes/<id>/theme.bundle.js` to a standalone `sudo ./build/lord-server` also works,+ but `startShell` switches to the theme saved in `~/.config/lordos/settings.json` (`"theme"`) if it+ is another one, so set that too.+4. After rebuilding, switch to another theme and back (or log out and in) to load the new bundle.+ There is no hot reload.++A theme that throws while its bundle is evaluated makes the switch fall back to the theme you came+from (`lord-server: the theme failed, going back to …`); the error is in the log. Keep Lord Flow or+Lord Classic installed: they are the fallback (`start_theme` in `main.c`).++**Debugging.**++- Sessions started by `lord-sessiond` write their log to **`~/.cache/lordos/session.log`** (the login+ screen to `greeter.log`); a standalone `lord-server` writes to the terminal it was started from.+- `console.log`, `.info`, `.debug` → `js: …` lines; `console.warn` → `js: [warn] …`;+ `console.error` → `js: [error] …` (the prelude in `server/src/ui/js.c`). Exceptions in timers+ and animation frames are logged as `js: [error] timer: …` / `raf: …`.+- Useful lines: `js: theme <path> loaded in N ms (K KB)`, `code: …` (the verified-code state and each+ check or refusal), `lord-server: cambiando a tema <path>` (a switch), `js: unsupported style '<key>'`.+- `sudo /usr/lib/lordos/bin/lord-server --check-code [<folder>]` checks a whole tree the way a session+ would; `lord-server --debug` and `--profile` (per-primitive timings) for drawing problems.+- `lord.getLayout(node.id)` returns `[x, y, w, h]` of a node (both themes use it to place menus).++## 5. Checklist before sharing a theme++Check each item on a real session and take a screenshot ([VM-SETUP.md](VM-SETUP.md), `screendump`):++- **Both kinds of window:** LordOS apps (the Terminal for a transparent one, Settings, Files) and+ Linux apps with and without their own frame (`args.csd`), including the window menu from a right+ click on an app's own bar, and an app opening at the size it asked for (`chrome`).+- **Menus:** every app's menus are reachable (`useAppMenus`), the Window menu works, menus never open+ under the Dock or off screen.+- **Light and dark**, every accent, transparency on and off.+- **Right to left:** with the Arabic test pack (`docs/packs/lordos-lang-ar.json`): rows mirrored,+ `textAlign: 'start'`, menus opening inwards, mouse-driven pieces in `direction: 'ltr'`.+- **Translations:** no hard-coded text; en, es and pt at least; long translations truncate with an+ ellipsis instead of overflowing.+- **Accessibility:** readable contrast of `text` and `textDim` on `windowBg`, `sidebarBg` and your+ bars in both modes; reduce motion respected; everything opened from the keyboard can be closed+ with Escape; targets big enough to hit with a touchpad.+- **Several displays:** wallpaper on each, the work area right on each, maximize on a second display,+ a display unplugged and plugged back, mirror mode; and a single display at 150 % scale.+- **The work area follows the bar and the Dock** (position, size, auto-hide) live.+- **Performance:** dragging and resizing stay smooth with your blur; nothing re-renders per frame+ when idle (no `requestAnimationFrame` loop left running).+- **Theme switch both ways** with windows open: they come back in your theme, and back in Lord Flow.+- **The login and lock screen** are the system's (`themes/greeter`): nothing in your theme should+ try to imitate them.+- **Notifications, search, permission prompts and the power dialog** look right inside your+ `ThemeProvider` (they use your tokens).+- And the [DESIGN.md](DESIGN.md#robustness-checklist) robustness checklist.diff --git a/examples/theme-minimal/README.md b/examples/theme-minimal/README.mdnew file mode 100644index 0000000..742bb8e--- /dev/null+++ b/examples/theme-minimal/README.md@@ -0,0 +1,44 @@+# Minimal: an example LordOS theme++A deliberately small theme that shows every piece a LordOS theme needs, for the guide+[`docs/THEMES-GUIDE.md`](../../docs/THEMES-GUIDE.md):++- `theme.json`: the name and description Settings → Appearance → Desktop style shows;+- `tokens.js`: the base tokens every app reads (`mode`, `accent`, `text`, `textDim`, `windowBg`,+ `sidebarBg`, `separator`, `hover`, `control`, `inputBg`), the `accents` map, the wallpapers, and a+ few keys of its own (`titleBg`, `windowBorder`, `barBg`, `blur`, `shadow`);+- `index.jsx`: the work area (`configureWindows`), a window frame built on `<WindowShell>` and+ `<AppHost>` (moving and resizing in C), Linux windows that draw their own frame (`args.csd`) and+ their window menu, a bar in the `dock` layer with an apps menu, one button per window and a clock,+ menus in the `popover` layer built from the SDK's item lists (`useAppMenus`, `windowMenuItems`),+ the power confirmations, desktop widgets, a wallpaper per display, and `startShell`.++It has no text of its own: every label is an existing key of the `shell` catalog+(`shell.menu.apps`, `shell.menu.settings`, `shell.menu.logout`, `shell.menu.window`,+`shell.classic.minimize`, `shell.classic.maximize`, `shell.classic.restore`, `shell.classic.close`),+so it is translated into every language LordOS ships. A theme with new text adds its own catalog (see+the guide, "Translations").++## Building it++Themes are built from the `themes/` folder of a LordOS development tree; `tools/build-theme.mjs`+has no option for a theme elsewhere. Copy this folder in and build only it:++```sh+cp -R examples/theme-minimal themes/minimal+node tools/build-theme.mjs minimal # → themes/minimal/theme.bundle.js (about 1.8 MB)+```++The build also rewrites `code-manifest.json` with the new bundle in it (and removes a+`code-manifest.sig` that no longer matches). That is what lets a development build of lord-server+load it; a release build will not (see the guide, "Verified code: what happens to a theme that+LordOS did not sign").++`themes/minimal` is a copy for your own tree: don't commit it to LordOS.++## Status++Built with the repository's own tooling (`node tools/build-theme.mjs minimal`, esbuild 0.24.2) on+2026-10-26 in a copy of the tree, where `node tools/i18n-check.mjs` also passed with it in `themes/`.+**Not yet run on a LordOS session**: there is no screenshot of it,+so treat it as a starting point and check it with the guide's checklist.diff --git a/examples/theme-minimal/index.jsx b/examples/theme-minimal/index.jsxnew file mode 100644index 0000000..f1130d7--- /dev/null+++ b/examples/theme-minimal/index.jsx@@ -0,0 +1,199 @@+// "Minimal" — an example LordOS theme (docs/THEMES-GUIDE.md). It is deliberately small: a bar at+// the bottom of the main display with an apps menu, one button per open window and a clock; a plain+// window frame; menus from the SDK's item lists. Everything an app needs from a theme is here+// (tokens, frames, both kinds of window, the work area, layers); the polish of the bundled themes+// (themes/default, themes/classic) is not.+//+// tokens.js the colors (the contract with the apps) and this theme's own keys+// index.jsx this file: work area, window frame, bar, menus, startShell+import {+ startShell, View, Text, Image, Layer, ScrollView, ThemeProvider, useSettings, useWindows, configureWindows, getApp, wm, AppHost,+ WindowShell, windowTitle, windowIcon, useAppMenus, windowMenuItems, useLauncherApps, launchApp, DesktopWidgets, PowerDialog,+ findWallpaper, wallpaperSrc, mainDisplay, screenDisplays, screen, useClock, formatTime, solidOver, session, t as tr,+} from '@lordos/sdk';+import { apps } from '@lordos/apps';+import { useState } from 'react';+import { makeTheme } from './tokens.js';++const BAR_H = 40;+const TITLE_H = 32;++// The free area for windows on each display: the bar takes the bottom of the main one; the other+// displays are all work area (docs/DISPLAYS.md). Maximized and new windows use it.+const workAreaFor = (d) => (d.main ? { x: d.x, y: d.y, w: d.w, h: d.h - BAR_H } : { x: d.x, y: d.y, w: d.w, h: d.h });++// chrome: what the frame adds around the content (1 px borders and the title bar), so Linux windows+// open at the size they ask for.+configureWindows({ apps, workArea: workAreaFor, chrome: { w: 2, h: TITLE_H + 2 } });++// A menu from the SDK's item lists ([{ label, onClick, hint, disabled, checked, submenu, header } | '-'],+// as useAppMenus, windowMenuItems and dockMenu return them). A submenu is shown inline under its+// label, to keep the example short. at: { x, y } where it opens, or { x, bottom } to open upwards.+function Menu({ t, at, items, onClose }) {+ const W = 240;+ const flat = [];+ const add = (list) => {+ for (const it of list || []) {+ if (it && it !== '-' && it.submenu) { flat.push({ label: it.label, header: true }); add(it.submenu); flat.push('-'); } else flat.push(it);+ }+ };+ add(items);+ // rows are 26 px and separators 9 px: a long list (every installed app) scrolls+ const h = Math.min(flat.reduce((n, it) => n + (it === '-' || it == null ? 9 : 26), 0), screen.height - 140);+ const left = Math.max(8, Math.min(at.x, screen.width - W - 8));+ const place = at.bottom != null ? { bottom: at.bottom } : { top: Math.max(8, Math.min(at.y, screen.height - h - 20)) };+ return (+ <Layer name="popover">+ {/* a click anywhere outside closes it */}+ <View onMouseDown={onClose} style={{ position: 'absolute', left: 0, top: 0, right: 0, bottom: 0 }} />+ <View onMouseDown={(e) => e.stopPropagation()}+ style={{ position: 'absolute', left, ...place, width: W, padding: 5, borderRadius: t.menuRadius, backgroundColor: t.popupBg || t.windowBg,+ border: `1px solid ${t.windowBorder}`, boxShadow: t.shadow }}>+ <ScrollView style={{ height: h }}>+ {flat.map((it, i) => (it === '-' || it == null+ ? <View key={i} style={{ height: 1, marginVertical: 4, backgroundColor: t.separator }} />+ : <MenuItem key={i} t={t} item={it} onClose={onClose} />))}+ </ScrollView>+ </View>+ </Layer>+ );+}++function MenuItem({ t, item, onClose }) {+ const [hover, setHover] = useState(false);+ const off = item.disabled || item.header;+ return (+ <View onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}+ onClick={() => { if (off) return; onClose(); item.onClick?.(); }}+ style={{ flexDirection: 'row', alignItems: 'center', height: 26, paddingHorizontal: 8, borderRadius: t.menuItemRadius,+ backgroundColor: hover && !off ? t.accent : 'transparent' }}>+ <Text style={{ width: 16, fontSize: 12, color: hover && !off ? '#ffffff' : t.text }}>{item.checked ? '✓' : ''}</Text>+ <Text style={{ flex: 1, fontSize: 13, textAlign: 'start', whiteSpace: 'nowrap', textOverflow: 'ellipsis',+ fontWeight: item.header ? 600 : 400, color: hover && !off ? '#ffffff' : off ? t.textDim : t.text }}>{item.label}</Text>+ {item.hint ? <Text style={{ fontSize: 12, color: hover && !off ? '#ffffff' : t.textDim }}>{item.hint}</Text> : null}+ </View>+ );+}++function FrameButton({ t, label, onClick }) {+ const [hover, setHover] = useState(false);+ return (+ <View onMouseDown={(e) => e.stopPropagation()} onClick={onClick} onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}+ style={{ height: 22, paddingHorizontal: 8, borderRadius: t.controlRadiusSmall, justifyContent: 'center', backgroundColor: hover ? t.hover : 'transparent' }}>+ <Text style={{ fontSize: 12, color: t.text, whiteSpace: 'nowrap' }}>{label}</Text>+ </View>+ );+}++// One window. Moving and resizing happen in C (WindowShell's edges, wm.beginMove): React gets no+// event per frame. A Linux window with its own decorations (args.csd) gets only the content.+function Window({ t, win, focused }) {+ const app = getApp(win.id);+ const menus = useAppMenus(win.id) || [];+ const [menu, setMenu] = useState(null);+ const border = focused ? t.windowBorder : t.separator;+ const items = [...menus.map((m) => ({ label: m.label, submenu: m.items })), { label: tr('shell.menu.window'), submenu: windowMenuItems(win.id) }];++ if (win.args?.csd) {+ // the app draws its own bar; a right click on it asks for the window menu (win.windowMenu)+ return (+ <WindowShell win={win} onMouseDown={() => wm.focus(win.id)} style={{ boxShadow: t.shadow }}>+ <AppHost id={win.id} focused={focused} />+ {win.windowMenu && <Menu t={t} at={win.windowMenu} items={windowMenuItems(win.id)} onClose={() => wm.closeWindowMenu(win.id)} />}+ </WindowShell>+ );+ }+ const Icon = windowIcon(win);+ return (+ <WindowShell win={win} onMouseDown={() => wm.focus(win.id)} style={{+ borderRadius: win.maximized ? 0 : 8, overflow: 'hidden', boxShadow: focused ? t.shadow : undefined,+ backgroundColor: app?.transparent ? 'transparent' : t.windowBg,+ // a transparent app (the Terminal) has nothing behind its border: draw it already mixed+ border: `1px solid ${app?.transparent ? solidOver(border, t.titleBg) : border}`,+ }}>+ <View onMouseDown={(e) => { if (!e.button) wm.beginMove(win.id); }} onDoubleClick={() => wm.toggleMaximize(win.id)}+ onContextMenu={(e) => setMenu({ x: e.x, y: e.y })}+ style={{ height: TITLE_H, flexDirection: 'row', alignItems: 'center', gap: 8, paddingStart: 10, paddingEnd: 4,+ backgroundColor: t.titleBg, borderBottom: `1px solid ${t.separator}` }}>+ {Icon ? <Icon size={16} /> : null}+ <Text style={{ flex: 1, fontSize: 12, fontWeight: 500, textAlign: 'start', whiteSpace: 'nowrap', textOverflow: 'ellipsis',+ color: focused ? t.text : t.textDim }}>{windowTitle(win)}</Text>+ <FrameButton t={t} label={tr('shell.classic.minimize')} onClick={() => wm.minimize(win.id)} />+ <FrameButton t={t} label={tr(win.maximized ? 'shell.classic.restore' : 'shell.classic.maximize')} onClick={() => wm.toggleMaximize(win.id)} />+ <FrameButton t={t} label={tr('shell.classic.close')} onClick={() => wm.close(win.id)} />+ </View>+ <View style={{ flex: 1 }}><AppHost id={win.id} focused={focused} /></View>+ {menu && <Menu t={t} at={menu} items={items} onClose={() => setMenu(null)} />}+ </WindowShell>+ );+}++// The bar: apps menu at the start, the windows, the clock at the end. The row flips by itself in a+// right-to-left language.+function Bar({ t, windows, focused, onApps }) {+ const m = mainDisplay();+ const clock = useClock((d) => formatTime(d), 1000);+ const own = windows.filter((w) => !(getApp(w.id)?.builtin && !String(w.id).startsWith('linux#')));+ return (+ <View style={{ position: 'absolute', left: m.x, top: m.y + m.h - BAR_H, width: m.w, height: BAR_H, flexDirection: 'row', alignItems: 'center',+ gap: 4, paddingHorizontal: 6, backgroundColor: t.barBg, backdropFilter: t.blur ? `blur(${t.blur}px)` : undefined,+ borderTop: `1px solid ${t.separator}` }}>+ <FrameButton t={t} label={tr('shell.menu.apps')} onClick={onApps} />+ <View style={{ flex: 1, flexDirection: 'row', gap: 4, overflow: 'hidden' }}>+ {own.map((w) => {+ const Icon = windowIcon(w);+ const front = w.id === focused;+ return (+ <View key={w.id} onClick={() => (front ? wm.minimize(w.id) : wm.focus(w.id))}+ style={{ maxWidth: 200, height: 30, flexDirection: 'row', alignItems: 'center', gap: 6, paddingHorizontal: 8, borderRadius: t.controlRadius,+ backgroundColor: front ? t.hover : 'transparent', borderBottom: `2px solid ${front ? t.accent : 'transparent'}` }}>+ {Icon ? <Icon size={18} /> : null}+ <Text style={{ fontSize: 12, color: w.minimized ? t.textDim : t.text, whiteSpace: 'nowrap', textOverflow: 'ellipsis' }}>{windowTitle(w)}</Text>+ </View>+ );+ })}+ </View>+ <Text style={{ fontSize: 13, color: t.text, paddingHorizontal: 8 }}>{clock}</Text>+ </View>+ );+}++function App() {+ const [s] = useSettings();+ const t = makeTheme(s);+ const { windows, visible, focused } = useWindows();+ const launcher = useLauncherApps();+ const [appsMenu, setAppsMenu] = useState(null);+ const m = mainDisplay();+ const wallpaper = findWallpaper(t.wallpapers, s.wallpaper);+ const appItems = [+ ...launcher.map((a) => ({ label: a.name, onClick: () => launchApp(a.id) })),+ '-',+ { label: tr('shell.menu.settings'), onClick: () => wm.open('settings') },+ { label: tr('shell.menu.logout'), onClick: () => session.quit() },+ ];+ return (+ <ThemeProvider tokens={t}>+ <View style={{ width: '100%', height: '100%', backgroundColor: t.mode === 'dark' ? '#111114' : '#d5d9e0' }}>+ {/* a wallpaper per display, at that display's pixel size */}+ {screenDisplays().map((d) => (+ <Image key={d.id + ':' + d.x} src={wallpaperSrc(wallpaper, d.w * (d.scale || 100) / 100, d.h * (d.scale || 100) / 100)}+ style={{ position: 'absolute', left: d.x, top: d.y, width: d.w, height: d.h, objectFit: 'cover' }} />+ ))}+ <DesktopWidgets layer="below" />+ {visible.map((w) => <Window key={w.id} t={t} win={w} focused={w.id === focused} />)}+ <DesktopWidgets layer="above" />+ <Layer name="dock">+ <Bar t={t} windows={windows} focused={focused} onApps={() => setAppsMenu((v) => (v ? null : { x: m.x + 6, bottom: screen.height - (m.y + m.h - BAR_H) + 6 }))} />+ </Layer>+ {appsMenu && (+ <Menu t={t} at={appsMenu} onClose={() => setAppsMenu(null)} items={appItems} />+ )}+ {/* Restart… and Shut Down… confirmations (sdk/power.jsx) */}+ <Layer name="modal"><PowerDialog /></Layer>+ </View>+ </ThemeProvider>+ );+}++startShell(<App />);diff --git a/examples/theme-minimal/theme.json b/examples/theme-minimal/theme.jsonnew file mode 100644index 0000000..a33b4af--- /dev/null+++ b/examples/theme-minimal/theme.json@@ -0,0 +1,4 @@+{+ "name": "Minimal",+ "description": "An example theme: a bottom bar with an apps menu, the open windows and a clock."+}diff --git a/examples/theme-minimal/tokens.js b/examples/theme-minimal/tokens.jsnew file mode 100644index 0000000..b514f44--- /dev/null+++ b/examples/theme-minimal/tokens.js@@ -0,0 +1,41 @@+// Tokens of the "Minimal" example theme. The base keys (mode … inputBg) are the contract with the+// apps (sdk/theme.js, docs/THEMES-GUIDE.md "tokens.js"); every app reads them through useTheme().+// The keys after "This theme's own" are used only by this theme's frame and bar.+import { lordosWallpapers } from '@lordos/sdk';++// The same names as the bundled themes' accents, so the user's choice in Settings → Appearance+// survives a theme switch (Settings shows these swatches).+export const accents = {+ azul: '#3478f6',+ violeta: '#9b5de5',+ rosa: '#e5487f',+ naranja: '#f08c2e',+ verde: '#2fb171',+ grafito: '#7d7d85',+};++export function makeTheme({ mode, accent, effects }) {+ const dark = mode === 'dark';+ return {+ mode,+ accent: accents[accent] || accents.azul,+ accents,+ wallpapers: lordosWallpapers,+ text: dark ? '#f2f2f5' : '#1c1c21',+ textDim: dark ? 'rgba(242,242,245,0.58)' : 'rgba(28,28,33,0.6)',+ windowBg: dark ? '#1e1e22' : '#fcfcfd',+ sidebarBg: dark ? '#242429' : '#f2f2f5',+ separator: dark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.08)',+ hover: dark ? 'rgba(255,255,255,0.07)' : 'rgba(0,0,0,0.05)',+ control: dark ? '#34343a' : '#e6e6eb',+ inputBg: dark ? '#28282d' : '#ffffff',+ // GTK apps put their buttons on the right, like this frame+ gtkButtons: ':minimize,maximize,close',+ // This theme's own:+ titleBg: dark ? '#26262b' : '#ededf0',+ windowBorder: dark ? 'rgba(255,255,255,0.12)' : 'rgba(0,0,0,0.14)',+ barBg: dark ? (effects !== false ? 'rgba(28,28,32,0.82)' : '#1c1c20') : (effects !== false ? 'rgba(244,244,247,0.85)' : '#f1f1f4'),+ blur: effects !== false ? 20 : 0,+ shadow: dark ? '0 12px 32px rgba(0,0,0,0.5)' : '0 12px 32px rgba(0,0,0,0.2)',+ };+}diff --git a/server/src/main.c b/server/src/main.cindex 2e062f6..ab0d7db 100644--- a/server/src/main.c+++ b/server/src/main.c@@ -1540,7 +1540,9 @@ static int check_code(int argc, char **argv) {return bad ? 1 : 0;}-static void switch_theme(const char *current) {+/* 0 if the requested theme is running; -1 if it failed and `current` (the last one that loaded) was put+ * back: the caller keeps `current` then, so a second failed switch never falls back to a refused theme */+static int switch_theme(const char *current) {char path[sizeof ui.theme_request];snprintf(path, sizeof path, "%s", ui.theme_request);ui.theme_request[0] = 0;@@ -1553,9 +1555,12 @@ static void switch_theme(const char *current) {snprintf(ui.theme_failed, sizeof ui.theme_failed, "%s", path);js_shutdown();ui_reset();- js_init(current);+ if (js_init(current)) fprintf(stderr, "lord-server: %s did not load again either\n", current);+ wl_remap_all();+ return -1;}wl_remap_all(); /* Linux app windows stay connected: they come back in the new theme */+ return 0;}/* ---- Settings → Displays and the other hardware pages (src/hw, docs/SETTINGS.md) ---- */@@ -1765,8 +1770,7 @@ int main(int argc, char **argv) {if (ui.theme_request[0]) {char next[sizeof current];snprintf(next, sizeof next, "%s", ui.theme_request);- switch_theme(current);- snprintf(current, sizeof current, "%s", next);+ if (!switch_theme(current)) snprintf(current, sizeof current, "%s", next);}/* El movimiento del puntero juntado: una vez por cuadro, cuando terminó el page flip. Así un* mouse de 1000 Hz no llama a JS (ni a las apps Linux) mil veces por segundo. */diff --git a/themes/README.md b/themes/README.mdindex 3ebf816..1f188d2 100644--- a/themes/README.md+++ b/themes/README.md@@ -14,12 +14,17 @@ npm install # once (React + esbuild)npm run build # bundles every theme, with the SDK and every app```-The user switches themes live from **Settings → Appearance → Desktop style** (Lord Flow and-Lord Classic) or **Settings → Themes** (any installed theme), with no restart: the LordOS app windows that-were open come back in the new theme. The choice is saved and respected on the next start.+The user switches themes live from **Settings → Appearance → Desktop style**, which lists every+installed theme (since 0.8.5 there is no separate Themes page), with no restart: the LordOS app+windows that were open come back in the new theme. The choice is saved and respected on the next start.## Creating a new theme+The full guide, for a React developer new to LordOS, is [`docs/THEMES-GUIDE.md`](../docs/THEMES-GUIDE.md)+(anatomy, the token contract, frames, menus, layers, building, the verified-code check, testing and+a checklist); a small starting point is [`examples/theme-minimal/`](../examples/theme-minimal/).+Note that a theme LordOS did not sign only loads on a development build (see the guide). In short:+1. Copy `themes/classic` to `themes/mytheme` (`index.jsx` puts the pieces together; the frame,taskbar and panels are in `components/`, the colors and shape tokens in `tokens.js`).2. Edit `theme.json` (the name and description Settings shows).@@ -60,7 +65,7 @@ were open come back in the new theme. The choice is saved and respected on the nWhen such an app asks for the window menu (right click on its own bar), `win.windowMenu` is`{ x, y }`: draw the theme's window menu there and call `wm.closeWindowMenu(win.id)` when itcloses.-4. `npm run build` and pick it in Settings → Themes.+4. `npm run build` and pick it in Settings → Appearance → Desktop style.Images (`<Image src="assets/...">`) are resolved relative to the theme's folder.