76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
---
|
|
name: tldraw-file
|
|
description: Create, repair, validate, or generate valid `.tldr` files that tldraw can open. Use when the user asks for a tldraw diagram, `.tldr` file, corrupted tldraw repair, or a diagram they can open in tldraw.
|
|
argument-hint: "[diagram request, file path, or validation target]"
|
|
user-invocable: true
|
|
---
|
|
|
|
# tldraw File
|
|
|
|
Use when creating, repairing, validating, or generating a `.tldr` file.
|
|
|
|
## Core Rule
|
|
|
|
Do not hand-wave validity. A `.tldr` file must validate through tldraw's own schema/importer, not just `JSON.parse`. Valid JSON can still be corrupted to tldraw.
|
|
|
|
## Temporary Setup
|
|
|
|
If the current project does not already depend on `tldraw`, install it in `/tmp/opencode`, not in the user's repo:
|
|
|
|
```bash
|
|
bun init -y
|
|
bun add tldraw
|
|
```
|
|
|
|
Run validation scripts from the directory where `tldraw` is installed.
|
|
|
|
## File Shape
|
|
|
|
A `.tldr` file has top-level `tldrawFileFormatVersion`, `schema`, and `records`. Records must be an array of valid tldraw records. Include at least a document record and a page record, then shapes parented to that page.
|
|
|
|
Use geo rectangles for most boxes, text shapes for headings, and simple arrows for flow. Avoid note shapes unless you know the current schema.
|
|
|
|
See [record templates](references/record-templates.md) for base records and shape JSON.
|
|
|
|
## Validation Workflow
|
|
|
|
1. Create or update `.tldr` with `apply_patch`.
|
|
2. Validate JSON syntax.
|
|
3. Validate records with `createTLStore({ snapshot })`.
|
|
4. Validate importer compatibility with `parseTldrawJsonFile`.
|
|
5. If tldraw says corrupted, trust tldraw and fix the specific schema path.
|
|
|
|
```bash
|
|
bun -e "const f='/path/to/file.tldr'; const data=await Bun.file(f).text(); JSON.parse(data); console.log('valid json')"
|
|
```
|
|
|
|
```bash
|
|
bun -e "import { createTLStore } from 'tldraw'; const file=JSON.parse(await Bun.file('/path/to/file.tldr').text()); const snapshot={store:Object.fromEntries(file.records.map(r=>[r.id,r])), schema:file.schema}; try { const store=createTLStore({snapshot}); console.log('ok records', store.allRecords().length); } catch(e){ console.error(e); process.exit(1)} process.exit(0)"
|
|
```
|
|
|
|
```bash
|
|
bun -e "import { createTLStore } from 'tldraw'; import { parseTldrawJsonFile } from './node_modules/tldraw/dist-esm/lib/utils/tldr/file.mjs'; const json=await Bun.file('/path/to/file.tldr').text(); const schema=createTLStore().schema; const result=parseTldrawJsonFile({json, schema}); console.log(result.ok ? 'parse ok' : result.error); process.exit(result.ok ? 0 : 1)"
|
|
```
|
|
|
|
## Common Corruption Causes
|
|
|
|
- File is valid JSON but does not match tldraw schema.
|
|
- Missing `labelColor` on arrow shapes.
|
|
- Missing required shape props, especially on note shapes.
|
|
- Old schema sequence numbers copied from another tldraw version.
|
|
- Invalid color names.
|
|
- Shape `parentId` points to a missing page.
|
|
- Duplicate record IDs.
|
|
- Records object used instead of records array.
|
|
- `richText` missing where current schemas expect it.
|
|
|
|
See [schema notes](references/schema-notes.md) for current sequence shape and valid colors.
|
|
|
|
## Practical Diagram Advice
|
|
|
|
- Keep diagrams editable rather than pixel-perfect.
|
|
- Use stable readable IDs, for example `shape:admin-review`.
|
|
- Use indexed records like `a1`, `a2`, `a3`.
|
|
- Keep labels in both `richText` and legacy `text` props for compatibility.
|
|
- Prefer simple layout and reliable schemas over fancy shapes.
|