@decky.fx/raven-tsx 0.0.0-stage → 0.1.1

package/src/core/frame.ts

@@ -0,0 +1,76 @@
+/**
+ * The one slot Raven has for a function called at each frame, shared. `onFrame` and
+ * `Rset_frame_callback` of the application both end up in one native callback, which goes away
+ * when nothing needs it. Without this, each would take the place of the others, and the binding
+ * would keep every function it was given alive for ever.
+ */
+
+import "./native";
+import { CFunction, JSCallback, ptr, type Pointer } from "bun:ffi";
+import { Rset_frame_callback as connectNative, type RFrameCallback, type RPointer } from "../vendor/raven";
+
+/** What is called at each frame, with the seconds since the last one. */
+export type FrameHandler = (deltaSeconds: number) => void;
+
+class FrameSlot {
+	private readonly subscribers = new Set<FrameHandler>();
+	private application: FrameHandler | null = null;
+	private callback: JSCallback | null = null;
+	private connected = false;
+
+	/** Connects the native callback when something needs it, and takes it away when nothing does. */
+	private sync(): void {
+		const wanted = this.application !== null || this.subscribers.size > 0;
+		if (wanted !== this.connected) {
+			this.callback ??= new JSCallback((delta: number): void => this.dispatch(delta), { args: ["f64", "ptr"], returns: "void" });
+			connectNative(wanted ? this.callback.ptr : null);
+			this.connected = wanted;
+		}
+	}
+
+	/** An exception must not cross the frames of C, nor keep the others from being called. */
+	private dispatch(delta: number): void {
+		for (const handler of [...(this.application ? [this.application] : []), ...this.subscribers]) {
+			try {
+				handler(delta);
+			} catch (error) {
+				console.error("raven-tsx: exception in a frame callback:", error);
+			}
+		}
+	}
+
+	/** What `Rset_frame_callback` does: one function, replaced by the next, beside the subscribers. */
+	setApplication(callback: RFrameCallback | Pointer | null, userData: RPointer): void {
+		if (typeof callback === "number") {
+			// a function of C: called from here, as it no longer has the slot to itself
+			const native = CFunction({ ptr: callback, args: ["f64", "ptr"], returns: "void" });
+			this.application = (delta) => void native(delta, userData);
+		} else if (callback) {
+			// an address, as C would give it. An array stays alive for as long as this function does.
+			this.application = (delta) => void callback(delta, userData === null || typeof userData === "number" ? userData : ptr(userData));
+		} else {
+			this.application = null;
+		}
+		this.sync();
+	}
+
+	/** Adds a function, and returns what takes it away. */
+	subscribe(handler: FrameHandler): () => void {
+		this.subscribers.add(handler);
+		this.sync();
+		return () => {
+			this.subscribers.delete(handler);
+			this.sync();
+		};
+	}
+}
+
+export const frameSlot = new FrameSlot();
+
+/**
+ * Registers a function called once per frame, before the layout, beside what `onFrame` added.
+ * Takes the place of the one of the C API, under the same name.
+ */
+export function Rset_frame_callback(callback: RFrameCallback | Pointer | null, user_data: RPointer = null): void {
+	frameSlot.setApplication(callback, user_data);
+}

package/src/core/index.ts

@@ -0,0 +1,28 @@
+/**
+ * raven-tsx: Raven's widgets from TSX. This is the core, which knows only Raven and is what the
+ * adapters are made on: an application writes its components with one (`@decky.fx/raven-tsx/react`,
+ * which also exports everything here), and imports this for code that is not a component:
+ *
+ *     import { defineTheme, loadTheme, raven } from "@decky.fx/raven-tsx";
+ *
+ * What an adapter needs beyond this (`finishPlacing`, `registerTagWith`, `WidgetInstance`...) is in
+ * the modules of this folder: it is for this package, not for applications.
+ */
+
+export type * from "./props.generated";
+export { RavenError } from "./errors";
+export { inEventScope, type MeasuredSize, type Painter, type PlotView } from "./events";
+export type { FrameHandler } from "./frame";
+export type { AttributeGroup, AttributeValue, EventHandler, PlotDragLine, PlotNumbers, PlotSeries, TreeItem } from "./props";
+export { onAction, onFrame, onShortcut, parseKeys } from "./subscriptions";
+export type { AttributeKind } from "./tags";
+export type { WidgetInstance } from "./widget-instance";
+export type { WindowInstance } from "./window-instance";
+/** All of Raven's C API, for what props do not cover: painting, for one. */
+export * as raven from "./raven";
+export { registerWebView, webFunctions, type WebViewProps } from "./web";
+export {
+	defineTheme, loadTheme, themeXml,
+	type GlassProperty, type LookName, type PartProperties, type PartShape, type SyntaxToken, type ThemeColor, type ThemeColors,
+	type ThemeMetrics, type ThemePart, type ThemeSpec, type ThemeState, type ThemeStyle,
+} from "./theme";

package/src/core/library-check.ts

@@ -0,0 +1,89 @@
+/**
+ * What a native library is, and whether it fits the binding. Raven cannot say by itself:
+ * `Rget_version` is the version in its CMakeLists, the same for every commit between two
+ * releases, and no commit is compiled in. So `raven.json` goes beside a library when it is
+ * packaged, and the functions the binding opens can be looked for in the file.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/** The file beside a packaged library that says what it is. */
+export const STAMP_FILE = "raven.json";
+
+/** What `raven.json` holds. */
+export interface LibraryStamp {
+	/** The commit of Raven it was built from, or an empty text when that is not known. */
+	readonly commit: string;
+	/** What `RAVEN_VERSION` said when it was packaged. */
+	readonly pin: string;
+	/** What `Rget_version` says. */
+	readonly version: string;
+	/** The SHA-256 of the library, to see that it is still that one. */
+	readonly sha256: string;
+	/** False when it was packaged with `--allow-mismatch`. */
+	readonly verified: boolean;
+}
+
+/** The stamp in a folder, if it has one that can be read. */
+export function readStamp(directory: string): LibraryStamp | null {
+	try {
+		return JSON.parse(readFileSync(`${directory}/${STAMP_FILE}`, "utf8")) as LibraryStamp;
+	} catch {
+		return null;
+	}
+}
+
+/** The names of the C functions a binding opens. */
+export function functionsOfBinding(binding: string): string[] {
+	return Array.from(binding.matchAll(/^\tR[a-z][a-z0-9_]*(?=: \{ args: )/gm), (match) => match[0].slice(1));
+}
+
+/**
+ * The functions a library does not have, from the bytes of the file: its table of exports
+ * holds them by name on Linux, macOS and Windows. A name in the file can be something else,
+ * so an empty answer proves nothing and the system still has the last word, but a name that is
+ * nowhere in the file is really missing. With most of them missing this is no such file.
+ */
+export function missingFunctions(functions: readonly string[], library: Buffer): string[] {
+	const found = new Set(library.toString("latin1").match(/R[a-z][a-z0-9_]*/g));
+	const missing = functions.filter((name) => !found.has(name));
+	return missing.length > functions.length / 2 ? [] : missing;
+}
+
+/** A commit as it is shown. */
+export function shortCommit(commit: string): string {
+	return /^[0-9a-f]{40}$/.test(commit) ? commit.slice(0, 7) : commit;
+}
+
+/**
+ * Says what is wrong with a library before the binding opens it, as all the system would say is
+ * that one symbol was not found. Nothing happens in an executable, which holds what it was
+ * built with, or when the stamp says the library was packaged for this pin and checked:
+ * `--allow-mismatch` writes the pin too, without having checked anything.
+ */
+export function checkLibrary(library: string): void {
+	const binding = `${import.meta.dir}/../vendor/raven.ts`;
+	if (!existsSync(binding) || !existsSync(library)) {
+		return;
+	}
+	const pinFile = resolve(import.meta.dir, "../../RAVEN_VERSION");
+	const pin = existsSync(pinFile) ? readFileSync(pinFile, "utf8").trim() : "";
+	const stamp = readStamp(dirname(library));
+	if (stamp?.verified && stamp.pin === pin) {
+		return;
+	}
+	const built = stamp?.commit ? `built from Raven ${shortCommit(stamp.commit)}` : "built from a commit it cannot say";
+	const missing = missingFunctions(functionsOfBinding(readFileSync(binding, "utf8")), readFileSync(library));
+	if (missing.length > 0) {
+		const named = `${missing.slice(0, 3).join(", ")}${missing.length > 3 ? ` and ${missing.length - 3} more` : ""}`;
+		throw new Error(
+			`raven-tsx: the library ${library} is older than the binding: it has no ${named}.\n` +
+				`The binding is pinned to Raven ${shortCommit(pin)}, and the library was ${built}.\n` +
+				`In packages/raven-tsx, bun run raven:status says what differs, and bun run native:local packages a library of the pin.`,
+		);
+	}
+	if (stamp) {
+		console.warn(`raven-tsx: the library was ${built}, and RAVEN_VERSION says ${shortCommit(pin)}: bun run raven:status says what differs`);
+	}
+}

package/src/core/native.ts

@@ -0,0 +1,82 @@
+/**
+ * Finds Raven's native library and says where it is, before the binding opens it.
+ *
+ * It comes in a package per platform, listed in `optionalDependencies`: the package manager
+ * installs the one that fits, without an install script (Bun does not run those by default).
+ * `RAVEN_LIBRARY` set by hand has priority, to try another build.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { checkLibrary } from "./library-check";
+
+/** What a package of a platform exports: the path of its library. */
+interface PlatformPackage {
+	readonly default: string;
+}
+
+/**
+ * The library of this platform, or nothing when its package is not installed.
+ *
+ * These `require` calls are literal, and inside `try`, on purpose: `bun build --compile` embeds
+ * what it can resolve, and takes an unresolved `require` in a `try` as optional. An `import()`
+ * of a package of another platform would stop the build.
+ */
+function findPackagedLibrary(): string | undefined {
+	let found: PlatformPackage | undefined;
+	try {
+		switch (`${process.platform}-${process.arch}`) {
+			case "linux-x64":
+				found = require("@decky.fx/raven-tsx-linux-x64");
+				break;
+			case "linux-arm64":
+				found = require("@decky.fx/raven-tsx-linux-arm64");
+				break;
+			case "darwin-arm64":
+				found = require("@decky.fx/raven-tsx-darwin-arm64");
+				break;
+			case "darwin-x64":
+				found = require("@decky.fx/raven-tsx-darwin-x64");
+				break;
+			case "win32-x64":
+				found = require("@decky.fx/raven-tsx-win32-x64");
+				break;
+		}
+	} catch {
+		// not installed: said below, with what to do about it
+	}
+	return found?.default;
+}
+
+/**
+ * A path the system can load. In a Windows executable the library is inside the file, at
+ * `B:/~BUN/...`, which `dlopen` cannot open: it is written to the temporary folder first,
+ * under a name made from its content. Bun does this by itself on Linux.
+ *
+ * Synchronous on purpose: a top-level `await` here would not hold back the binding, which
+ * is imported beside this module and does not depend on it.
+ */
+function loadablePath(path: string): string {
+	if (!path.startsWith("B:/~BUN/")) {
+		return path;
+	}
+	const bytes = readFileSync(path);
+	const extracted = `${tmpdir()}\\raven-tsx-${Bun.hash(bytes).toString(16)}.dll`;
+	if (Bun.file(extracted).size !== bytes.length) {
+		writeFileSync(extracted, bytes);
+	}
+	return extracted;
+}
+
+if (!process.env["RAVEN_LIBRARY"]) {
+	const packaged = findPackagedLibrary();
+	if (!packaged) {
+		throw new Error(
+			`raven-tsx: no native library for ${process.platform}-${process.arch}. ` +
+				`Install @decky.fx/raven-tsx-${process.platform}-${process.arch}, or set RAVEN_LIBRARY to the path of a library you built.`,
+		);
+	}
+	process.env["RAVEN_LIBRARY"] = loadablePath(packaged);
+}
+
+checkLibrary(process.env["RAVEN_LIBRARY"] ?? "");

package/src/core/plot.ts

@@ -0,0 +1,179 @@
+/**
+ * The curves and drag lines of a `Plot`, given as props. XML would have them as elements inside the
+ * widget, with their numbers as text: here they go to Raven by calling it, so that a million points
+ * stay one typed array, and a new render only sends what changed.
+ */
+
+import { RavenError } from "./errors";
+import type { DataValue, PlotDragLine, PlotNumbers, PlotSeries } from "./props";
+import * as r from "./raven";
+
+/** The data props of a widget, by name. */
+type PlotData = ReadonlyMap<string, DataValue>;
+
+const LINES: Readonly<Record<NonNullable<PlotSeries["Line"]>, r.RPlotLine>> = {
+	Solid: r.R_PLOT_LINE_SOLID,
+	Dashed: r.R_PLOT_LINE_DASHED,
+	Dotted: r.R_PLOT_LINE_DOTTED,
+	DashDot: r.R_PLOT_LINE_DASH_DOT,
+	None: r.R_PLOT_LINE_NONE,
+};
+
+const MARKERS: Readonly<Record<NonNullable<PlotSeries["Marker"]>, r.RPlotMarker>> = {
+	None: r.R_PLOT_MARKER_NONE,
+	Circle: r.R_PLOT_MARKER_CIRCLE,
+	Square: r.R_PLOT_MARKER_SQUARE,
+	Diamond: r.R_PLOT_MARKER_DIAMOND,
+	TriangleUp: r.R_PLOT_MARKER_TRIANGLE_UP,
+	TriangleDown: r.R_PLOT_MARKER_TRIANGLE_DOWN,
+	Cross: r.R_PLOT_MARKER_CROSS,
+	Plus: r.R_PLOT_MARKER_PLUS,
+	Asterisk: r.R_PLOT_MARKER_ASTERISK,
+};
+
+const AXES: Readonly<Record<NonNullable<PlotDragLine["Axis"]>, r.RPlotAxis>> = { X: r.R_PLOT_X, Y: r.R_PLOT_Y, X2: r.R_PLOT_X2, Y2: r.R_PLOT_Y2 };
+
+const NEW_SERIES: PlotSeries = {};
+const COLOR = /^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+const seriesOf = (data: PlotData): readonly PlotSeries[] => (data.get("Series") ?? []) as readonly PlotSeries[];
+const linesOf = (data: PlotData): readonly PlotDragLine[] => (data.get("DragLines") ?? []) as readonly PlotDragLine[];
+
+/** A color as the four numbers Raven takes for a series or a line. */
+function colorOf(color: string): [red: number, green: number, blue: number, alpha: number] {
+	const channel = (from: number): number => parseInt(color.slice(from, from + 2), 16) / 255;
+	return [channel(1), channel(3), channel(5), color.length > 7 ? channel(7) : 1];
+}
+
+/** Whether two lists of numbers hold the same values. NaN, a gap in a curve, is the same as NaN. */
+function sameNumbers(a: PlotNumbers | undefined, b: PlotNumbers | undefined): boolean {
+	if (a === b) {
+		return true;
+	}
+	if (!a || !b || a.length !== b.length) {
+		return false;
+	}
+	for (let index = 0; index < a.length; index++) {
+		if (!Object.is(a[index], b[index])) {
+			return false;
+		}
+	}
+	return true;
+}
+
+/** Whether something an entry had is gone from it: Raven has no way to give it its default back. */
+function lostSomething<T extends object>(before: T, after: T): boolean {
+	return Object.entries(before).some(([name, value]) => value !== undefined && after[name as keyof T] === undefined);
+}
+
+/** How many entries, from the first, can be changed in place. The others are made again. */
+function keptCount<T>(before: readonly T[], after: readonly T[], remake: (before: T, after: T) => boolean): number {
+	const shared = Math.min(before.length, after.length);
+	const first = before.slice(0, shared).findIndex((entry, index) => remake(entry, after[index] as T));
+	return first < 0 ? shared : first;
+}
+
+/** Gives a series what changed in its props. */
+function setSeries(plot: r.Rid, index: number, before: PlotSeries, after: PlotSeries): void {
+	if (before.Name !== after.Name) {
+		r.Rplot_set_series_name(plot, index, after.Name ?? null);
+	}
+	if (after.Color !== undefined && before.Color !== after.Color) {
+		r.Rplot_set_series_color(plot, index, ...colorOf(after.Color));
+	}
+	// (a width of 0 and a size of 0 keep what the series has)
+	if (before.Line !== after.Line || before.LineWidth !== after.LineWidth) {
+		r.Rplot_set_series_line(plot, index, LINES[after.Line ?? "Solid"], after.LineWidth ?? 0);
+	}
+	if (before.Marker !== after.Marker || before.MarkerSize !== after.MarkerSize) {
+		r.Rplot_set_series_marker(plot, index, MARKERS[after.Marker ?? "None"], after.MarkerSize ?? 0);
+	}
+	if (after.MarkerFilled !== undefined && before.MarkerFilled !== after.MarkerFilled) {
+		r.Rplot_set_series_marker_filled(plot, index, Number(after.MarkerFilled));
+	}
+	if (after.Step !== undefined && before.Step !== after.Step) {
+		r.Rplot_set_series_step(plot, index, Number(after.Step));
+	}
+	if (after.Fill !== undefined && before.Fill !== after.Fill) {
+		r.Rplot_set_series_fill(plot, index, after.Fill);
+	}
+	if (before.XAxis !== after.XAxis || before.YAxis !== after.YAxis) {
+		r.Rplot_set_series_axes(plot, index, AXES[after.XAxis ?? "X"], AXES[after.YAxis ?? "Y"]);
+	}
+	if (after.Visible !== undefined && before.Visible !== after.Visible) {
+		r.Rplot_set_series_visible(plot, index, Number(after.Visible));
+	}
+	// (before the points, as in XML, so that they are cut to it once)
+	if (after.MaxPoints !== undefined && before.MaxPoints !== after.MaxPoints) {
+		r.Rplot_set_series_max_points(plot, index, after.MaxPoints);
+	}
+	if (!sameNumbers(before.X, after.X) || !sameNumbers(before.Y, after.Y)) {
+		r.Rplot_set_series_data(plot, index, after.X ?? null, after.Y ?? null, after.Y?.length ?? 0);
+	}
+}
+
+/** Goes from one list of series to another, by their place in it. */
+function applySeries(plot: r.Rid, before: readonly PlotSeries[], after: readonly PlotSeries[]): void {
+	const kept = keptCount(before, after, lostSomething);
+	for (let index = before.length - 1; index >= kept; index--) {
+		r.Rplot_remove_series(plot, index);
+	}
+	after.forEach((series, index) => {
+		if (index >= kept) {
+			r.Rplot_add_series(plot, null);
+		}
+		setSeries(plot, index, (index < kept ? before[index] : undefined) ?? NEW_SERIES, series);
+	});
+}
+
+/** Goes from one list of drag lines to another. Raven cannot change the axis or the label of a line. */
+function applyDragLines(plot: r.Rid, before: readonly PlotDragLine[], after: readonly PlotDragLine[]): void {
+	const kept = keptCount(before, after, (old, now) => lostSomething(old, now) || old.Axis !== now.Axis || old.Label !== now.Label);
+	for (let index = before.length - 1; index >= kept; index--) {
+		r.Rplot_remove_drag_line(plot, index);
+	}
+	after.forEach((line, index) => {
+		const old = index < kept ? before[index] : undefined;
+		if (!old) {
+			r.Rplot_add_drag_line(plot, AXES[line.Axis ?? "X"], line.Value, line.Label ?? null);
+		} else if (old.Value !== line.Value) {
+			r.Rplot_set_drag_line_value(plot, index, line.Value);
+		}
+		if (line.Color !== undefined && line.Color !== old?.Color) {
+			r.Rplot_set_drag_line_color(plot, index, ...colorOf(line.Color));
+		}
+	});
+}
+
+/** Throws when the data of a `Plot` cannot be shown. Called before anything changes. */
+export function checkPlotData(data: PlotData): void {
+	for (const { Name, X, Y, Color } of seriesOf(data)) {
+		if (X && X.length !== (Y?.length ?? 0)) {
+			RavenError.throw(`raven-tsx: the series ${Name ?? "without a name"} of a Plot has ${X.length} X for ${Y?.length ?? 0} Y`);
+		}
+		if (Color !== undefined && !COLOR.test(Color)) {
+			RavenError.throw(`raven-tsx: the color of a series of a Plot should be #RRGGBB or #RRGGBBAA, and is ${Color}`);
+		}
+	}
+	for (const { Color } of linesOf(data)) {
+		if (Color !== undefined && !COLOR.test(Color)) {
+			RavenError.throw(`raven-tsx: the color of a drag line of a Plot should be #RRGGBB or #RRGGBBAA, and is ${Color}`);
+		}
+	}
+}
+
+/** Gives a `Plot` what changed in its data. */
+export function applyPlotData(plot: r.Rid, previous: PlotData, next: PlotData): void {
+	applySeries(plot, seriesOf(previous), seriesOf(next));
+	applyDragLines(plot, linesOf(previous), linesOf(next));
+}
+
+/** Puts the drag lines back where the props say, after a handler that refused the move. */
+export function restorePlotData(plot: r.Rid, data: PlotData): void {
+	const held = r.Rplot_get_drag_line_count(plot);
+	linesOf(data).slice(0, held).forEach(({ Value }, index) => {
+		if (r.Rplot_get_drag_line_value(plot, index) !== Value) {
+			r.Rplot_set_drag_line_value(plot, index, Value);
+		}
+	});
+}