@khalido/home 0.2.0 → 0.2.2

package/src/connectors/enphase/client.ts

@@ -8,7 +8,7 @@ import {
   type Measurement,
 } from "./schemas.ts";
 
-/** A failed Enphase call. `status` 401 means the token is wrong or expired. */
+/** A failed Enphase call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or expired. */
 export class EnphaseError extends ConnectorError {}
 
 /** Solar right now and today. Watts and watt-hours as the gateway reports them, negatives included. */

package/src/connectors/enphase/index.ts

@@ -1,4 +1,5 @@
 import { type Clock, localDay, realClock } from "../../clock.ts";
+import { isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import {
   type DeviceRecord,
@@ -180,7 +181,7 @@ export function enphase(
           });
         } catch (error) {
           if (signal.aborted) return; // stopped mid-read: not a failure
-          if (error instanceof EnphaseError && error.status === 401)
+          if (isRejectedKey(error))
             return update({
               status: "unavailable",
               reason: "auth",

package/src/connectors/hue/events.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type Clock, realClock } from "../../clock.ts";
+import { isRejectedKey } from "../../connector.ts";
 import { HueError, type HueOptions } from "./client.ts";
 import { HueEvent } from "./schemas.ts";
 
@@ -56,10 +57,6 @@ const safeJson = (text: string): unknown => {
   }
 };
 
-/** A 401 or 403: the key is wrong or revoked. */
-export const isRejectedKey = (error: unknown) =>
-  error instanceof HueError && (error.status === 401 || error.status === 403);
-
 /** What the stream yields: a (re)connection, a batch of events, or a drop with the wait before the next try. */
 export type StreamItem =
   | { kind: "connected" }

package/src/connectors/hue/index.ts

@@ -1,5 +1,5 @@
 import { asOf, type Clock, realClock } from "../../clock.ts";
-import { errorText } from "../../connector.ts";
+import { errorText, isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import {
@@ -13,7 +13,7 @@ import {
 } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { bunPinnedFetch, type HueClient, hueClient } from "./client.ts";
-import { hueEvents, isRejectedKey } from "./events.ts";
+import { hueEvents } from "./events.ts";
 import type { HueEvent } from "./schemas.ts";
 import {
   type GroupView,

package/src/connectors/printers/README.md

@@ -1,8 +1,8 @@
 # Printers
 
-AirPrint printers, found by mDNS and read over IPP on the local network. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Built read-only; first read of a live printer 2026-11-10 (see Live findings).
+AirPrint printers, found by mDNS and read over IPP on the local network, and a PDF printed on one. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Reads live since 2026-11-10; a print live on 2026-11-12 (see Live findings).
 
-Try it: `home printers`
+Try it: `home printers`, `home printers print page.pdf --dry-run`
 
 ## Built
 
@@ -12,7 +12,10 @@ Try it: `home printers`
 - **Odd values pass through.** A `printer-state` outside 3 to 5 leaves `state` out, keeps `stateCode`, and is named in `anomaly`. A marker level outside 0 to 100 stays as sent and is named (PWG 5100.13 reserves negative levels for "unknown" kinds; read it before treating one as empty). Marker lists of different lengths are named too.
 - **Identity check.** The printer's `printer-uuid` must match the entry's UUID, or the read fails with "the address answers as another printer", so a recycled address never shows one printer's toner under another's name.
 - **Discovery** is one shared scan, as Cast's is, not a relocator per printer (the relocator is one device and one scan each; three printers down would be three `dns-sd` runs). It runs at start, after a failed read at 1, 5 and 15 minutes then hourly (`rescanDelay`), hourly for new printers, and a `refresh()` resets the backoff. A moved printer is found by its UUID and read again at once; `detail` says "not found by discovery" only after a scan looked and missed it (`lostDetail`).
-- `home discover` lists printers and `--write` adds them (`uuid`, `name`, `host`, `port`); `home probe` reads each once. No writes. The place for them is marked `TODO(writes…)` in `client.ts`.
+- `home discover` lists printers and `--write` adds them (`uuid`, `name`, `host`, `port`); `home probe` reads each once.
+- **Writes** (`client.ts`, exported): `identifyPrinter` (the printer shows or sounds; no paper), `validateJob` (checks a job, prints nothing), `printJob` (attributes and document in one request; resolves the job's id and state) and `cancelJob`. Each takes the printer's address (`host`, `port`, `rp` and `ipps` are in the snapshot) and bytes already in a format the printer lists. A job is `one-sided` unless it says otherwise, so a printer's duplex default never applies. A Print-Job that times out (60 s) is a `timeout` error that says it may still print: never resend it blindly.
+- **PWG Raster** (`raster.ts`): `pwgRaster(pages, media, total?)` packs 8-bit grey pages, an array or one at a time from a generator, into `image/pwg-raster` (PWG 5102.4), for a printer that lists no PDF. `mediaPixels` gives a page's size at a resolution. Only `sgray_8`.
+- **`home printers print <file.pdf> [printer]`**: sends the PDF as is when the printer lists `application/pdf`; otherwise renders each page with poppler's `pdftoppm` at the printer's raster resolution, fitted to the loaded media and centred (a page's `/Rotate` applied; a landscape page shrunk to fit, not turned), then Validate-Job, then Print-Job. One page is held at a time. `--dry-run` renders and has the printer validate the job (Validate-Job prints nothing), and sends no job. `home printers identify [printer]` and `cancel <job> [printer]`. The printer can be left out when there is one.
 
 ## Protocol
 
@@ -30,10 +33,12 @@ Discovery is mDNS `_ipp._tcp` and `_ipps._tcp` ([Apple's AirPrint TXT keys](http
 
 ## Unverified
 
-Everything, until a real printer answers: the request bytes (the codec is checked against RFC 8010's layout and a fixture of invented values, not a printer), the default path `ipp/print`, that `printer-uuid` equals TXT `UUID` on a Brother, that a sleeping printer wakes for the request, what a Brother sends for `marker-levels` and `printer-alert` (the sample uses invented values), Bun's `fetch` on port 631, and the macOS local-network prompt on first use.
+`printer-uuid` against TXT `UUID` on a Brother, a sleeping printer waking for a request, what `printer-alert` means on it, and the macOS local-network prompt on first use. For printing: a printer that takes PDF, a document of more than one page, two-sided, a colour printer, and the Node CLI (only Bun has run it).
 
 ## Live findings
 
+**2026-11-12, from a Mac (Bun 1.4.4), Brother HL-L2350DW.** It lists `application/octet-stream`, `image/urf` and `image/pwg-raster`, no PDF; PWG Raster at 600 dpi, `sgray_8` only, `pwg-raster-document-sheet-back` `rotated`; operations include Validate-Job, Cancel-Job and Identify-Printer. Identify-Printer and Validate-Job answered OK. Two one-page jobs printed: first a raster macOS's own filters made (`cupsfilter` with the AirPrint PPD; now `test/fixtures/printers/macos-a4-600.pwg`), then one from `home printers print` and `pwgRaster`, 60 kB for a page of text. Each answered `job-state` 5 (processing), both pages came out right (two lines of text, A4), and the printer was idle again within 30 s.
+
 **2026-11-10, from a Pi (Bun 1.4.4, 0.1.2; chota-bot's session).** `home discover` found the Brother by mDNS and `home printers` read it: "Brother HL-L2350DW series: idle · BK 80% · A4 ready". So discovery, the request, the default path, a real `marker-levels` and `media-ready` work on this model. Still unverified from the list above: `printer-uuid` against TXT `UUID`, a sleeping printer waking, `printer-alert`, and the macOS local-network prompt.
 
 2026-10-14 (Bun 1.4.3): `home discover` (two passes) and `home printers` found no `_ipp._tcp` or `_ipps._tcp` instance on the network, so the Brother was not advertising (off, asleep, or on another network).

package/src/connectors/printers/client.ts

@@ -3,12 +3,16 @@ import {
   attributesOf,
   decodeMessage,
   getPrinterAttributesRequest,
+  type IppAttribute,
   type IppMessage,
+  OPERATION,
+  operationRequest,
+  TAG,
 } from "./codec.ts";
 
-// Pure reads: a `fetch`, an address and a path come in, the printer's attributes go out. No writes here yet.
-// TODO(writes, behind KO's hand): Identify-Printer (0x003C, a beep) first, then Print-Job (0x0002) with application/pdf
-// where `document-format-supported` lists it. Each is one more request builder in codec.ts and one function here.
+// Pure calls: a `fetch`, an address and the bytes to send come in, the printer's answer goes out. The reads are
+// Get-Printer-Attributes; the writes Identify-Printer, Validate-Job, Print-Job and Cancel-Job. The document is the caller's,
+// already in a format the printer lists (`document-format-supported`): this package makes no PDF into raster.
 
 /** Everything the integration reads from one printer. */
 export const REQUESTED = [
@@ -74,18 +78,21 @@ const STATUS: Record<number, string> = {
   0x0507: "server-error-busy",
 };
 
+type CallOptions = {
+  requestId?: number;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+};
+
 /**
- * Get-Printer-Attributes over HTTP, through `fetchTimeout`. A non-ok HTTP status or an IPP status of 0x0100 and up throws a
- * ConnectorError saying which. Returns the whole response; `attributesOf` gives the printer's attributes.
+ * One IPP request over HTTP, through `fetchTimeout`. A non-ok HTTP status or an IPP status of 0x0100 and up throws a
+ * ConnectorError saying which (`code: "ipp"`, the IPP status in `status`).
  */
-export async function getPrinterAttributes(
+async function call(
   fetcher: typeof fetch,
   address: PrinterAddress,
-  options: {
-    requestId?: number;
-    signal?: AbortSignal;
-    timeoutMs?: number;
-  } = {},
+  body: (ippUri: string) => Uint8Array<ArrayBuffer>,
+  options: CallOptions = {},
 ): Promise<IppMessage> {
   const url = printerUrl(address);
   const res = await fetchTimeout(
@@ -94,7 +101,7 @@ export async function getPrinterAttributes(
     {
       method: "POST",
       headers: { "content-type": "application/ipp", accept: "application/ipp" },
-      body: getPrinterAttributesRequest(url.ipp, REQUESTED, options.requestId),
+      body: body(url.ipp),
     },
     options,
   );
@@ -112,3 +119,170 @@ export async function getPrinterAttributes(
   }
   return message;
 }
+
+/** Get-Printer-Attributes: the whole response; `attributesOf` gives the printer's attributes. `requested` replaces the poll's list. */
+export const getPrinterAttributes = (
+  fetcher: typeof fetch,
+  address: PrinterAddress,
+  options: CallOptions & { requested?: string[] } = {},
+): Promise<IppMessage> =>
+  call(
+    fetcher,
+    address,
+    (uri) =>
+      getPrinterAttributesRequest(
+        uri,
+        options.requested ?? REQUESTED,
+        options.requestId,
+      ),
+    options,
+  );
+
+/** Identify-Printer: the printer shows or sounds that it is the one (PWG 5100.13). No paper. */
+export const identifyPrinter = (
+  fetcher: typeof fetch,
+  address: PrinterAddress,
+  options: CallOptions = {},
+): Promise<unknown> =>
+  call(
+    fetcher,
+    address,
+    (uri) =>
+      operationRequest(OPERATION.identifyPrinter, uri, {
+        requestId: options.requestId,
+      }),
+    options,
+  );
+
+/**
+ * What a job says about itself. `format` is the document's MIME type and must be one the printer lists; `media` a PWG
+ * media name (`iso_a4_210x297mm`). `sides` defaults to `one-sided`, sent explicitly so a printer's duplex default
+ * never applies to a document made for one side.
+ */
+export type PrintJob = {
+  format: string;
+  name?: string;
+  user?: string;
+  media?: string;
+  sides?: "one-sided" | "two-sided-long-edge" | "two-sided-short-edge";
+  copies?: number;
+};
+
+/** A job the printer took: its id, and its state when it answered (RFC 8011: 3 pending, 5 processing, 9 completed). */
+export type PrintedJob = { jobId?: number; state?: number; reasons?: string[] };
+
+/** Who asks: RFC 8011 has a client send it on every operation. `home` unless the caller names someone. */
+const userAttribute = (user = "home"): IppAttribute => ({
+  name: "requesting-user-name",
+  tag: TAG.nameWithoutLanguage,
+  values: [user],
+});
+
+function jobAttributes(job: PrintJob): {
+  attributes: IppAttribute[];
+  job: IppAttribute[];
+} {
+  const attributes: IppAttribute[] = [
+    userAttribute(job.user),
+    {
+      name: "job-name",
+      tag: TAG.nameWithoutLanguage,
+      values: [job.name ?? "home"],
+    },
+    { name: "document-format", tag: TAG.mimeMediaType, values: [job.format] },
+  ];
+  const attrs: IppAttribute[] = [
+    { name: "sides", tag: TAG.keyword, values: [job.sides ?? "one-sided"] },
+  ];
+  if (job.media)
+    attrs.push({ name: "media", tag: TAG.keyword, values: [job.media] });
+  if (job.copies !== undefined)
+    attrs.push({ name: "copies", tag: TAG.integer, values: [job.copies] });
+  return { attributes, job: attrs };
+}
+
+/** Validate-Job: the printer checks the job's attributes as Print-Job would, and prints nothing. */
+export const validateJob = (
+  fetcher: typeof fetch,
+  address: PrinterAddress,
+  job: PrintJob,
+  options: CallOptions = {},
+): Promise<unknown> =>
+  call(
+    fetcher,
+    address,
+    (uri) =>
+      operationRequest(OPERATION.validateJob, uri, {
+        ...jobAttributes(job),
+        requestId: options.requestId,
+      }),
+    options,
+  );
+
+/** No upload waits longer than this: a page of raster is a few hundred kB, and a printer can be slow to take it. */
+export const PRINT_TIMEOUT_MS = 60_000;
+
+/**
+ * Print-Job: the job's attributes and the document in one request. A timeout leaves it unknown whether the printer took
+ * the job, so the error says not to send it again blindly.
+ */
+export async function printJob(
+  fetcher: typeof fetch,
+  address: PrinterAddress,
+  job: PrintJob,
+  document: Uint8Array,
+  options: CallOptions = {},
+): Promise<PrintedJob> {
+  let answer: IppMessage;
+  try {
+    answer = await call(
+      fetcher,
+      address,
+      (uri) =>
+        operationRequest(OPERATION.printJob, uri, {
+          ...jobAttributes(job),
+          data: document,
+          requestId: options.requestId,
+        }),
+      { timeoutMs: PRINT_TIMEOUT_MS, ...options },
+    );
+  } catch (error) {
+    if (error instanceof Error && error.name === "TimeoutError")
+      throw new ConnectorError(
+        "the printer did not answer the print job in time; it may still print, so check the printer before sending it again",
+        { code: "timeout", cause: error },
+      );
+    throw error;
+  }
+  const a = attributesOf(answer, TAG.job);
+  const n = (v: unknown) => (typeof v === "number" ? v : undefined);
+  const reasons = a["job-state-reasons"]?.filter(
+    (r): r is string => typeof r === "string",
+  );
+  return {
+    jobId: n(a["job-id"]?.[0]),
+    state: n(a["job-state"]?.[0]),
+    reasons: reasons?.length ? reasons : undefined,
+  };
+}
+
+/** Cancel-Job: stop a job by its id, from Print-Job's answer. */
+export const cancelJob = (
+  fetcher: typeof fetch,
+  address: PrinterAddress,
+  jobId: number,
+  options: CallOptions & { user?: string } = {},
+): Promise<unknown> =>
+  call(
+    fetcher,
+    address,
+    (uri) =>
+      operationRequest(OPERATION.cancelJob, uri, {
+        requestId: options.requestId,
+        attributes: [
+          { name: "job-id", tag: TAG.integer, values: [jobId] },
+          userAttribute(options.user), // printers often let only the job's owner cancel it
+        ],
+      }),
+    options,
+  );

package/src/connectors/printers/codec.ts

@@ -29,8 +29,14 @@ export const TAG = {
   mimeMediaType: 0x49,
 } as const;
 
-/** The operation ids this package sends. Identify-Printer (0x003C) and Print-Job (0x0002) are the writes that come later. */
-export const OPERATION = { getPrinterAttributes: 0x000b } as const;
+/** The operation ids this package sends (RFC 8011; Identify-Printer from PWG 5100.13). */
+export const OPERATION = {
+  printJob: 0x0002,
+  validateJob: 0x0004,
+  cancelJob: 0x0008,
+  getPrinterAttributes: 0x000b,
+  identifyPrinter: 0x003c,
+} as const;
 
 const STRING_TAGS: ReadonlySet<number> = new Set([
   TAG.textWithoutLanguage,
@@ -138,19 +144,30 @@ export function encodeMessage(m: IppMessage): Uint8Array<ArrayBuffer> {
       });
   }
   out.push(TAG.end);
-  return Uint8Array.from([...out, ...(m.data ?? [])]);
+  const bytes = new Uint8Array(out.length + (m.data?.length ?? 0));
+  bytes.set(out);
+  if (m.data) bytes.set(m.data, out.length);
+  return bytes;
 }
 
-/** The Get-Printer-Attributes request: IPP 2.0, utf-8, English, the printer's `ipp://` URI, and the attributes wanted. */
-export function getPrinterAttributesRequest(
+/**
+ * A request to one printer: IPP 2.0, utf-8, English, the printer's `ipp://` URI, then `attributes` in the operation
+ * group, `job` (when given) in a job group, and `data` (a document) after the end tag.
+ */
+export function operationRequest(
+  code: number,
   printerUri: string,
-  requested: string[],
-  requestId = 1,
+  options: {
+    attributes?: IppAttribute[];
+    job?: IppAttribute[];
+    data?: Uint8Array;
+    requestId?: number;
+  } = {},
 ): Uint8Array<ArrayBuffer> {
   return encodeMessage({
     version: [2, 0],
-    code: OPERATION.getPrinterAttributes,
-    requestId,
+    code,
+    requestId: options.requestId ?? 1,
     groups: [
       {
         tag: TAG.operation,
@@ -162,13 +179,30 @@ export function getPrinterAttributesRequest(
             values: ["en"],
           },
           { name: "printer-uri", tag: TAG.uri, values: [printerUri] },
-          { name: "requested-attributes", tag: TAG.keyword, values: requested },
+          ...(options.attributes ?? []),
         ],
       },
+      ...(options.job?.length
+        ? [{ tag: TAG.job, attributes: options.job }]
+        : []),
     ],
+    data: options.data,
   });
 }
 
+/** The Get-Printer-Attributes request: the attributes wanted. */
+export const getPrinterAttributesRequest = (
+  printerUri: string,
+  requested: string[],
+  requestId = 1,
+) =>
+  operationRequest(OPERATION.getPrinterAttributes, printerUri, {
+    requestId,
+    attributes: [
+      { name: "requested-attributes", tag: TAG.keyword, values: requested },
+    ],
+  });
+
 const fail = (why: string): never => {
   throw new Error(`ipp: ${why}`);
 };

package/src/connectors/printers/index.ts

@@ -39,6 +39,21 @@ export {
   type PrinterStatus,
   printerText,
 } from "./state.ts";
+export {
+  cancelJob,
+  identifyPrinter,
+  type PrintedJob,
+  type PrinterAddress,
+  type PrintJob,
+  printJob,
+  validateJob,
+} from "./client.ts";
+export {
+  type GreyPage,
+  mediaPixels,
+  pwgRaster,
+  type RasterMedia,
+} from "./raster.ts";
 
 /** One printer in a home config. Everything the printer reports about itself (model, markers, state) comes live; `host` and `port` are only where it last answered. */
 export const configSchema = z.looseObject({
@@ -184,6 +199,8 @@ export function printers(
       name: t.name,
       model: good.model ?? t.foundModel,
       host: t.host,
+      port: t.port,
+      rp: t.rp,
       room: t.room,
       ...(offline ? { state: "offline" as const } : {}),
       ipps: t.ipps,

package/src/connectors/printers/raster.ts

@@ -0,0 +1,215 @@
+// PWG Raster (PWG 5102.4), 8-bit grey only: what an AirPrint printer that lists `image/pwg-raster` takes when it lists no
+// PDF. A file is "RaS2", then per page a 1796-byte big-endian header and the page's pixels, compressed line by line:
+// a line-repeat byte (the line appears n + 1 times), then runs: 0 to 127 is one pixel repeated n + 1 times, 129 to 255 is
+// 257 − n pixels as they are. Checked against a page macOS's own filters made for a Brother (test/fixtures/printers).
+
+/** One page: `pixels` is `width × height` bytes, row by row from the top, 0 black to 255 white. */
+export type GreyPage = {
+  width: number;
+  height: number;
+  pixels: Uint8Array;
+};
+
+/** What every page is printed as: the printer's resolution and the PWG media name and size it lists. */
+export type RasterMedia = {
+  /** PWG self-describing name, as the printer lists it in `media-supported`: `iso_a4_210x297mm`. */
+  name: string;
+  /** dots per inch, one of the printer's `pwg-raster-document-resolution-supported`. */
+  dpi: number;
+};
+
+const HEADER = 1796;
+const SGRAY = 18; // cupsColorSpace for sgray (PWG 5102.4 table 9)
+const WHITE = 0xffffff; // AlternatePrimary: the white point, as PWG 5102.4 recommends
+
+/** A PWG media name's size in inches: `iso_a4_210x297mm` is 8.27 × 11.69. */
+function mediaInches(name: string): { width: number; height: number } {
+  const m = /_(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)(mm|in)$/.exec(name);
+  if (!m) throw new RangeError(`not a PWG media size: ${name}`);
+  const per = m[3] === "mm" ? 1 / 25.4 : 1;
+  return { width: Number(m[1]) * per, height: Number(m[2]) * per };
+}
+
+/** The pixels a page of this media is at its resolution, rounded down as macOS's filters do: A4 at 600 dpi is 4960 × 7015. */
+export function mediaPixels(media: RasterMedia): {
+  width: number;
+  height: number;
+} {
+  const i = mediaInches(media.name);
+  return {
+    width: Math.floor(i.width * media.dpi),
+    height: Math.floor(i.height * media.dpi),
+  };
+}
+
+function header(page: GreyPage, media: RasterMedia, total: number) {
+  const h = new Uint8Array(HEADER);
+  const v = new DataView(h.buffer);
+  const u32 = (offset: number, n: number) => v.setUint32(offset, n);
+  const str = (offset: number, s: string) =>
+    h.set(new TextEncoder().encode(s).subarray(0, 63), offset);
+  const pt = mediaPixels({ name: media.name, dpi: 72 }); // PageSize is in points
+  str(0, "PwgRaster"); // MediaClass
+  u32(276, media.dpi); // HWResolution
+  u32(280, media.dpi);
+  u32(340, 1); // NumCopies: copies are the job's, not the page's
+  u32(352, pt.width); // PageSize, points
+  u32(356, pt.height);
+  u32(372, page.width); // Width, Height in pixels
+  u32(376, page.height);
+  u32(384, 8); // BitsPerColor
+  u32(388, 8); // BitsPerPixel
+  u32(392, page.width); // BytesPerLine
+  u32(400, SGRAY); // ColorSpace; ColorOrder (396) 0 is chunky
+  u32(420, 1); // NumColors
+  u32(452, total); // TotalPageCount
+  u32(456, 1); // CrossFeedTransform
+  u32(460, 1); // FeedTransform
+  u32(480, WHITE); // AlternatePrimary
+  str(1732, media.name); // PageSizeName
+  return h;
+}
+
+/** One line's runs, appended to `out`. */
+function packLine(line: Uint8Array, out: number[]) {
+  let i = 0;
+  while (i < line.length) {
+    let run = 1;
+    while (run < 128 && i + run < line.length && line[i + run] === line[i])
+      run++;
+    if (run > 1 || i + 1 === line.length) {
+      out.push(run - 1, line[i]!);
+      i += run;
+      continue;
+    }
+    // Literal: up to 128 pixels, stopping before two equal pixels that would pack better as a repeat.
+    let n = 1;
+    while (
+      n < 128 &&
+      i + n < line.length &&
+      !(i + n + 1 < line.length && line[i + n] === line[i + n + 1])
+    )
+      n++;
+    if (n === 1) {
+      out.push(0, line[i]!); // a lone pixel is a repeat of one: 257 − 256 can't be written
+      i += 1;
+      continue;
+    }
+    out.push(257 - n);
+    for (let k = 0; k < n; k++) out.push(line[i + k]!);
+    i += n;
+  }
+}
+
+/**
+ * Pages as one PWG Raster document, `image/pwg-raster`. Every page must be `width × height` bytes. Pages may come one at
+ * a time (a generator), so only the packed document and the current page are held; then `total` is the page count.
+ */
+export function pwgRaster(
+  pages: Iterable<GreyPage>,
+  media: RasterMedia,
+  total = Array.isArray(pages) ? pages.length : 0,
+): Uint8Array<ArrayBuffer> {
+  const chunks: Uint8Array[] = [new TextEncoder().encode("RaS2")];
+  for (const page of pages) {
+    if (page.pixels.length !== page.width * page.height)
+      throw new RangeError(
+        `a ${page.width} × ${page.height} page needs ${page.width * page.height} bytes, got ${page.pixels.length}`,
+      );
+    chunks.push(header(page, media, total));
+    let y = 0;
+    while (y < page.height) {
+      const line = page.pixels.subarray(y * page.width, (y + 1) * page.width);
+      let repeat = 0;
+      while (
+        repeat < 255 &&
+        y + repeat + 1 < page.height &&
+        equal(
+          line,
+          page.pixels.subarray(
+            (y + repeat + 1) * page.width,
+            (y + repeat + 2) * page.width,
+          ),
+        )
+      )
+        repeat++;
+      const out = [repeat]; // one line at a time: a page as a number[] would be hundreds of MB
+      packLine(line, out);
+      chunks.push(Uint8Array.from(out));
+      y += repeat + 1;
+    }
+  }
+  const size = chunks.reduce((n, c) => n + c.length, 0);
+  const file = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) (file.set(c, at), (at += c.length));
+  return file;
+}
+
+function equal(a: Uint8Array, b: Uint8Array) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** A PWG Raster document back as pages and their headers' key fields; for tests and for checking a file before it prints. */
+export function readPwgRaster(file: Uint8Array): (GreyPage & {
+  dpi: number;
+  pageSizeName: string;
+  colorSpace: number;
+  bitsPerPixel: number;
+})[] {
+  const text = new TextDecoder();
+  if (text.decode(file.subarray(0, 4)) !== "RaS2")
+    throw new Error("pwg raster: no RaS2 sync word");
+  const pages = [];
+  let at = 4;
+  while (at < file.length) {
+    const v = new DataView(file.buffer, file.byteOffset + at, HEADER);
+    const width = v.getUint32(372);
+    const height = v.getUint32(376);
+    const bitsPerPixel = v.getUint32(388);
+    const bytes = bitsPerPixel / 8;
+    const name = file.subarray(at + 1732, at + 1796);
+    const pageSizeName = text.decode(name.subarray(0, name.indexOf(0)));
+    const page = {
+      width,
+      height,
+      dpi: v.getUint32(276),
+      pageSizeName,
+      colorSpace: v.getUint32(400),
+      bitsPerPixel,
+      pixels: new Uint8Array(width * height * bytes),
+    };
+    at += HEADER;
+    const lineBytes = width * bytes;
+    let y = 0;
+    while (y < height) {
+      const repeat = file[at++]! + 1;
+      const line = new Uint8Array(lineBytes);
+      let x = 0;
+      while (x < lineBytes) {
+        const c = file[at++]!;
+        if (c === 128) {
+          line.fill(255, x); // the rest of the line is white
+          break;
+        }
+        if (c < 128) {
+          const px = file.subarray(at, at + bytes);
+          for (let k = 0; k <= c; k++) line.set(px, x + k * bytes);
+          at += bytes;
+          x += (c + 1) * bytes;
+        } else {
+          const n = (257 - c) * bytes;
+          line.set(file.subarray(at, at + n), x);
+          at += n;
+          x += n;
+        }
+      }
+      for (let k = 0; k < repeat && y < height; k++, y++)
+        page.pixels.set(line, y * lineBytes);
+    }
+    pages.push(page);
+  }
+  return pages;
+}

package/src/connectors/printers/state.ts

@@ -21,6 +21,8 @@ export type Printer = {
   name: string;
   model?: string;
   host?: string;
+  port?: number; // where it last answered, with `rp`: what a write needs to reach it
+  rp?: string; // the IPP path from discovery's TXT; absent is `ipp/print`
   room?: string;
   state?: PrinterStatus; // absent when the printer sent a code outside 3 to 5; `stateCode` has it
   stateCode?: number;