@nexlibris/crosspoint-tools 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nolan Hawkins
+
+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

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @nexlibris/crosspoint-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Files for [CrossPoint](https://github.com/crosspoint-reader/crosspoint-reader) e-readers (the Xteink X4 and X3), built on [`@nexlibris/tools`](https://www.npmjs.com/package/@nexlibris/tools):
+
+- `formats` and `convert`: the X4 and X3 EPUB formats and their converter from EPUB (the optimizer, `xteink/`, a port of the CrossPoint Calibre plugin's), registered with the tools' format registry.
+- `sleepImage`: sleep images as screen-sized grayscale BMPs.
+- `stardict`: StarDict dictionaries unpacked and checked.
+- `fonts`: fonts sorted into families.
+- `libraryIndex`: the reader's `/.crosspoint/library.idx`.
+
+Modules are imported one by one, as with the tools:
+
+```ts
+import { registerFormats } from '@nexlibris/tools/formats/formats';
+import { registerConverters } from '@nexlibris/tools/formats/convert/converters';
+import { CROSSPOINT_FORMATS } from '@nexlibris/crosspoint-tools/formats';
+import { CROSSPOINT_CONVERTERS } from '@nexlibris/crosspoint-tools/convert';
+
+registerFormats(CROSSPOINT_FORMATS);
+registerConverters(CROSSPOINT_CONVERTERS);
+```
+
+Like the tools, they're written for a bundler such as Vite (assets are imported as `?url`). Under Node, the `nexlibris` command ([`@nexlibris/cli`](https://www.npmjs.com/package/@nexlibris/cli)) runs them.
+
+Part of [nexlibris](https://github.com/digitaltembo/nexlibris), under the MIT licence.

package/convert.d.ts

@@ -0,0 +1,6 @@
+import type { Converter } from '@nexlibris/tools/formats/convert/converters';
+import { type OptimizeOptions } from './xteink/options';
+/** The CrossPoint optimizer for a reader's screen, with its options recorded in its version. */
+export declare function xteinkConverter(profile: 'X4' | 'X3', options?: OptimizeOptions): Converter;
+/** Converting EPUBs to the X4's and X3's optimized EPUBs. */
+export declare const CROSSPOINT_CONVERTERS: Converter[];

package/convert.js

@@ -0,0 +1,22 @@
+import { DEFAULT_OPTIMIZE_OPTIONS, OPTIMIZE_FIELDS, optimizeOptionsFrom, optimizerVersion } from "./xteink/options.js";
+//#region crosspoint-tools/src/convert.ts
+/** The CrossPoint optimizer for a reader's screen, with its options recorded in its version. */
+function xteinkConverter(profile, options = DEFAULT_OPTIMIZE_OPTIONS) {
+	return {
+		id: profile === "X4" ? "xteink-x4" : "xteink-x3",
+		from: ["epub"],
+		to: profile === "X4" ? "x4.epub" : "x3.epub",
+		version: optimizerVersion(options),
+		fidelity: .9,
+		options: OPTIMIZE_FIELDS,
+		withOptions: (values) => xteinkConverter(profile, optimizeOptionsFrom(values)),
+		run: async (data) => {
+			const [{ optimizeEpub }, { PROFILES }] = await Promise.all([import("./xteink/optimize.js"), import("./xteink/image.js")]);
+			return optimizeEpub(data, PROFILES[profile], options);
+		}
+	};
+}
+/** Converting EPUBs to the X4's and X3's optimized EPUBs. */
+const CROSSPOINT_CONVERTERS = [xteinkConverter("X4"), xteinkConverter("X3")];
+//#endregion
+export { CROSSPOINT_CONVERTERS, xteinkConverter };

package/fonts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fonts for CrossPoint (crosspoint-reader's docs/sd-card-fonts.md). `.cpfont` files, made for the
+ * reader at fixed sizes (`Literata_12.cpfont`), go through its font API into a family; TTF, OTF and
+ * TTC files are copied into `/fonts/<family>/`, and only readers with external RAM use those.
+ */
+export declare const FONT_ROOT = "/fonts";
+export interface FontUpload {
+    family: string;
+    /** `.cpfont` through the font API; anything else copied into the family's folder. */
+    kind: 'cpfont' | 'direct';
+    name: string;
+    data: Blob;
+}
+/** A family name as the reader takes it: letters, digits, hyphens and underscores. */
+export declare const familyName: (text: string) => string;
+/**
+ * Sorts picked font files into families. A `.cpfont`'s family is its name without the size
+ * (`Literata_12`); a TTF/OTF/TTC's is its folder's, when picked in one, else its name without the
+ * style (`Bookerly-Bold`). Other files are reported.
+ */
+export declare function sortFonts(picked: {
+    path: string;
+    data: Blob;
+}[]): {
+    uploads: FontUpload[];
+    skipped: string[];
+};
+/** Whether a file starts as a `.cpfont` must (the reader checks the same). */
+export declare function isCpfont(data: Blob): Promise<boolean>;

package/fonts.js

@@ -0,0 +1,54 @@
+//#region crosspoint-tools/src/fonts.ts
+/**
+* Fonts for CrossPoint (crosspoint-reader's docs/sd-card-fonts.md). `.cpfont` files, made for the
+* reader at fixed sizes (`Literata_12.cpfont`), go through its font API into a family; TTF, OTF and
+* TTC files are copied into `/fonts/<family>/`, and only readers with external RAM use those.
+*/
+const FONT_ROOT = "/fonts";
+/** A family name as the reader takes it: letters, digits, hyphens and underscores. */
+const familyName = (text) => text.replace(/\s+/g, "_").replace(/[^\w-]+/g, "").slice(0, 48);
+const STYLES = /[-_ ]?(regular|bold|italic|bolditalic|bold[-_ ]?italic|book|medium|light|semibold|oblique)$/i;
+/**
+* Sorts picked font files into families. A `.cpfont`'s family is its name without the size
+* (`Literata_12`); a TTF/OTF/TTC's is its folder's, when picked in one, else its name without the
+* style (`Bookerly-Bold`). Other files are reported.
+*/
+function sortFonts(picked) {
+	const uploads = [];
+	const skipped = [];
+	for (const { path, data } of picked) {
+		const parts = path.split("/");
+		const name = parts.at(-1);
+		const folder = parts.length > 1 ? parts.at(-2) : void 0;
+		if (/\.cpfont$/i.test(name)) {
+			const family = familyName(name.replace(/\.cpfont$/i, "").replace(/_\d+$/, ""));
+			if (family) uploads.push({
+				family,
+				kind: "cpfont",
+				name: name.replace(/ /g, "_"),
+				data
+			});
+			else skipped.push(name);
+		} else if (/\.(ttf|otf|ttc)$/i.test(name)) {
+			const family = familyName(folder ?? name.replace(/\.[^.]+$/, "").replace(STYLES, ""));
+			if (family) uploads.push({
+				family,
+				kind: "direct",
+				name,
+				data
+			});
+			else skipped.push(name);
+		} else if (!name.startsWith(".")) skipped.push(name);
+	}
+	return {
+		uploads,
+		skipped
+	};
+}
+/** Whether a file starts as a `.cpfont` must (the reader checks the same). */
+async function isCpfont(data) {
+	const head = new Uint8Array(await data.slice(0, 8).arrayBuffer());
+	return new TextDecoder().decode(head) === "CPFONT\0\0";
+}
+//#endregion
+export { FONT_ROOT, familyName, isCpfont, sortFonts };

package/formats.d.ts

@@ -0,0 +1,22 @@
+declare module '@nexlibris/tools/formats/formats' {
+    interface PluginFormats {
+        'x4.epub': true;
+        'x3.epub': true;
+    }
+}
+/**
+ * The CrossPoint readers' optimized EPUBs, made by the optimizer (`convert.ts`). They're EPUBs to
+ * the rest of the tools, once registered (`registerFormats`): read, parsed, indexed and written as any EPUB is.
+ */
+export declare const CROSSPOINT_FORMATS: {
+    'x4.epub': {
+        label: string;
+        mediaType: string;
+        epub: true;
+    };
+    'x3.epub': {
+        label: string;
+        mediaType: string;
+        epub: true;
+    };
+};

package/formats.js

@@ -0,0 +1,19 @@
+//#region crosspoint-tools/src/formats.ts
+/**
+* The CrossPoint readers' optimized EPUBs, made by the optimizer (`convert.ts`). They're EPUBs to
+* the rest of the tools, once registered (`registerFormats`): read, parsed, indexed and written as any EPUB is.
+*/
+const CROSSPOINT_FORMATS = {
+	"x4.epub": {
+		label: "EPUB (X4)",
+		mediaType: "application/epub+zip",
+		epub: true
+	},
+	"x3.epub": {
+		label: "EPUB (X3)",
+		mediaType: "application/epub+zip",
+		epub: true
+	}
+};
+//#endregion
+export { CROSSPOINT_FORMATS };

package/libraryIndex.d.ts

@@ -0,0 +1,72 @@
+/**
+ * CrossPoint's library index, `/.crosspoint/library.idx` on the reader's SD card (format CLX1).
+ * The reader writes it describing every book on the card, with the metadata it read from each,
+ * so one download says what's on the card. A port of the Kaitai Struct definition in
+ * `crosspoint-reader/docs/files/library_idx.ksy` (the format is documented in its
+ * `docs/file-formats.md`); keep the two in step.
+ *
+ * Only format version 3 is read: the reader rebuilds an index of any other version when it opens
+ * it, so an older one is out of date anyway.
+ */
+export declare const LIBRARY_INDEX_PATH = "/.crosspoint/library.idx";
+export declare const LIBRARY_INDEX_VERSION = 3;
+export type MetadataStatus = 'not-attempted' | 'extracted' | 'failed';
+/** A book on the card, as the index records it. */
+export interface IndexedBook {
+    /** The file's full path on the card, e.g. `/Books/Dune - Frank Herbert.epub`. */
+    path: string;
+    folder: string;
+    name: string;
+    size: number;
+    /** The book's own title, or the file name without its extension when it gave none. */
+    title: string;
+    /** The display author: one spelling for the same person across the library; empty if none. */
+    author: string;
+    /** The author as this book spells it. */
+    sourceAuthor: string;
+    /** The primary author's sort form ("Herbert, Frank"), if the book gave one. */
+    authorSort: string;
+    series: string;
+    /** As written in the book, e.g. "3" or "1.5"; empty without a series. */
+    seriesIndex: string;
+    tags: string[];
+    metadata: MetadataStatus;
+    /** When the file landed on the card, as an ISO timestamp; undefined if the card didn't say. */
+    modified?: string;
+    /** The order the reader first saw books in, for those without a time. */
+    firstSeen: number;
+}
+export type ListKind = 'identity' | 'books' | 'groups' | 'mixed';
+export type ListRole = 'external' | 'recent' | 'title' | 'author' | 'series' | 'tags' | 'folders' | 'generated' | 'custom';
+/**
+ * One of the reader's lists (shelves). `books` are indexes into `LibraryIndex.books`; `lists`
+ * are indexes into `LibraryIndex.lists` of the lists it contains (for groups and mixed lists).
+ */
+export interface IndexList {
+    kind: ListKind;
+    role: ListRole;
+    /** Shown as a tab or in the list picker. */
+    topLevel: boolean;
+    /** Built-in lists (Recent, Title, Author) have none; the reader names them. */
+    label?: string;
+    icon: number;
+    books: number[];
+    lists: number[];
+}
+export interface LibraryIndex {
+    /** Whether the reader read each book's metadata, rather than going by file names. */
+    metadataEnabled: boolean;
+    foldVersion: number;
+    books: IndexedBook[];
+    lists: IndexList[];
+}
+export declare class LibraryIndexError extends Error {
+}
+/** Reads a library index. Throws `LibraryIndexError` for a file that isn't one, or is another version. */
+export declare function parseLibraryIndex(data: ArrayBuffer | Uint8Array): LibraryIndex;
+/** The books on the reader's Recent list, newest first. */
+export declare function recentBooks(index: LibraryIndex): IndexedBook[];
+/** FNV-1a 64 of a path's UTF-8 bytes, as the index keys books (`clixPathHash` in the firmware). */
+export declare function pathHash(path: string): bigint;
+/** A book's stored path hash, for checking a path rebuilt from the index (tests use it). */
+export declare function storedPathHash(data: ArrayBuffer | Uint8Array, book: number): bigint;

package/libraryIndex.js

@@ -0,0 +1,191 @@
+//#region crosspoint-tools/src/libraryIndex.ts
+/**
+* CrossPoint's library index, `/.crosspoint/library.idx` on the reader's SD card (format CLX1).
+* The reader writes it describing every book on the card, with the metadata it read from each,
+* so one download says what's on the card. A port of the Kaitai Struct definition in
+* `crosspoint-reader/docs/files/library_idx.ksy` (the format is documented in its
+* `docs/file-formats.md`); keep the two in step.
+*
+* Only format version 3 is read: the reader rebuilds an index of any other version when it opens
+* it, so an older one is out of date anyway.
+*/
+const LIBRARY_INDEX_PATH = "/.crosspoint/library.idx";
+const LIBRARY_INDEX_VERSION = 3;
+const KINDS = [
+	"identity",
+	"books",
+	"groups",
+	"mixed"
+];
+const ROLES = [
+	"external",
+	"recent",
+	"title",
+	"author",
+	"series",
+	"tags",
+	"folders",
+	"generated",
+	"custom"
+];
+const STATUSES = [
+	"not-attempted",
+	"extracted",
+	"failed"
+];
+const RECORD_SIZE = 128;
+const LIST_DESC_SIZE = 16;
+var LibraryIndexError = class extends Error {};
+/** Reads a library index. Throws `LibraryIndexError` for a file that isn't one, or is another version. */
+function parseLibraryIndex(data) {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const fail = (message) => {
+		throw new LibraryIndexError(`Not a readable library index: ${message}.`);
+	};
+	if (bytes.length < 64 || text(bytes, 0, 4) !== "CLX1") fail("it doesn’t start with CLX1");
+	const version = bytes[4];
+	if (version !== 3) fail(`it’s version ${version}, not 3`);
+	const foldVersion = bytes[5];
+	const u16 = (offset) => view.getUint16(offset, true);
+	const u32 = (offset) => view.getUint32(offset, true);
+	const header = {
+		bookCount: u16(8),
+		folderCount: u16(10),
+		folderStart: u32(16),
+		recordStart: u32(24),
+		listStart: u32(28),
+		nameStart: u32(32),
+		nameLen: u32(36),
+		listLen: u32(44),
+		listCount: u16(48)
+	};
+	const within = (start, length, what) => {
+		if (start + length > bytes.length) fail(`${what} runs past the end`);
+	};
+	within(header.recordStart, header.bookCount * RECORD_SIZE, "the records");
+	within(header.nameStart, header.nameLen, "the names");
+	within(header.listStart, header.listLen, "the lists");
+	const folders = [];
+	let at = header.folderStart;
+	for (let i = 0; i < header.folderCount; i++) {
+		within(at, 1, "the folders");
+		const length = bytes[at];
+		within(at + 1, length, "the folders");
+		folders.push(text(bytes, at + 1, length));
+		at += 1 + length;
+	}
+	const books = [];
+	for (let i = 0; i < header.bookCount; i++) {
+		const record = header.recordStart + i * RECORD_SIZE;
+		const nameOffset = u32(record);
+		const nameLength = bytes[record + 12];
+		const folder = folders[u16(record + 10)] ?? fail(`book ${i} is in a folder that isn’t listed`);
+		let blob = header.nameStart + nameOffset;
+		within(blob, 8 + nameLength, "a book’s names");
+		blob += 8;
+		const name = text(bytes, blob, nameLength);
+		blob += nameLength;
+		const end = header.nameStart + header.nameLen;
+		const field = () => {
+			if (blob >= end) return "";
+			const length = bytes[blob];
+			within(blob + 1, length, "a book’s names");
+			const value = text(bytes, blob + 1, length);
+			blob += 1 + length;
+			return value;
+		};
+		const author = field();
+		const title = field();
+		const sourceAuthor = field();
+		const authorSort = foldVersion >= 5 ? field() : "";
+		const [series, seriesIndex, tags] = foldVersion >= 6 ? [
+			field(),
+			field(),
+			field()
+		] : [
+			"",
+			"",
+			""
+		];
+		const modified = fatTime(u32(record + 124));
+		books.push({
+			path: folder === "/" ? `/${name}` : `${folder}/${name}`,
+			folder,
+			name,
+			size: u32(record + 4),
+			title: title || name.replace(/\.[^.]+$/, ""),
+			author,
+			sourceAuthor,
+			authorSort,
+			series,
+			seriesIndex,
+			tags: tags ? tags.split("\n") : [],
+			metadata: STATUSES[bytes[record + 15]] ?? "not-attempted",
+			...modified && { modified },
+			firstSeen: u16(record + 8)
+		});
+	}
+	const lists = [];
+	within(header.listStart, header.listCount * LIST_DESC_SIZE, "the list table");
+	for (let i = 0; i < header.listCount; i++) {
+		const desc = header.listStart + i * LIST_DESC_SIZE;
+		const kind = KINDS[bytes[desc]] ?? fail(`list ${i} is of an unknown kind`);
+		const labelLength = bytes[desc + 3];
+		const count = u16(desc + 4);
+		const entries = [];
+		if (kind !== "identity") {
+			const start = header.listStart + u32(desc + 8);
+			within(start, count * 2, `list ${i}`);
+			for (let n = 0; n < count; n++) entries.push(u16(start + n * 2));
+		}
+		const labelStart = header.listStart + u32(desc + 12);
+		if (labelLength) within(labelStart, labelLength, `list ${i}’s label`);
+		const books = kind === "identity" ? [...Array(header.bookCount).keys()] : kind === "groups" ? [] : entries.filter((e) => !(kind === "mixed" && e & 32768));
+		const contained = kind === "groups" ? entries : kind === "mixed" ? entries.filter((e) => e & 32768).map((e) => e & 32767) : [];
+		lists.push({
+			kind,
+			role: ROLES[bytes[desc + 1]] ?? "external",
+			topLevel: (bytes[desc + 2] & 1) === 1,
+			...labelLength && { label: text(bytes, labelStart, labelLength) },
+			icon: bytes[desc + 6],
+			books: books.filter((b) => b < header.bookCount),
+			lists: contained.filter((l) => l > i && l < header.listCount)
+		});
+	}
+	return {
+		metadataEnabled: (bytes[7] & 1) === 1,
+		foldVersion,
+		books,
+		lists
+	};
+}
+/** The books on the reader's Recent list, newest first. */
+function recentBooks(index) {
+	return ((index.lists.find((list) => list.role === "recent") ?? index.lists[0])?.books ?? []).map((n) => index.books[n]).reverse();
+}
+/** FNV-1a 64 of a path's UTF-8 bytes, as the index keys books (`clixPathHash` in the firmware). */
+function pathHash(path) {
+	let hash = 14695981039346656037n;
+	for (const byte of new TextEncoder().encode(path)) hash = (hash ^ BigInt(byte)) * 1099511628211n & 18446744073709551615n;
+	return hash;
+}
+/** A book's stored path hash, for checking a path rebuilt from the index (tests use it). */
+function storedPathHash(data, book) {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const record = view.getUint32(24, true) + book * RECORD_SIZE;
+	return view.getBigUint64(view.getUint32(32, true) + view.getUint32(record, true), true);
+}
+const decoder = new TextDecoder();
+const text = (bytes, start, length) => decoder.decode(bytes.subarray(start, start + length));
+/** A packed FAT date and time (date in the high 16 bits), as local time read as UTC; undefined for zero. */
+function fatTime(packed) {
+	if (!packed) return void 0;
+	const date = packed >>> 16;
+	const time = packed & 65535;
+	const iso = new Date(Date.UTC(1980 + (date >>> 9), (date >>> 5 & 15) - 1, date & 31, time >>> 11, time >>> 5 & 63, (time & 31) * 2));
+	return Number.isNaN(iso.getTime()) ? void 0 : iso.toISOString();
+}
+//#endregion
+export { LIBRARY_INDEX_PATH, LIBRARY_INDEX_VERSION, LibraryIndexError, parseLibraryIndex, pathHash, recentBooks, storedPathHash };

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@nexlibris/crosspoint-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Files for CrossPoint e-readers (Xteink X4 and X3): optimized EPUBs, sleep images, StarDict dictionaries, fonts and the reader's library index",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/digitaltembo/nexlibris.git",
+    "directory": "crosspoint-tools"
+  },
+  "homepage": "https://github.com/digitaltembo/nexlibris/tree/main/crosspoint-tools#readme",
+  "type": "module",
+  "exports": {
+    "./*": {
+      "types": "./*.d.ts",
+      "default": "./*.js"
+    }
+  },
+  "dependencies": {
+    "@nexlibris/tools": "0.1.1",
+    "jszip": "^3.10.2"
+  }
+}

package/sleepImage.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Sleep images for CrossPoint (crosspoint-reader's USER_GUIDE, "Sleep Screen"): uncompressed BMPs
+ * at the screen's size, in `/.sleep` (one picked at random each time it sleeps), or a single
+ * `/sleep.bmp`, which wins over the folder. Pictures are made into them here, in grayscale (the
+ * screen is) so what's shown here is what the reader shows.
+ */
+export type Profile = 'X4' | 'X3';
+/** Screen sizes, portrait, from the user guide. */
+export declare const SCREEN: Record<Profile, {
+    width: number;
+    height: number;
+}>;
+/** Where the reader looks, in order: the single image, then the folder, then its visible fallback. */
+export declare const SLEEP_FILE = "/sleep.bmp";
+export declare const SLEEP_FOLDER = "/.sleep";
+export declare const SLEEP_FALLBACK_FOLDER = "/sleep";
+/** The reader's `sleepScreen` setting: positions in its options (CrossPointSettings' SLEEP_SCREEN_MODE). */
+export declare const SLEEP_CUSTOM = 2;
+export declare const SLEEP_COVER_CUSTOM = 4;
+/** Fill: crop to cover the screen. Fit: the whole picture, on white. */
+export type Placement = 'fill' | 'fit';
+/** RGBA pixels as a 24-bit uncompressed BMP (bottom-up rows, each padded to 4 bytes). */
+export declare function encodeBmp(rgba: Uint8ClampedArray, width: number, height: number): Blob;
+/** Pixels in place as gray, by luminance; transparent ones as on white. */
+export declare function toGray(rgba: Uint8ClampedArray): void;
+/** Where a picture goes on the screen: its drawn rectangle. Exported for tests. */
+export declare function placement(image: {
+    width: number;
+    height: number;
+}, screen: {
+    width: number;
+    height: number;
+}, how: Placement): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** A picture (any format the browser reads) as a sleep image for the reader's screen. */
+export declare function makeSleepImage(picture: Blob, profile: Profile, how: Placement): Promise<Blob>;
+/** A name for a sleep image made from a file: its name as a .bmp, kept to what the reader's file names allow. */
+export declare function sleepImageName(name: string, taken: ReadonlySet<string>): string;

package/sleepImage.js

@@ -0,0 +1,102 @@
+//#region crosspoint-tools/src/sleepImage.ts
+/** Screen sizes, portrait, from the user guide. */
+const SCREEN = {
+	X4: {
+		width: 480,
+		height: 800
+	},
+	X3: {
+		width: 528,
+		height: 792
+	}
+};
+/** Where the reader looks, in order: the single image, then the folder, then its visible fallback. */
+const SLEEP_FILE = "/sleep.bmp";
+const SLEEP_FOLDER = "/.sleep";
+const SLEEP_FALLBACK_FOLDER = "/sleep";
+/** The reader's `sleepScreen` setting: positions in its options (CrossPointSettings' SLEEP_SCREEN_MODE). */
+const SLEEP_CUSTOM = 2;
+const SLEEP_COVER_CUSTOM = 4;
+/** RGBA pixels as a 24-bit uncompressed BMP (bottom-up rows, each padded to 4 bytes). */
+function encodeBmp(rgba, width, height) {
+	const rowSize = Math.ceil(width * 3 / 4) * 4;
+	const dataSize = rowSize * height;
+	const buffer = new ArrayBuffer(54 + dataSize);
+	const view = new DataView(buffer);
+	view.setUint8(0, 66);
+	view.setUint8(1, 77);
+	view.setUint32(2, buffer.byteLength, true);
+	view.setUint32(10, 54, true);
+	view.setUint32(14, 40, true);
+	view.setInt32(18, width, true);
+	view.setInt32(22, height, true);
+	view.setUint16(26, 1, true);
+	view.setUint16(28, 24, true);
+	view.setUint32(34, dataSize, true);
+	view.setInt32(38, 2835, true);
+	view.setInt32(42, 2835, true);
+	const bytes = new Uint8Array(buffer);
+	for (let y = 0; y < height; y++) {
+		const row = 54 + (height - 1 - y) * rowSize;
+		for (let x = 0; x < width; x++) {
+			const from = (y * width + x) * 4;
+			const to = row + x * 3;
+			bytes[to] = rgba[from + 2];
+			bytes[to + 1] = rgba[from + 1];
+			bytes[to + 2] = rgba[from];
+		}
+	}
+	return new Blob([buffer], { type: "image/bmp" });
+}
+/** Pixels in place as gray, by luminance; transparent ones as on white. */
+function toGray(rgba) {
+	for (let i = 0; i + 3 < rgba.length; i += 4) {
+		const alpha = rgba[i + 3] / 255;
+		const gray = .2126 * rgba[i] + .7152 * rgba[i + 1] + .0722 * rgba[i + 2];
+		rgba[i] = rgba[i + 1] = rgba[i + 2] = Math.round(gray * alpha + 255 * (1 - alpha));
+		rgba[i + 3] = 255;
+	}
+}
+/** Where a picture goes on the screen: its drawn rectangle. Exported for tests. */
+function placement(image, screen, how) {
+	const scale = (how === "fill" ? Math.max : Math.min)(screen.width / image.width, screen.height / image.height);
+	const width = Math.round(image.width * scale);
+	const height = Math.round(image.height * scale);
+	return {
+		x: Math.round((screen.width - width) / 2),
+		y: Math.round((screen.height - height) / 2),
+		width,
+		height
+	};
+}
+/** A picture (any format the browser reads) as a sleep image for the reader's screen. */
+async function makeSleepImage(picture, profile, how) {
+	const screen = SCREEN[profile];
+	const bitmap = await createImageBitmap(picture).catch(() => {
+		throw new Error("This isn’t a picture nexlibris can read.");
+	});
+	try {
+		const canvas = document.createElement("canvas");
+		canvas.width = screen.width;
+		canvas.height = screen.height;
+		const context = canvas.getContext("2d");
+		context.fillStyle = "#fff";
+		context.fillRect(0, 0, screen.width, screen.height);
+		const at = placement(bitmap, screen, how);
+		context.drawImage(bitmap, at.x, at.y, at.width, at.height);
+		const pixels = context.getImageData(0, 0, screen.width, screen.height).data;
+		toGray(pixels);
+		return encodeBmp(pixels, screen.width, screen.height);
+	} finally {
+		bitmap.close();
+	}
+}
+/** A name for a sleep image made from a file: its name as a .bmp, kept to what the reader's file names allow. */
+function sleepImageName(name, taken) {
+	const stem = name.replace(/\.[^.]+$/, "").replace(/[^\w\- ]+/g, "").trim().slice(0, 60) || "sleep";
+	let candidate = `${stem}.bmp`;
+	for (let n = 2; taken.has(candidate.toLowerCase()); n++) candidate = `${stem} ${n}.bmp`;
+	return candidate;
+}
+//#endregion
+export { SCREEN, SLEEP_COVER_CUSTOM, SLEEP_CUSTOM, SLEEP_FALLBACK_FOLDER, SLEEP_FILE, SLEEP_FOLDER, encodeBmp, makeSleepImage, placement, sleepImageName, toGray };