rmapi-js 12.0.3 → 14.0.0

package/dist/rm6.d.ts

@@ -5,11 +5,13 @@
  * 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.
+ * ordered layers, strokes, and text. Nothing is dropped, so
+ * {@link serializeRmScene | `serializeRmScene`} reproduces the original bytes
+ * exactly, including blocks it could not parse.
  *
  * @packageDocumentation
  */
+import { type RmBrushCode, type RmColorCode } from "./codes.js";
 /**
  * a CRDT identifier: an `(authorId, counter)` pair, unique across replicas
  *
@@ -44,7 +46,7 @@ export interface RmV6Point {
     y: number;
     /** pen speed */
     speed: number;
-    /** stroke width */
+    /** stroke width; integral for version 2 points, fractional for version 1 */
     width: number;
     /** pen direction, 0–255 mapping onto 0–2π */
     direction: number;
@@ -53,16 +55,20 @@ 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 */
     startingLength: number;
     /** the sampled points */
     points: RmV6Point[];
+    /** the stroke's timestamp id, if the file carried one */
+    timestampId?: CrdtId;
+    /** the stroke's move id, if the file carried one */
+    moveId?: CrdtId;
     /**
      * a packed little-endian uint32 color, only present for highlighter strokes
      *
@@ -89,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 */
@@ -128,6 +134,12 @@ export interface RmV6Text {
 }
 /** fields carried by every block */
 interface BlockCommon {
+    /**
+     * the header byte between the block length and the versions
+     *
+     * Zero in every well-formed file seen, but preserved rather than assumed.
+     */
+    reserved: number;
     /** the block's minimum reader version */
     minVersion: number;
     /** the block's current version (selects the point encoding for lines) */
@@ -167,14 +179,19 @@ export interface TreeNodeBlock extends BlockCommon {
     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>;
+    /** where the node is anchored, when it is */
+    anchor?: TreeNodeAnchor;
+}
+/** the four values a tree node carries when it's anchored, always together */
+export interface TreeNodeAnchor {
+    /** the anchor node's crdt id */
+    id: LwwValue<CrdtId>;
+    /** the anchor type */
+    type: LwwValue<number>;
+    /** the anchor threshold */
+    threshold: LwwValue<number>;
+    /** the anchor's horizontal origin */
+    originX: LwwValue<number>;
 }
 /** the `0x05` scene line item block — a stroke */
 export interface SceneLineItemBlock extends BlockCommon {
@@ -242,8 +259,8 @@ export interface PageInfoBlock extends BlockCommon {
     textCharsCount: number;
     /** the number of text lines on the page */
     textLinesCount: number;
-    /** the type-folio use count */
-    typeFolioUseCount: number;
+    /** the type-folio use count, if the block carried one */
+    typeFolioUseCount?: number;
 }
 /** the `0x09` author ids block — the author-id to uuid table */
 export interface AuthorIdsBlock extends BlockCommon {
@@ -273,6 +290,13 @@ export interface UnknownBlock extends BlockCommon {
     blockType: number;
     /** the raw block body bytes */
     data: Uint8Array;
+    /**
+     * the length the block header declared, when it overran the file
+     *
+     * Corrupt files exist in the wild; keeping the original figure lets them
+     * round-trip byte for byte instead of being silently rewritten.
+     */
+    declaredLength?: number;
 }
 /** any parsed version 6 block */
 export type RmBlock = MigrationInfoBlock | SceneTreeBlock | TreeNodeBlock | SceneLineItemBlock | SceneGlyphItemBlock | SceneGroupItemBlock | SceneTextItemBlock | SceneTombstoneItemBlock | RootTextBlock | PageInfoBlock | AuthorIdsBlock | SceneInfoBlock | UnknownBlock;
@@ -329,6 +353,8 @@ export declare class RmScene {
     /** the page's document text, if any */
     text(): RmV6Text | undefined;
 }
+/** serialize a parsed scene back to version 6 `.rm` bytes */
+export declare function serializeRmScene(scene: RmScene): Uint8Array;
 /** parse a version 6 `.rm` file into a resolvable scene */
 export declare function parseRmScene(data: Uint8Array): RmScene;
 export {};