rmapi-js 13.0.0 → 14.0.0

package/dist/codes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The pen and color codes a stroke carries, shared by every `.rm` version.
+ *
+ * A stroke stores its pen and its color as small integers. Both sets grew with
+ * the firmware, so a code from a newer device can name the same pen or color
+ * as an older one. Reading a page checks the codes against these lists.
+ *
+ * @packageDocumentation
+ */
+import { z } from "zod";
+/** a pen/tool name for a stroke */
+export type RmBrush = "brush" | "pencil" | "ballpoint" | "marker" | "fineliner" | "highlighter" | "eraser" | "mechanicalPencil" | "eraseArea" | "calligraphy" | "shader";
+/** a pen code that appears in a file */
+export type RmBrushCode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 21 | 23;
+export declare const rmBrushCode: z.ZodType<RmBrushCode>;
+/**
+ * the reMarkable pens, by code
+ *
+ * The codes come in two firmware families, so two codes can name the same pen.
+ */
+export declare const rmBrushes: Readonly<Record<RmBrushCode, RmBrush>>;
+/** a color name for a stroke */
+export type RmColor = "black" | "gray" | "white" | "yellow" | "green" | "pink" | "blue" | "red" | "grayOverlap" | "highlight" | "cyan" | "magenta";
+/** a color code that appears in a file */
+export type RmColorCode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+export declare const rmColorCode: z.ZodType<RmColorCode>;
+/**
+ * the reMarkable palette, by code
+ *
+ * The palette grew when colored annotations arrived and again for the Paper
+ * Pro, so two codes can name the same color. `"highlight"` is a marker rather
+ * than a color — the stroke's real color is its `colorRgba`. The shade a name
+ * renders as depends on the device.
+ */
+export declare const rmColors: Readonly<Record<RmColorCode, RmColor>>;

package/dist/codes.js

@@ -0,0 +1,61 @@
+/**
+ * The pen and color codes a stroke carries, shared by every `.rm` version.
+ *
+ * A stroke stores its pen and its color as small integers. Both sets grew with
+ * the firmware, so a code from a newer device can name the same pen or color
+ * as an older one. Reading a page checks the codes against these lists.
+ *
+ * @packageDocumentation
+ */
+import { z } from "zod";
+export const rmBrushCode = z.literal([0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 14, 15, 16, 17, 18, 21, 23], { error: "unknown pen code" });
+/**
+ * the reMarkable pens, by code
+ *
+ * The codes come in two firmware families, so two codes can name the same pen.
+ */
+export const rmBrushes = {
+    0: "brush",
+    12: "brush",
+    1: "pencil",
+    14: "pencil",
+    2: "ballpoint",
+    15: "ballpoint",
+    3: "marker",
+    16: "marker",
+    4: "fineliner",
+    17: "fineliner",
+    5: "highlighter",
+    18: "highlighter",
+    6: "eraser",
+    7: "mechanicalPencil",
+    13: "mechanicalPencil",
+    8: "eraseArea",
+    21: "calligraphy",
+    23: "shader",
+};
+export const rmColorCode = z.literal([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], { error: "unknown color code" });
+/**
+ * the reMarkable palette, by code
+ *
+ * The palette grew when colored annotations arrived and again for the Paper
+ * Pro, so two codes can name the same color. `"highlight"` is a marker rather
+ * than a color — the stroke's real color is its `colorRgba`. The shade a name
+ * renders as depends on the device.
+ */
+export const rmColors = {
+    0: "black",
+    1: "gray",
+    2: "white",
+    3: "yellow",
+    4: "green",
+    5: "pink",
+    6: "blue",
+    7: "red",
+    8: "grayOverlap",
+    9: "highlight",
+    10: "green",
+    11: "cyan",
+    12: "magenta",
+    13: "yellow",
+};

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type Highlight, type ItemRef, type Metadata, type Orientation, type PageMetadata, RawRemarkable, type RmPage, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw.js";
+export type { RmBrush, RmBrushCode, RmColor, RmColorCode, } from "./codes.js";
+export { rmBrushes, rmColors } from "./codes.js";
 export { type DeviceModel, type DeviceScreen, deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
 export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPageStringValue, CPages, CPageUUID, DocumentContent, DocumentMetadata, Entries, EntryType, FileType, Highlight, HighlightRect, ItemRef, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageLayer, PageMetadata, PageTag, PendingEntry, RawEntry, RawRemarkableApi, RmPage, SchemaVersion, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw.js";
-export type { RmBrush, RmLayer, RmLine, RmPageV5, RmPoint, RmVersion, } from "./rm5.js";
-export { decodeBrush, rmColors } from "./rm5.js";
+export type { RmLayer, RmLine, RmPageV5, RmPoint, RmVersion, } from "./rm5.js";
 export type { AuthorIdsBlock, CrdtId, GlyphRange, LwwValue, MigrationInfoBlock, PageInfoBlock, Rectangle, RmBlock, RmScene, RmSceneItem, RmSceneLayer, RmV6Line, RmV6Point, RmV6Text, RmV6TextValue, RootTextBlock, SceneGlyphItemBlock, SceneGroupItemBlock, SceneInfoBlock, SceneItem, SceneLineItemBlock, SceneTextItemBlock, SceneTombstoneItemBlock, SceneTreeBlock, TreeNodeAnchor, TreeNodeBlock, UnknownBlock, } from "./rm6.js";
 export { crdtKey } from "./rm6.js";
 /** common properties shared by collections and documents */

package/dist/index.js

@@ -110,9 +110,9 @@ import { z } from "zod";
 import { HashNotFoundError, ValidationError } from "./error.js";
 import { LruCache } from "./lru.js";
 import { BYTES_PREFIX, CACHE_VERSION, parseMetadata, RawRemarkable, TEXT_PREFIX, } from "./raw.js";
+export { rmBrushes, rmColors } from "./codes.js";
 export { deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
-export { decodeBrush, rmColors } from "./rm5.js";
 export { crdtKey } from "./rm6.js";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 const RAW_HOST = "https://eu.tectonic.remarkable.com";

package/dist/rm5.d.ts

@@ -13,6 +13,7 @@
  *
  * @packageDocumentation
  */
+import { type RmBrushCode, type RmColorCode } from "./codes.js";
 /** the flat reMarkable `.lines` file versions read into an {@link RmPageV5} */
 export type RmVersion = 3 | 5;
 /** a single sampled point along a stroke */
@@ -30,20 +31,12 @@ export interface RmPoint {
     /** the pen pressure, from 0 to 1 */
     pressure: number;
 }
-/**
- * a single stroke (called a "line") within a layer
- *
- * `brushType` and `color` are kept as raw integers because both are overloaded
- * across firmware versions (there are two pen-code families, and the color
- * field is reinterpreted as a palette index when colored annotations are
- * enabled), so the right meaning can only be resolved with the source firmware
- * in mind.
- */
+/** a single stroke (called a "line") within a layer */
 export interface RmLine {
-    /** the raw brush/pen type code */
-    brushType: number;
-    /** the raw color code */
-    color: number;
+    /** the pen code, named by {@link rmBrushes | `rmBrushes`} */
+    brushType: RmBrushCode;
+    /** the color code, named by {@link rmColors | `rmColors`} */
+    color: RmColorCode;
     /** a per-stroke padding field, typically 0 */
     padding?: number;
     /** the base brush size */
@@ -70,23 +63,6 @@ export interface RmPageV5 {
     /** the drawing layers, back to front */
     layers: RmLayer[];
 }
-/** a decoded pen/tool for a stroke */
-export type RmBrush = "brush" | "pencil" | "ballpoint" | "marker" | "fineliner" | "highlighter" | "eraser" | "mechanicalPencil" | "eraseArea" | "calligraphy" | "shader";
-/**
- * decode a raw {@link RmLine.brushType | `brushType`} code to a pen name
- *
- * Best-effort and advisory: the reMarkable pen codes come in two firmware
- * families and new ones appear over time, so an unrecognized code returns
- * `undefined`. The raw `brushType` int stays authoritative.
- */
-export declare function decodeBrush(code: number): RmBrush | undefined;
-/**
- * the default (monochrome) reMarkable palette, by raw {@link RmLine.color | `color`}
- *
- * Advisory only: when "colored annotations" are enabled or on version 6, the
- * `color` field is reinterpreted, so resolve against the source firmware.
- */
-export declare const rmColors: Readonly<Record<number, string>>;
 /** the length of the fixed `.lines` header, in bytes */
 export declare const HEADER_LENGTH = 43;
 /** the ascii prefix of the header, immediately followed by the version digit */

package/dist/rm5.js

@@ -13,47 +13,7 @@
  *
  * @packageDocumentation
  */
-const BRUSHES = {
-    0: "brush",
-    12: "brush",
-    1: "pencil",
-    14: "pencil",
-    2: "ballpoint",
-    15: "ballpoint",
-    3: "marker",
-    16: "marker",
-    4: "fineliner",
-    17: "fineliner",
-    5: "highlighter",
-    18: "highlighter",
-    6: "eraser",
-    7: "mechanicalPencil",
-    13: "mechanicalPencil",
-    8: "eraseArea",
-    21: "calligraphy",
-    23: "shader",
-};
-/**
- * decode a raw {@link RmLine.brushType | `brushType`} code to a pen name
- *
- * Best-effort and advisory: the reMarkable pen codes come in two firmware
- * families and new ones appear over time, so an unrecognized code returns
- * `undefined`. The raw `brushType` int stays authoritative.
- */
-export function decodeBrush(code) {
-    return BRUSHES[code];
-}
-/**
- * the default (monochrome) reMarkable palette, by raw {@link RmLine.color | `color`}
- *
- * Advisory only: when "colored annotations" are enabled or on version 6, the
- * `color` field is reinterpreted, so resolve against the source firmware.
- */
-export const rmColors = {
-    0: "black",
-    1: "gray",
-    2: "white",
-};
+import { rmBrushCode, rmColorCode, } from "./codes.js";
 /** the length of the fixed `.lines` header, in bytes */
 export const HEADER_LENGTH = 43;
 /** the ascii prefix of the header, immediately followed by the version digit */
@@ -83,8 +43,8 @@ export function parseV5(data, version) {
         const numLines = readInt();
         const lines = [];
         for (let line = 0; line < numLines; line++) {
-            const brushType = readInt();
-            const color = readInt();
+            const brushType = rmBrushCode.parse(readInt());
+            const color = rmColorCode.parse(readInt());
             const padding = readInt();
             const brushBaseSize = readFloat();
             const unknown = version === 5 ? readInt() : undefined;

package/dist/rm6.d.ts

@@ -11,6 +11,7 @@
  *
  * @packageDocumentation
  */
+import { type RmBrushCode, type RmColorCode } from "./codes.js";
 /**
  * a CRDT identifier: an `(authorId, counter)` pair, unique across replicas
  *
@@ -54,10 +55,10 @@ export interface RmV6Point {
 }
 /** a version 6 stroke */
 export interface RmV6Line {
-    /** the raw pen/tool code */
-    tool: number;
-    /** the raw color code */
-    color: number;
+    /** the pen code, named by `rmBrushes` */
+    tool: RmBrushCode;
+    /** the color code, named by `rmColors` */
+    color: RmColorCode;
     /** the stroke thickness scale */
     thicknessScale: number;
     /** the length at which the stroke starts */
@@ -94,8 +95,8 @@ export interface GlyphRange {
     start?: number;
     /** the length of the range */
     length: number;
-    /** the raw color code */
-    color: number;
+    /** the color code, named by `rmColors` */
+    color: RmColorCode;
     /** the highlighted text */
     text: string;
     /** the bounding rectangles of the highlight */

package/dist/rm6.js

@@ -11,6 +11,7 @@
  *
  * @packageDocumentation
  */
+import { rmBrushCode, rmColorCode, } from "./codes.js";
 /** the scene-tree root node id */
 export const ROOT_ID = { authorId: 0, counter: 1 };
 /** the CRDT sequence end marker / unset id */
@@ -342,8 +343,8 @@ function readItemEnvelope(reader, readValue) {
     return { parentId, item: { itemId, leftId, rightId, deletedLength, value } };
 }
 function readLineValue(reader, version) {
-    const tool = reader.readInt(1);
-    const color = reader.readInt(2);
+    const tool = rmBrushCode.parse(reader.readInt(1));
+    const color = rmColorCode.parse(reader.readInt(2));
     const thicknessScale = reader.readDouble(3);
     const startingLength = reader.readFloat(4);
     const points = reader.subblock(5, () => {
@@ -394,7 +395,7 @@ function readGlyphValue(reader) {
     const explicitLength = reader.hasTag(3, TAG_BYTE4)
         ? reader.readInt(3)
         : undefined;
-    const color = reader.readInt(4);
+    const color = rmColorCode.parse(reader.readInt(4));
     const text = reader.readString(5);
     const rectangles = reader.subblock(6, () => {
         const count = reader.varuint();