snapshot of https://github.com/tldraw/tldraw.git (main, 2026-09-23; blobs > 131072B omitted)

apps/docs/content/getting-started/installation.mdx

@@ -0,0 +1,211 @@
+---
+title: Installation
+status: published
+author: steveruizok
+date: 3/22/2023
+order: 1
+keywords:
+  - hello world
+---
+
+To use the tldraw SDK, first install the `tldraw` package:
+
+```bash
+npm install tldraw
+```
+
+Now import and use the [Tldraw](?) component inside of any React component. You will need React 18 or 19.
+
+```tsx
+import { Tldraw } from 'tldraw'
+import 'tldraw/tldraw.css'
+
+export default function () {
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw />
+		</div>
+	)
+}
+```
+
+### Wrapper
+
+The [Tldraw](?) component must be wrapped in a parent container with an explicit size. Its height and width are set to `100%`, so it will fill its parent container.
+
+### Accessing the editor
+
+Use the `onMount` prop to access the [Editor](?) instance when it's ready:
+
+```tsx
+function App() {
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw
+				onMount={(editor) => {
+					// Do something with the editor
+					editor.selectAll()
+				}}
+			/>
+		</div>
+	)
+}
+```
+
+The callback can return a cleanup function that runs when the editor unmounts.
+
+### CSS
+
+In addition to the [Tldraw](?) component itself, you should also import the `tldraw.css` file from the `tldraw` package.
+
+```tsx
+import 'tldraw/tldraw.css'
+```
+
+You can alternatively import this file inside of another CSS file using the `@import` syntax.
+
+```css
+@import url('tldraw/tldraw.css');
+```
+
+If you'd like to deeply change the way that tldraw looks, you can copy the `tldraw.css` file into a new CSS file, make your changes, and import that instead.
+
+### Fonts
+
+The tldraw SDK bundles its own fonts for shapes: IBM Plex (Sans, Serif, Mono) and Shantell Sans (for draw-style text). These are loaded automatically from the CDN or self-hosted [static assets](#Static-assets).
+
+The tldraw UI will inherit its font family. You can set this to any font you like. For example, to use Inter:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@500;700&display=swap');
+
+.tl-container {
+	font-family: 'Inter', sans-serif;
+}
+```
+
+### HTML
+
+If you're using the [Tldraw](?) component in a full-screen app, update your `index.html`'s meta viewport element as shown below.
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+Without these viewport options, some features like safe area positioning won't work correctly.
+
+## License
+
+If you have a [license key](https://tldraw.dev/pricing), you can pass your key to the `licenseKey` prop.
+
+```tsx
+<Tldraw licenseKey={YOUR_LICENSE_KEY} />
+```
+
+To learn more about the license and license key, visit [our pricing page](https://tldraw.dev/pricing).
+
+## Static assets
+
+To use the [Tldraw](?) component, the app must be able to find certain assets. These are contained in the `embed-icons`, `fonts`, `icons`, and `translations` folders. We offer a few different ways of making these assets available to your app.
+
+### Using a bundler
+
+If you're using a bundler like webpack or rollup, you can import the assets directly from the `@tldraw/assets` package. Your bundler will copy the assets with your bundle and insert the correct URLs in their place.
+
+There are three options:
+
+- `import {getAssetUrlsByImport} from '@tldraw/assets/imports'`: import asset files using import statements. You'll need to configure your bundler to treat imports of .svg, .png, .json, and .woff2 files as external assets.
+- `import {getAssetUrlsByImport} from '@tldraw/assets/imports.vite'`: import asset files, appending `?url` to the asset path. This works correctly with [vite](https://vitejs.dev/guide/assets#explicit-url-imports) without any extra configuration needed.
+- `import {getAssetUrlsByMetaUrl} from '@tldraw/assets/urls'`: get asset urls using `new URL(path, import.meta.url)`. This is a standards-based approach that works natively in most modern browsers & bundlers.
+
+Call the function, and pass the resulting `assetUrls` into the `Tldraw` component:
+
+```tsx
+import { getAssetUrlsByMetaUrl } from '@tldraw/assets/urls'
+
+const assetUrls = getAssetUrlsByMetaUrl()
+
+<Tldraw assetUrls={assetUrls} />
+```
+
+### Using a public CDN
+
+By default, we serve these assets from a public CDN. This works without configuration and is a good starting point.
+
+If you would like to customize some of the assets you can pass the customizations to our [Tldraw](?) component. For example, to use a custom icon for the `hand` tool you can do the following:
+
+```tsx
+const assetUrls = {
+    icons: {
+        'tool-hand': './custom-tool-hand.svg',
+    },
+}
+
+<Tldraw assetUrls={assetUrls} />
+```
+
+This will use the custom icon for the `hand` tool and the default assets for everything else.
+
+### Self-hosting assets
+
+You can also host these assets yourself:
+
+1. Download the `embed-icons`, `fonts`, `icons`, and `translations` folders from the [assets folder](https://github.com/tldraw/tldraw/tree/main/assets) of the tldraw repository.
+2. Place the folders in your project's public path.
+3. Pass `assetUrls` prop to our `<Tldraw/>` component to let the component know where the assets live.
+
+You can use our `getAssetUrls` helper function from the `@tldraw/assets` package to generate these urls for you.
+
+```tsx
+import { getAssetUrls } from '@tldraw/assets/selfHosted'
+
+const assetUrls = getAssetUrls()
+
+<Tldraw assetUrls={assetUrls} />
+```
+
+While these files must be available, you can overwrite the individual files: for example, by placing different icons under the same name or by modifying or adding translations.
+
+If you use a CDN for hosting these files you can specify the base url of your assets. To recreate the above option of serving the assets from our CDN you would do the following:
+
+```ts
+import { getDefaultCdnBaseUrl } from 'tldraw'
+
+const assetUrls = getAssetUrls({
+	baseUrl: getDefaultCdnBaseUrl(),
+})
+```
+
+## Subcomponents
+
+The [Tldraw](?) component combines two lower-level components: [TldrawEditor](?) and [TldrawUi](?). If you want more granular control, you can use those lower-level components directly. See the [exploded example](/examples/configuration/exploded) for reference.
+
+### Customizing components
+
+You can customize the appearance of the tldraw editor and UI using the [Tldraw](?) (or [TldrawEditor](?)) component's `components` prop. This prop accepts a [TLComponents](?) object, which combines [TLEditorComponents](?) (canvas-level components like the background and grid) with [TLUiComponents](?) (UI elements like toolbar, menus, and panels).
+
+```tsx
+import { TLComponents } from 'tldraw'
+
+const components: TLComponents = {
+	// Editor components
+	Background: YourCustomBackground,
+	Grid: YourCustomGrid,
+
+	// UI components
+	Toolbar: YourCustomToolbar,
+	MainMenu: YourCustomMainMenu,
+	StylePanel: YourCustomStylePanel,
+	ContextMenu: YourCustomContextMenu,
+}
+
+<Tldraw components={components} />
+```
+
+Canvas overlay elements like the selection foreground, brush, snap indicators, and scribble are rendered via the [OverlayUtil](?) system rather than React components. You can customize them by extending the built-in overlay utils and passing them via the `overlayUtils` prop.
+
+See the [TLEditorComponents](?) and [TLUiComponents](?) type definitions for the complete list of customizable components.
+
+## Versioning
+
+The tldraw SDK does not follow semantic versioning. To learn more, read about how we do [release versioning](/releases).

apps/docs/content/getting-started/quick-start.mdx

@@ -0,0 +1,159 @@
+---
+title: Quick start
+status: published
+author: steveruizok
+date: 3/22/2023
+order: 0
+keywords:
+  - hello world
+  - intro
+  - start
+  - installation
+---
+
+Have five minutes? Run this command in your terminal to explore tldraw [starter kits](/starter-kits):
+
+```bash
+npm create tldraw@latest
+```
+
+Have a little more time? Let's try out the tldraw SDK in a React project.
+
+If you're new to React, we recommend using a [Vite template](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) as a starter. We'll assume your project is already running locally.
+
+## Getting started
+
+First, install the `tldraw` package from npm:
+
+```bash
+npm install tldraw
+```
+
+Next, in your React project, import the `Tldraw` component and tldraw's CSS styles. Then render the `Tldraw` component inside a full screen container:
+
+```tsx
+import { Tldraw } from 'tldraw'
+import 'tldraw/tldraw.css'
+
+export default function App() {
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw />
+		</div>
+	)
+}
+```
+
+That's pretty much it! At this point, you should have a complete working single-user canvas. You can draw, write, add images and video, zoom, pan, copy and paste, undo and redo—everything you'd expect from a canvas.
+
+You'll be starting from our default [shapes](/docs/shapes), [tools](/docs/tools), and [user interface](/docs/user-interface), but you can customize all of these things for your project if you wish. For now, let's show off a few more features.
+
+## Local persistence
+
+Let's add local persistence by passing a `persistenceKey` prop to the `Tldraw` component:
+
+<FocusLines lines={[4]}>
+
+```tsx
+export default function App() {
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw persistenceKey="example" />
+		</div>
+	)
+}
+```
+
+</FocusLines>
+
+The `persistenceKey` prop saves your project to the browser's storage so that it survives a refresh. It also synchronizes the project with other instances that share the same key—even in other browser tabs! Give it a try by opening your app in a second window.
+
+## Real-time collaboration
+
+To add support for multiple users collaborating in real time, you can use the [**tldraw sync**](/docs/sync) library. Its demo hook connects your app to tldraw's demo server, which hosts temporary rooms.
+
+First, install the `@tldraw/sync` package:
+
+```bash
+npm install @tldraw/sync
+```
+
+Next, import the `useSyncDemo` hook from the `@tldraw/sync` package. Call it in your component with a unique ID and pass the store that it returns to the `Tldraw` component:
+
+<FocusLines lines={[2,6,10]}>
+
+```tsx
+import { Tldraw } from 'tldraw'
+import { useSyncDemo } from '@tldraw/sync'
+import 'tldraw/tldraw.css'
+
+export default function App() {
+	const store = useSyncDemo({ roomId: 'insert-any-string-here' })
+
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw store={store} />
+		</div>
+	)
+}
+```
+
+</FocusLines>
+
+Try it out by opening your project in a second incognito window, or else access it from another device. You should see all of tldraw's multiplayer features: live cursors, user names, viewport following, cursor chat, and more.
+
+If you want to go further with real-time collaboration, be sure to check out our guide to the [**tldraw sync**](/docs/sync) library.
+
+## Controlling the canvas
+
+The tldraw [editor](/docs/editor) has a runtime JavaScript API. Everything that can happen in tldraw can be done programmatically through the [Editor](?) instance.
+
+For simplicity's sake, let's roll back our persistence and sync code. We can then use the `Tldraw` component's `onMount` callback to get access to the Editor instance. We'll use the editor to create a new shape on the canvas, select it, then slowly zoom to it.
+
+```tsx
+import { Editor, Tldraw, toRichText } from 'tldraw'
+import 'tldraw/tldraw.css'
+
+export default function App() {
+	const handleMount = (editor: Editor) => {
+		editor.createShape({
+			type: 'text',
+			x: 200,
+			y: 200,
+			props: {
+				richText: toRichText('Hello world!'),
+			},
+		})
+
+		editor.selectAll()
+
+		editor.zoomToSelection({
+			animation: { duration: 5000 },
+		})
+	}
+
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw onMount={handleMount} />
+		</div>
+	)
+}
+```
+
+The Editor is tldraw's main interface for controlling the canvas. Be sure to check out the [Editor](?) API documentation for more information on what you can do with it, as well as our [guide on using the editor](/docs/editor).
+
+## Next steps
+
+Now that you've seen how the tldraw canvas works, you can:
+
+- Create your own [shapes](/docs/shapes) and [tools](/docs/tools)
+- Customize the [user interface](/docs/user-interface)
+- Learn more about the [editor](/docs/editor)
+- Explore our [examples](/examples)
+- Build with our [starter kits](/starter-kits)
+
+The SDK lets you customize shapes, tools, UI, and more. In addition to our long-form docs, we have dozens of examples in our [examples section](/examples) that cover more of its functionality. You can run these locally with the tldraw [GitHub repository](https://github.com/tldraw/tldraw).
+
+## Join our community
+
+If you build something great, please share it with us in our [#show-and-tell](https://discord.tldraw.com/?utm_source=docs&utm_medium=organic&utm_campaign=sociallink) channel on Discord. Good luck!

apps/docs/content/getting-started/releases.mdx

@@ -0,0 +1,76 @@
+---
+title: Releases
+status: published
+author: steveruizok
+order: 3
+---
+
+Release notes for all tldraw SDK versions. Each minor release has its own page documenting new features, breaking changes, API additions, improvements, and bug fixes. Patch releases are listed within their parent minor release.
+
+For the original releases, see the [GitHub releases page](https://github.com/tldraw/tldraw/releases).
+
+## How tldraw is versioned
+
+Unlike many JavaScript packages distributed on [NPM](https://www.npmjs.com/), the tldraw SDK does not follow [semantic versioning](https://semver.org/) in its release versions. Instead:
+
+- Major version bumps are rare. We reserve them for fundamental changes to how the SDK works.
+- Minor version bumps are released on a regular cadence, approximately monthly. **They may contain breaking changes**. We aim to make breaking changes as minimally disruptive as possible, but tldraw is actively evolving as we add new features. We recommend updating at a similar pace and checking the release notes.
+- Patch version bumps are for bugfixes and hotfixes that can't wait for the next cadence release.
+
+## Latest tldraw versions
+
+- Run `npm install tldraw` to get the latest minor version of tldraw
+- Use `npm install tldraw@next` to get the latest version of tldraw that is used on [tldraw.com](https://www.tldraw.com)
+- The latest changes to the `main` branch of tldraw are available to test through our [pre-release canary builds](https://www.npmjs.com/package/tldraw?activeTab=versions).
+
+## Migration skill
+
+We ship an experimental `tldraw-migrate` agent skill that helps a coding agent update your project to the latest version of the SDK. It detects your current version, fetches the relevant release notes, upgrades packages, and works through any type errors using the migration guides in our release notes. See our [migration skill guide](/releases/migration-skill) for details on how to install and use the skill.
+
+## Next
+
+- [next](/releases/next) - Changes for the upcoming release.
+
+## v5.x
+
+- [v5.4](/releases/v5.4.0) - A center align operation, a tleditors registry of mounted editors, faster signals and store layers, and a broad reliability pass across the SDK
+- [v5.3](/releases/v5.3.0) - Commenting with anchored threads on the canvas, new collaboration packages, geo shape flipping, crop snapping, and faster viewport culling
+- [v5.2](/releases/v5.2.0) - Faster freehand ink, a frame selection action, SDK-wide performance improvements, and breaking changes to the collaborator user-id types and Node support
+- [v5.1](/releases/v5.1.0) - Page menu redesign, copy-styles shortcut, selectable locked shapes, public translation APIs, and performance improvements
+- [v5.0](/releases/v5.0.0) - Custom themes, overlays, performance, extensiblity, and attribution
+
+## v4.x
+
+- [v4.5](/releases/v4.5.0) - Click-through on transparent pixels, SVG sanitization, configurable embed definitions
+- [v4.4](/releases/v4.4.0) - Image pipeline starter kit, performance improvements, quick zoom, canvas indicators
+- [v4.3](/releases/v4.3.0) - SQLite sync storage, improved custom shape types, reactive inputs, draw shape encoding
+- [v4.2](/releases/v4.2.0) - TipTap v3, dynamic tools, custom socket implementations
+- [v4.1](/releases/v4.1.0) - Shader starter kit, localStorage atoms, minimap filtering
+- [v4.0](/releases/v4.0.0) - Starter kits, WCAG 2.2 AA compliance, licensing updates
+
+## v3.x
+
+- [v3.15](/releases/v3.15.0) - `npm create tldraw` CLI, accessibility improvements
+- [v3.14](/releases/v3.14.0) - Contextual toolbars, PathBuilder API
+- [v3.13](/releases/v3.13.0) - Elbow arrows for technical diagrams
+- [v3.12](/releases/v3.12.0) - Accessibility focus, keyboard navigation
+- [v3.11](/releases/v3.11.0) - Rich text fixes, zoom improvements
+- [v3.10](/releases/v3.10.0) - Rich text as first-class primitive
+- [v3.9](/releases/v3.9.0) - Layout improvements, AtomMap class
+- [v3.8](/releases/v3.8.0) - React 19 compatibility, i18n expansion
+- [v3.7](/releases/v3.7.0) - Presence sync customization
+- [v3.6](/releases/v3.6.0) - Expanded action helpers
+- [v3.5](/releases/v3.5.0) - Grid snapping, layer improvements
+- [v3.4](/releases/v3.4.0) - Excalidraw compatibility
+- [v3.3](/releases/v3.3.0) - Readonly mode, sync improvements
+- [v3.2](/releases/v3.2.0) - Version alignment release
+- [v3.1](/releases/v3.1.0) - Shape visibility, server-side updates
+- [v3.0](/releases/v3.0.0) - New licensing, deep links, custom embeds
+
+## v2.x
+
+- [v2.4](/releases/v2.4.0)
+- [v2.3](/releases/v2.3.0)
+- [v2.2](/releases/v2.2.0)
+- [v2.1](/releases/v2.1.0)
+- [v2.0](/releases/v2.0.0) - Initial public release