@kitschpatrol/tldraw-cli 2.2.2 → 3.0.0

package/dist/tldraw/translations/tr.json

@@ -63,7 +63,7 @@
 	"action.stretch-vertical": "Dikey olarak esnet",
 	"action.stretch-horizontal.short": "Yatay esnet",
 	"action.stretch-vertical.short": "Dikey esnet",
-	"action.toggle-auto-size": "Otomatik boyuta geçiş yap",
+	"action.toggle-auto-size": "Boyutu Uyarla aç/kapat",
 	"action.toggle-dark-mode.menu": "Karanlık mod",
 	"action.toggle-dark-mode": "Karanlık moda geçiş yap",
 	"action.toggle-debug-mode.menu": "Hata ayıklama modu",
@@ -267,9 +267,10 @@
 	"style-panel.mixed": "Karışık",
 	"style-panel.opacity": "Opaklık",
 	"style-panel.size": "Boyut",
+	"style-panel.spline": "Eğri",
 	"tool-panel.drawing": "Çizim",
 	"tool-panel.shapes": "Şekiller",
-	"navigation-zone.toggle-minimap": "Mini haritaya geçiş yap",
+	"navigation-zone.toggle-minimap": "Mini haritayı aç/kapat",
 	"navigation-zone.zoom": "Yakınlaştır",
 	"focus-mode.toggle-focus-mode": "Odak modunu değiştir",
 	"toast.close": "Kapat",
@@ -290,5 +291,65 @@
 	"file-system.shared-document-file-open-error.description": "Paylaşılan projelerdeki dosyaların açılmaası desteklenmemektedir.",
 	"vscode.file-open.dont-show-again": "Bir daha sorma",
 	"vscode.file-open.desc": "Bu dosya daha önceki bir tldraw versiyonu ile oluşturulmuştur. Yeni versiyonla çalışmak için güncellemek ister misiniz?",
-	"context.pages.new-page": "Yeni sayfa"
+	"context.pages.new-page": "Yeni sayfa",
+	"style-panel.arrowhead-start": "Başlangıç",
+	"style-panel.arrowhead-end": "Bitiş",
+	"vscode.file-open.open": "Devam",
+	"vscode.file-open.backup": "Yedek",
+	"vscode.file-open.backup-saved": "Yedek Kaydedildi",
+	"vscode.file-open.backup-failed": "Yedekleme başarısız: bu .tldr uzantısına sahip bir dosya değil.",
+	"tool-panel.more": "Daha Fazla",
+	"debug-panel.more": "Daha Fazla",
+	"action.new-project": "Yeni Proje",
+	"file-system.confirm-clear.title": "Mevcut projeyi temizle",
+	"file-system.confirm-clear.description": "Yeni proje başlatmak, mevcut projedeki herşeyi siler. Devam etmek istiyor musun?",
+	"file-system.confirm-clear.cancel": "Vazgeç",
+	"file-system.confirm-clear.continue": "Devam",
+	"file-system.confirm-clear.dont-show-again": "Bir daha sorma",
+	"action.stop-following": "Takibi bırak",
+	"people-menu.follow": "Takip et",
+	"style-panel.position": "Pozisyon",
+	"page-menu.go-to-page": "Sayfaya git",
+	"action.insert-embed": "Dışardan çağır",
+	"people-menu.following": "Takip ediliyor",
+	"people-menu.leading": "Seni takip ediyor",
+	"geo-style.check-box": "Onay Kutusu",
+	"tool.check-box": "Onay Kutusu",
+	"share-menu.create-snapshot-link": "Link ile dışarıya ver",
+	"share-menu.save-note": "Projeyi .tldr olarak dışa aktar",
+	"share-menu.fork-note": "Linki üzerinden projeyi içe aktar",
+	"share-menu.snapshot-link-note": "Link ile sadece görüntülenebilir şekilde dışarıya ver",
+	"share-menu.upload-failed": "Proje yüklenirken hata oluştu, lütfen daha sonra tekrar deneyin.",
+	"style-panel.vertical-align": "Dikey Hizalama",
+	"tool.laser": "Lazer",
+	"action.fork-project": "Bu projeyi forkla",
+	"action.leave-shared-project": "Paylaşılan Projeyi Kapat",
+	"sharing.confirm-leave.title": "Açık Projeyi Kapat",
+	"sharing.confirm-leave.description": "Paylaşılan projeden ayrılamak istediğinize emin misiniz?. Daha sonra aynı link ile geri dönebilirsiniz.",
+	"sharing.confirm-leave.cancel": "Vazgeç",
+	"sharing.confirm-leave.leave": "Ayrıl",
+	"sharing.confirm-leave.dont-show-again": "Bir daha sorma",
+	"action.toggle-reduce-motion.menu": "Hareketi azalt",
+	"action.toggle-reduce-motion": "Hareketi azaltmayı aç/kapat",
+	"tool.highlight": "Vurgu",
+	"action.toggle-lock": "Kilidi Aç / Kilidi Kapat",
+	"share-menu.default-project-name": "Projeyi Paylaş",
+	"home-project-dialog.title": "Ana Proje",
+	"home-project-dialog.description": "Bu sizin yerel ana projenizdir. Sadece sizin için.",
+	"rename-project-dialog.title": "Projeyi yeniden adlandır",
+	"rename-project-dialog.cancel": "Vazgeç",
+	"rename-project-dialog.rename": "Yeniden Adlandır",
+	"home-project-dialog.ok": "Tamam",
+	"action.open-cursor-chat": "Sohbet imleci",
+	"shortcuts-dialog.collaboration": "İşbirliği",
+	"cursor-chat.type-to-chat": "Bir şeyler yaz...",
+	"geo-style.cloud": "Bulut",
+	"tool.cloud": "Bulut",
+	"action.unlock-all": "Tüm Kilitleri Aç",
+	"status.offline": "Çevrimdışı",
+	"status.online": "Çevrimiçi",
+	"action.remove-frame": "Çerçeveyi kaldır",
+	"action.fit-frame-to-content": "İçeriği Hizala",
+	"action.toggle-edge-scrolling.menu": "Kaydırma çubuğu",
+	"action.toggle-edge-scrolling": "Kaydırma çubuğunu aç/kapat"
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kitschpatrol/tldraw-cli",
-  "version": "2.2.2",
+  "version": "3.0.0",
   "type": "module",
-  "description": "A tiny little CLI tool for rendering tldraw URLs and .tldr files into svg or png images.",
+  "description": "A tiny little CLI tool for exporting tldraw sketches to svg or png images.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kitschpatrol/tldraw-cli.git"
@@ -48,8 +48,8 @@
   "devDependencies": {
     "@kitschpatrol/shared-config": "^4.3.3",
     "@sindresorhus/slugify": "^2.2.1",
-    "@tldraw/assets": "2.0.0-beta.2",
-    "@tldraw/tldraw": "2.0.0-beta.2",
+    "@tldraw/assets": "2.0.0-canary.ade38247d8a4",
+    "@tldraw/tldraw": "2.0.0-canary.ade38247d8a4",
     "@types/express": "^4.17.21",
     "@types/react": "^18.2.48",
     "@types/react-dom": "^18.2.18",
@@ -61,13 +61,15 @@
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react-refresh": "^0.4.5",
     "get-port": "^7.0.0",
+    "nanoid": "^5.0.4",
+    "open": "^10.0.3",
     "path-type": "^5.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3",
     "untildify": "^5.0.0",
-    "vite": "^5.0.11",
+    "vite": "^5.0.12",
     "vitest": "^1.2.1",
     "yargs": "^17.7.2"
   },
@@ -78,13 +80,16 @@
     "build": "pnpm run build:tldraw && pnpm run build:lib && pnpm run build:cli",
     "build:cli": "tsx ./scripts/build-cli.ts",
     "build:lib": "tsx ./scripts/build-lib.ts && tsc -p tsconfig.lib.json",
-    "build:tldraw": "pnpm run tldraw-copy-assets && vite build",
-    "dev": "pnpm run tldraw-copy-assets && vite",
+    "build:tldraw": "pnpm run tldraw:copy-assets && vite build",
+    "dev": "pnpm run dev:tldraw",
+    "dev:tldraw": "pnpm run tldraw:copy-assets && vite",
     "fix": "shared-config --fix",
     "lint": "shared-config --lint",
-    "preview": "vite preview",
-    "release": "pnpm build && pnpm bumpp --commit 'Release: %s' && pnpm publish --otp $(op read 'op://Personal/Npmjs/one-time password?attribute=otp')",
-    "test": "vitest",
-    "tldraw-copy-assets": "rsync -av --include='/*/' --exclude='/*' ./node_modules/@tldraw/assets/ ./src/tldraw/public/"
+    "preview": "pnpm run preview:tldraw",
+    "preview:tldraw": "vite preview",
+    "release": "pnpm run build && pnpm bumpp --commit 'Release: %s' && pnpm publish --otp $(op read 'op://Personal/Npmjs/one-time password?attribute=otp')",
+    "test": "pnpm run test:lib",
+    "test:lib": "pnpm run build && vitest",
+    "tldraw:copy-assets": "rsync -av --include='/*/' --exclude='/*' --exclude='favicon.ico' ./node_modules/@tldraw/assets/ ./src/tldraw/public/"
   }
 }

package/readme.md

@@ -8,61 +8,100 @@
 
 This could be useful in the context of a content publishing pipeline where you want to use a `.tldr` file (perhaps under version control) as the "source of truth" for assets to be embedded elsewhere, and you don't want to manage the export of that diagram manually.
 
-_Note: This tool is not a part of the official tldraw project, and it is currently only tested and compatible with tldraw 2.0.0-beta.2._
+_For `.tldr` file import support in Vite projects, please see [@kitschpatrol/vite-plugin-tldraw](https://github.com/kitschpatrol/vite-plugin-tldraw)._
 
 ## Installation
 
 Invoke directly:
 
 ```sh
-npx @kitschpatrol/tldraw-cli some-file.tldr
+npx @kitschpatrol/tldraw-cli export some-file.tldr
 ```
 
 ...or install locally:
 
 ```sh
-npm --install --save-dev @kitschpatrol/tldraw-cli
+npm install --save-dev @kitschpatrol/tldraw-cli
 ```
 
 ...or install globally:
 
 ```sh
-npm --install --global @kitschpatrol/tldraw-cli
+npm install --global @kitschpatrol/tldraw-cli
 ```
 
 ## Command line usage
 
 ### Invocation
 
+To leave room for future functionality, `tldraw-cli` exposes functionality under several sub-commands.
+
+#### Top-level
+
+```sh
+tldraw-cli <command>
+```
+
+The top-level collection of CLI tools for tldraw.
+
+| Argument  | Description         |
+| --------- | ------------------- |
+| `command` | `export` or `open`. |
+
+| Option      | Alias | Description Value    |
+| ----------- | ----- | -------------------- |
+| `--help `   | `-h`  | Show help.           |
+| `--version` | `-v`  | Show version number. |
+
+#### Command: Export
+
+```sh
+tldraw-cli export <file-or-url>
+```
+
+Export a tldraw ".tldr" file or tldraw\.com URL to an svg, png image, and other formats.
+
+| Argument        | Description                                                                                                                                                                   |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<file-or-url>` | The sketch to convert export an image — either a path to a local ".tldr" file, or a tldraw\.com sketch URL. Prints the absolute path(s) to the exported image(s) to `stdout`. |
+
+| Option              | Alias | Description Value                                                                                                                                                              | Default Value |
+| ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
+| `--format <string>` | `-f`  | Output image format, one of `svg`, `png`, `json`, or `tldr`.                                                                                                                   | `svg`         |
+| `--dark-mode `      | `-d`  | Output a dark theme version of the image.                                                                                                                                      | `false`       |
+| `--transparent `    | `-t`  | Output an image with a transparent background.                                                                                                                                 | `false`       |
+| `--output <string>` | `-o`  | Output directory.                                                                                                                                                              | `./`          |
+| `--name <string>`   | `-n`  | Output file name without extension; by default the original file name or URL id is used.                                                                                       |               |
+| `--frames <array?>` |       | Export each sketch "frame" as a separate image, use the option flag alone to export all frames, or pass one or more frame names or IDs, slugified frame names will also match. | `false`       |
+| `--strip-style`     |       | Remove `<style>` elements from SVG output, useful to lighten the load of embedded fonts or if you are going to provide your own stylesheet for the SVG.                        | `false`       |
+| `--verbose`         |       | Enable verbose output.                                                                                                                                                         | `false`       |
+
+#### Command: Open
+
 ```sh
-tldraw-cli file-or-url {options}
+tldraw-cli open [file-or-url]
 ```
 
-| Argument      | Description                                                                                             |
-| ------------- | ------------------------------------------------------------------------------------------------------- |
-| `file-or-url` | The sketch to convert to an image — either a path to a local ".tldr" file, or a tldraw\.com sketch URL. |
+Open a tldraw ".tldr" file or tldraw\.com URL your default browser. Uses a locally-hosted instance of tldraw. Call `open` without an argument to open a blank sketch.
+
+Sketches opened via URL are copied to the local system, and will not be kept in sync with tldraw.com.
 
-| Option                | Alias | Description Value                                                                                                                                                             | Default Value |
-| --------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| `--format <svg\|png>` | `-f`  | Output image format, one of `svg` or `png`                                                                                                                                    | `svg`         |
-| `--dark-mode `        | `-d`  | Output a dark theme version of the image                                                                                                                                      | `false`       |
-| `--transparent `      | `-t`  | Output an image with a transparent background                                                                                                                                 | `false`       |
-| `--output <string>`   | `-o`  | Output directory                                                                                                                                                              | `./`          |
-| `--name <string>`     | `-n`  | Output file name without extension; by default the original file name or URL id is used                                                                                       |               |
-| `--frames <array?>`   |       | Export each sketch "frame" as a separate image, use the option flag alone to export all frames, or pass one or more frame names or IDs, slugified frame names will also match | `false`       |
-| `--strip-style`       |       | Remove `<style>` elements from SVG output, useful to lighten the load of embedded fonts or if you are going to provide your own stylesheet for the SVG                        | `false`       |
-| `--help `             | `-h`  | Show help                                                                                                                                                                     |               |
-| `--version`           | `-v`  | Show version number                                                                                                                                                           |               |
-| `--verbose`           |       | Enable verbose output                                                                                                                                                         | `false`       |
+"Save as" support is not yet implemented in the local tldraw instance, so it's recommended for viewing purposes only at the moment.
+
+| Argument        | Description                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `[file-or-url]` | The .tldr file or tldraw\.com sketch url to open. Omit to open a blank sketch. Prints the url of the local server to `stdout`. |
+
+No options.
 
 ## Examples
 
-### Basic .tldr file conversion
+### Basic .tldr file image export
 
-To convert the file `your-drawing.tldr` to an svg named `your-drawing.svg` saved in the current working directory, run the following command. Note that the default output format is svg, and the default export location is the current working directory.
+To export the file `your-drawing.tldr` to an svg named `your-drawing.svg` in the current working directory, run the following command. Note that the default output format is SVG, and the default export location is the current working directory.
 
 ```sh
-npx @kitschpatrol/tldraw-cli your-drawing.tldr
+npx @kitschpatrol/tldraw-cli export your-drawing.tldr
 ```
 
 The file will retain its original name, e.g. `your-drawing.svg`
@@ -70,46 +109,62 @@ The file will retain its original name, e.g. `your-drawing.svg`
 ### Basic tldraw\.com image download
 
 ```sh
-npx @kitschpatrol/tldraw-cli https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4
+npx @kitschpatrol/tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4
 ```
 
 The tldraw URL's id (e.g. `v2_c_JsxJk8dag6QsrqExukis4`) will be used for the file name.
 
+This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → SVG" menu item.
+
+### Export a remote tldraw\.com image to a local .tldr file
+
+```sh
+npx @kitschpatrol/tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4 --format tldr
+```
+
+This is approximately equivalent to clicking the tldraw\.com "☰ → File → Save a copy" menu item.
+
+Note that using `--format tldr` with a _file path_ instead of a _URL_ will still send the file through the pipeline, but it's effectively a no-op. (Except perhaps rare edge cases where tldraw performs a file format version migration).
+
 ### Export to a specific format
 
 ```sh
-npx @kitschpatrol/tldraw-cli your-drawing.tldr --format png
+npx @kitschpatrol/tldraw-cli export your-drawing.tldr --format png
 ```
 
+This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → PNG" menu item.
+
 ### Export with a transparent background
 
 ```sh
-npx @kitschpatrol/tldraw-cli your-drawing.tldr --transparent --format png
+npx @kitschpatrol/tldraw-cli export your-drawing.tldr --transparent --format png
 ```
 
+This is approximately equivalent to checking the tldraw\.com "☰ → Edit → Export As → ☐ Transparent" menu item.
+
 ### Export to a specific destination
 
 ```sh
-npx @kitschpatrol/tldraw-cli your-drawing.tldr --output ~/Desktop
+npx @kitschpatrol/tldraw-cli export your-drawing.tldr --output ~/Desktop
 ```
 
-Saves to `~/Desktop/your-drawing.svg`
+Exports to `~/Desktop/your-drawing.svg`
 
 ### Export to a specific destination and filename
 
 ```sh
-npx @kitschpatrol/tldraw-cli your-drawing.tldr --output ~/Desktop --name not-your-drawing
+npx @kitschpatrol/tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
 ```
 
-Saves to `~/Desktop/not-your-drawing.svg`
+Exports to `~/Desktop/not-your-drawing.svg`
 
-### Export all frames from a single tldraw URL
+### Export all frames from a tldraw URL
 
 ```sh
-npx @kitschpatrol/tldraw-cli https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames
+npx @kitschpatrol/tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames
 ```
 
-The saved files will be suffixed with their frame name, e.g.:
+The exported files will be suffixed with their frame name, e.g.:
 
 `v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-1.png`
 `v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-2.png`
@@ -122,40 +177,61 @@ It's possible in tldraw to give multiple frames in a single sketch the same name
 ### Export a specific frame from a tldraw URL
 
 ```sh
-npx @kitschpatrol/tldraw-cli https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
+npx @kitschpatrol/tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
 ```
 
+### Export to JSON
+
+```sh
+npx @kitschpatrol/tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
+```
+
+The .tldr file format is also JSON under the covers, but the `--format json` flag will yield a slightly different format than `--format tldr`. `--format json` is equivalent to what's produced via the tldraw\.com "☰ → Edit → Export As → JSON" menu item.
+
+I'm not completely clear on the use-case for this format, but since tldr.com supports it, so too shall `tldraw-cli`.
+
+### Open a tldraw URL
+
+```sh
+npx @kitschpatrol/tldraw-cli open https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw
+```
+
+The remote sketch is copied to a locally-hosted instance of tldraw, which is then opened in your default browser.
+
 ## API usage
 
-The conversion tool's functionality is also exposed as a module for use in TypeScript or JavaScript Node projects.
+The `export` command's functionality is also provided as a module for use in TypeScript or JavaScript Node projects.
 
 The library exports a single async function, `tldrawToImage`, which takes an options argument mirroring the arguments available via the command line. The same default values apply:
 
 ```ts
- tldrawToImage(
+ async function tldrawToImage(
   tldrPathOrUrl: string,
   {
     darkMode?: boolean
-    output?: string
-    format?: 'png' | 'svg'
+    format?: 'svg' | 'png' | 'json' | 'tldr'
     frames?: boolean | string[]
+    name?: string
+    output?: string
     stripStyle?: boolean
     transparent?: boolean
     verbose?: boolean
- }): Promise<string | string[]>;
+ }): Promise<string[]>;
 ```
 
-The function exports the image in the requested format returns the full path to the output image.
+The function exports the image in the requested format returns an array of the output image(s) or file(s).
+
+Generally, a single file is returned — but the `string[]` return type also accommodates invocations with `frame: true` where multiple images will be generated.
 
 Assuming you've installed `@kitschpatrol/tldraw-cli` locally in your project, it may be used as follows:
 
 ```ts
-// tldr-cli-api-test.ts
+// tldraw-cli-api-test.ts
 
 import { tldrawToImage } from '@kitschpatrol/tldraw-cli'
 
 // Convert a local file to PNG
-const imagePath = await tldrawToImage('./some-file.tldr', { format: 'png', output: './' })
+const [imagePath] = await tldrawToImage('./some-file.tldr', { format: 'png', output: './' })
 console.log(`Wrote image to: "${imagePath}"`)
 
 // Convert a remote tldraw URL to SVG
@@ -175,14 +251,14 @@ await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
   format: 'png',
 })
 
-// You can also use the frame id instead of name, if you're into that sort of thing
+// You can also use the frame id instead of the frame name, if you're into that sort of thing
 // It will work with or without the `shape:` prefix
 await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
   frames: ['shape:x8z3Qf7Hgw4Qqp2AC-eet'],
 })
 ```
 
-_Note that the library provided is ESM only, and requires a Node-compatible runtime. TypeScript type definitions are included._
+_Note that the library provided is ESM-only, and requires a Node-compatible runtime. TypeScript type definitions are included._
 
 ## Background
 
@@ -202,9 +278,11 @@ 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.\_
+
 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 [Puppeteer](https://pptr.dev).
 
-This can be a bit slow, (exporting seems to take a second or two), but in the context of a content pipeline it's not the end of the world.
+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.
 
 In terms of Puppeteer vs. Playwright and other headless browser automation tools, it [looks like](https://www.checklyhq.com/blog/puppeteer-vs-selenium-vs-playwright-speed-comparison/) Puppeteer's performance likely compares favorably. (Though I have not tested and benchmarked the alternatives in the specific context of `tldraw-cli`.)
 
@@ -214,6 +292,7 @@ The local instance of tldraw includes its assets dependencies, so the tool shoul
 
 This is a very minimal implementation. Current plans for future improvements include the following:
 
+- Add save button to local tldraw
 - Add CLI tests
 - Implement the ability to export specific pages as separate image files
 - Add an option flag to set dpi when exporting to a bitmap format