---
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.