rmapi-js 11.1.2 → 11.2.0

package/dist/rm6.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Parse (and re-serialize) reMarkable `.rm` version 6 "scene tree" files.
+ *
+ * Version 6 is a CRDT scene tree, not a flat struct: a header then a sequence
+ * of length-prefixed, tagged blocks. This module reads every block faithfully
+ * — preserving `CrdtId`s, `LwwValue` wrappers, and each block's unread tail —
+ * into an {@link RmScene | `RmScene`}, whose methods resolve the CRDT into
+ * ordered layers, strokes, and text. Because nothing is dropped, the blocks
+ * round-trip back to bytes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * a CRDT identifier: an `(authorId, counter)` pair, unique across replicas
+ *
+ * The wire encodes it positionally — a single author byte then a varuint
+ * counter — with no field names; the `rmscene` reference calls these `part1`
+ * and `part2`.
+ */
+export interface CrdtId {
+    /** the author (device/replica) that minted this id, the leading wire byte */
+    authorId: number;
+    /** the author's monotonic counter (a varuint, may exceed 32 bits) */
+    counter: number;
+}
+/** the scene-tree root node id */
+export declare const ROOT_ID: CrdtId;
+/** the CRDT sequence end marker / unset id */
+export declare const END_MARKER: CrdtId;
+/** a stable string key for a {@link CrdtId | `CrdtId`} */
+export declare function crdtKey(id: CrdtId): string;
+/** a last-writer-wins value, a `value` stamped with a `timestamp` id */
+export interface LwwValue<T> {
+    /** the id of the writer that last set this value */
+    timestamp: CrdtId;
+    /** the stored value */
+    value: T;
+}
+/** a single sampled point of a version 6 stroke, in native (v2) units */
+export interface RmV6Point {
+    /** horizontal position in device pixels (centered origin, may be negative) */
+    x: number;
+    /** vertical position in device pixels (centered origin) */
+    y: number;
+    /** pen speed */
+    speed: number;
+    /** stroke width */
+    width: number;
+    /** pen direction, 0–255 mapping onto 0–2π */
+    direction: number;
+    /** pen pressure, 0–255 */
+    pressure: number;
+}
+/** a version 6 stroke */
+export interface RmV6Line {
+    /** the raw pen/tool code */
+    tool: number;
+    /** the raw color code */
+    color: number;
+    /** the stroke thickness scale */
+    thicknessScale: number;
+    /** the length at which the stroke starts */
+    startingLength: number;
+    /** the sampled points */
+    points: RmV6Point[];
+    /**
+     * a packed little-endian uint32 color, only present for highlighter strokes
+     *
+     * Logical channels are RGBA, stored in BGRA byte order (the integer is
+     * `0xAARRGGBB`): `r = (v >> 16) & 0xff`, `g = (v >> 8) & 0xff`, `b = v &
+     * 0xff`, `a = (v >> 24) & 0xff`. Kept as the raw packed value.
+     */
+    colorRgba?: number;
+}
+/** an axis-aligned rectangle */
+export interface Rectangle {
+    /** the left edge */
+    x: number;
+    /** the top edge */
+    y: number;
+    /** the width */
+    w: number;
+    /** the height */
+    h: number;
+}
+/** a highlighted run of underlying text */
+export interface GlyphRange {
+    /** the start offset into the underlying text, if present */
+    start?: number;
+    /** the length of the range */
+    length: number;
+    /** the raw color code */
+    color: number;
+    /** the highlighted text */
+    text: string;
+    /** the bounding rectangles of the highlight */
+    rectangles: Rectangle[];
+    /** a packed little-endian uint32 color (RGBA channels, BGRA byte order), if present */
+    colorRgba?: number;
+}
+/** the CRDT-sequence envelope shared by every scene item */
+export interface SceneItem<V> {
+    /** this item's own id */
+    itemId: CrdtId;
+    /** the id of the left sibling in the CRDT sequence */
+    leftId: CrdtId;
+    /** the id of the right sibling */
+    rightId: CrdtId;
+    /** how many following items this deletes */
+    deletedLength: number;
+    /** the item's value, or `undefined` if it carries none (e.g. a tombstone) */
+    value: V | undefined;
+}
+/** a text run or an inline format code within {@link RmV6Text | `RmV6Text`} */
+export type RmV6TextValue = string | number;
+/** the parsed document text of a page (from the root text block) */
+export interface RmV6Text {
+    /** the text runs / inline formats as a CRDT sequence of items */
+    items: SceneItem<RmV6TextValue>[];
+    /** paragraph styles keyed by the char id they attach to */
+    styles: Map<string, LwwValue<number>>;
+    /** the text block's horizontal position */
+    posX: number;
+    /** the text block's vertical position */
+    posY: number;
+    /** the text block's width */
+    width: number;
+}
+/** fields carried by every block */
+interface BlockCommon {
+    /** the block's minimum reader version */
+    minVersion: number;
+    /** the block's current version (selects the point encoding for lines) */
+    currentVersion: number;
+    /** the unread tail of the block, preserved for round-tripping */
+    extraData: Uint8Array;
+}
+/** the `0x00` migration info block */
+export interface MigrationInfoBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "migrationInfo";
+    /** the migration's crdt id */
+    migrationId: CrdtId;
+    /** whether the migration ran on the device */
+    isDevice: boolean;
+}
+/** the `0x01` scene tree block — a node/parent edge */
+export interface SceneTreeBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "sceneTree";
+    /** the tree entry's crdt id */
+    treeId: CrdtId;
+    /** the node this entry describes */
+    nodeId: CrdtId;
+    /** whether this is an update to an existing entry */
+    isUpdate: boolean;
+    /** the parent node's crdt id */
+    parentId: CrdtId;
+}
+/** the `0x02` tree node block — a group's metadata (layer name/visibility) */
+export interface TreeNodeBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "treeNode";
+    /** the node's crdt id */
+    nodeId: CrdtId;
+    /** the layer name */
+    label: LwwValue<string>;
+    /** whether the layer is visible */
+    visible: LwwValue<boolean>;
+    /** the anchor node's crdt id, if anchored */
+    anchorId?: LwwValue<CrdtId>;
+    /** the anchor type, if anchored */
+    anchorType?: LwwValue<number>;
+    /** the anchor threshold, if anchored */
+    anchorThreshold?: LwwValue<number>;
+    /** the anchor's horizontal origin, if anchored */
+    anchorOriginX?: LwwValue<number>;
+}
+/** the `0x05` scene line item block — a stroke */
+export interface SceneLineItemBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "sceneLineItem";
+    /** the parent group's crdt id */
+    parentId: CrdtId;
+    /** the stroke, in its crdt-sequence envelope */
+    item: SceneItem<RmV6Line>;
+}
+/** the `0x03` scene glyph item block — a text highlight */
+export interface SceneGlyphItemBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "sceneGlyphItem";
+    /** the parent group's crdt id */
+    parentId: CrdtId;
+    /** the highlight, in its crdt-sequence envelope */
+    item: SceneItem<GlyphRange>;
+}
+/** the `0x04` scene group item block — attaches a child node to a parent */
+export interface SceneGroupItemBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "sceneGroupItem";
+    /** the parent group's crdt id */
+    parentId: CrdtId;
+    /** the child node's crdt id, in its crdt-sequence envelope */
+    item: SceneItem<CrdtId>;
+}
+/** the `0x06` scene text item block — carries no parsed value */
+export interface SceneTextItemBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "sceneTextItem";
+    /** the parent group's crdt id */
+    parentId: CrdtId;
+    /** the (unparsed) item, in its crdt-sequence envelope */
+    item: SceneItem<undefined>;
+}
+/** the `0x08` scene tombstone item block — a deleted-item marker */
+export interface SceneTombstoneItemBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "sceneTombstone";
+    /** the parent group's crdt id */
+    parentId: CrdtId;
+    /** the deleted item's envelope (no value) */
+    item: SceneItem<undefined>;
+}
+/** the `0x07` root text block — the page's document text */
+export interface RootTextBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "rootText";
+    /** the text block's crdt id */
+    blockId: CrdtId;
+    /** the parsed document text */
+    text: RmV6Text;
+}
+/** the `0x0a` page info block */
+export interface PageInfoBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "pageInfo";
+    /** how many times the page has been loaded */
+    loadsCount: number;
+    /** how many times the page has been merged */
+    mergesCount: number;
+    /** the number of text characters on the page */
+    textCharsCount: number;
+    /** the number of text lines on the page */
+    textLinesCount: number;
+    /** the type-folio use count */
+    typeFolioUseCount: number;
+}
+/** the `0x09` author ids block — the author-id to uuid table */
+export interface AuthorIdsBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "authorIds";
+    /** the author-id to uuid table */
+    authors: Map<number, string>;
+}
+/** the `0x0d` scene info block */
+export interface SceneInfoBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "sceneInfo";
+    /** the currently-selected layer's crdt id */
+    currentLayer: LwwValue<CrdtId>;
+    /** whether the background is visible */
+    backgroundVisible?: LwwValue<boolean>;
+    /** whether the underlying document is visible */
+    rootDocumentVisible?: LwwValue<boolean>;
+    /** the page size in device pixels, if present */
+    paperSize?: [number, number];
+}
+/** a block whose type we don't parse, kept verbatim for round-tripping */
+export interface UnknownBlock extends BlockCommon {
+    /** the block-type discriminant */
+    type: "unknown";
+    /** the raw numeric block type */
+    blockType: number;
+    /** the raw block body bytes */
+    data: Uint8Array;
+}
+/** any parsed version 6 block */
+export type RmBlock = MigrationInfoBlock | SceneTreeBlock | TreeNodeBlock | SceneLineItemBlock | SceneGlyphItemBlock | SceneGroupItemBlock | SceneTextItemBlock | SceneTombstoneItemBlock | RootTextBlock | PageInfoBlock | AuthorIdsBlock | SceneInfoBlock | UnknownBlock;
+/** a resolved item within a layer, in CRDT order */
+export type RmSceneItem = {
+    /** the item discriminant */
+    kind: "layer";
+    /** a nested layer (scene-tree group) */
+    layer: RmSceneLayer;
+} | {
+    /** the item discriminant */
+    kind: "line";
+    /** a stroke */
+    line: RmV6Line;
+} | {
+    /** the item discriminant */
+    kind: "glyph";
+    /** a text highlight */
+    glyph: GlyphRange;
+};
+/** a resolved drawing layer (a scene-tree group) */
+export interface RmSceneLayer {
+    /** the group's crdt id */
+    id: CrdtId;
+    /** the layer name, if set */
+    label?: string;
+    /** whether the layer is visible, if set */
+    visible?: boolean;
+    /** the layer's items (nested layers, strokes, glyphs) in CRDT order */
+    items: RmSceneItem[];
+}
+/**
+ * a parsed version 6 scene
+ *
+ * The raw {@link RmBlock | `blocks`} are the faithful source of truth (they
+ * preserve the CRDT ids and re-serialize); the methods resolve them into
+ * ordered layers, strokes, and text.
+ */
+export declare class RmScene {
+    #private;
+    /** the discriminant for the {@link RmPage} union */
+    readonly version: 6;
+    /** every parsed block, in file order */
+    readonly blocks: readonly RmBlock[];
+    /** the author-id to uuid table */
+    readonly authors: Map<number, string>;
+    /** the page size, if the scene info block carried one */
+    readonly paperSize?: [number, number];
+    constructor(blocks: readonly RmBlock[]);
+    /** the drawing layers, in order, each with its items */
+    layers(): RmSceneLayer[];
+    /** every stroke on the page, in draw order, flattened across layers */
+    strokes(): RmV6Line[];
+    /** the page's document text, if any */
+    text(): RmV6Text | undefined;
+}
+/** parse a version 6 `.rm` file into a resolvable scene */
+export declare function parseRmScene(data: Uint8Array): RmScene;
+export {};