rmapi-js 12.0.2 → 13.0.0

package/dist/index.js

@@ -1,3 +1,55 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 /**
  * Create and interact with reMarkable cloud.
  *
@@ -36,11 +88,12 @@
  * The cloud api is essentially a collection of entries. Each entry has an id,
  * which is a uuid4 and a hash, which indicates it's current state, and changes
  * as the item mutates, where the id is constant. Most mutable operations take
- * the initial hash so that merge conflicts can be resolved. Each entry has a
- * number of properties, but a key property is the `parent`, which represents
- * its parent in the file structure. This will be another document id, or one of
- * two special ids, "" (the empty string) for the root directory, or "trash" for
- * the trash.
+ * both, as an {@link ItemRef | `ItemRef`}: the id says which item, and the hash
+ * says which state you meant to change, so a conflicting update fails rather
+ * than overwriting. Each entry has a number of properties, but a key property
+ * is the `parent`, which represents its parent in the file structure. This will
+ * be another document id, or one of two special ids, "" (the empty string) for
+ * the root directory, or "trash" for the trash.
  *
  * Detailed information about the low-level storage an apis can be found in
  * {@link RawRemarkableApi | `RawRemarkableApi`}.
@@ -56,11 +109,11 @@ import { v4 as uuid4 } from "uuid";
 import { z } from "zod";
 import { HashNotFoundError, ValidationError } from "./error.js";
 import { LruCache } from "./lru.js";
-import { parseMetadata, RawRemarkable, } from "./raw.js";
+import { BYTES_PREFIX, CACHE_VERSION, parseMetadata, RawRemarkable, TEXT_PREFIX, } from "./raw.js";
 export { deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
 export { decodeBrush, rmColors } from "./rm5.js";
-export { crdtKey, END_MARKER, parseRmScene, ROOT_ID } from "./rm6.js";
+export { crdtKey } from "./rm6.js";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 const RAW_HOST = "https://eu.tectonic.remarkable.com";
 const UPLOAD_HOST = "https://internal.cloud.remarkable.com";
@@ -71,7 +124,6 @@ const TRASH_ID = "trash";
 /** the id of the root entry list */
 const ROOT_LIST = "root";
 /** the file name of the root entry index */
-const ROOT_SCHEMA = `${ROOT_LIST}.docSchema`;
 /** base backoff in milliseconds for transient request retries */
 const TRANSIENT_BASE_MS = 200;
 /** base backoff in milliseconds for generation-conflict retries */
@@ -90,27 +142,25 @@ function backoffMs(attempt, baseMs) {
     return Math.random() * capped;
 }
 /**
- * a mutex acquired by async iteration
+ * a mutex held for the scope of the acquiring block
  *
- * `for await (const _lock of mutex) { ... }` runs the body with the lock held
- * and releases it when the body exits — by return, throw, or break — the way a
- * `using` block would. Waiters are served in acquisition order.
+ * `await using lock = await mutex.lock()` releases when the block exits, by
+ * return or by throw. Waiters are served in acquisition order.
  */
 class Mutex {
     #tail = Promise.resolve();
-    async *[Symbol.asyncIterator]() {
+    async lock() {
         const previous = this.#tail;
         let release;
         this.#tail = new Promise((resolve) => {
             release = resolve;
         });
         await previous;
-        try {
-            yield;
-        }
-        finally {
-            release();
-        }
+        return {
+            async [Symbol.asyncDispose]() {
+                release();
+            },
+        };
     }
 }
 /** the ordered page ids of a document's content, from cPages or the legacy list */
@@ -215,12 +265,12 @@ class Remarkable {
     #schemaVersion;
     /** serializes root updates on this instance so they don't self-conflict */
     #rootMutex = new Mutex();
-    constructor(sessionToken, rawHost, uploadHost, cache, maxGenerationRetries, maxTransientRetries) {
+    constructor(sessionToken, rawHost, uploadHost, cache, maxGenerationRetries, maxTransientRetries, maxCachedBytes) {
         this.#sessionToken = sessionToken;
         this.#cache = cache;
         this.#maxGenerationRetries = maxGenerationRetries;
         this.#maxTransientRetries = maxTransientRetries;
-        this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost, uploadHost);
+        this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost, uploadHost, maxCachedBytes);
     }
     async #getRootHash(refresh = false) {
         if (refresh || this.#lastHashGen === undefined) {
@@ -257,10 +307,12 @@ class Remarkable {
      * before this so retries reuse the same (cached) blobs.
      */
     async #withRetry(op) {
-        // hold the root lock across the whole read-merge-write so concurrent
-        // mutators serialize instead of sharing a generation and forcing each
-        // other into avoidable conflicts
-        for await (const _lock of this.#rootMutex) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            // hold the root lock across the whole read-merge-write so concurrent
+            // mutators serialize instead of sharing a generation and forcing each
+            // other into avoidable conflicts
+            const _lock = __addDisposableResource(env_1, await this.#rootMutex.lock(), true);
             for (let attempt = 0;; attempt++) {
                 try {
                     return await op();
@@ -276,8 +328,15 @@ class Remarkable {
                 }
             }
         }
-        // the mutex yields exactly once, so the loop always returns or throws
-        throw new Error("unreachable");
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
     }
     /**
      * splice an already-uploaded item entry into the root
@@ -290,13 +349,28 @@ class Remarkable {
         await this.#withRetry(async () => {
             const [rootHash, generation] = await this.#getRootHash();
             const { entries } = await this.raw.getEntries({
-                id: ROOT_SCHEMA,
+                id: ROOT_LIST,
                 hash: rootHash,
             });
             entries.push(entry);
-            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, entries, 4);
-            await uploadRoot;
-            await this.#putRootHash(rootEntry.hash, generation);
+            let newRoot;
+            {
+                const env_2 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const rootEntry = __addDisposableResource(env_2, await this.raw.putEntries(ROOT_LIST, entries, 4), true);
+                    newRoot = rootEntry.hash;
+                }
+                catch (e_2) {
+                    env_2.error = e_2;
+                    env_2.hasError = true;
+                }
+                finally {
+                    const result_2 = __disposeResources(env_2);
+                    if (result_2)
+                        await result_2;
+                }
+            }
+            await this.#putRootHash(newRoot, generation);
         });
     }
     async #authedFetch(url, { body, method = "POST", headers = {}, }) {
@@ -345,11 +419,9 @@ class Remarkable {
             }
         }
     }
-    async #convertEntry({ hash, id }) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
+    async #convertEntry(ref) {
+        const { id, hash } = ref;
+        const { entries } = await this.raw.getEntries(ref);
         const metaEnt = entries.find((ent) => ent.id.endsWith(".metadata"));
         const contentEnt = entries.find((ent) => ent.id.endsWith(".content"));
         if (metaEnt === undefined) {
@@ -423,17 +495,20 @@ class Remarkable {
      * @returns a list of all items with some metadata
      */
     async listItems(refresh = false) {
-        const ids = await this.listIds(refresh);
+        const ids = await this.listRefs(refresh);
         return await Promise.all(ids.map((id) => this.#convertEntry(id)));
     }
     /**
-     * similar to {@link listItems | `listItems`} but backed by the low level api
+     * list a reference to every item, backed by the low level api
+     *
+     * Unlike {@link listItems | `listItems`} this doesn't read each item's
+     * metadata, so it's cheaper but only gives you ids and hashes.
      *
      * @param refresh - if true, refresh the root hash before listing
      */
-    async listIds(refresh = false) {
+    async listRefs(refresh = false) {
         const [hash] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries({ id: ROOT_SCHEMA, hash });
+        const { entries } = await this.raw.getEntries({ id: ROOT_LIST, hash });
         return entries.map(({ id, hash }) => ({ id, hash }));
     }
     /**
@@ -444,14 +519,12 @@ class Remarkable {
      * the low-level api to get the raw text of the `.content` file in the
      * `RawEntry` for this hash.
      *
-     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
+     * @param ref - a reference to the item (e.g. from `listItems` or `listRefs`)
      * @returns the content
      */
-    async getContent({ id, hash }) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
+    async getContent(ref) {
+        const { hash } = ref;
+        const { entries } = await this.raw.getEntries(ref);
         const cont = entries.find((e) => e.id.endsWith(".content"));
         if (cont === undefined) {
             throw new Error(`couldn't find contents for hash ${hash}`);
@@ -468,14 +541,12 @@ class Remarkable {
      * the low-level api to get the raw text of the `.metadata` file in the
      * `RawEntry` for this hash.
      *
-     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
+     * @param ref - a reference to the item (e.g. from `listItems` or `listRefs`)
      * @returns the metadata
      */
-    async getMetadata({ id, hash }) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
+    async getMetadata(ref) {
+        const { hash } = ref;
+        const { entries } = await this.raw.getEntries(ref);
         const meta = entries.find((e) => e.id.endsWith(".metadata"));
         if (meta === undefined) {
             throw new Error(`couldn't find metadata for hash ${hash}`);
@@ -492,11 +563,9 @@ class Remarkable {
      * @param ref - a reference to the document (e.g. from `listItems`)
      * @returns the pdf bytes
      */
-    async getPdf({ id, hash }) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
+    async getPdf(ref) {
+        const { hash } = ref;
+        const { entries } = await this.raw.getEntries(ref);
         const pdf = entries.find((e) => e.id.endsWith(".pdf"));
         if (pdf === undefined) {
             throw new Error(`couldn't find pdf for hash ${hash}`);
@@ -513,11 +582,9 @@ class Remarkable {
      * @param ref - a reference to the document (e.g. from `listItems`)
      * @returns the epub bytes
      */
-    async getEpub({ id, hash }) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
+    async getEpub(ref) {
+        const { hash } = ref;
+        const { entries } = await this.raw.getEntries(ref);
         const epub = entries.find((e) => e.id.endsWith(".epub"));
         if (epub === undefined) {
             throw new Error(`couldn't find epub for hash ${hash}`);
@@ -526,6 +593,95 @@ class Remarkable {
             return await this.raw.getHash(epub);
         }
     }
+    #rmPageFile = {
+        name: (docId, pageId) => `${docId}/${pageId}.rm`,
+        read: (entry) => this.raw.getRm(entry),
+        write: (fileName, page) => this.raw.putRm(fileName, page),
+    };
+    #highlightPageFile = {
+        name: (docId, pageId) => `${docId}.highlights/${pageId}.json`,
+        read: (entry) => this.raw.getHighlights(entry),
+        write: (fileName, highlights) => this.raw.putHighlights(fileName, highlights),
+    };
+    #pageMetadataFile = {
+        name: (docId, pageId) => `${docId}/${pageId}-metadata.json`,
+        read: (entry) => this.raw.getPageMetadata(entry),
+        write: (fileName, meta) => this.raw.putPageMetadata(fileName, meta),
+    };
+    async #getPageFile(ref, pageId, file) {
+        const { id } = ref;
+        const { entries } = await this.raw.getEntries(ref);
+        const content = await this.getContent(ref);
+        if (!pageOrder(content).includes(pageId)) {
+            throw new Error(`document ${id} has no page ${pageId}`);
+        }
+        const entry = entries.find((ent) => ent.id === file.name(id, pageId));
+        if (entry === undefined) {
+            return undefined;
+        }
+        else {
+            return await file.read(entry);
+        }
+    }
+    async #getPageFiles(ref, file) {
+        const { id } = ref;
+        const { entries } = await this.raw.getEntries(ref);
+        const content = await this.getContent(ref);
+        const byName = new Map(entries.map((entry) => [entry.id, entry]));
+        const found = pageOrder(content)
+            .map((pageId) => [pageId, byName.get(file.name(id, pageId))])
+            .filter((pair) => pair[1] !== undefined);
+        const parsed = await Promise.all(found.map(([, entry]) => file.read(entry)));
+        return new Map(found.map(([pageId], index) => [pageId, parsed[index]]));
+    }
+    async #putPageFilesRaw(ref, pages, file, schemaVersion) {
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            const { id, hash } = ref;
+            const { entries } = await this.raw.getEntries(ref);
+            const contentEntry = entries.find((ent) => ent.id.endsWith(".content"));
+            if (contentEntry === undefined) {
+                throw new Error(`couldn't find contents for hash ${hash}`);
+            }
+            const content = await this.raw.getContent(contentEntry);
+            const order = new Set(pageOrder(content));
+            for (const pageId of pages.keys()) {
+                if (!order.has(pageId)) {
+                    throw new Error(`document ${id} has no page ${pageId}`);
+                }
+            }
+            const uploads = __addDisposableResource(env_3, new AsyncDisposableStack(), true);
+            const written = await Promise.all([...pages].map(([pageId, value]) => file.write(file.name(id, pageId), value)));
+            for (const pageEntry of written) {
+                uploads.use(pageEntry);
+                const pageInd = entries.findIndex((ent) => ent.id === pageEntry.id);
+                if (pageInd === -1) {
+                    entries.push(pageEntry);
+                }
+                else {
+                    entries[pageInd] = pageEntry;
+                }
+            }
+            return await this.raw.putEntries(id, entries, schemaVersion);
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            const result_3 = __disposeResources(env_3);
+            if (result_3)
+                await result_3;
+        }
+    }
+    async #putPageFiles(ref, pages, file, refresh) {
+        if (pages.size === 0) {
+            return ref;
+        }
+        else {
+            return await this.#editEntry(ref, refresh, (item, schemaVersion) => this.#putPageFilesRaw(item, pages, file, schemaVersion));
+        }
+    }
     /**
      * get a single page's parsed reMarkable lines (`.rm`) drawing
      *
@@ -537,22 +693,7 @@ class Remarkable {
      * @throws if `pageId` is not a page of the document
      */
     async getRmPage(ref, pageId) {
-        const { id, hash } = ref;
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
-        const content = await this.getContent(ref);
-        if (!pageOrder(content).includes(pageId)) {
-            throw new Error(`document ${id} has no page ${pageId}`);
-        }
-        const entry = entries.find((ent) => ent.id === `${id}/${pageId}.rm`);
-        if (entry === undefined) {
-            return undefined;
-        }
-        else {
-            return await this.raw.getRm(entry);
-        }
+        return await this.#getPageFile(ref, pageId, this.#rmPageFile);
     }
     /**
      * get every drawn page of a document, parsed, keyed by page id
@@ -566,18 +707,243 @@ class Remarkable {
      * @returns the drawn pages, keyed by page id, in document order
      */
     async getRmPages(ref) {
-        const { id, hash } = ref;
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
+        return await this.#getPageFiles(ref, this.#rmPageFile);
+    }
+    /**
+     * write a single page's reMarkable lines (`.rm`) drawing
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @param page - the drawing to write, replacing any already there
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if `pageId` is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    async putRmPage(ref, pageId, page, refresh = false) {
+        return await this.putRmPages(ref, new Map([[pageId, page]]), refresh);
+    }
+    /**
+     * write several pages' reMarkable lines (`.rm`) drawings in one commit
+     *
+     * @param ref - a reference to the document
+     * @param pages - the drawings to write, keyed by page id, replacing any
+     *     already on those pages and leaving every other page alone
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if any key is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    async putRmPages(ref, pages, refresh = false) {
+        return await this.#putPageFiles(ref, pages, this.#rmPageFile, refresh);
+    }
+    /**
+     * get a single page's text highlights
+     *
+     * These are separate from the highlighter strokes drawn in a `.rm` scene.
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @returns the page's highlights, or `undefined` if the page has none
+     * @throws if `pageId` is not a page of the document
+     */
+    async getHighlights(ref, pageId) {
+        return await this.#getPageFile(ref, pageId, this.#highlightPageFile);
+    }
+    /**
+     * get every highlighted page of a document, keyed by page id
+     *
+     * @param ref - a reference to the document
+     * @returns the highlights in page order, omitting pages with none
+     */
+    async getHighlightPages(ref) {
+        return await this.#getPageFiles(ref, this.#highlightPageFile);
+    }
+    /**
+     * write a single page's text highlights, replacing any already there
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @param highlights - the highlights to write
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if `pageId` is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    async putHighlights(ref, pageId, highlights, refresh = false) {
+        return await this.putHighlightPages(ref, new Map([[pageId, highlights]]), refresh);
+    }
+    /**
+     * write several pages' text highlights in one commit
+     *
+     * @param ref - a reference to the document
+     * @param pages - the highlights to write, keyed by page id, replacing any
+     *     already on those pages and leaving every other page alone
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if any key is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    async putHighlightPages(ref, pages, refresh = false) {
+        return await this.#putPageFiles(ref, pages, this.#highlightPageFile, refresh);
+    }
+    /**
+     * get a template attached to an item as a `.template` sidecar
+     *
+     * This is distinct from a {@link TemplateEntry | `TemplateEntry`} (whose
+     * template is its `.content`); collections and documents can carry a template
+     * this way.
+     *
+     * @param ref - a reference to the item
+     * @returns the template content, or `undefined` if the item has no `.template`
+     */
+    async getTemplate(ref) {
+        const { id } = ref;
+        const { entries } = await this.raw.getEntries(ref);
+        const entry = entries.find((e) => e.id === `${id}.template`);
+        if (entry === undefined) {
+            return undefined;
+        }
+        else {
+            return await this.raw.getTemplate(entry);
+        }
+    }
+    /**
+     * attach a template to an item as a `.template` sidecar
+     *
+     * @param ref - a reference to the item
+     * @param template - the template to attach, replacing any already there
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns a reference to the updated item, with its new hash
+     */
+    async putTemplate(ref, template, refresh = false) {
+        return await this.#editEntry(ref, refresh, async (item, schemaVersion) => {
+            const env_4 = { stack: [], error: void 0, hasError: false };
+            try {
+                const { id } = item;
+                const { entries } = await this.raw.getEntries(item);
+                const templateEntry = __addDisposableResource(env_4, await this.raw.putTemplate(`${id}.template`, template), true);
+                const ind = entries.findIndex((ent) => ent.id === templateEntry.id);
+                if (ind === -1) {
+                    entries.push(templateEntry);
+                }
+                else {
+                    entries[ind] = templateEntry;
+                }
+                return await this.raw.putEntries(id, entries, schemaVersion);
+            }
+            catch (e_4) {
+                env_4.error = e_4;
+                env_4.hasError = true;
+            }
+            finally {
+                const result_4 = __disposeResources(env_4);
+                if (result_4)
+                    await result_4;
+            }
         });
-        const content = await this.getContent(ref);
-        const byName = new Map(entries.map((entry) => [entry.id, entry]));
-        const drawn = pageOrder(content)
-            .map((pageId) => [pageId, byName.get(`${id}/${pageId}.rm`)])
-            .filter((pair) => pair[1] !== undefined);
-        const parsed = await Promise.all(drawn.map(([, entry]) => this.raw.getRm(entry)));
-        return new Map(drawn.map(([pageId], index) => [pageId, parsed[index]]));
+    }
+    /**
+     * get a document's per-page template names
+     *
+     * The `.pagedata` file lists one template name per page, in page order (an
+     * empty string for a page with no template).
+     *
+     * @param ref - a reference to the document
+     * @returns the per-page template names, or `undefined` if the document has
+     *     no `.pagedata`
+     */
+    async getPagedata(ref) {
+        const { id } = ref;
+        const { entries } = await this.raw.getEntries(ref);
+        const entry = entries.find((e) => e.id === `${id}.pagedata`);
+        if (entry === undefined) {
+            return undefined;
+        }
+        else {
+            const lines = (await this.raw.getText(entry)).split("\n");
+            if (lines.at(-1) === "")
+                lines.pop();
+            return lines;
+        }
+    }
+    /**
+     * set a document's per-page template names
+     *
+     * @param ref - a reference to the document
+     * @param templates - one template name per page, in page order, an empty
+     *     string for a page with no template
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns a reference to the updated document, with its new hash
+     */
+    async putPagedata(ref, templates, refresh = false) {
+        return await this.#editEntry(ref, refresh, async (item, schemaVersion) => {
+            const env_5 = { stack: [], error: void 0, hasError: false };
+            try {
+                const { id } = item;
+                const { entries } = await this.raw.getEntries(item);
+                const pagedataEntry = __addDisposableResource(env_5, await this.raw.putPagedata(`${id}.pagedata`, templates), true);
+                const ind = entries.findIndex((ent) => ent.id === pagedataEntry.id);
+                if (ind === -1) {
+                    entries.push(pagedataEntry);
+                }
+                else {
+                    entries[ind] = pagedataEntry;
+                }
+                return await this.raw.putEntries(id, entries, schemaVersion);
+            }
+            catch (e_5) {
+                env_5.error = e_5;
+                env_5.hasError = true;
+            }
+            finally {
+                const result_5 = __disposeResources(env_5);
+                if (result_5)
+                    await result_5;
+            }
+        });
+    }
+    /**
+     * get a single page's layer metadata
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @returns the page's layer metadata, or `undefined` if the page has none
+     * @throws if `pageId` is not a page of the document
+     */
+    async getPageMetadata(ref, pageId) {
+        return await this.#getPageFile(ref, pageId, this.#pageMetadataFile);
+    }
+    /**
+     * get every page's layer metadata, keyed by page id
+     *
+     * @param ref - a reference to the document
+     * @returns the layer metadata in page order, omitting pages with none
+     */
+    async getPageMetadataPages(ref) {
+        return await this.#getPageFiles(ref, this.#pageMetadataFile);
+    }
+    /**
+     * write a single page's layer metadata, replacing any already there
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @param meta - the layer metadata to write
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if `pageId` is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    async putPageMetadata(ref, pageId, meta, refresh = false) {
+        return await this.putPageMetadataPages(ref, new Map([[pageId, meta]]), refresh);
+    }
+    /**
+     * write several pages' layer metadata in one commit
+     *
+     * @param ref - a reference to the document
+     * @param pages - the layer metadata to write, keyed by page id, replacing any
+     *     already on those pages and leaving every other page alone
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if any key is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    async putPageMetadataPages(ref, pages, refresh = false) {
+        return await this.#putPageFiles(ref, pages, this.#pageMetadataFile, refresh);
     }
     /**
      * get a document's entire contents as a zip archive
@@ -591,11 +957,8 @@ class Remarkable {
      *
      * @param ref - a reference to the document (e.g. from `listItems`)
      */
-    async getDocumentArchive({ id, hash }) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
+    async getDocumentArchive(ref) {
+        const { entries } = await this.raw.getEntries(ref);
         const zip = new JSZip();
         for (const entry of entries) {
             // TODO if this is .metadata we might want to assert type === "DocumentType"
@@ -610,16 +973,16 @@ class Remarkable {
      * as a blob, and commits a new document into the root.
      *
      * @remarks
-     * This is an experimental feature. By default a fresh document id is generated
-     * so re-uploading to the same account doesn't collide with the original; pass
-     * {@link PutDocumentOptions.id | `id`} to keep the original id. Like the other
-     * low-level puts, this may throw a {@link GenerationError | `GenerationError`}
-     * if the generation is stale, requiring a retry.
+     * This is an experimental feature. A fresh document id is generated, so
+     * re-uploading to the same account doesn't collide with the original. Like
+     * the other low-level puts, this may throw a
+     * {@link GenerationError | `GenerationError`} if the generation is stale,
+     * requiring a retry.
      *
      * @param buffer - the archive bytes, as returned by `getDocumentArchive`
-     * @param options - overrides for parent, visible name, and id
+     * @param options - overrides for parent and visible name
      */
-    async putDocumentArchive(buffer, { refresh = false, parent, visibleName, id: keepId, } = {}) {
+    async putDocumentArchive(buffer, { refresh = false, parent, visibleName } = {}) {
         if (parent !== undefined && parent && !idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
@@ -633,7 +996,7 @@ class Remarkable {
         if (oldId.includes("/")) {
             throw new Error(`unexpected nested .metadata path '${metaPath}'`);
         }
-        const newId = keepId ?? uuid4();
+        const newId = uuid4();
         // rewrite the old document id prefix on every archived file to the new id,
         // patching the .metadata as we pass it (parent/name/lastModified). the
         // blobs don't depend on the generation, so upload the rewritten files and
@@ -659,9 +1022,27 @@ class Remarkable {
             }
             return this.raw.putFile(newPath, bytes);
         }));
-        const fileEntries = fileUploads.map(([entry]) => entry);
-        const [docEntry, uploadDoc] = await this.raw.putEntries(newId, fileEntries, schemaVersion);
-        await Promise.all([...fileUploads.map(([, upload]) => upload), uploadDoc]);
+        let docEntry;
+        {
+            const env_6 = { stack: [], error: void 0, hasError: false };
+            try {
+                const uploads = __addDisposableResource(env_6, new AsyncDisposableStack(), true);
+                for (const entry of fileUploads) {
+                    uploads.use(entry);
+                }
+                const indexEntry = __addDisposableResource(env_6, await this.raw.putEntries(newId, fileUploads, schemaVersion), true);
+                docEntry = indexEntry;
+            }
+            catch (e_6) {
+                env_6.error = e_6;
+                env_6.hasError = true;
+            }
+            finally {
+                const result_6 = __disposeResources(env_6);
+                if (result_6)
+                    await result_6;
+            }
+        }
         await this.#commit(docEntry);
         return { id: newId, hash: docEntry.hash };
     }
@@ -715,24 +1096,35 @@ class Remarkable {
         // themselves don't depend on the generation, so upload them once and let
         // #commit retry only the root merge
         const [, , schemaVersion] = await this.#getRootHash(refresh);
-        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata], [pagedataEntry, uploadPagedata], [fileEntry, uploadFile],] = await Promise.all([
-            this.raw.putContent(`${id}.content`, content),
-            this.raw.putMetadata(`${id}.metadata`, metadata),
-            this.raw.putText(`${id}.pagedata`, "\n"),
-            this.raw.putFile(`${id}.${fileType}`, buffer),
-        ]);
-        const [collectionEntry, uploadCollection] = await this.raw.putEntries(id, [contentEntry, metadataEntry, pagedataEntry, fileEntry], schemaVersion);
         // TODO we could return a full entry here, but we should probably decide
         // what that should be, e.g. we could return more fields than the standard
         // entry. Same for putFolder
         // TODO we should also decide if the api should take hashes or ids...
-        await Promise.all([
-            uploadContent,
-            uploadMetadata,
-            uploadPagedata,
-            uploadFile,
-            uploadCollection,
-        ]);
+        let collectionEntry;
+        {
+            const env_7 = { stack: [], error: void 0, hasError: false };
+            try {
+                const contentReq = this.raw.putContent(`${id}.content`, content);
+                const metadataReq = this.raw.putMetadata(`${id}.metadata`, metadata);
+                const pagedataReq = this.raw.putFile(`${id}.pagedata`, new TextEncoder().encode("\n"));
+                const fileReq = this.raw.putFile(`${id}.${fileType}`, buffer);
+                const contentEntry = __addDisposableResource(env_7, await contentReq, true);
+                const metadataEntry = __addDisposableResource(env_7, await metadataReq, true);
+                const pagedataEntry = __addDisposableResource(env_7, await pagedataReq, true);
+                const fileEntry = __addDisposableResource(env_7, await fileReq, true);
+                const indexEntry = __addDisposableResource(env_7, await this.raw.putEntries(id, [contentEntry, metadataEntry, pagedataEntry, fileEntry], schemaVersion), true);
+                collectionEntry = indexEntry;
+            }
+            catch (e_7) {
+                env_7.error = e_7;
+                env_7.hasError = true;
+            }
+            finally {
+                const result_7 = __disposeResources(env_7);
+                if (result_7)
+                    await result_7;
+            }
+        }
         await this.#commit(collectionEntry);
         return { id, hash: collectionEntry.hash };
     }
@@ -818,12 +1210,27 @@ class Remarkable {
         // the blobs don't depend on the generation, so upload them once and let
         // #commit retry only the root merge
         const [, , schemaVersion] = await this.#getRootHash(refresh);
-        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata]] = await Promise.all([
-            this.raw.putContent(`${id}.content`, content),
-            this.raw.putMetadata(`${id}.metadata`, metadata),
-        ]);
-        const [collectionEntry, uploadCollection] = await this.raw.putEntries(id, [contentEntry, metadataEntry], schemaVersion);
-        await Promise.all([uploadContent, uploadMetadata, uploadCollection]);
+        let collectionEntry;
+        {
+            const env_8 = { stack: [], error: void 0, hasError: false };
+            try {
+                const contentReq = this.raw.putContent(`${id}.content`, content);
+                const metadataReq = this.raw.putMetadata(`${id}.metadata`, metadata);
+                const contentEntry = __addDisposableResource(env_8, await contentReq, true);
+                const metadataEntry = __addDisposableResource(env_8, await metadataReq, true);
+                const indexEntry = __addDisposableResource(env_8, await this.raw.putEntries(id, [contentEntry, metadataEntry], schemaVersion), true);
+                collectionEntry = indexEntry;
+            }
+            catch (e_8) {
+                env_8.error = e_8;
+                env_8.hasError = true;
+            }
+            finally {
+                const result_8 = __disposeResources(env_8);
+                if (result_8)
+                    await result_8;
+            }
+        }
         await this.#commit(collectionEntry);
         return { id, hash: collectionEntry.hash };
     }
@@ -866,49 +1273,87 @@ class Remarkable {
         return await this.raw.uploadFile(visibleName, new Uint8Array(0), "folder");
     }
     /** edit just a content entry */
-    async #editContentRaw(id, hash, update, schemaVersion) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
-        const contInd = entries.findIndex((ent) => ent.id.endsWith(".content"));
-        const contEntry = entries[contInd];
-        if (contEntry === undefined) {
-            throw new Error("internal error: couldn't find content in entry hash");
+    async #editContentRaw(ref, update, schemaVersion) {
+        const env_9 = { stack: [], error: void 0, hasError: false };
+        try {
+            const { id } = ref;
+            const { entries } = await this.raw.getEntries(ref);
+            const contInd = entries.findIndex((ent) => ent.id.endsWith(".content"));
+            const contEntry = entries[contInd];
+            if (contEntry === undefined) {
+                throw new Error("internal error: couldn't find content in entry hash");
+            }
+            const cont = await this.raw.getContent(contEntry);
+            Object.assign(cont, update);
+            const newContEntry = __addDisposableResource(env_9, await this.raw.putContent(contEntry.id, cont), true);
+            entries[contInd] = newContEntry;
+            return await this.raw.putEntries(id, entries, schemaVersion);
+        }
+        catch (e_9) {
+            env_9.error = e_9;
+            env_9.hasError = true;
+        }
+        finally {
+            const result_9 = __disposeResources(env_9);
+            if (result_9)
+                await result_9;
         }
-        const cont = await this.raw.getContent(contEntry);
-        Object.assign(cont, update);
-        const [newContEntry, uploadCont] = await this.raw.putContent(contEntry.id, cont);
-        entries[contInd] = newContEntry;
-        const [result, uploadEntries] = await this.raw.putEntries(id, entries, schemaVersion);
-        const upload = Promise.all([uploadCont, uploadEntries]);
-        return [result, upload];
     }
-    /** fully sync a content edit */
-    async #editContent(hash, update, expectedType, refresh) {
+    /**
+     * rewrite one item's files and splice the result into the root
+     *
+     * `edit` receives a ref to the item and the schema version, and returns its
+     * new entry plus a promise for the uploads. Everything generation-dependent
+     * lives here, so writers only describe the file change.
+     */
+    async #editEntry(ref, refresh, edit) {
         return await this.#withRetry(async () => {
             const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
             const { entries } = await this.raw.getEntries({
-                id: ROOT_SCHEMA,
+                id: ROOT_LIST,
                 hash: rootHash,
             });
-            const hashInd = entries.findIndex((ent) => ent.hash === hash);
+            const hashInd = entries.findIndex((ent) => ent.id === ref.id && ent.hash === ref.hash);
             const hashEnt = entries[hashInd];
             if (hashEnt === undefined) {
-                throw new HashNotFoundError(hash);
+                throw new HashNotFoundError(ref.hash);
             }
-            const [[newEnt, uploadEnt], meta] = await Promise.all([
-                this.#editContentRaw(hashEnt.id, hash, update, schemaVersion),
-                this.getMetadata(hashEnt),
+            let newRoot;
+            let newHash;
+            {
+                const env_10 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const newEnt = __addDisposableResource(env_10, await edit({ id: hashEnt.id, hash: ref.hash }, schemaVersion), true);
+                    entries[hashInd] = newEnt;
+                    const rootEntry = __addDisposableResource(env_10, await this.raw.putEntries(ROOT_LIST, entries, 4), true);
+                    newRoot = rootEntry.hash;
+                    newHash = newEnt.hash;
+                }
+                catch (e_10) {
+                    env_10.error = e_10;
+                    env_10.hasError = true;
+                }
+                finally {
+                    const result_10 = __disposeResources(env_10);
+                    if (result_10)
+                        await result_10;
+                }
+            }
+            await this.#putRootHash(newRoot, generation);
+            return { id: hashEnt.id, hash: newHash };
+        });
+    }
+    /** fully sync a content edit */
+    async #editContent(ref, update, expectedType, refresh) {
+        return await this.#editEntry(ref, refresh, async (item, schemaVersion) => {
+            const [newEnt, meta] = await Promise.all([
+                this.#editContentRaw(item, update, schemaVersion),
+                this.getMetadata(item),
             ]);
             if (meta.type !== expectedType) {
-                throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${hash}`);
+                throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${item.hash}`);
             }
-            entries[hashInd] = newEnt;
-            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, entries, 4);
-            await Promise.all([uploadEnt, uploadRoot]);
-            await this.#putRootHash(rootEntry.hash, generation);
-            return { id: hashEnt.id, hash: newEnt.hash };
+            return newEnt;
         });
     }
     /**
@@ -924,7 +1369,7 @@ class Remarkable {
      * @returns a reference to the updated entry, with its new hash
      */
     async updateDocument(ref, content, refresh = false) {
-        return await this.#editContent(ref.hash, content, "DocumentType", refresh);
+        return await this.#editContent(ref, content, "DocumentType", refresh);
     }
     /**
      * update content metadata for a collection
@@ -939,7 +1384,7 @@ class Remarkable {
      * @returns a reference to the updated entry, with its new hash
      */
     async updateCollection(ref, content, refresh = false) {
-        return await this.#editContent(ref.hash, content, "CollectionType", refresh);
+        return await this.#editContent(ref, content, "CollectionType", refresh);
     }
     /**
      * update content metadata for a template
@@ -954,47 +1399,38 @@ class Remarkable {
      * @returns a reference to the updated entry, with its new hash
      */
     async updateTemplate(ref, content, refresh = false) {
-        return await this.#editContent(ref.hash, content, "TemplateType", refresh);
+        return await this.#editContent(ref, content, "TemplateType", refresh);
     }
-    async #editMetaRaw(id, hash, update, schemaVersion) {
-        const { entries } = await this.raw.getEntries({
-            id: `${id}.docSchema`,
-            hash,
-        });
-        const metaInd = entries.findIndex((ent) => ent.id.endsWith(".metadata"));
-        const metaEntry = entries[metaInd];
-        if (metaEntry === undefined) {
-            throw new Error("internal error: couldn't find metadata in entry hash");
-        }
-        const meta = await this.raw.getMetadata(metaEntry);
-        Object.assign(meta, update);
-        meta.version = (meta.version ?? 0) + 1;
-        meta.metadatamodified = true;
-        const [newMetaEntry, uploadMeta] = await this.raw.putMetadata(metaEntry.id, meta);
-        entries[metaInd] = newMetaEntry;
-        const [result, uploadEntries] = await this.raw.putEntries(id, entries, schemaVersion);
-        const upload = Promise.all([uploadMeta, uploadEntries]);
-        return [result, upload];
-    }
-    async #editMeta(hash, update, refresh = false) {
-        return await this.#withRetry(async () => {
-            const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-            const { entries } = await this.raw.getEntries({
-                id: ROOT_SCHEMA,
-                hash: rootHash,
-            });
-            const hashInd = entries.findIndex((ent) => ent.hash === hash);
-            const hashEnt = entries[hashInd];
-            if (hashEnt === undefined) {
-                throw new HashNotFoundError(hash);
+    async #editMetaRaw(ref, update, schemaVersion) {
+        const env_11 = { stack: [], error: void 0, hasError: false };
+        try {
+            const { id } = ref;
+            const { entries } = await this.raw.getEntries(ref);
+            const metaInd = entries.findIndex((ent) => ent.id.endsWith(".metadata"));
+            const metaEntry = entries[metaInd];
+            if (metaEntry === undefined) {
+                throw new Error("internal error: couldn't find metadata in entry hash");
             }
-            const [newEnt, uploadEnt] = await this.#editMetaRaw(hashEnt.id, hash, update, schemaVersion);
-            entries[hashInd] = newEnt;
-            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, entries, 4);
-            await Promise.all([uploadEnt, uploadRoot]);
-            await this.#putRootHash(rootEntry.hash, generation);
-            return { id: hashEnt.id, hash: newEnt.hash };
-        });
+            const meta = await this.raw.getMetadata(metaEntry);
+            Object.assign(meta, update);
+            meta.version = (meta.version ?? 0) + 1;
+            meta.metadatamodified = true;
+            const newMetaEntry = __addDisposableResource(env_11, await this.raw.putMetadata(metaEntry.id, meta), true);
+            entries[metaInd] = newMetaEntry;
+            return await this.raw.putEntries(id, entries, schemaVersion);
+        }
+        catch (e_11) {
+            env_11.error = e_11;
+            env_11.hasError = true;
+        }
+        finally {
+            const result_11 = __disposeResources(env_11);
+            if (result_11)
+                await result_11;
+        }
+    }
+    async #editMeta(ref, update, refresh = false) {
+        return await this.#editEntry(ref, refresh, (item, schemaVersion) => this.#editMetaRaw(item, update, schemaVersion));
     }
     /**
      * move an entry
@@ -1012,7 +1448,7 @@ class Remarkable {
         if (!idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
-        return await this.#editMeta(ref.hash, { parent }, refresh);
+        return await this.#editMeta(ref, { parent }, refresh);
     }
     /**
      * delete an entry
@@ -1039,7 +1475,7 @@ class Remarkable {
      * @returns a reference to the renamed entry, with its new hash
      */
     async rename(ref, visibleName, refresh = false) {
-        return await this.#editMeta(ref.hash, { visibleName }, refresh);
+        return await this.#editMeta(ref, { visibleName }, refresh);
     }
     /**
      * star or unstar an entry
@@ -1053,7 +1489,7 @@ class Remarkable {
      * @returns a reference to the updated entry, with its new hash
      */
     async star(ref, starred, refresh = false) {
-        return await this.#editMeta(ref.hash, { pinned: starred }, refresh);
+        return await this.#editMeta(ref, { pinned: starred }, refresh);
     }
     /**
      * move many entries
@@ -1074,27 +1510,56 @@ class Remarkable {
         return await this.#withRetry(async () => {
             const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
             const { entries } = await this.raw.getEntries({
-                id: ROOT_SCHEMA,
+                id: ROOT_LIST,
                 hash: rootHash,
             });
-            const hashSet = new Set(refs.map((ref) => ref.hash));
+            const wanted = new Set(refs.map((ref) => `${ref.id}\0${ref.hash}`));
+            const found = new Set();
             const toUpdate = [];
             const newEntries = [];
             for (const entry of entries) {
-                const part = hashSet.has(entry.hash) ? toUpdate : newEntries;
-                part.push(entry);
+                const key = `${entry.id}\0${entry.hash}`;
+                if (wanted.has(key)) {
+                    toUpdate.push(entry);
+                    found.add(key);
+                }
+                else {
+                    newEntries.push(entry);
+                }
+            }
+            for (const ref of refs) {
+                if (!found.has(`${ref.id}\0${ref.hash}`)) {
+                    throw new HashNotFoundError(ref.hash);
+                }
             }
-            const resolved = await Promise.all(toUpdate.map(({ id, hash }) => this.#editMetaRaw(id, hash, { parent }, schemaVersion)));
-            const uploads = [];
+            const resolved = await Promise.all(toUpdate.map((entry) => this.#editMetaRaw(entry, { parent }, schemaVersion)));
             const result = [];
-            for (const [i, [newEnt, upload]] of resolved.entries()) {
+            for (const [i, newEnt] of resolved.entries()) {
                 newEntries.push(newEnt);
-                uploads.push(upload);
                 result.push({ id: toUpdate[i].id, hash: newEnt.hash });
             }
-            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, newEntries, 4);
-            await Promise.all([Promise.all(uploads), uploadRoot]);
-            await this.#putRootHash(rootEntry.hash, generation);
+            let newRoot;
+            {
+                const env_12 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const docs = __addDisposableResource(env_12, new AsyncDisposableStack(), true);
+                    for (const entry of resolved) {
+                        docs.use(entry);
+                    }
+                    const rootEntry = __addDisposableResource(env_12, await this.raw.putEntries(ROOT_LIST, newEntries, 4), true);
+                    newRoot = rootEntry.hash;
+                }
+                catch (e_12) {
+                    env_12.error = e_12;
+                    env_12.hasError = true;
+                }
+                finally {
+                    const result_12 = __disposeResources(env_12);
+                    if (result_12)
+                        await result_12;
+                }
+            }
+            await this.#putRootHash(newRoot, generation);
             return result;
         });
     }
@@ -1145,15 +1610,15 @@ class Remarkable {
         // should only go one step) to track all hashes encountered
         // NOTE that we could increase the cache in this process, or it's possible
         // for other calls to increase the cache with misc values.
-        const base = await this.raw.getEntries({ id: ROOT_SCHEMA, hash: rootHash });
+        const base = await this.raw.getEntries({ id: ROOT_LIST, hash: rootHash });
         let entries = [base.entries];
         let nextEntries = [];
         while (entries.length) {
             for (const entryList of entries) {
-                for (const { hash, subfiles, id } of entryList) {
-                    toDelete.delete(hash);
-                    if (subfiles > 0) {
-                        nextEntries.push(this.raw.getEntries({ id: `${id}.docSchema`, hash }));
+                for (const entry of entryList) {
+                    toDelete.delete(entry.hash);
+                    if (entry.subfiles > 0) {
+                        nextEntries.push(this.raw.getEntries(entry));
                     }
                 }
             }
@@ -1175,7 +1640,46 @@ class Remarkable {
         this.raw.clearCache();
     }
 }
-const cached = z.record(z.string(), z.string().nullable());
+/** the default {@link RemarkableSessionOptions.maxCachedBytes} */
+const MAX_CACHED_BYTES = 1024 * 1024;
+const cacheEntries = z.record(z.string(), z.string().nullable());
+/**
+ * a dumped cache, either the tagged envelope or the original bare mapping
+ *
+ * The original format had no version, so its absence marks untagged text.
+ */
+const cacheDump = z
+    .object({
+    version: z.literal(CACHE_VERSION),
+    entries: cacheEntries,
+})
+    .or(cacheEntries.transform((entries) => ({ version: undefined, entries })));
+/** decode a dumped cache into the byte map the api holds */
+function decodeCache(dumped) {
+    const parsed = cacheDump.safeParse(dumped);
+    if (!parsed.success) {
+        throw new Error(`cache was neither a version ${CACHE_VERSION} dump nor the original mapping of hashes to text. Either construct the api without a cache, or fix its format.`);
+    }
+    const { version, entries } = parsed.data;
+    const enc = new TextEncoder();
+    return Object.entries(entries).map(([hash, value]) => {
+        if (value === null) {
+            return [hash, null];
+        }
+        else if (version === undefined) {
+            return [hash, enc.encode(value)];
+        }
+        else if (value.startsWith(BYTES_PREFIX)) {
+            return [hash, Uint8Array.fromBase64(value.slice(1))];
+        }
+        else if (value.startsWith(TEXT_PREFIX)) {
+            return [hash, enc.encode(value.slice(1))];
+        }
+        else {
+            throw new Error(`cache entry ${hash} wasn't tagged '${TEXT_PREFIX}' or '${BYTES_PREFIX}'. Either construct the api without a cache, or fix its format.`);
+        }
+    });
+}
 /**
  * Exchange a device token for a session token.
  *
@@ -1204,17 +1708,12 @@ export async function auth(deviceToken, { authHost = AUTH_HOST } = {}) {
  * @param sessionToken - the session token used for authorization
  * @returns an api instance
  */
-export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_HOST, cache, maxCacheSize = Infinity, maxGenerationRetries = 10, maxTransientRetries = 3, } = {}) {
-    const initCache = JSON.parse(cache ?? "{}");
-    const parsedCache = cached.safeParse(initCache);
-    if (parsedCache.success) {
-        const entries = Object.entries(parsedCache.data);
-        const cacheMap = maxCacheSize === Infinity
-            ? new Map(entries)
-            : new LruCache(maxCacheSize, entries);
-        return new Remarkable(sessionToken, rawHost, uploadHost, cacheMap, maxGenerationRetries, maxTransientRetries);
-    }
-    throw new Error("cache was not a valid cache (json string mapping); your cache must be corrupted somehow. Either initialize remarkable without a cache, or fix its format.");
+export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_HOST, cache, maxCacheSize = Infinity, maxCachedBytes = MAX_CACHED_BYTES, maxGenerationRetries = 10, maxTransientRetries = 3, } = {}) {
+    const entries = decodeCache(JSON.parse(cache ?? "{}"));
+    const cacheMap = maxCacheSize === Infinity
+        ? new Map(entries)
+        : new LruCache(maxCacheSize, entries);
+    return new Remarkable(sessionToken, rawHost, uploadHost, cacheMap, maxGenerationRetries, maxTransientRetries, maxCachedBytes);
 }
 /**
  * create an instance of the api
@@ -1227,14 +1726,9 @@ export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_
  * @returns an api instance
  */
 export async function remarkable(deviceToken, options = {}) {
-    const { authHost, rawHost, uploadHost, cache, maxCacheSize, maxGenerationRetries, maxTransientRetries, } = options ?? {};
+    // forward everything but the auth option, so a new session option can't be
+    // dropped here by omission
+    const { authHost, ...sessionOptions } = options ?? {};
     const sessionToken = await auth(deviceToken, { authHost });
-    return session(sessionToken, {
-        rawHost,
-        uploadHost,
-        cache,
-        maxCacheSize,
-        maxGenerationRetries,
-        maxTransientRetries,
-    });
+    return session(sessionToken, sessionOptions);
 }