@kitschpatrol/tldraw-cli 4.3.2 → 4.4.1

package/bin/cli.js

@@ -17247,81 +17247,13 @@ var TldrawController = class {
   async close() {
     if (!this.browser)
       throw new Error("Controller not started");
+    const pages = await this.browser.pages();
+    await Promise.all(pages.map(async (page) => page.close()));
     await this.browser.close();
     log_default.info("Stopped controller");
   }
-  // Public method doesn't expose pageFrame
+  // eslint-disable-next-line complexity
   async download(options) {
-    return this._download(void 0, options);
-  }
-  async downloadFrame(frameNameOrId, options) {
-    return this.downloadFrames([frameNameOrId], options);
-  }
-  async downloadFrames(frameNamesOrIds, options) {
-    const validPageFrames = [];
-    for (const frame of frameNamesOrIds) {
-      const pageFrame = await this.getPageFrameWithNameOrId(frame);
-      if (pageFrame === void 0) {
-        log_default.warn(`Frame "${frame}" not found, skipping`);
-      } else {
-        validPageFrames.push(pageFrame);
-      }
-    }
-    if (validPageFrames.length === 0) {
-      throw new Error("No valid frames found");
-    }
-    const validFrameNames = validPageFrames.map((frame) => slugify(frame.name));
-    const isFrameNameCollision = validFrameNames.length !== new Set(validFrameNames).size;
-    if (isFrameNameCollision) {
-      log_default.warn(
-        "Frame names are not unique, including frame IDs in the output filenames to avoid collisions"
-      );
-    }
-    const outputAccumulator = [];
-    for (const frame of validPageFrames) {
-      const frameSuffix = isFrameNameCollision ? `-${frame.id.replace("shape:", "")}` : "";
-      outputAccumulator.push(
-        ...await this._download(frame, {
-          ...options,
-          name: `${options.name}${frameSuffix}`
-        })
-      );
-    }
-    return outputAccumulator;
-  }
-  async downloadAllFrames(options) {
-    const pageFrames = await this.getPageFrames();
-    const frameNamesOrIds = pageFrames.map((f) => f.id);
-    return this.downloadFrames(frameNamesOrIds, options);
-  }
-  async loadFile(filePath) {
-    if (!this.page)
-      throw new Error("Controller not started");
-    if (this.isLocal)
-      throw new Error(
-        "File loading is only supported for remote tldraw.com instances. See tldraw-open.ts for local file loading approach."
-      );
-    await this.closeMenus();
-    await this.page.evaluate(`userPreferences.showFileOpenWarning.set(false);`);
-    log_default.info(`Uploading local file to tldraw.com: ${filePath}`);
-    const tldrFile = await fs.readFile(filePath, "utf8");
-    await this.page.evaluate(set_tldr_iife_default);
-    await this.page.evaluate(`window.setTldr(${tldrFile})`);
-  }
-  async getShareUrl() {
-    if (!this.page)
-      throw new Error("Controller not started");
-    if (this.isLocal)
-      throw new Error("Share URLs are only supported for remote tldraw.com instances.");
-    await this.closeMenus();
-    await this.clickButtonTitles(["Menu", "File", "Share this project"]);
-    await this.page.waitForNavigation({ waitUntil: "networkidle0" });
-    const shareUrl = new URL(this.page.url());
-    shareUrl.search = "";
-    return shareUrl.href;
-  }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
-  async _download(pageFrame, options) {
     if (!this.page)
       throw new Error("Controller not started");
     if (this.isEmpty)
@@ -17329,10 +17261,14 @@ var TldrawController = class {
     if (options.stripStyle && options.format !== "svg")
       log_default.warn("--strip-style is only supported for SVG output");
     if (options.format === "tldr") {
-      if (pageFrame !== void 0)
+      if (options.frames !== void 0)
         log_default.warn(
           '--frames is not supported when exporting to "tldr", ignoring flag and exporting entire sketch file'
         );
+      if (options.pages !== void 0)
+        log_default.warn(
+          '--pages is not supported when exporting to "tldr", ignoring flag and exporting entire sketch file'
+        );
       if (options.dark !== false) {
         log_default.warn(
           '--dark is not supported when exporting to "tldr", ignoring flag and exporting sketch file'
@@ -17365,22 +17301,37 @@ var TldrawController = class {
       stripStyle = false,
       transparent = false
     } = this.stripUndefined(options);
-    let frameSuffix = "";
-    let base64String = "";
     if (format3 === "tldr") {
       await this.page.evaluate(get_tldr_iife_default);
-      base64String = await this.page.evaluate(async () => window.getTldr());
-    } else {
-      if (pageFrame === void 0) {
+      const base64String = await this.page.evaluate(async () => window.getTldr());
+      if (print) {
+        const plainString = base64ToString(base64String).replaceAll("\n", "");
+        return [plainString];
+      }
+      const outputPath = path2.resolve(untildify(path2.join(output, `${filename}.${format3}`)));
+      await fs.writeFile(outputPath, base64ToUint8Array(base64String));
+      return [outputPath];
+    }
+    await this.page.evaluate(get_image_iife_default);
+    const sketchStructure = await this.getSketchStructure();
+    const downloadPlan = this.getDownloadPlans(sketchStructure, options.pages, options.frames);
+    const outputAccumulator = [];
+    const initialPageId = await this.getCurrentPage();
+    let pageChanged = false;
+    for (const download of downloadPlan) {
+      if (download.pageId !== initialPageId) {
+        log_default.info(`Selecting sketch page "${download.pageId}"`);
+        await this.setCurrentPage(download.pageId);
+        pageChanged = true;
+      }
+      if (download.frameId === void 0) {
         await this.page.evaluate("editor.selectAll()");
       } else {
-        log_default.info(`Selecting sketch frame "${pageFrame.name}" with ID "${pageFrame.id}"`);
-        frameSuffix = `-${slugify(pageFrame.name)}`;
+        log_default.info(`Selecting sketch frame "${download.frameId}"`);
         await this.page.evaluate("editor.selectNone()");
-        await this.page.evaluate(`editor.select('${pageFrame.id}')`);
+        await this.page.evaluate(`editor.select('${download.frameId}')`);
       }
-      await this.page.evaluate(get_image_iife_default);
-      base64String = await this.page.evaluate(async (options2) => window.getImage(options2), {
+      let base64String = await this.page.evaluate(async (options2) => window.getImage(options2), {
         background: transparent === void 0 ? void 0 : !transparent,
         darkMode: dark,
         format: format3,
@@ -17390,19 +17341,51 @@ var TldrawController = class {
       if (stripStyle && format3 === "svg") {
         base64String = stringToBase64(this.stripStyleElement(base64ToString(base64String)));
       }
-    }
-    const outputPath = path2.resolve(
-      untildify(path2.join(output, `${filename}${frameSuffix}.${format3}`))
-    );
-    if (print) {
-      if (format3 === "png") {
-        return [base64String];
+      if (print) {
+        if (format3 === "png") {
+          outputAccumulator.push(base64String);
+        } else {
+          const plainString = base64ToString(base64String).replaceAll("\n", "");
+          outputAccumulator.push(plainString);
+        }
+      } else {
+        const outputPath = path2.resolve(
+          untildify(path2.join(output, `${filename}${download.fileSuffix}.${format3}`))
+        );
+        await fs.writeFile(outputPath, base64ToUint8Array(base64String));
+        outputAccumulator.push(outputPath);
       }
-      const plainString = base64ToString(base64String).replaceAll("\n", "");
-      return [plainString];
     }
-    await fs.writeFile(outputPath, base64ToUint8Array(base64String));
-    return [outputPath];
+    if (pageChanged) {
+      await this.setCurrentPage(initialPageId);
+    }
+    return outputAccumulator;
+  }
+  async loadFile(filePath) {
+    if (!this.page)
+      throw new Error("Controller not started");
+    if (this.isLocal)
+      throw new Error(
+        "File loading is only supported for remote tldraw.com instances. See tldraw-open.ts for local file loading approach."
+      );
+    await this.closeMenus();
+    await this.page.evaluate(`userPreferences.showFileOpenWarning.set(false);`);
+    log_default.info(`Uploading local file to tldraw.com: ${filePath}`);
+    const tldrFile = await fs.readFile(filePath, "utf8");
+    await this.page.evaluate(set_tldr_iife_default);
+    await this.page.evaluate(`window.setTldr(${tldrFile})`);
+  }
+  async getShareUrl() {
+    if (!this.page)
+      throw new Error("Controller not started");
+    if (this.isLocal)
+      throw new Error("Share URLs are only supported for remote tldraw.com instances.");
+    await this.closeMenus();
+    await this.clickButtonTitles(["Menu", "File", "Share this project"]);
+    await this.page.waitForNavigation({ waitUntil: "networkidle0" });
+    const shareUrl = new URL(this.page.url());
+    shareUrl.search = "";
+    return shareUrl.href;
   }
   async closeMenus() {
     if (!this.page)
@@ -17419,28 +17402,163 @@ var TldrawController = class {
       await this.page.click(`button[title="${title}"]`);
     }
   }
-  // TODO memoize...
-  async getPageFrameWithNameOrId(nameOrId) {
-    const pageFrames = await this.getPageFrames();
-    if (pageFrames.length === 0) {
-      throw new Error("No frames found");
+  // Deduplicates, verifies existence, and normalizes to ids of the style 'page:xxxx'
+  validatePages(sketch, pages) {
+    if (Array.isArray(pages)) {
+      const validPages = [];
+      for (const p of pages) {
+        const matchingPage = typeof p === "number" ? sketch[p] : sketch.find(
+          (page) => slugify(p) === slugify(page.name) || `page:${p.replace(/^page:/, "")}` === page.id
+        );
+        if (matchingPage) {
+          if (!validPages.includes(matchingPage.id)) {
+            validPages.push(matchingPage.id);
+          }
+        } else {
+          log_default.warn(`Page "${p}" not found in sketch`);
+        }
+      }
+      if (validPages.length === 0) {
+        log_default.warn("None of the requested pages were found in sketch, ignoring pages option");
+        return void 0;
+      }
+      return validPages;
+    }
+    return pages;
+  }
+  validateFrames(sketch, pages, frames) {
+    if (Array.isArray(frames)) {
+      const validSketch = sketch.filter(
+        (page, index2) => pages === void 0 || typeof pages === "boolean" && !pages && index2 === 0 || typeof pages === "boolean" && pages || Array.isArray(pages) && pages.some(
+          (p, index3) => typeof p === "number" ? index3 === p : slugify(p) === slugify(page.name) || p.replace(/^page:/, "") === page.id.replace(/^page:/, "")
+        )
+      );
+      const validFrames = [];
+      for (const f of frames) {
+        const matchingFrames = [];
+        for (const page of validSketch) {
+          const match = page.frames.find(
+            (frame) => slugify(f) === slugify(frame.name) || `shape:${f.replace(/^shape:/, "")}` === frame.id
+          );
+          if (match && !matchingFrames.includes(match.id)) {
+            matchingFrames.push(match.id);
+          }
+        }
+        if (matchingFrames.length === 0) {
+          log_default.warn(`Frame "${f}" not found in sketch`);
+        } else {
+          validFrames.push(...matchingFrames);
+        }
+        if (validFrames.length === 0) {
+          log_default.warn("None of the requested frames were found in sketch, ignoring frames option");
+          return void 0;
+        }
+      }
+      return validFrames;
     }
-    return pageFrames.find((f) => f.name === nameOrId || slugify(f.name) === nameOrId) ?? pageFrames.find(
-      (f) => f.id === (nameOrId.startsWith("shape:") ? nameOrId : `shape:${nameOrId}`)
+    return frames;
+  }
+  // eslint-disable-next-line complexity
+  getDownloadPlans(sketch, pages, frames) {
+    const validPages = this.validatePages(sketch, pages);
+    const validFrames = this.validateFrames(sketch, validPages, frames);
+    const filteredSketch = validPages === void 0 ? [sketch[0]] : typeof validPages === "boolean" && !validPages ? [sketch[0]] : sketch.filter(
+      (sketchPage) => typeof validPages === "boolean" && validPages ? true : validPages.some(
+        (p) => slugify(p) === slugify(sketchPage.name) || p.replace("page:", "") === sketchPage.id.replace("page:", "")
+      )
     );
+    for (const page of filteredSketch) {
+      page.frames = validFrames === void 0 || typeof validFrames === "boolean" && !validFrames ? [] : page.frames.filter(
+        (frame) => typeof validFrames === "boolean" && validFrames ? true : validFrames.some(
+          (f) => slugify(f) === slugify(frame.name) || f.replace("shape:", "") === frame.id.replace("shape:", "")
+        )
+      );
+    }
+    const downloadPlans = [];
+    const isPageNameCollision = new Set(filteredSketch.map((page) => slugify(page.name))).size !== filteredSketch.length;
+    if (isPageNameCollision) {
+      log_default.warn(
+        "Page names are not unique, including page IDs in the output filenames to avoid collisions"
+      );
+    }
+    for (const page of filteredSketch) {
+      const pageSuffix = validPages === void 0 || typeof validPages === "boolean" && !validPages ? void 0 : isPageNameCollision ? `${slugify(page.name)}-${page.id.replace("page:", "")}` : slugify(page.name);
+      if (page.frames.length === 0) {
+        downloadPlans.push({
+          fileSuffix: pageSuffix ?? "",
+          frameId: void 0,
+          pageId: page.id
+        });
+      } else {
+        const isFrameNameCollision = new Set(page.frames.map((frame) => slugify(frame.name))).size !== page.frames.length;
+        if (isFrameNameCollision) {
+          log_default.warn(
+            "Frame names are not unique, including frame IDs in the output filenames to avoid collisions"
+          );
+        }
+        for (const frame of page.frames) {
+          const frameSuffix = isFrameNameCollision ? [slugify(frame.name), frame.id.replace("shape:", "")].filter((value) => value !== "").join("-") : slugify(frame.name);
+          downloadPlans.push({
+            fileSuffix: [pageSuffix, frameSuffix].filter((value) => value !== void 0).join("-"),
+            frameId: frame.id,
+            pageId: page.id
+          });
+        }
+      }
+    }
+    for (const plan of downloadPlans) {
+      if (plan.fileSuffix !== "") {
+        plan.fileSuffix = `-${plan.fileSuffix}`;
+      }
+    }
+    return downloadPlans;
   }
-  // TODO memoize
-  async getPageFrames() {
+  // Structure
+  async getSketchStructure() {
+    if (!this.page)
+      throw new Error("Controller not started");
+    const document = await this.getPages();
+    for (const page of document) {
+      page.frames = await this.getPageFrames(page.id);
+    }
+    return document;
+  }
+  async getPages() {
     if (!this.page)
       throw new Error("Controller not started");
     return await this.page.evaluate(
+      `editor.getPages().map((page) => ({ id: page.id, name: page.name, frames: []}))`
+    );
+  }
+  async getPageFrames(pageId) {
+    if (!this.page)
+      throw new Error("Controller not started");
+    const initialPageId = await this.getCurrentPage();
+    if (pageId !== initialPageId) {
+      await this.setCurrentPage(pageId);
+    }
+    const frames = await this.page.evaluate(
       `editor.getCurrentPageShapes().reduce((accumulator, shape) => {
 				if (shape.type === 'frame') {
-					accumulator.push({ id: shape.id, name: shape.props.name })
+					accumulator.push({ id: shape.id, name: shape.props.name === '' ? 'Frame' : shape.props.name })
 				}
 				return accumulator
 			}, [])`
     );
+    if (pageId !== initialPageId) {
+      await this.setCurrentPage(initialPageId);
+    }
+    return frames;
+  }
+  async getCurrentPage() {
+    if (!this.page)
+      throw new Error("Controller not started");
+    return await this.page.evaluate(`editor.getCurrentPageId()`);
+  }
+  async setCurrentPage(pageId) {
+    if (!this.page)
+      throw new Error("Controller not started");
+    await this.page.evaluate(`editor.setCurrentPage("${pageId}")`);
   }
   // Helpers
   stripStyleElement(svg) {
@@ -17676,14 +17794,7 @@ async function tldrawToImage(tldrPathOrUrl, options = {}) {
   const tldrawUrl = isLocal ? tldrawServer.href : validatedPathOrUrl.href;
   const tldrawController = new TldrawController(tldrawUrl);
   await tldrawController.start();
-  let exportReport;
-  if (options.frames && typeof options.frames === "boolean") {
-    exportReport = await tldrawController.downloadAllFrames(options);
-  } else if (Array.isArray(options.frames) && options.frames.length > 0) {
-    exportReport = await tldrawController.downloadFrames(options.frames, options);
-  } else {
-    exportReport = await tldrawController.download(options);
-  }
+  const exportReport = await tldrawController.download(options);
   await tldrawController.close();
   if (isLocal)
     tldrawServer.close();
@@ -23183,7 +23294,17 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
     // value to true, and still be able to extract meaning from the
     // absence of the option
     defaultDescription: "false",
-    describe: 'Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or skip the arguments to export all frames.',
+    describe: 'Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or pass the flag without the arguments to export all frames. By default, the entire first page is exported with all frames.',
+    type: "array"
+  }).option("pages", {
+    coerce(args) {
+      return args.length === 0 ? true : args;
+    },
+    // Do not set a default value, so we can coerce --pages without a
+    // value to true, and still be able to extract meaning from the
+    // absence of the option
+    defaultDescription: "false",
+    describe: 'Export each sketch "page" as a separate image. Pass one or more page names or IDs to export specific page, or pass one or more page index numbers (from 0), or pass the flag without the arguments to export all pages. By default, only the first page is exported.',
     type: "array"
   }).option("transparent", {
     alias: "t",
@@ -23233,6 +23354,7 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
       name,
       output,
       padding,
+      pages,
       print,
       scale,
       stripStyle,
@@ -23254,6 +23376,7 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
           name: resolvedName,
           output,
           padding,
+          pages,
           print,
           scale,
           stripStyle,
@@ -23342,7 +23465,7 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
       process.exit(1);
     }
   }
-).demandCommand(1).alias("h", "help").version("version").alias("v", "version").help().wrap(process.stdout.isTTY ? Math.min(120, yargsInstance.terminalWidth()) : 0).parse();
+).demandCommand(1).alias("h", "help").version().alias("v", "version").help().wrap(process.stdout.isTTY ? Math.min(120, yargsInstance.terminalWidth()) : 0).parse();
 /*! Bundled license information:
 
 yargs-parser/build/lib/string-utils.js:

package/dist/lib/index.js

@@ -17049,81 +17049,13 @@ var TldrawController = class {
   async close() {
     if (!this.browser)
       throw new Error("Controller not started");
+    const pages = await this.browser.pages();
+    await Promise.all(pages.map(async (page) => page.close()));
     await this.browser.close();
     log_default.info("Stopped controller");
   }
-  // Public method doesn't expose pageFrame
+  // eslint-disable-next-line complexity
   async download(options) {
-    return this._download(void 0, options);
-  }
-  async downloadFrame(frameNameOrId, options) {
-    return this.downloadFrames([frameNameOrId], options);
-  }
-  async downloadFrames(frameNamesOrIds, options) {
-    const validPageFrames = [];
-    for (const frame of frameNamesOrIds) {
-      const pageFrame = await this.getPageFrameWithNameOrId(frame);
-      if (pageFrame === void 0) {
-        log_default.warn(`Frame "${frame}" not found, skipping`);
-      } else {
-        validPageFrames.push(pageFrame);
-      }
-    }
-    if (validPageFrames.length === 0) {
-      throw new Error("No valid frames found");
-    }
-    const validFrameNames = validPageFrames.map((frame) => slugify(frame.name));
-    const isFrameNameCollision = validFrameNames.length !== new Set(validFrameNames).size;
-    if (isFrameNameCollision) {
-      log_default.warn(
-        "Frame names are not unique, including frame IDs in the output filenames to avoid collisions"
-      );
-    }
-    const outputAccumulator = [];
-    for (const frame of validPageFrames) {
-      const frameSuffix = isFrameNameCollision ? `-${frame.id.replace("shape:", "")}` : "";
-      outputAccumulator.push(
-        ...await this._download(frame, {
-          ...options,
-          name: `${options.name}${frameSuffix}`
-        })
-      );
-    }
-    return outputAccumulator;
-  }
-  async downloadAllFrames(options) {
-    const pageFrames = await this.getPageFrames();
-    const frameNamesOrIds = pageFrames.map((f) => f.id);
-    return this.downloadFrames(frameNamesOrIds, options);
-  }
-  async loadFile(filePath) {
-    if (!this.page)
-      throw new Error("Controller not started");
-    if (this.isLocal)
-      throw new Error(
-        "File loading is only supported for remote tldraw.com instances. See tldraw-open.ts for local file loading approach."
-      );
-    await this.closeMenus();
-    await this.page.evaluate(`userPreferences.showFileOpenWarning.set(false);`);
-    log_default.info(`Uploading local file to tldraw.com: ${filePath}`);
-    const tldrFile = await fs.readFile(filePath, "utf8");
-    await this.page.evaluate(set_tldr_iife_default);
-    await this.page.evaluate(`window.setTldr(${tldrFile})`);
-  }
-  async getShareUrl() {
-    if (!this.page)
-      throw new Error("Controller not started");
-    if (this.isLocal)
-      throw new Error("Share URLs are only supported for remote tldraw.com instances.");
-    await this.closeMenus();
-    await this.clickButtonTitles(["Menu", "File", "Share this project"]);
-    await this.page.waitForNavigation({ waitUntil: "networkidle0" });
-    const shareUrl = new URL(this.page.url());
-    shareUrl.search = "";
-    return shareUrl.href;
-  }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
-  async _download(pageFrame, options) {
     if (!this.page)
       throw new Error("Controller not started");
     if (this.isEmpty)
@@ -17131,10 +17063,14 @@ var TldrawController = class {
     if (options.stripStyle && options.format !== "svg")
       log_default.warn("--strip-style is only supported for SVG output");
     if (options.format === "tldr") {
-      if (pageFrame !== void 0)
+      if (options.frames !== void 0)
         log_default.warn(
           '--frames is not supported when exporting to "tldr", ignoring flag and exporting entire sketch file'
         );
+      if (options.pages !== void 0)
+        log_default.warn(
+          '--pages is not supported when exporting to "tldr", ignoring flag and exporting entire sketch file'
+        );
       if (options.dark !== false) {
         log_default.warn(
           '--dark is not supported when exporting to "tldr", ignoring flag and exporting sketch file'
@@ -17167,22 +17103,37 @@ var TldrawController = class {
       stripStyle = false,
       transparent = false
     } = this.stripUndefined(options);
-    let frameSuffix = "";
-    let base64String = "";
     if (format === "tldr") {
       await this.page.evaluate(get_tldr_iife_default);
-      base64String = await this.page.evaluate(async () => window.getTldr());
-    } else {
-      if (pageFrame === void 0) {
+      const base64String = await this.page.evaluate(async () => window.getTldr());
+      if (print) {
+        const plainString = base64ToString(base64String).replaceAll("\n", "");
+        return [plainString];
+      }
+      const outputPath = path2.resolve(untildify(path2.join(output, `${filename}.${format}`)));
+      await fs.writeFile(outputPath, base64ToUint8Array(base64String));
+      return [outputPath];
+    }
+    await this.page.evaluate(get_image_iife_default);
+    const sketchStructure = await this.getSketchStructure();
+    const downloadPlan = this.getDownloadPlans(sketchStructure, options.pages, options.frames);
+    const outputAccumulator = [];
+    const initialPageId = await this.getCurrentPage();
+    let pageChanged = false;
+    for (const download of downloadPlan) {
+      if (download.pageId !== initialPageId) {
+        log_default.info(`Selecting sketch page "${download.pageId}"`);
+        await this.setCurrentPage(download.pageId);
+        pageChanged = true;
+      }
+      if (download.frameId === void 0) {
         await this.page.evaluate("editor.selectAll()");
       } else {
-        log_default.info(`Selecting sketch frame "${pageFrame.name}" with ID "${pageFrame.id}"`);
-        frameSuffix = `-${slugify(pageFrame.name)}`;
+        log_default.info(`Selecting sketch frame "${download.frameId}"`);
         await this.page.evaluate("editor.selectNone()");
-        await this.page.evaluate(`editor.select('${pageFrame.id}')`);
+        await this.page.evaluate(`editor.select('${download.frameId}')`);
       }
-      await this.page.evaluate(get_image_iife_default);
-      base64String = await this.page.evaluate(async (options2) => window.getImage(options2), {
+      let base64String = await this.page.evaluate(async (options2) => window.getImage(options2), {
         background: transparent === void 0 ? void 0 : !transparent,
         darkMode: dark,
         format,
@@ -17192,19 +17143,51 @@ var TldrawController = class {
       if (stripStyle && format === "svg") {
         base64String = stringToBase64(this.stripStyleElement(base64ToString(base64String)));
       }
-    }
-    const outputPath = path2.resolve(
-      untildify(path2.join(output, `${filename}${frameSuffix}.${format}`))
-    );
-    if (print) {
-      if (format === "png") {
-        return [base64String];
+      if (print) {
+        if (format === "png") {
+          outputAccumulator.push(base64String);
+        } else {
+          const plainString = base64ToString(base64String).replaceAll("\n", "");
+          outputAccumulator.push(plainString);
+        }
+      } else {
+        const outputPath = path2.resolve(
+          untildify(path2.join(output, `${filename}${download.fileSuffix}.${format}`))
+        );
+        await fs.writeFile(outputPath, base64ToUint8Array(base64String));
+        outputAccumulator.push(outputPath);
       }
-      const plainString = base64ToString(base64String).replaceAll("\n", "");
-      return [plainString];
     }
-    await fs.writeFile(outputPath, base64ToUint8Array(base64String));
-    return [outputPath];
+    if (pageChanged) {
+      await this.setCurrentPage(initialPageId);
+    }
+    return outputAccumulator;
+  }
+  async loadFile(filePath) {
+    if (!this.page)
+      throw new Error("Controller not started");
+    if (this.isLocal)
+      throw new Error(
+        "File loading is only supported for remote tldraw.com instances. See tldraw-open.ts for local file loading approach."
+      );
+    await this.closeMenus();
+    await this.page.evaluate(`userPreferences.showFileOpenWarning.set(false);`);
+    log_default.info(`Uploading local file to tldraw.com: ${filePath}`);
+    const tldrFile = await fs.readFile(filePath, "utf8");
+    await this.page.evaluate(set_tldr_iife_default);
+    await this.page.evaluate(`window.setTldr(${tldrFile})`);
+  }
+  async getShareUrl() {
+    if (!this.page)
+      throw new Error("Controller not started");
+    if (this.isLocal)
+      throw new Error("Share URLs are only supported for remote tldraw.com instances.");
+    await this.closeMenus();
+    await this.clickButtonTitles(["Menu", "File", "Share this project"]);
+    await this.page.waitForNavigation({ waitUntil: "networkidle0" });
+    const shareUrl = new URL(this.page.url());
+    shareUrl.search = "";
+    return shareUrl.href;
   }
   async closeMenus() {
     if (!this.page)
@@ -17221,28 +17204,163 @@ var TldrawController = class {
       await this.page.click(`button[title="${title}"]`);
     }
   }
-  // TODO memoize...
-  async getPageFrameWithNameOrId(nameOrId) {
-    const pageFrames = await this.getPageFrames();
-    if (pageFrames.length === 0) {
-      throw new Error("No frames found");
+  // Deduplicates, verifies existence, and normalizes to ids of the style 'page:xxxx'
+  validatePages(sketch, pages) {
+    if (Array.isArray(pages)) {
+      const validPages = [];
+      for (const p of pages) {
+        const matchingPage = typeof p === "number" ? sketch[p] : sketch.find(
+          (page) => slugify(p) === slugify(page.name) || `page:${p.replace(/^page:/, "")}` === page.id
+        );
+        if (matchingPage) {
+          if (!validPages.includes(matchingPage.id)) {
+            validPages.push(matchingPage.id);
+          }
+        } else {
+          log_default.warn(`Page "${p}" not found in sketch`);
+        }
+      }
+      if (validPages.length === 0) {
+        log_default.warn("None of the requested pages were found in sketch, ignoring pages option");
+        return void 0;
+      }
+      return validPages;
+    }
+    return pages;
+  }
+  validateFrames(sketch, pages, frames) {
+    if (Array.isArray(frames)) {
+      const validSketch = sketch.filter(
+        (page, index2) => pages === void 0 || typeof pages === "boolean" && !pages && index2 === 0 || typeof pages === "boolean" && pages || Array.isArray(pages) && pages.some(
+          (p, index3) => typeof p === "number" ? index3 === p : slugify(p) === slugify(page.name) || p.replace(/^page:/, "") === page.id.replace(/^page:/, "")
+        )
+      );
+      const validFrames = [];
+      for (const f of frames) {
+        const matchingFrames = [];
+        for (const page of validSketch) {
+          const match = page.frames.find(
+            (frame) => slugify(f) === slugify(frame.name) || `shape:${f.replace(/^shape:/, "")}` === frame.id
+          );
+          if (match && !matchingFrames.includes(match.id)) {
+            matchingFrames.push(match.id);
+          }
+        }
+        if (matchingFrames.length === 0) {
+          log_default.warn(`Frame "${f}" not found in sketch`);
+        } else {
+          validFrames.push(...matchingFrames);
+        }
+        if (validFrames.length === 0) {
+          log_default.warn("None of the requested frames were found in sketch, ignoring frames option");
+          return void 0;
+        }
+      }
+      return validFrames;
     }
-    return pageFrames.find((f) => f.name === nameOrId || slugify(f.name) === nameOrId) ?? pageFrames.find(
-      (f) => f.id === (nameOrId.startsWith("shape:") ? nameOrId : `shape:${nameOrId}`)
+    return frames;
+  }
+  // eslint-disable-next-line complexity
+  getDownloadPlans(sketch, pages, frames) {
+    const validPages = this.validatePages(sketch, pages);
+    const validFrames = this.validateFrames(sketch, validPages, frames);
+    const filteredSketch = validPages === void 0 ? [sketch[0]] : typeof validPages === "boolean" && !validPages ? [sketch[0]] : sketch.filter(
+      (sketchPage) => typeof validPages === "boolean" && validPages ? true : validPages.some(
+        (p) => slugify(p) === slugify(sketchPage.name) || p.replace("page:", "") === sketchPage.id.replace("page:", "")
+      )
     );
+    for (const page of filteredSketch) {
+      page.frames = validFrames === void 0 || typeof validFrames === "boolean" && !validFrames ? [] : page.frames.filter(
+        (frame) => typeof validFrames === "boolean" && validFrames ? true : validFrames.some(
+          (f) => slugify(f) === slugify(frame.name) || f.replace("shape:", "") === frame.id.replace("shape:", "")
+        )
+      );
+    }
+    const downloadPlans = [];
+    const isPageNameCollision = new Set(filteredSketch.map((page) => slugify(page.name))).size !== filteredSketch.length;
+    if (isPageNameCollision) {
+      log_default.warn(
+        "Page names are not unique, including page IDs in the output filenames to avoid collisions"
+      );
+    }
+    for (const page of filteredSketch) {
+      const pageSuffix = validPages === void 0 || typeof validPages === "boolean" && !validPages ? void 0 : isPageNameCollision ? `${slugify(page.name)}-${page.id.replace("page:", "")}` : slugify(page.name);
+      if (page.frames.length === 0) {
+        downloadPlans.push({
+          fileSuffix: pageSuffix ?? "",
+          frameId: void 0,
+          pageId: page.id
+        });
+      } else {
+        const isFrameNameCollision = new Set(page.frames.map((frame) => slugify(frame.name))).size !== page.frames.length;
+        if (isFrameNameCollision) {
+          log_default.warn(
+            "Frame names are not unique, including frame IDs in the output filenames to avoid collisions"
+          );
+        }
+        for (const frame of page.frames) {
+          const frameSuffix = isFrameNameCollision ? [slugify(frame.name), frame.id.replace("shape:", "")].filter((value) => value !== "").join("-") : slugify(frame.name);
+          downloadPlans.push({
+            fileSuffix: [pageSuffix, frameSuffix].filter((value) => value !== void 0).join("-"),
+            frameId: frame.id,
+            pageId: page.id
+          });
+        }
+      }
+    }
+    for (const plan of downloadPlans) {
+      if (plan.fileSuffix !== "") {
+        plan.fileSuffix = `-${plan.fileSuffix}`;
+      }
+    }
+    return downloadPlans;
   }
-  // TODO memoize
-  async getPageFrames() {
+  // Structure
+  async getSketchStructure() {
+    if (!this.page)
+      throw new Error("Controller not started");
+    const document = await this.getPages();
+    for (const page of document) {
+      page.frames = await this.getPageFrames(page.id);
+    }
+    return document;
+  }
+  async getPages() {
     if (!this.page)
       throw new Error("Controller not started");
     return await this.page.evaluate(
+      `editor.getPages().map((page) => ({ id: page.id, name: page.name, frames: []}))`
+    );
+  }
+  async getPageFrames(pageId) {
+    if (!this.page)
+      throw new Error("Controller not started");
+    const initialPageId = await this.getCurrentPage();
+    if (pageId !== initialPageId) {
+      await this.setCurrentPage(pageId);
+    }
+    const frames = await this.page.evaluate(
       `editor.getCurrentPageShapes().reduce((accumulator, shape) => {
 				if (shape.type === 'frame') {
-					accumulator.push({ id: shape.id, name: shape.props.name })
+					accumulator.push({ id: shape.id, name: shape.props.name === '' ? 'Frame' : shape.props.name })
 				}
 				return accumulator
 			}, [])`
     );
+    if (pageId !== initialPageId) {
+      await this.setCurrentPage(initialPageId);
+    }
+    return frames;
+  }
+  async getCurrentPage() {
+    if (!this.page)
+      throw new Error("Controller not started");
+    return await this.page.evaluate(`editor.getCurrentPageId()`);
+  }
+  async setCurrentPage(pageId) {
+    if (!this.page)
+      throw new Error("Controller not started");
+    await this.page.evaluate(`editor.setCurrentPage("${pageId}")`);
   }
   // Helpers
   stripStyleElement(svg) {
@@ -17478,14 +17596,7 @@ async function tldrawToImage(tldrPathOrUrl, options = {}) {
   const tldrawUrl = isLocal ? tldrawServer.href : validatedPathOrUrl.href;
   const tldrawController = new TldrawController(tldrawUrl);
   await tldrawController.start();
-  let exportReport;
-  if (options.frames && typeof options.frames === "boolean") {
-    exportReport = await tldrawController.downloadAllFrames(options);
-  } else if (Array.isArray(options.frames) && options.frames.length > 0) {
-    exportReport = await tldrawController.downloadFrames(options.frames, options);
-  } else {
-    exportReport = await tldrawController.download(options);
-  }
+  const exportReport = await tldrawController.download(options);
   await tldrawController.close();
   if (isLocal)
     tldrawServer.close();

package/dist/lib/tldraw-controller.d.ts

@@ -1,5 +1,4 @@
 import type { TldrawToImageOptions } from './tldraw-to-image';
-type DownloadOptions = Omit<TldrawToImageOptions, 'frames'>;
 export default class TldrawController {
     private readonly href;
     private page?;
@@ -9,18 +8,19 @@ export default class TldrawController {
     private get isLocal();
     start(): Promise<void>;
     close(): Promise<void>;
-    download(options: DownloadOptions): Promise<string[]>;
-    downloadFrame(frameNameOrId: string, options: DownloadOptions): Promise<string[]>;
-    downloadFrames(frameNamesOrIds: string[], options: DownloadOptions): Promise<string[]>;
-    downloadAllFrames(options: DownloadOptions): Promise<string[]>;
+    download(options: TldrawToImageOptions): Promise<string[]>;
     loadFile(filePath: string): Promise<void>;
     getShareUrl(): Promise<string>;
-    private _download;
     private closeMenus;
     private clickButtonTitles;
-    private getPageFrameWithNameOrId;
+    private validatePages;
+    private validateFrames;
+    private getDownloadPlans;
+    private getSketchStructure;
+    private getPages;
     private getPageFrames;
+    private getCurrentPage;
+    private setCurrentPage;
     private stripStyleElement;
     private stripUndefined;
 }
-export {};

package/dist/lib/tldraw-to-image.d.ts

@@ -6,6 +6,7 @@ export type TldrawToImageOptions = {
     name?: string;
     output?: string;
     padding?: number;
+    pages?: boolean | number[] | string[];
     print?: boolean;
     scale?: number;
     stripStyle?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitschpatrol/tldraw-cli",
-  "version": "4.3.2",
+  "version": "4.4.1",
   "type": "module",
   "description": "A CLI tool for exporting tldraw sketch URLs and local .tldr files to SVG or PNG images.",
   "repository": {
@@ -18,7 +18,7 @@
     "url": "https://ericmika.com"
   },
   "license": "MIT",
-  "packageManager": "pnpm@8.15.5",
+  "packageManager": "pnpm@8.15.6",
   "engines": {
     "node": ">=18.0.0",
     "pnpm": ">=8.0.0"
@@ -46,7 +46,7 @@
   "dependencies": {
     "@fontsource/inter": "^5.0.17",
     "express": "^4.19.2",
-    "puppeteer": "^22.6.1",
+    "puppeteer": "^22.6.3",
     "uint8array-extras": "^1.1.0"
   },
   "devDependencies": {
@@ -54,8 +54,8 @@
     "@sindresorhus/slugify": "^2.2.1",
     "@tldraw/assets": "^2.0.2",
     "@types/express": "^4.17.21",
-    "@types/react": "^18.2.73",
-    "@types/react-dom": "^18.2.22",
+    "@types/react": "^18.2.74",
+    "@types/react-dom": "^18.2.24",
     "@types/yargs": "^17.0.32",
     "@vitejs/plugin-react-swc": "^3.6.0",
     "bumpp": "^9.4.0",
@@ -73,10 +73,10 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "tldraw": "^2.0.2",
-    "tsx": "^4.7.1",
-    "typescript": "^5.4.3",
+    "tsx": "^4.7.2",
+    "typescript": "^5.4.4",
     "untildify": "^5.0.0",
-    "vite": "^5.1.7",
+    "vite": "^5.2.8",
     "vitest": "^1.4.0",
     "yargs": "^17.7.2"
   },

package/readme.md

@@ -109,21 +109,22 @@ tldraw-cli export <files-or-urls..>
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
 | `files-or-urls`     | The tldraw sketch to export. May be one or more paths to local `.tldr` files, or tldraw\.com sketch URLs. Accepts a mix of both file paths and URLs, and supports glob matching via your shell. Prints the absolute path(s) to the exported image(s) to `stdout`. _(Required.)_ | `array` |
 
-| Option          | Alias | Argument   | Description                                                                                                                                                           | Type      | Default                                   |
-| --------------- | ----- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
-| `--format`      | `-f`  |            | Output image format.                                                                                                                                                  | `string`  | `"svg"`                                   |
-| `--output`      | `-o`  |            | Output image directory.                                                                                                                                               | `string`  | `"./"`                                    |
-| `--name`        | `-n`  |            | Output image name (without extension).                                                                                                                                | `string`  | The original file name or URL id is used. |
-| `--frames`      |       |            | Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or skip the arguments to export all frames.            | `array`   | `false`                                   |
-| `--transparent` | `-t`  |            | Export an image with a transparent background.                                                                                                                        | `boolean` | `false`                                   |
-| `--dark`        | `-d`  |            | Export a dark theme version of the image.                                                                                                                             | `boolean` | `false`                                   |
-| `--padding`     |       | `[number]` | Set a specific padding amount around the exported image.                                                                                                              |           | `32`                                      |
-| `--scale`       |       | `[number]` | Set a sampling amount for raster image exports.                                                                                                                       |           | `1`                                       |
-| `--strip-style` |       |            | Remove `<style>` elements from SVG output, useful to lighten the load of embedded fonts if you intend to provide your own stylesheets. Applies to SVG output only.    | `boolean` | `false`                                   |
-| `--print`       | `-p`  |            | Print the exported image(s) to stdout instead of saving to a file. Incompatible with `--output`, and disregards `--name`. PNGs are printed as base64-encoded strings. | `boolean` | `false`                                   |
-| `--verbose`     |       |            | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection.                                       | `boolean` | `false`                                   |
-| `--help`        | `-h`  |            | Show help                                                                                                                                                             | `boolean` |                                           |
-| `--version`     | `-v`  |            | Show version number                                                                                                                                                   | `boolean` |                                           |
+| Option          | Alias | Argument   | Description                                                                                                                                                                                                                                                          | Type      | Default                                   |
+| --------------- | ----- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
+| `--format`      | `-f`  |            | Output image format.                                                                                                                                                                                                                                                 | `string`  | `"svg"`                                   |
+| `--output`      | `-o`  |            | Output image directory.                                                                                                                                                                                                                                              | `string`  | `"./"`                                    |
+| `--name`        | `-n`  |            | Output image name (without extension).                                                                                                                                                                                                                               | `string`  | The original file name or URL id is used. |
+| `--frames`      |       |            | Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or pass the flag without the arguments to export all frames. By default, the entire first page is exported with all frames.                           | `array`   | `false`                                   |
+| `--pages`       |       |            | Export each sketch "page" as a separate image. Pass one or more page names or IDs to export specific page, or pass one or more page index numbers (from 0), or pass the flag without the arguments to export all pages. By default, only the first page is exported. | `array`   | `false`                                   |
+| `--transparent` | `-t`  |            | Export an image with a transparent background.                                                                                                                                                                                                                       | `boolean` | `false`                                   |
+| `--dark`        | `-d`  |            | Export a dark theme version of the image.                                                                                                                                                                                                                            | `boolean` | `false`                                   |
+| `--padding`     |       | `[number]` | Set a specific padding amount around the exported image.                                                                                                                                                                                                             |           | `32`                                      |
+| `--scale`       |       | `[number]` | Set a sampling factor for raster image exports.                                                                                                                                                                                                                      |           | `1`                                       |
+| `--strip-style` |       |            | Remove `<style>` elements from SVG output, useful to lighten the load of embedded fonts if you intend to provide your own stylesheets. Applies to SVG output only.                                                                                                   | `boolean` | `false`                                   |
+| `--print`       | `-p`  |            | Print the exported image(s) to stdout instead of saving to a file. Incompatible with `--output`, and disregards `--name`. PNGs are printed as base64-encoded strings.                                                                                                | `boolean` | `false`                                   |
+| `--verbose`     |       |            | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection.                                                                                                                                      | `boolean` | `false`                                   |
+| `--help`        | `-h`  |            | Show help                                                                                                                                                                                                                                                            | `boolean` |                                           |
+| `--version`     | `-v`  |            | Show version number                                                                                                                                                                                                                                                  | `boolean` |                                           |
 
 #### Subcommand: `tldraw-cli open`
 
@@ -240,6 +241,24 @@ tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "
 tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
 ```
 
+##### Export a specific page by name from a tldraw\.com URL
+
+```sh
+tldraw-cli export https://www.tldraw.com/s/v2_c_L_RFQ3mJA_BWHejdH2hlD --pages "Page 3"
+```
+
+##### Export a specific pages by index from a tldraw\.com URL
+
+```sh
+tldraw-cli export https://www.tldraw.com/s/v2_c_L_RFQ3mJA_BWHejdH2hlD --pages 0 2
+```
+
+##### Export each pages as its own SVG from a tldraw\.com URL
+
+```sh
+tldraw-cli export https://www.tldraw.com/s/v2_c_L_RFQ3mJA_BWHejdH2hlD --pages
+```
+
 ##### Export to JSON
 
 ```sh
@@ -280,6 +299,7 @@ The library exports a single async function, `tldrawToImage`, which takes an opt
     name?: string
     output?: string
     padding?: number
+    pages?: boolean | string[] | number[]
     print?: boolean
     scale?: number
     stripStyle?: boolean
@@ -362,9 +382,9 @@ On Discord:
 
 ## Implementation notes
 
-This tool is not a part of the official tldraw project, and it is currently only tested and known to be compatible with tldraw 2.0.0-beta.2.\_
+This tool is not a part of the official tldraw project.
 
-Due to the current implementation of tldraw, export depends on functionality provided by a web browser. So, behind the scenes, this app serves a local instance of tldraw, then loads a `.tldr` and invokes the export download via the [Puppeteer](https://pptr.dev) headless browser automation tool.
+Due to the architecture of tldraw, export depends on functionality provided by a web browser. So, behind the scenes, this app serves a local instance of tldraw, then loads a `.tldr` and invokes the export download via the [Puppeteer](https://pptr.dev) headless browser automation tool.
 
 This can be a bit slow, (exporting seems to take a second or two), but in the context of a statically-generated content pipeline it's not the end of the world.