fix(images): use dual DPI baselines for correct pixelRatio on all platforms (tldraw#8163)

High-DPI PNGs (e.g. Retina screenshots) store their logical size in
`asset.props.w`/`h`, but their actual pixel dimensions are larger.
Without knowing the pixel ratio, the CDN image resize endpoints cap the
requested width at the logical size, returning a downscaled image that
looks blurry on retina displays.

This PR adds an optional `pixelRatio` property to `TLImageAsset`,
populated from the PNG pHYs chunk via `MediaHelpers.getImageSize()`, and
uses it in both `multiplayerAssetStore` and `createDemoAssetStore` to
request the correct pixel-level width from image transform endpoints.

The pHYs DPI detection now tries both standard baselines — 96 DPI
(Windows/web) and 72 DPI (macOS) — and picks whichever yields a clean
integer ratio above 1. This correctly handles all common cases:

| Image DPI | Source | pixelRatio |
|-----------|--------|------------|
| 72 | macOS 1x | 1 |
| 96 | Windows 1x / web standard | 1 |
| 144 | macOS 2x Retina | 2 |
| 192 | Windows 2x HiDPI | 2 |
| 216 | macOS 3x | 3 |
| 288 | Windows 3x | 3 |

The previous implementation used 72 DPI as the sole baseline, which was
only correct for macOS. Any standard 96 DPI PNG (extremely common from
Windows and tools like Photoshop/GIMP) got a pixelRatio of ~1.333,
causing those images to appear ~25% smaller than intended.

before+after (looking at her blue hair can show you the crispness of the
lines)
<img width="1171" height="1065" alt="Screenshot 2026-03-05 at 15 15 46"
src="https://github.com/user-attachments/assets/83ccf063-27b4-48bc-9c72-0ca021087dcb"
/>
<img width="1158" height="1070" alt="Screenshot 2026-03-05 at 16 19 34"
src="https://github.com/user-attachments/assets/715dd7d6-288f-4342-8929-173c5741808b"
/>


### Change type

- [x] `improvement`

### API changes

- Added optional `pixelRatio` property to `TLImageAsset`
- Added `pixelRatio: number` to `MediaHelpers.getImageSize()` return
type
- Added migration `AddPixelRatio` (version 6) for image assets

### Test plan

1. Drop a macOS 2x Retina screenshot (144 DPI pHYs) onto the canvas —
should get `pixelRatio: 2` and display at half its pixel dimensions
2. Drop a standard Windows/web PNG (96 DPI pHYs) — should get no
`pixelRatio` set (treated as 1) and display at full pixel size
3. Drop a Windows HiDPI screenshot (192 DPI) — should get `pixelRatio:
2`
4. Zoom in/out on a high-DPI image and confirm the resolved image URL
requests width scaled by the pixel ratio

- [x] Unit tests

### Release notes

- Fix high-DPI image sizing to work correctly across macOS and Windows
by detecting the source DPI baseline from the PNG metadata.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Introduces a new optional `TLImageAsset.props.pixelRatio` and uses it
to change how resized image URLs are computed, which can affect image
rendering quality and bandwidth/costs across clients. Also updates
schema validation/migrations and `MediaHelpers.getImageSize`’s return
type, so downstream consumers may need to handle the new field.
> 
> **Overview**
> Fixes blurry/incorrectly scaled high-DPI PNG rendering by *recording
the source `pixelRatio` on image assets* and using it when generating
resize URLs.
> 
> `MediaHelpers.getImageSize` now returns `{ w, h, pixelRatio }` and
detects pixel ratio from PNG `pHYs` using dual 96/72 DPI baselines.
`TLImageAsset` gains optional `pixelRatio` with validator + migration
(`AddPixelRatio`), and both `multiplayerAssetStore` and the sync demo
asset store scale requested transform width by `w * pixelRatio` to fetch
true-resolution images.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
864fe31. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: mimecuvalo

apps/dotcom/client/src/utils/multiplayerAssetStore.ts

@@ -125,13 +125,15 @@ export function multiplayerAssetStore(opts?: {
 				const networkCompensation =
 					!context.networkEffectiveType || context.networkEffectiveType === '4g' ? 1 : 0.5
 
+				const pixelRatio = asset.props.pixelRatio ?? 1
+				const trueWidth = asset.props.w * pixelRatio
 				const width = Math.ceil(
 					Math.min(
-						asset.props.w *
+						trueWidth *
 							clamp(context.steppedScreenScale, 1 / 32, 1) *
 							networkCompensation *
 							context.dpr,
-						asset.props.w
+						trueWidth
 					)
 				)
 

packages/sync/src/useSyncDemo.ts

@@ -236,13 +236,15 @@ function createDemoAssetStore(host: string): TLAssetStore {
 				const networkCompensation =
 					!context.networkEffectiveType || context.networkEffectiveType === '4g' ? 1 : 0.5
 
+				const pixelRatio = asset.props.pixelRatio ?? 1
+				const trueWidth = asset.props.w * pixelRatio
 				const width = Math.ceil(
 					Math.min(
-						asset.props.w *
+						trueWidth *
 							clamp(context.steppedScreenScale, 1 / 32, 1) *
 							networkCompensation *
 							context.dpr,
-						asset.props.w
+						trueWidth
 					)
 				)
 

packages/tldraw/src/lib/defaultExternalContentHandlers.ts

@@ -666,6 +666,8 @@ export async function getMediaAssetInfoPartial(
 
 	const isAnimated = (await MediaHelpers.isAnimated(file)) || isVideoType
 
+	const pixelRatio = 'pixelRatio' in size && size.pixelRatio !== 1 ? size.pixelRatio : undefined
+
 	const assetInfo = {
 		id: assetId,
 		type: isImageType ? 'image' : 'video',
@@ -678,6 +680,7 @@ export async function getMediaAssetInfoPartial(
 			fileSize: file.size,
 			mimeType: fileType,
 			isAnimated,
+			...(isImageType && pixelRatio ? { pixelRatio } : undefined),
 		},
 		meta: {},
 	} as TLImageAsset | TLVideoAsset

packages/tlschema/api-report.api.md

@@ -1134,6 +1134,7 @@ export type TLImageAsset = TLBaseAsset<'image', {
     isAnimated: boolean;
     mimeType: null | string;
     name: string;
+    pixelRatio?: number;
     src: null | string;
     w: number;
 }>;

packages/tlschema/src/assets/TLImageAsset.ts

@@ -17,6 +17,7 @@ export type TLImageAsset = TLBaseAsset<
 		mimeType: string | null
 		src: string | null
 		fileSize?: number
+		pixelRatio?: number
 	}
 >
 
@@ -60,6 +61,7 @@ export const imageAssetValidator: T.Validator<TLImageAsset> = createAssetValidat
 		mimeType: T.string.nullable(),
 		src: T.srcUrl.nullable(),
 		fileSize: T.nonZeroNumber.optional(),
+		pixelRatio: T.positiveNumber.optional(),
 	})
 )
 
@@ -69,6 +71,7 @@ const Versions = createMigrationIds('com.tldraw.asset.image', {
 	MakeUrlsValid: 3,
 	AddFileSize: 4,
 	MakeFileSizeOptional: 5,
+	AddPixelRatio: 6,
 } as const)
 
 /**
@@ -165,5 +168,14 @@ export const imageAssetMigrations = createRecordMigrationSequence({
 				}
 			},
 		},
+		{
+			id: Versions.AddPixelRatio,
+			up: (_asset: any) => {
+				// noop — pixelRatio is optional and undefined by default
+			},
+			down: (asset: any) => {
+				delete asset.props.pixelRatio
+			},
+		},
 	],
 })

packages/tlschema/src/migrations.test.ts

@@ -2102,6 +2102,21 @@ describe('Make image asset file size optional', () => {
 	})
 })
 
+describe('Add pixelRatio to image asset', () => {
+	const { up, down } = getTestMigration(imageAssetVersions.AddPixelRatio)
+
+	test('up works as expected', () => {
+		expect(up({ props: { w: 100, h: 100 } })).toEqual({ props: { w: 100, h: 100 } })
+	})
+
+	test('down works as expected', () => {
+		expect(down({ props: { w: 100, h: 100, pixelRatio: 2 } })).toEqual({
+			props: { w: 100, h: 100 },
+		})
+		expect(down({ props: { w: 100, h: 100 } })).toEqual({ props: { w: 100, h: 100 } })
+	})
+})
+
 describe('Add flipX, flipY to image shape', () => {
 	const { up, down } = getTestMigration(imageShapeVersions.AddFlipProps)
 

packages/utils/api-report.api.md

@@ -300,6 +300,7 @@ export class MediaHelpers {
     }>;
     static getImageSize(blob: Blob): Promise<{
         h: number;
+        pixelRatio: number;
         w: number;
     }>;
     static getVideoFrameAsDataUrl(video: HTMLVideoElement, time?: number): Promise<string>;

packages/utils/src/lib/media/media.ts

@@ -309,7 +309,7 @@ export class MediaHelpers {
 	 * ```
 	 * @public
 	 */
-	static async getImageSize(blob: Blob): Promise<{ w: number; h: number }> {
+	static async getImageSize(blob: Blob): Promise<{ w: number; h: number; pixelRatio: number }> {
 		const { w, h } = await MediaHelpers.usingObjectURL(blob, MediaHelpers.getImageAndDimensions)
 
 		try {
@@ -320,25 +320,33 @@ export class MediaHelpers {
 					if (physChunk) {
 						const physData = PngHelpers.parsePhys(view, physChunk.dataOffset)
 						if (physData.unit === 1 && physData.ppux === physData.ppuy) {
-							// Calculate pixels per meter:
-							// - 1 inch = 0.0254 meters
-							// - 72 DPI is 72 dots per inch
-							// - pixels per meter = 72 / 0.0254
-							const pixelsPerMeter = 72 / 0.0254
-							const pixelRatio = Math.max(physData.ppux / pixelsPerMeter, 1)
-							return {
-								w: Math.round(w / pixelRatio),
-								h: Math.round(h / pixelRatio),
+							const dpi = Math.round(physData.ppux * 0.0254)
+							// Try both standard baselines: Windows/web = 96, macOS = 72.
+							// Pick whichever yields a clean integer ratio > 1.
+							const r96 = dpi / 96
+							const r72 = dpi / 72
+							let pixelRatio = 1
+							if (Number.isInteger(r96) && r96 > 1) {
+								pixelRatio = r96
+							} else if (Number.isInteger(r72) && r72 > 1) {
+								pixelRatio = r72
+							}
+							if (pixelRatio > 1) {
+								return {
+									w: Math.ceil(w / pixelRatio),
+									h: Math.ceil(h / pixelRatio),
+									pixelRatio,
+								}
 							}
 						}
 					}
 				}
 			}
 		} catch (err) {
 			console.error(err)
-			return { w, h }
+			return { w, h, pixelRatio: 1 }
 		}
-		return { w, h }
+		return { w, h, pixelRatio: 1 }
 	}
 
 	/**