@domicile-desktop/system-backlight 0.0.0-alpha-a330bf5f3aae

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connor Prussin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @domicile-desktop/system-backlight
+
+Screen brightness for a Domicile shell, on the system calls of
+[`@domicile-desktop/sdk/system`](/packages/chrome-sdk/src/system.ts). See
+[SHELL-SYSTEM-ACCESS.md](/docs/SHELL-SYSTEM-ACCESS.md).
+
+## Usage
+
+```ts
+import { system } from "@domicile-desktop/sdk/system";
+import { brightnessSetter } from "@domicile-desktop/system-backlight/set-brightness";
+import { watchBrightness } from "@domicile-desktop/system-backlight/watch-brightness";
+
+const host = system(domicile);
+const watch = await watchBrightness(host, (level) => show(level));
+const set = brightnessSetter(host);
+await set(0.5);
+```
+
+- `readBacklight` (`./read-backlight`): the preferred device under
+  `/sys/class/backlight`: firmware, then platform, then raw, in systemd's
+  order; ties by name. `None` without one.
+- `watchBrightness`: the level (0 to 1) now and on each change of a whole
+  percent. Re-reads on each `udevadm monitor` uevent and every two minutes.
+- `brightnessSetter`: sets a level through logind's
+  `org.freedesktop.login1.Session.SetBrightness`. Never sets zero, which turns
+  most panels off. Sends one level at a time; a level superseded while waiting
+  resolves `SetOutcome.Superseded`.
+- Every call resolves a `Result<…, SystemError>`. A level that is not a number
+  throws.
+
+## Requirements
+
+- `udevadm` on the compositor's `PATH` (systemd).
+- A logind session.
+- Watching and setting work while the desktop is locked, so a lock screen can
+  adjust the brightness ([LOCK.md](/docs/LOCK.md)).
+
+## Testing
+
+`bun run turbo test --filter @domicile-desktop/system-backlight`. Tests answer
+the system calls from files recorded on a ThinkPad (`src/fake-system.ts`).

package/dist/raw-for.d.ts

@@ -0,0 +1,8 @@
+import type { Backlight } from "./read-backlight";
+/**
+ * The raw value for `level`, clamped to 0..1 and rounded.
+ *
+ * Never zero: most panels turn off at zero, leaving no visible slider to raise
+ * it again. Throws on a level that is not finite, which is a caller's bug.
+ */
+export declare const rawFor: ({ max }: Backlight, level: number) => number;

package/dist/raw-for.js

@@ -0,0 +1,14 @@
+/**
+ * The raw value for `level`, clamped to 0..1 and rounded.
+ *
+ * Never zero: most panels turn off at zero, leaving no visible slider to raise
+ * it again. Throws on a level that is not finite, which is a caller's bug.
+ */
+export const rawFor = ({ max }, level) => {
+    if (Number.isFinite(level)) {
+        return Math.max(1, Math.round(Math.min(1, Math.max(0, level)) * max));
+    }
+    else {
+        throw new Error(`a brightness must be a number, not ${level}`);
+    }
+};

package/dist/read-backlight.d.ts

@@ -0,0 +1,21 @@
+import type { Option, Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+/** The calls {@link readBacklight} makes. */
+export type SysfsHost = Pick<System, "readDir" | "readTextFile">;
+/** One backlight device's current and maximum raw brightness. */
+export type Backlight = {
+    /** The name under `/sys/class/backlight`, which logind takes. */
+    device: string;
+    raw: number;
+    max: number;
+};
+/**
+ * The backlight to show and set, or `None` if there is none.
+ *
+ * Picks the preferred type, breaking ties by name so the choice is stable.
+ * Skips a device whose files are missing or not numbers, or whose maximum is
+ * zero.
+ */
+export declare const readBacklight: (host: SysfsHost) => Promise<Result<Option<Backlight>, SystemError>>;
+/** Brightness from 0 to 1. */
+export declare const levelOf: ({ max, raw }: Backlight) => number;

package/dist/read-backlight.js

@@ -0,0 +1,64 @@
+// Reads the screen's backlight from `/sys/class/backlight`.
+import { Err, None, Ok, Some } from "@cprussin/option-result";
+import { SystemErrorKind } from "@domicile-desktop/sdk/system";
+import { z } from "zod";
+/** Sysfs directory listing every backlight. */
+const BACKLIGHT = "/sys/class/backlight";
+/**
+ * Backlight types, preferred first, in systemd's order. A firmware interface
+ * knows the panel's curve; a raw one drives the same panel without it.
+ */
+const KINDS = ["firmware", "platform", "raw"];
+/** The files read from each device, in the order `readOne` takes them. */
+const FILES = ["type", "max_brightness", "brightness"];
+/**
+ * The backlight to show and set, or `None` if there is none.
+ *
+ * Picks the preferred type, breaking ties by name so the choice is stable.
+ * Skips a device whose files are missing or not numbers, or whose maximum is
+ * zero.
+ */
+export const readBacklight = async (host) => (await host.readDir(BACKLIGHT)).match({
+    Err: async (error) => error.kind === SystemErrorKind.NotFound ? Ok(None()) : Err(error),
+    Ok: async (entries) => collected(await Promise.all(entries
+        .map(({ name }) => name)
+        .toSorted()
+        .map((device) => readOne(host, device)))).map((devices) => firstSome(KINDS.map((kind) => firstSome(devices.map((device) => device.andThen((read) => read.kind === kind ? Some(read.backlight) : None())))))),
+});
+/** Brightness from 0 to 1. */
+export const levelOf = ({ max, raw }) => raw / max;
+const readOne = async (host, device) => collected(await Promise.all(FILES.map((file) => readFile(host, device, file)))).map(([kind, max, raw]) => {
+    const parsed = deviceSchema.safeParse({
+        kind: present(kind),
+        max: present(max),
+        raw: present(raw),
+    });
+    return parsed.success
+        ? Some({
+            backlight: {
+                device,
+                max: parsed.data.max,
+                raw: Math.min(parsed.data.raw, parsed.data.max),
+            },
+            kind: parsed.data.kind,
+        })
+        : None();
+});
+/** A file of `device`, trimmed, or `None` if it is missing. */
+const readFile = async (host, device, file) => (await host.readTextFile(`${BACKLIGHT}/${device}/${file}`)).match({
+    Err: (error) => error.kind === SystemErrorKind.NotFound ? Ok(None()) : Err(error),
+    Ok: (text) => Ok(Some(text.trim())),
+});
+const count = z
+    .string()
+    .regex(/^\d+$/)
+    .transform((digits) => Number.parseInt(digits, 10));
+const deviceSchema = z.object({
+    kind: z.enum(KINDS),
+    max: count.refine((max) => max > 0),
+    raw: count,
+});
+/** Every value, or the first error. */
+const collected = (results) => results.reduce((all, next) => all.andThen((values) => next.map((value) => [...values, value])), Ok([]));
+const present = (text) => text?.match({ None: () => undefined, Some: (value) => value });
+const firstSome = (options) => options.reduce((found, next) => found.or(next), None());

package/dist/set-brightness.d.ts

@@ -0,0 +1,26 @@
+import type { Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+import type { SysfsHost } from "./read-backlight";
+export declare enum SetOutcome {
+    /** logind set it. */
+    Set = 0,
+    /** A newer level was asked for before this one was sent. */
+    Superseded = 1,
+    NoBacklight = 2
+}
+/** The calls {@link brightnessSetter} makes. */
+export type SetterHost = SysfsHost & Pick<System, "dbusCall">;
+/** Sets the backlight to a level from 0 to 1, and says how it went. */
+export type SetBrightness = (level: number) => Promise<Result<SetOutcome, SystemError>>;
+/**
+ * A function that sets the preferred backlight to a level from 0 to 1.
+ *
+ * - Reads the device again for each level, since the raw scale is the
+ *   device's and it may have gone away.
+ * - Never sets zero; see `rawFor`.
+ * - Sends one level at a time. A dragged slider asks many times while logind
+ *   answers once, so only the newest level waiting is sent and the others
+ *   resolve {@link SetOutcome.Superseded}.
+ * - A level that is not a number rejects.
+ */
+export declare const brightnessSetter: (host: SetterHost) => SetBrightness;

package/dist/set-brightness.js

@@ -0,0 +1,76 @@
+// Sets the screen's backlight through logind.
+//
+// `/sys/class/backlight/*/brightness` is writable only by root. logind's
+// `Session.SetBrightness` lets the session's owner set it without a udev rule
+// or a setuid helper.
+import { Ok } from "@cprussin/option-result";
+import { Bus } from "@domicile-desktop/sdk/system";
+import { z } from "zod";
+import { rawFor } from "./raw-for";
+import { readBacklight } from "./read-backlight";
+export var SetOutcome;
+(function (SetOutcome) {
+    /** logind set it. */
+    SetOutcome[SetOutcome["Set"] = 0] = "Set";
+    /** A newer level was asked for before this one was sent. */
+    SetOutcome[SetOutcome["Superseded"] = 1] = "Superseded";
+    SetOutcome[SetOutcome["NoBacklight"] = 2] = "NoBacklight";
+})(SetOutcome || (SetOutcome = {}));
+/**
+ * A function that sets the preferred backlight to a level from 0 to 1.
+ *
+ * - Reads the device again for each level, since the raw scale is the
+ *   device's and it may have gone away.
+ * - Never sets zero; see `rawFor`.
+ * - Sends one level at a time. A dragged slider asks many times while logind
+ *   answers once, so only the newest level waiting is sent and the others
+ *   resolve {@link SetOutcome.Superseded}.
+ * - A level that is not a number rejects.
+ */
+export const brightnessSetter = (host) => {
+    const queue = { pending: undefined, sending: false };
+    return (level) => {
+        if (queue.sending) {
+            queue.pending?.settle(Ok(SetOutcome.Superseded));
+            return new Promise((settle, fail) => {
+                queue.pending = { fail, level, settle };
+            });
+        }
+        else {
+            queue.sending = true;
+            return sendFrom(host, queue, level);
+        }
+    };
+};
+/** Send `level`, then whatever waits behind it. */
+const sendFrom = async (host, queue, level) => {
+    try {
+        return await send(host, level);
+    }
+    finally {
+        const next = queue.pending;
+        queue.pending = undefined;
+        if (next === undefined) {
+            queue.sending = false;
+        }
+        else {
+            sendFrom(host, queue, next.level).then(next.settle, next.fail);
+        }
+    }
+};
+const send = async (host, level) => (await readBacklight(host)).andThenAsync(async (read) => read.match({
+    None: async () => Ok(SetOutcome.NoBacklight),
+    Some: async (backlight) => (await host.dbusCall({
+        body: ["backlight", backlight.device, rawFor(backlight, level)],
+        bus: Bus.System,
+        destination: "org.freedesktop.login1",
+        interface: "org.freedesktop.login1.Session",
+        member: "SetBrightness",
+        path: "/org/freedesktop/login1/session/auto",
+        signature: "ssu",
+    })).map(({ body }) => {
+        returnsNothing.parse(body);
+        return SetOutcome.Set;
+    }),
+}));
+const returnsNothing = z.tuple([]);

package/dist/watch-brightness.d.ts

@@ -0,0 +1,24 @@
+import type { Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+import type { SysfsHost } from "./read-backlight";
+/** The calls {@link watchBrightness} makes. */
+export type WatchHost = SysfsHost & Pick<System, "spawn">;
+export type BrightnessWatch = {
+    stop: () => void;
+    /** `Ok` after {@link BrightnessWatch.stop}, `Err` if the watch broke. */
+    ended: Promise<Result<"stopped", SystemError>>;
+};
+/**
+ * Calls `onLevel` with the backlight's level from 0 to 1, now and after each
+ * change.
+ *
+ * - Reports only a move of a whole percent, since the slider shows no finer.
+ * - Never called on a machine without a backlight. A backlight that goes away
+ *   and comes back is reported again.
+ * - Runs `udevadm` from the compositor's `PATH`. Works while the desktop is
+ *   locked.
+ */
+export declare const watchBrightness: (host: WatchHost, onLevel: (level: number) => void, every?: typeof everyInterval) => Promise<Result<BrightnessWatch, SystemError>>;
+/** Calls `tick` every `ms`, until the returned function is called. */
+declare const everyInterval: (ms: number, tick: () => void) => (() => void);
+export {};

package/dist/watch-brightness.js

@@ -0,0 +1,117 @@
+// Watches the screen's backlight.
+//
+// inotify sees no change to a file under `/sys`, so the watch runs
+// `udevadm monitor` and reads the backlight again on each kernel uevent.
+import { Err, Ok } from "@cprussin/option-result";
+import { SystemErrorKind } from "@domicile-desktop/sdk/system";
+import { levelOf, readBacklight } from "./read-backlight";
+/** Prints a line for each backlight uevent. */
+const UDEVADM = [
+    "udevadm",
+    "monitor",
+    "--kernel",
+    "--subsystem-match=backlight",
+];
+/** How often to read again without a uevent: firmware keys may send none. */
+const BACKSTOP_MS = 120_000;
+/**
+ * Calls `onLevel` with the backlight's level from 0 to 1, now and after each
+ * change.
+ *
+ * - Reports only a move of a whole percent, since the slider shows no finer.
+ * - Never called on a machine without a backlight. A backlight that goes away
+ *   and comes back is reported again.
+ * - Runs `udevadm` from the compositor's `PATH`. Works while the desktop is
+ *   locked.
+ */
+export const watchBrightness = async (host, onLevel, every = everyInterval) => (await host.spawn(UDEVADM)).map((udevadm) => {
+    const watch = {
+        failure: undefined,
+        reading: Promise.resolve(),
+        shown: undefined,
+        stopped: false,
+    };
+    const reread = () => {
+        watch.reading = watch.reading.then(() => readOnce(host, watch, udevadm, onLevel));
+    };
+    reread();
+    const stopClock = every(BACKSTOP_MS, reread);
+    return {
+        ended: ended(udevadm, watch, reread, stopClock),
+        stop: () => {
+            watch.stopped = true;
+            udevadm.kill();
+        },
+    };
+});
+/** Calls `tick` every `ms`, until the returned function is called. */
+const everyInterval = (ms, tick) => {
+    const id = setInterval(tick, ms);
+    return () => {
+        clearInterval(id);
+    };
+};
+const readOnce = async (host, watch, udevadm, onLevel) => {
+    const read = await readBacklight(host);
+    if (!watch.stopped && watch.failure === undefined) {
+        read.match({
+            Err: (error) => {
+                watch.failure = error;
+                udevadm.kill();
+            },
+            Ok: (backlight) => {
+                const level = backlight.map(levelOf);
+                const shown = level.match({
+                    None: () => undefined,
+                    Some: (now) => Math.round(now * 100),
+                });
+                if (shown !== watch.shown) {
+                    watch.shown = shown;
+                    level.match({ None: () => undefined, Some: onLevel });
+                }
+            },
+        });
+    }
+};
+/** Reads `udevadm`'s lines until it exits, then says why it did. */
+const ended = async (udevadm, watch, reread, stopClock) => {
+    await eachLine(udevadm.stdout, (line) => {
+        if (line.startsWith("KERNEL[")) {
+            reread();
+        }
+    });
+    const exit = await udevadm.exited;
+    stopClock();
+    await watch.reading;
+    if (watch.failure !== undefined) {
+        return Err(watch.failure);
+    }
+    else if (watch.stopped) {
+        return Ok("stopped");
+    }
+    else {
+        return exit.andThen((exited) => Err(unexpectedExit(exited)));
+    }
+};
+const eachLine = async (stream, onLine) => {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let unfinished = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        const lines = (unfinished + decoder.decode(value, { stream: true })).split("\n");
+        unfinished = lines.pop() ?? "";
+        for (const line of lines) {
+            onLine(line);
+        }
+    }
+};
+const unexpectedExit = ({ code, signal }) => ({
+    kind: SystemErrorKind.Other,
+    message: code === undefined
+        ? `udevadm monitor was killed by signal ${signal}`
+        : `udevadm monitor exited with code ${code}`,
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "dependencies": {
+    "@cprussin/option-result": "^2.0.1",
+    "@domicile-desktop/sdk": "0.0.0-alpha-a330bf5f3aae",
+    "zod": "^4.5.4"
+  },
+  "description": "Screen brightness for a Domicile shell: reads /sys/class/backlight, watches it and sets it through logind, on @domicile-desktop/sdk/system.",
+  "devDependencies": {
+    "@cprussin/tsconfig": "^5.0.0",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    "./read-backlight": {
+      "types": "./dist/read-backlight.d.ts",
+      "default": "./dist/read-backlight.js"
+    },
+    "./set-brightness": {
+      "types": "./dist/set-brightness.d.ts",
+      "default": "./dist/set-brightness.js"
+    },
+    "./watch-brightness": {
+      "types": "./dist/watch-brightness.d.ts",
+      "default": "./dist/watch-brightness.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "license": "MIT",
+  "name": "@domicile-desktop/system-backlight",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/system-backlight",
+    "type": "git",
+    "url": "git+https://github.com/cprussin/domicile.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test:types": "tsc --noEmit",
+    "test:unit": "bun test"
+  },
+  "type": "module",
+  "version": "0.0.0-alpha-a330bf5f3aae"
+}