Skip to content

AI-native design editor. Open-source Figma alternative.

perf(canvas): rebuild navigation rendering (#591)

Danila Poyarkov379ef8b62db4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index af6bdcafa..508b47616 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
### Added
+- Add a timestamp-faithful pan and zoom benchmark workflow with physical macOS trackpad recording, CDP and DOM replay, Chromium traces, frame-pacing and latency distributions, zoom-anchor drift and viewport-jump detection, retained-backing settlement metrics, and a documented native Instruments acceptance procedure.
+
- Choose and persist the app interface language from General settings.
- Duplicate guides with Option/Alt-drag, show active guide coordinates in rulers, measure ruler-created guides against selected frames and their contents, and remove guides from the context menu.
- Create, select, move, transfer, and delete canvas and frame guides directly from rulers, with undoable edits and `.fig` round-trip fidelity.
@@ -56,6 +58,8 @@
### Performance
+- Keep rapid trackpad zoom reversals responsive on complex documents by cancelling obsolete high-resolution scene reconstruction and settling only after navigation becomes idle.
+- Keep zooming responsive on effect-heavy documents by reusing bounded, invalidation-aware raster snapshots for supported shadow effects while retaining vector-picture fallbacks for backdrop-dependent and oversized effects.
- Show the FIG page list from a lightweight Kiwi scan before materializing the full document, making large files feel responsive sooner.
- Avoid redundant collaboration writes when synchronized node fields have not changed.
- Release obsolete streamed Markdown parser history after each AI response completes, preventing chat memory from multiplying with every streamed chunk. (#544)
diff --git a/bun.lock b/bun.lock
index 44711623b..9f7f39725 100644
--- a/bun.lock
+++ b/bun.lock
@@ -190,6 +190,7 @@
"ofetch": "^1.5.1",
"opentype.js": "^2.0.0",
"pptxgenjs": "^4.0.1",
+ "rbush": "^4.0.1",
"sucrase": "^3.35.1",
"svg-path-properties": "^2.0.2",
"svg2pdf.js": "^2.7.0",
@@ -202,6 +203,7 @@
"@types/culori": "^4.0.1",
"@types/diff": "^8.0.0",
"@types/opentype.js": "^1.3.10",
+ "@types/rbush": "^4.0.0",
"typescript": "~5.8.3",
},
},
@@ -1761,6 +1763,8 @@
"@types/raf": ["@types/[email protected]", "", {}, "sha512-c4YAvMedbPZ5tEyxzQdMoOhhJ4RD3rngZIdwC2/qDN3d7JpEhB6fiBRKVY1lg5B7Wk+uPBjn5f39j1/2MY1oOw=="],
+ "@types/rbush": ["@types/[email protected]", "", {}, "sha512-+N+2H39P8X+Hy1I5mC6awlTX54k3FhiUmvt7HWzGJZvF+syUAAxP/stwppS8JE84YHqFgRMv6fCy31202CMFxQ=="],
+
"@types/react": ["@types/[email protected]", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-AnzbBERsrLKtk2XSfTbYRLjQPdy116Sty4q+T+Bp3IC4l6jNBvreVPAHmpq9qhXQM7CXZPjLVmGMw9sy+hxQ3w=="],
"@types/readable-stream": ["@types/[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-NRvUNC/JFGPJvqdAfEve8oginbM6V08u5NzLWpG8MwA2kTPOLnqk+wpwuPT+mp3aUsxyuT6m2gnrPuHYCruzEg=="],
@@ -3637,6 +3641,8 @@
"quickjs-emscripten-core": ["[email protected]", "", { "dependencies": { "@jitl/quickjs-ffi-types": "0.32.0" } }, "sha512-QFnPfjFey8EqknSrSxe1hZrf1/8z7/6s1QzGOmKo6++02r7QRRX7ZoyNaZh7JuVjWsVW87KnQrbZqnHkOAzUyg=="],
+ "quickselect": ["[email protected]", "", {}, "sha512-XdjUArbK4Bm5fLLvlm5KpTFOiOThgfWWI4axAZDWg4E/0mKdZyI9tNEfds27qCi1ze/vwTR16kvmmGhRra3c2g=="],
+
"quote-unquote": ["[email protected]", "", {}, "sha512-twwRO/ilhlG/FIgYeKGFqyHhoEhqgnKVkcmqMKi2r524gz3ZbDTcyFt38E9xjJI2vT+KbRNHVbnJ/e0I25Azwg=="],
"race-event": ["[email protected]", "", { "dependencies": { "abort-error": "^1.0.1" } }, "sha512-vi7WH5g5KoTFpu2mme/HqZiWH14XSOtg5rfp6raBskBHl7wnmy3F/biAIyY5MsK+BHWhoPhxtZ1Y2R7OHHaWyQ=="],
@@ -3653,6 +3659,8 @@
"raw-body": ["[email protected]", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
+ "rbush": ["[email protected]", "", { "dependencies": { "quickselect": "^3.0.0" } }, "sha512-IP0UpfeWQujYC8Jg162rMNc01Rf0gWMMAb2Uxus/Q0qOFw4lCcq6ZnQEZwUoJqWyUGJ9th7JjwI4yIWo+uvoAQ=="],
+
"rc": ["[email protected]", "", { "dependencies": { "deep-extend": "^0.6.0", "ini": "~1.3.0", "minimist": "^1.2.0", "strip-json-comments": "~2.0.1" }, "bin": { "rc": "./cli.js" } }, "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw=="],
"re2js": ["[email protected]", "", {}, "sha512-KTOIcZTSOpOxbu3i0+T6mFQ6tkxXKlTxfcMFs1trQbsMnG84qNq+DjXr8Afu+FEFjvF1NNlldpC7roPyazFI8g=="],
diff --git a/package.json b/package.json
index f0eef7053..9d9e89b3f 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,8 @@
"build-storybook": "storybook build",
"tauri": "tauri",
"build:native-test": "bun run build:packages && bun tauri build --debug --no-bundle --features native-test --config desktop/tauri.native-test.conf.json",
+ "benchmark:navigation": "bun tools/navigation-benchmark/src/cli.ts run",
+ "benchmark:navigation:test": "bun test tools/navigation-benchmark/tests",
"test:native": "bun run build:native-test && wdio run wdio.conf.ts",
"lint": "bun run lint:structure && oxlint -c oxlint.json --type-aware --type-check src/ packages/scene-graph/src/ packages/core/src/ packages/vue/src/ packages/cli/src/ packages/mcp/src/ packages/harness/src/ packages/dom-css/src/ packages/pen/src/ packages/kiwi/src/ packages/fig/src/",
"lint:structure": "oxlint -c oxlint.json vite.config.ts vite/ .storybook/ src/ packages/scene-graph/src/ packages/scene-graph/scripts/ packages/core/src/ packages/vue/src/ packages/cli/src/ packages/mcp/src/ packages/harness/src/ packages/harness/tests/ packages/dom-css/src/ packages/dom-css/tests/ packages/dom-css/scripts/ packages/pen/src/ packages/pen/scripts/ packages/kiwi/src/ packages/kiwi/tests/ packages/kiwi/scripts/ packages/fig/src/ packages/fig/tests/ packages/fig/scripts/ tests/ scripts/ tools/",
diff --git a/packages/core/package.json b/packages/core/package.json
index 4a309049e..affda0e42 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -196,6 +196,7 @@
"ofetch": "^1.5.1",
"opentype.js": "^2.0.0",
"pptxgenjs": "^4.0.1",
+ "rbush": "^4.0.1",
"sucrase": "^3.35.1",
"svg-path-properties": "^2.0.2",
"svg2pdf.js": "^2.7.0",
@@ -208,6 +209,7 @@
"@types/culori": "^4.0.1",
"@types/diff": "^8.0.0",
"@types/opentype.js": "^1.3.10",
+ "@types/rbush": "^4.0.0",
"typescript": "~5.8.3"
}
}
diff --git a/packages/core/src/canvas/renderer.ts b/packages/core/src/canvas/renderer.ts
index 855b26950..b9bd426a2 100644
--- a/packages/core/src/canvas/renderer.ts
+++ b/packages/core/src/canvas/renderer.ts
@@ -29,6 +29,7 @@ import { destroyRenderer } from './renderer/lifecycle'
import { installRendererDomainMethods } from './renderer/methods'
import { initializeRendererPaints } from './renderer/paints'
import * as RenderPipeline from './renderer/pipeline'
+import type { SceneBacking, SceneBackingBuild } from './renderer/retained-backing/types'
import * as RendererState from './renderer/state'
import * as RenderText from './text'
export type { MeasurementMode, RenderOverlays, RulerTheme } from './renderer/types'
@@ -61,6 +62,8 @@ export interface PendingFontNode {
keys: Set<string>
}
+import type { EffectRasterCacheEntry } from './renderer/effect-raster-cache'
+import { TiledSceneController } from './renderer/tiles'
import type { RenderOverlays, RulerTheme } from './renderer/types'
export class SkiaRenderer {
@@ -101,58 +104,31 @@ export class SkiaRenderer {
strokeGeometryCache = new Map<string, Path[]>()
/** Path-text glyph silhouettes (stroke-and-union, font units) keyed by blob hash + relative weight. */
glyphSilhouetteCache = new Map<string, Path>()
+ renderingSceneBacking = false
scenePicture: SkPicture | null = null
scenePictureVersion = -1
scenePictureFontGeneration = -1
scenePicturePositionPreviewVersion = -1
scenePicturePageId: string | null = null
- sceneBacking: {
- image: CKImage
- pageId: string | null
- sceneVersion: number
- positionPreviewVersion: number
- fontGeneration: number
- panX: number
- panY: number
- zoom: number
- width: number
- height: number
- dpr: number
- worldX: number
- worldY: number
- worldWidth: number
- worldHeight: number
- } | null = null
+ sceneBacking: SceneBacking | null = null
sceneBackingPreviewUntil = 0
sceneBackingNeedsCrispRender = false
sceneBackingAllocationFailed = false
- sceneBackingBuild: {
- surface: Surface
- graph: SceneGraph
- childIds: string[]
- index: number
- startedAt: number
- pageId: string | null
- sceneVersion: number
- positionPreviewVersion: number
- fontGeneration: number
- panX: number
- panY: number
- zoom: number
- width: number
- height: number
- dpr: number
- worldX: number
- worldY: number
- worldWidth: number
- worldHeight: number
- } | null = null
+ sceneBackingBuild: SceneBackingBuild | null = null
sceneBackingAverageRecordMs = 40
sceneBackingAverageViewportIntervalMs = 80
sceneBackingLastViewportEventAt = 0
+ navigationPhase: EditorState['navigation']['phase'] = 'idle'
+ navigationGeneration = 0
+ tiledSceneEnabled = false
+ tracksSceneSettlement = true
+ tiledScenePending = false
+ tiledSceneCovered = false
lastSceneViewport: { panX: number; panY: number; zoom: number } | null = null
nodePictureCache = new Map<string, SkPicture | null>()
nodePictureCacheGenerations = new Map<string, number>()
+ nodePictureCacheDependencies = new Map<string, readonly string[]>()
+ effectRasterCache = new Map<string, EffectRasterCacheEntry>()
subtreePictureCache = new Map<string, SubtreePictureCacheEntry>()
subtreePictureCachePageId: string | null = null
subtreePictureCacheSceneVersion = -1
@@ -160,6 +136,7 @@ export class SkiaRenderer {
subtreePictureCacheFontGeneration = -1
readonly labelCache = new LabelCache()
readonly labelParagraphCache = new LabelParagraphCache()
+ readonly tiledScene = new TiledSceneController()
readonly profiler: RenderProfiler
declare rulerBgPaint: Paint
@@ -185,6 +162,7 @@ export class SkiaRenderer {
rulerTheme: RulerTheme | null = null
pageId: string | null = null
+ boundEffectLayersToViewport = false
worldViewport = { x: 0, y: 0, w: 0, h: 0 }
_nodeCount = 0
_culledCount = 0
@@ -278,6 +256,12 @@ export class SkiaRenderer {
) => void
declare drawSectionTitles: (canvas: Canvas, graph: SceneGraph) => void
declare drawComponentLabels: (canvas: Canvas, graph: SceneGraph) => void
+ declare renderNodeSelf: (
+ canvas: Canvas,
+ graph: SceneGraph,
+ nodeId: string,
+ overlays?: RenderOverlays
+ ) => void
declare renderNode: (
canvas: Canvas,
graph: SceneGraph,
@@ -466,6 +450,7 @@ export class SkiaRenderer {
}
replaceSurface(surface: Surface): void {
+ this.tiledScene.destroy()
this.surface.delete()
this.surface = surface
this.sceneBackingAllocationFailed = false
diff --git a/packages/core/src/canvas/renderer/chunks/cache.ts b/packages/core/src/canvas/renderer/chunks/cache.ts
new file mode 100644
index 000000000..82913c1b7
--- /dev/null
+++ b/packages/core/src/canvas/renderer/chunks/cache.ts
@@ -0,0 +1,45 @@
+import type { SkPicture } from 'canvaskit-wasm'
+
+import type { SceneGraph } from '@open-pencil/scene-graph'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+
+import type { RenderChunk } from './index'
+import { recordRenderChunk } from './record'
+
+interface CachedChunkPicture {
+ picture: SkPicture
+ fontGeneration: number
+}
+
+export class RenderChunkPictureCache {
+ private readonly entries = new Map<string, CachedChunkPicture>()
+
+ get(renderer: SkiaRenderer, graph: SceneGraph, chunk: RenderChunk): SkPicture {
+ const cached = this.entries.get(chunk.id)
+ if (cached?.fontGeneration === renderer.fontGeneration) return cached.picture
+ cached?.picture.delete()
+ this.entries.delete(chunk.id)
+ const recorded = recordRenderChunk(renderer, graph, chunk)
+ this.entries.set(chunk.id, {
+ picture: recorded.picture,
+ fontGeneration: renderer.fontGeneration
+ })
+ return recorded.picture
+ }
+
+ invalidate(chunkId: string): void {
+ const entry = this.entries.get(chunkId)
+ entry?.picture.delete()
+ this.entries.delete(chunkId)
+ }
+
+ clear(): void {
+ for (const entry of this.entries.values()) entry.picture.delete()
+ this.entries.clear()
+ }
+
+ size(): number {
+ return this.entries.size
+ }
+}
diff --git a/packages/core/src/canvas/renderer/chunks/index.ts b/packages/core/src/canvas/renderer/chunks/index.ts
new file mode 100644
index 000000000..f987038ed
--- /dev/null
+++ b/packages/core/src/canvas/renderer/chunks/index.ts
@@ -0,0 +1,303 @@
+import RBush from 'rbush'
+
+import type { SceneGraph, SceneNode } from '@open-pencil/scene-graph'
+import { getWorldMatrix } from '@open-pencil/scene-graph/coordinate'
+import { computeDescendantVisualBounds } from '@open-pencil/scene-graph/geometry'
+import type { Mat3 } from '@open-pencil/scene-graph/matrix'
+import Matrix from '@open-pencil/scene-graph/matrix'
+
+import { worldNodeVisualBounds } from '#core/canvas/renderer/visual-bounds'
+
+export type RenderChunkKind = 'self' | 'subtree'
+
+export interface RenderChunkContext {
+ parentTransform: Mat3
+ ancestorClipIds: string[]
+}
+
+export interface RenderChunk {
+ id: string
+ nodeId: string
+ kind: RenderChunkKind
+ context: RenderChunkContext
+ interruptible: boolean
+ painterOrder: number
+ minX: number
+ minY: number
+ maxX: number
+ maxY: number
+ nodeCount: number
+ estimatedCost: number
+}
+
+export interface RenderChunkBuildStats {
+ nodesVisited: number
+ chunksBuilt: number
+ maximumChunkNodes: number
+ maximumAtomicChunkNodes: number
+ oversizedAtomicChunks: number
+}
+
+const MAX_CHUNK_NODES = 32
+
+export function nodeRequiresAtomicChunk(graph: SceneGraph, node: SceneNode): boolean {
+ const isolated =
+ node.opacity < 1 ||
+ (node.blendMode !== 'NORMAL' && node.blendMode !== 'PASS_THROUGH') ||
+ node.effects.some(
+ (effect) =>
+ effect.visible &&
+ (effect.type === 'LAYER_BLUR' ||
+ effect.type === 'FOREGROUND_BLUR' ||
+ effect.type === 'BACKGROUND_BLUR')
+ )
+ const hasMasks = node.childIds.some((childId) => graph.getNode(childId)?.isMask === true)
+ return isolated || hasMasks
+}
+
+function shouldSplit(graph: SceneGraph, node: SceneNode, descendantCount: number): boolean {
+ return (
+ node.childIds.length > 0 &&
+ descendantCount > MAX_CHUNK_NODES &&
+ !nodeRequiresAtomicChunk(graph, node)
+ )
+}
+
+function estimateCost(nodeCount: number, node: SceneNode): number {
+ const visibleEffects = node.effects.filter((effect) => effect.visible).length
+ return nodeCount + visibleEffects * 8
+}
+
+function subtreeBounds(graph: SceneGraph, nodeId: string) {
+ return computeDescendantVisualBounds(
+ [nodeId],
+ (id) => graph.getNode(id),
+ (id) => graph.getAbsolutePosition(id)
+ )
+}
+
+function clipAncestorIds(graph: SceneGraph, node: SceneNode): string[] {
+ const ids: string[] = []
+ let parent = node.parentId ? graph.getNode(node.parentId) : undefined
+ while (parent) {
+ if (parent.clipsContent) ids.unshift(parent.id)
+ parent = parent.parentId ? graph.getNode(parent.parentId) : undefined
+ }
+ return ids
+}
+
+function chunkContext(graph: SceneGraph, node: SceneNode): RenderChunkContext {
+ const parent = node.parentId ? graph.getNode(node.parentId) : undefined
+ return {
+ parentTransform: parent ? getWorldMatrix(parent, graph) : Matrix.identity(),
+ ancestorClipIds: clipAncestorIds(graph, node)
+ }
+}
+
+function countDescendants(graph: SceneGraph, nodeIds: string[]) {
+ const counts = new Map<string, number>()
+ let visited = 0
+ const stack: Array<{ nodeId: string; expanded: boolean }> = nodeIds.map((nodeId) => ({
+ nodeId,
+ expanded: false
+ }))
+ while (stack.length > 0) {
+ const entry = stack.pop()
+ if (!entry) continue
+ const node = graph.getNode(entry.nodeId)
+ if (!node?.visible) continue
+ if (!entry.expanded) {
+ visited++
+ stack.push({ nodeId: entry.nodeId, expanded: true })
+ for (const childId of node.childIds) stack.push({ nodeId: childId, expanded: false })
+ continue
+ }
+ let count = 1
+ for (const childId of node.childIds) count += counts.get(childId) ?? 0
+ counts.set(node.id, count)
+ }
+ return { counts, visited }
+}
+
+function buildChunks(graph: SceneGraph, nodeIds: string[], counts: Map<string, number>) {
+ const chunks: RenderChunk[] = []
+ let painterOrder = 0
+ const stack = [...nodeIds].reverse()
+ while (stack.length > 0) {
+ const nodeId = stack.pop()
+ if (!nodeId) continue
+ const node = graph.getNode(nodeId)
+ if (!node?.visible) continue
+ const descendantCount = counts.get(nodeId) ?? 1
+ const split = shouldSplit(graph, node, descendantCount)
+ const kind: RenderChunkKind = split ? 'self' : 'subtree'
+ const bounds = split ? worldNodeVisualBounds(graph, node) : subtreeBounds(graph, nodeId)
+ if (bounds) {
+ const nodeCount = split ? 1 : descendantCount
+ chunks.push({
+ id: `${nodeId}:${kind}`,
+ nodeId,
+ kind,
+ context: chunkContext(graph, node),
+ interruptible: split || !nodeRequiresAtomicChunk(graph, node),
+ painterOrder: painterOrder++,
+ ...bounds,
+ nodeCount,
+ estimatedCost: estimateCost(nodeCount, node)
+ })
+ }
+ if (!split) continue
+ for (let childIndex = node.childIds.length - 1; childIndex >= 0; childIndex--) {
+ const childId = node.childIds[childIndex]
+ if (childId) stack.push(childId)
+ }
+ }
+ return chunks
+}
+
+export class RenderChunkIndex {
+ private readonly tree = new RBush<RenderChunk>()
+ private readonly chunks = new Map<string, RenderChunk>()
+ private readonly chunkIdsByNode = new Map<string, Set<string>>()
+ private readonly chunkIdsByDependency = new Map<string, Set<string>>()
+
+ static build(
+ graph: SceneGraph,
+ pageId: string
+ ): { index: RenderChunkIndex; stats: RenderChunkBuildStats } {
+ const index = new RenderChunkIndex()
+ const page = graph.getNode(pageId)
+ if (!page) {
+ return {
+ index,
+ stats: {
+ nodesVisited: 0,
+ chunksBuilt: 0,
+ maximumChunkNodes: 0,
+ maximumAtomicChunkNodes: 0,
+ oversizedAtomicChunks: 0
+ }
+ }
+ }
+
+ const { counts, visited } = countDescendants(graph, page.childIds)
+ const chunks = buildChunks(graph, page.childIds, counts)
+ index.bulkLoad(chunks, graph)
+ return {
+ index,
+ stats: {
+ nodesVisited: visited,
+ chunksBuilt: chunks.length,
+ maximumChunkNodes: chunks.reduce((maximum, chunk) => Math.max(maximum, chunk.nodeCount), 0),
+ maximumAtomicChunkNodes: chunks.reduce(
+ (maximum, chunk) => (chunk.interruptible ? maximum : Math.max(maximum, chunk.nodeCount)),
+ 0
+ ),
+ oversizedAtomicChunks: chunks.filter(
+ (chunk) => !chunk.interruptible && chunk.nodeCount > MAX_CHUNK_NODES
+ ).length
+ }
+ }
+ }
+
+ bulkLoad(chunks: RenderChunk[], graph?: SceneGraph): void {
+ this.tree.clear()
+ this.chunks.clear()
+ this.chunkIdsByNode.clear()
+ this.chunkIdsByDependency.clear()
+ this.tree.load(chunks)
+ for (const chunk of chunks) {
+ this.chunks.set(chunk.id, chunk)
+ const ids = this.chunkIdsByNode.get(chunk.nodeId) ?? new Set<string>()
+ ids.add(chunk.id)
+ this.chunkIdsByNode.set(chunk.nodeId, ids)
+ if (graph) this.indexDependencies(graph, chunk)
+ }
+ }
+
+ search(bounds: Pick<RenderChunk, 'minX' | 'minY' | 'maxX' | 'maxY'>): RenderChunk[] {
+ return this.tree.search(bounds).sort((a, b) => a.painterOrder - b.painterOrder)
+ }
+
+ updateNode(graph: SceneGraph, nodeId: string): number {
+ const ids = this.chunkIdsByNode.get(nodeId)
+ const node = graph.getNode(nodeId)
+ if (!ids || !node) return 0
+ let updated = 0
+ for (const id of ids) {
+ const chunk = this.chunks.get(id)
+ if (!chunk) continue
+ this.tree.remove(chunk)
+ const bounds =
+ chunk.kind === 'self' ? worldNodeVisualBounds(graph, node) : subtreeBounds(graph, nodeId)
+ if (!bounds) {
+ this.tree.insert(chunk)
+ continue
+ }
+ Object.assign(chunk, bounds, { context: chunkContext(graph, node) })
+ this.tree.insert(chunk)
+ updated++
+ }
+ return updated
+ }
+
+ getChunksForNode(nodeId: string): RenderChunk[] {
+ return [...(this.chunkIdsByNode.get(nodeId) ?? [])].flatMap((id) => {
+ const chunk = this.chunks.get(id)
+ return chunk ? [chunk] : []
+ })
+ }
+
+ getChunksDependingOnNode(nodeId: string): RenderChunk[] {
+ return [...(this.chunkIdsByDependency.get(nodeId) ?? [])].flatMap((id) => {
+ const chunk = this.chunks.get(id)
+ return chunk ? [chunk] : []
+ })
+ }
+
+ private indexDependencies(graph: SceneGraph, chunk: RenderChunk): void {
+ const dependencies = new Set<string>()
+ let ancestor = graph.getNode(chunk.nodeId)
+ while (ancestor) {
+ dependencies.add(ancestor.id)
+ ancestor = ancestor.parentId ? graph.getNode(ancestor.parentId) : undefined
+ }
+ if (chunk.kind === 'subtree') {
+ const pending = [chunk.nodeId]
+ const visited = new Set<string>()
+ while (pending.length > 0) {
+ const id = pending.pop()
+ if (!id || visited.has(id)) continue
+ visited.add(id)
+ dependencies.add(id)
+ const node = graph.getNode(id)
+ if (node) pending.push(...node.childIds)
+ }
+ }
+ for (const dependencyId of dependencies) {
+ const ids = this.chunkIdsByDependency.get(dependencyId) ?? new Set<string>()
+ ids.add(chunk.id)
+ this.chunkIdsByDependency.set(dependencyId, ids)
+ }
+ }
+
+ size(): number {
+ return this.chunks.size
+ }
+
+ dispose(): void {
+ this.tree.clear()
+ this.chunks.clear()
+ this.chunkIdsByNode.clear()
+ this.chunkIdsByDependency.clear()
+ }
+}
+
+export { RenderChunkPictureCache } from './cache'
+export {
+ deleteRecordedRenderChunks,
+ drawRecordedRenderChunks,
+ drawRenderChunkDirect,
+ recordRenderChunk
+} from './record'
+export type { RecordedRenderChunk } from './record'
diff --git a/packages/core/src/canvas/renderer/chunks/record.ts b/packages/core/src/canvas/renderer/chunks/record.ts
new file mode 100644
index 000000000..99b0662ee
--- /dev/null
+++ b/packages/core/src/canvas/renderer/chunks/record.ts
@@ -0,0 +1,89 @@
+import type { Canvas, SkPicture } from 'canvaskit-wasm'
+
+import type { SceneGraph, SceneNode } from '@open-pencil/scene-graph'
+import { getWorldMatrix } from '@open-pencil/scene-graph/coordinate'
+import Matrix from '@open-pencil/scene-graph/matrix'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+import { clipNodeShape, nodeHasRadius } from '#core/canvas/shapes'
+
+import type { RenderChunk } from './index'
+
+export interface RecordedRenderChunk {
+ chunk: RenderChunk
+ picture: SkPicture
+}
+
+function clipAncestor(r: SkiaRenderer, canvas: Canvas, graph: SceneGraph, node: SceneNode): void {
+ canvas.concat(getWorldMatrix(node, graph))
+ clipNodeShape(r, canvas, node, r.ck.LTRBRect(0, 0, node.width, node.height), nodeHasRadius(node))
+ const inverse = Matrix.invert(getWorldMatrix(node, graph))
+ if (inverse) canvas.concat(inverse)
+}
+
+function drawChunkContent(
+ renderer: SkiaRenderer,
+ canvas: Canvas,
+ graph: SceneGraph,
+ chunk: RenderChunk
+): void {
+ canvas.save()
+ for (const ancestorId of chunk.context.ancestorClipIds) {
+ const ancestor = graph.getNode(ancestorId)
+ if (ancestor) clipAncestor(renderer, canvas, graph, ancestor)
+ }
+ canvas.concat(chunk.context.parentTransform)
+ if (chunk.kind === 'self') renderer.renderNodeSelf(canvas, graph, chunk.nodeId)
+ else renderer.renderNode(canvas, graph, chunk.nodeId, {}, 0, 0, true)
+ canvas.restore()
+}
+
+function withChunkViewport(renderer: SkiaRenderer, chunk: RenderChunk, draw: () => void): void {
+ const previousViewport = renderer.worldViewport
+ renderer.worldViewport = {
+ x: chunk.minX,
+ y: chunk.minY,
+ w: chunk.maxX - chunk.minX,
+ h: chunk.maxY - chunk.minY
+ }
+ try {
+ draw()
+ } finally {
+ renderer.worldViewport = previousViewport
+ }
+}
+
+export function drawRenderChunkDirect(
+ renderer: SkiaRenderer,
+ canvas: Canvas,
+ graph: SceneGraph,
+ chunk: RenderChunk
+): void {
+ withChunkViewport(renderer, chunk, () => drawChunkContent(renderer, canvas, graph, chunk))
+}
+
+export function recordRenderChunk(
+ renderer: SkiaRenderer,
+ graph: SceneGraph,
+ chunk: RenderChunk
+): RecordedRenderChunk {
+ const recorder = new renderer.ck.PictureRecorder()
+ try {
+ const canvas = recorder.beginRecording(
+ renderer.ck.LTRBRect(chunk.minX, chunk.minY, chunk.maxX, chunk.maxY)
+ )
+ withChunkViewport(renderer, chunk, () => drawChunkContent(renderer, canvas, graph, chunk))
+ const picture = recorder.finishRecordingAsPicture()
+ return { chunk, picture }
+ } finally {
+ recorder.delete()
+ }
+}
+
+export function drawRecordedRenderChunks(canvas: Canvas, chunks: RecordedRenderChunk[]): void {
+ for (const recorded of chunks) canvas.drawPicture(recorded.picture)
+}
+
+export function deleteRecordedRenderChunks(chunks: RecordedRenderChunk[]): void {
+ for (const recorded of chunks) recorded.picture.delete()
+}
diff --git a/packages/core/src/canvas/renderer/clock.ts b/packages/core/src/canvas/renderer/clock.ts
new file mode 100644
index 000000000..41ce6e873
--- /dev/null
+++ b/packages/core/src/canvas/renderer/clock.ts
@@ -0,0 +1,3 @@
+export function rendererNow(): number {
+ return typeof performance === 'undefined' ? Date.now() : performance.now()
+}
diff --git a/packages/core/src/canvas/renderer/effect-raster-cache.ts b/packages/core/src/canvas/renderer/effect-raster-cache.ts
new file mode 100644
index 000000000..b3226be04
--- /dev/null
+++ b/packages/core/src/canvas/renderer/effect-raster-cache.ts
@@ -0,0 +1,95 @@
+import type { Image as CKImage } from 'canvaskit-wasm'
+
+export interface EffectRasterCacheEntry {
+ image: CKImage
+ left: number
+ top: number
+ width: number
+ height: number
+ scale: number
+ pixels: number
+ fontGeneration: number
+ dependencyIds: readonly string[]
+}
+
+const MAX_EFFECT_RASTER_CACHE_PIXELS = 24_000_000
+const MAX_EFFECT_RASTER_ENTRY_PIXELS = 1_000_000
+const MIN_EFFECT_RASTER_SCALE = 1
+const MAX_EFFECT_RASTER_SCALE = 4
+const EFFECT_RASTER_SCALE_STEP = 0.25
+const MIN_REUSABLE_SCALE_RATIO = 0.85
+const MAX_REUSABLE_SCALE_RATIO = 1.25
+
+export function effectRasterScale(targetScale: number): number {
+ const quantized = Math.ceil(targetScale / EFFECT_RASTER_SCALE_STEP) * EFFECT_RASTER_SCALE_STEP
+ return Math.min(MAX_EFFECT_RASTER_SCALE, Math.max(MIN_EFFECT_RASTER_SCALE, quantized))
+}
+
+export function effectRasterScaleMatches(cachedScale: number, targetScale: number): boolean {
+ const ratio = cachedScale / targetScale
+ return ratio >= MIN_REUSABLE_SCALE_RATIO && ratio <= MAX_REUSABLE_SCALE_RATIO
+}
+
+export function canCacheEffectRaster(width: number, height: number, scale: number): boolean {
+ return (
+ width > 0 &&
+ height > 0 &&
+ Math.ceil(width * scale) * Math.ceil(height * scale) <= MAX_EFFECT_RASTER_ENTRY_PIXELS
+ )
+}
+
+export function installEffectRaster(
+ cache: Map<string, EffectRasterCacheEntry>,
+ nodeId: string,
+ entry: EffectRasterCacheEntry
+): void {
+ const previous = cache.get(nodeId)
+ previous?.image.delete()
+ cache.delete(nodeId)
+ cache.set(nodeId, entry)
+
+ let pixels = 0
+ for (const value of cache.values()) pixels += value.pixels
+ while (pixels > MAX_EFFECT_RASTER_CACHE_PIXELS) {
+ const oldest = cache.entries().next().value
+ if (!oldest) break
+ const [oldestId, oldestEntry] = oldest
+ cache.delete(oldestId)
+ oldestEntry.image.delete()
+ pixels -= oldestEntry.pixels
+ }
+}
+
+export function touchEffectRaster(
+ cache: Map<string, EffectRasterCacheEntry>,
+ nodeId: string
+): EffectRasterCacheEntry | null {
+ const entry = cache.get(nodeId)
+ if (!entry) return null
+ cache.delete(nodeId)
+ cache.set(nodeId, entry)
+ return entry
+}
+
+export function deleteEffectRaster(
+ cache: Map<string, EffectRasterCacheEntry>,
+ nodeId: string
+): void {
+ const entry = cache.get(nodeId)
+ entry?.image.delete()
+ cache.delete(nodeId)
+}
+
+export function deleteEffectRasterDependencies(
+ cache: Map<string, EffectRasterCacheEntry>,
+ nodeId: string
+): void {
+ for (const [ownerId, entry] of cache) {
+ if (entry.dependencyIds.includes(nodeId)) deleteEffectRaster(cache, ownerId)
+ }
+}
+
+export function clearEffectRasterCache(cache: Map<string, EffectRasterCacheEntry>): void {
+ for (const entry of cache.values()) entry.image.delete()
+ cache.clear()
+}
diff --git a/packages/core/src/canvas/renderer/lifecycle.ts b/packages/core/src/canvas/renderer/lifecycle.ts
index 373e00b49..741537adf 100644
--- a/packages/core/src/canvas/renderer/lifecycle.ts
+++ b/packages/core/src/canvas/renderer/lifecycle.ts
@@ -1,4 +1,5 @@
import type { SkiaRenderer } from '#core/canvas/renderer'
+import { clearEffectRasterCache } from '#core/canvas/renderer/effect-raster-cache'
import { clearSubtreePictureCache } from '#core/canvas/renderer/state'
import { fontManager } from '#core/text/fonts'
@@ -73,6 +74,8 @@ export function destroyRenderer(r: SkiaRenderer): void {
for (const pic of r.nodePictureCache.values()) pic?.delete()
r.nodePictureCache.clear()
r.labelParagraphCache.clear()
+ clearEffectRasterCache(r.effectRasterCache)
+ r.tiledScene.destroy()
clearSubtreePictureCache(r)
clearRetainedSceneState(r)
r._flashPaint?.delete()
diff --git a/packages/core/src/canvas/renderer/methods.ts b/packages/core/src/canvas/renderer/methods.ts
index 3b447f7f6..5b02faf7f 100644
--- a/packages/core/src/canvas/renderer/methods.ts
+++ b/packages/core/src/canvas/renderer/methods.ts
@@ -159,6 +159,15 @@ const rendererMethods: ThisType<SkiaRenderer> = {
Labels.drawComponentLabels(this, canvas, graph)
},
+ renderNodeSelf(
+ canvas: Canvas,
+ graph: SceneGraph,
+ nodeId: string,
+ overlays?: RenderOverlays
+ ): void {
+ SceneRender.renderNodeSelf(this, canvas, graph, nodeId, overlays)
+ },
+
renderNode(
canvas: Canvas,
graph: SceneGraph,
diff --git a/packages/core/src/canvas/renderer/pipeline.ts b/packages/core/src/canvas/renderer/pipeline.ts
index 9d44349ca..5ade3ea60 100644
--- a/packages/core/src/canvas/renderer/pipeline.ts
+++ b/packages/core/src/canvas/renderer/pipeline.ts
@@ -5,6 +5,7 @@ import { computeDescendantVisualBounds } from '@open-pencil/scene-graph/geometry
import type { RenderOverlays, SkiaRenderer } from '#core/canvas/renderer'
import type { EditorState } from '#core/editor/types'
+import { emitNavigationTrace } from '#core/profiler'
import { drawChromePass, drawLabelPass, drawOverlayPass } from './overlay-pass'
import { renderSceneBacking, updateSceneBackingPreviewState } from './retained-backing'
@@ -49,6 +50,8 @@ export function renderFromEditorState(
r.pageColor = state.pageColor
r.rulerTheme = state.rulerTheme ?? null
r.pageId = state.currentPageId
+ r.navigationPhase = state.navigation.phase
+ r.navigationGeneration = state.navigation.generation
render(
r,
graph,
@@ -140,6 +143,13 @@ export function render(
sceneVersion = -1,
layer: RenderLayer = 'full'
): void {
+ emitNavigationTrace('render:start', {
+ layer,
+ sceneVersion,
+ panX: r.panX,
+ panY: r.panY,
+ zoom: r.zoom
+ })
r.syncFontGeneration()
const p = r.profiler
p.beginFrame()
@@ -183,13 +193,41 @@ export function render(
canvas.scale(r.dpr, r.dpr)
p.beginPhase('render:scene')
+ let renderedScene = false
+ if (layer === 'scene' && !requiresUncachedSceneRender && r.tiledSceneEnabled) {
+ const backingPresented = renderSceneBacking(r, canvas, graph, sceneVersion)
+ if (!backingPresented) {
+ canvas.save()
+ canvas.translate(r.panX, r.panY)
+ canvas.scale(r.zoom, r.zoom)
+ renderSceneContent(
+ r,
+ canvas,
+ graph,
+ overlays,
+ sceneVersion,
+ canUsePicture,
+ cacheMissReason,
+ requiresUncachedSceneRender
+ )
+ canvas.restore()
+ }
+ const tiled = r.tiledScene.renderFrame(r, canvas, graph, sceneVersion, r.navigationGeneration)
+ r.tiledScenePending = tiled.pending
+ r.tiledSceneCovered = tiled.covered
+ renderedScene = true
+ p.setScenePictureMode('hit', tiled.covered ? 'tiled' : 'tiled-fallback')
+ }
if (
+ !renderedScene &&
layer === 'scene' &&
!requiresUncachedSceneRender &&
renderSceneBacking(r, canvas, graph, sceneVersion)
) {
+ renderedScene = true
p.setScenePictureMode('hit', 'backing')
- } else {
+ }
+ if (!renderedScene) {
canvas.translate(r.panX, r.panY)
canvas.scale(r.zoom, r.zoom)
renderSceneContent(
@@ -231,6 +269,17 @@ export function render(
p.setNodeCounts(r._nodeCount, r._culledCount)
p.endFrame()
+ emitNavigationTrace('render:end', {
+ layer,
+ sceneVersion,
+ panX: r.panX,
+ panY: r.panY,
+ zoom: r.zoom,
+ flushMs: flushDuration,
+ nodes: r._nodeCount,
+ culledNodes: r._culledCount,
+ backingCrisp: !r.sceneBackingNeedsCrispRender
+ })
}
function renderSceneContent(
@@ -291,44 +340,48 @@ function recordScenePicture(
sceneVersion: number
): void {
r.scenePicture?.delete()
+ r.scenePicture = null
const prevViewport = r.worldViewport
r.worldViewport = { x: -1e6, y: -1e6, w: 2e6, h: 2e6 }
const recorder = new r.ck.PictureRecorder()
- const pageNode = graph.getNode(r.pageId ?? graph.rootId)
- const sceneContentBounds = pageNode
- ? computeDescendantVisualBounds(
- pageNode.childIds,
- (id) => graph.getNode(id),
- (id) => graph.getAbsolutePosition(id)
- )
- : null
- const sceneBounds = sceneContentBounds
- ? {
- x: sceneContentBounds.minX,
- y: sceneContentBounds.minY,
- width: sceneContentBounds.maxX - sceneContentBounds.minX,
- height: sceneContentBounds.maxY - sceneContentBounds.minY
+ try {
+ const pageNode = graph.getNode(r.pageId ?? graph.rootId)
+ const sceneContentBounds = pageNode
+ ? computeDescendantVisualBounds(
+ pageNode.childIds,
+ (id) => graph.getNode(id),
+ (id) => graph.getAbsolutePosition(id)
+ )
+ : null
+ const sceneBounds = sceneContentBounds
+ ? {
+ x: sceneContentBounds.minX,
+ y: sceneContentBounds.minY,
+ width: sceneContentBounds.maxX - sceneContentBounds.minX,
+ height: sceneContentBounds.maxY - sceneContentBounds.minY
+ }
+ : { x: 0, y: 0, width: 1, height: 1 }
+ const padding = 1024
+ const bounds = r.ck.LTRBRect(
+ sceneBounds.x - padding,
+ sceneBounds.y - padding,
+ sceneBounds.x + sceneBounds.width + padding,
+ sceneBounds.y + sceneBounds.height + padding
+ )
+ const recCanvas = recorder.beginRecording(bounds)
+ if (pageNode) {
+ for (const childId of pageNode.childIds) {
+ r.renderNode(recCanvas, graph, childId, {})
}
- : { x: 0, y: 0, width: 1, height: 1 }
- const padding = 1024
- const bounds = r.ck.LTRBRect(
- sceneBounds.x - padding,
- sceneBounds.y - padding,
- sceneBounds.x + sceneBounds.width + padding,
- sceneBounds.y + sceneBounds.height + padding
- )
- const recCanvas = recorder.beginRecording(bounds)
- if (pageNode) {
- for (const childId of pageNode.childIds) {
- r.renderNode(recCanvas, graph, childId, {})
}
+ r.scenePicture = recorder.finishRecordingAsPicture()
+ r.scenePictureVersion = sceneVersion
+ r.scenePictureFontGeneration = r.fontGeneration
+ r.scenePicturePositionPreviewVersion = graph.positionPreviewVersion
+ r.scenePicturePageId = r.pageId
+ canvas.drawPicture(r.scenePicture)
+ } finally {
+ recorder.delete()
+ r.worldViewport = prevViewport
}
- r.scenePicture = recorder.finishRecordingAsPicture()
- recorder.delete()
- r.worldViewport = prevViewport
- r.scenePictureVersion = sceneVersion
- r.scenePictureFontGeneration = r.fontGeneration
- r.scenePicturePositionPreviewVersion = graph.positionPreviewVersion
- r.scenePicturePageId = r.pageId
- canvas.drawPicture(r.scenePicture)
}
diff --git a/packages/core/src/canvas/renderer/retained-backing.ts b/packages/core/src/canvas/renderer/retained-backing.ts
index de95c28e8..fec5d0856 100644
--- a/packages/core/src/canvas/renderer/retained-backing.ts
+++ b/packages/core/src/canvas/renderer/retained-backing.ts
@@ -1,75 +1,28 @@
+/* eslint-disable max-lines -- retained backing allocation, coverage, and incremental construction share renderer state */
import type { Canvas, Image as CKImage, Surface } from 'canvaskit-wasm'
-import { getWorldMatrix, TransformMatrix, type SceneGraph } from '@open-pencil/scene-graph'
+import { type SceneGraph } from '@open-pencil/scene-graph'
import {
computeDescendantVisualBounds,
- effectOverflow,
- strokeOverflow,
unionVisualBounds,
type VisualBounds
} from '@open-pencil/scene-graph/geometry'
import type { SkiaRenderer } from '#core/canvas/renderer'
import { clearSubtreePictureCache } from '#core/canvas/renderer/state'
+import { worldNodeVisualBounds } from '#core/canvas/renderer/visual-bounds'
+import { emitNavigationTrace } from '#core/profiler'
-import type { RenderLayer } from './pipeline'
+import { clamp, smoothAverage } from './retained-backing/timing'
+import type { SceneBackingGeometry } from './retained-backing/types'
+
+export { updateSceneBackingPreviewState } from './retained-backing/preview'
const now = typeof performance !== 'undefined' ? () => performance.now() : () => 0
const SCENE_BACKING_SCALE = 3
const MAX_SCENE_BACKING_DEVICE_PIXELS = 16_000_000
-const FRAME_BUDGET_60HZ_MS = 1000 / 60
-const MIN_SCENE_BACKING_IDLE_FRAMES = 2
-const MAX_SCENE_BACKING_IDLE_FRAMES = 18
-const MAX_SCENE_BACKING_QUIET_INPUT_INTERVALS = 4
const SCENE_BACKING_BUILD_BUDGET_MS = 6
-function clamp(value: number, min: number, max: number): number {
- return Math.min(max, Math.max(min, value))
-}
-
-function smoothAverage(previous: number, next: number, weight = 0.2): number {
- return previous * (1 - weight) + next * weight
-}
-
-function sceneBackingPreviewIdleMs(r: SkiaRenderer): number {
- const minDelay = FRAME_BUDGET_60HZ_MS * MIN_SCENE_BACKING_IDLE_FRAMES
- const maxDelay = FRAME_BUDGET_60HZ_MS * MAX_SCENE_BACKING_IDLE_FRAMES
- const renderMs = clamp(r.sceneBackingAverageRecordMs, minDelay, maxDelay)
- const inputIntervalMs = clamp(r.sceneBackingAverageViewportIntervalMs, 1, maxDelay)
- if (inputIntervalMs > FRAME_BUDGET_60HZ_MS * MAX_SCENE_BACKING_QUIET_INPUT_INTERVALS) {
- return renderMs
- }
-
- const expectedEventsDuringRender = renderMs / inputIntervalMs
- const quietInputIntervals = clamp(
- expectedEventsDuringRender,
- 1,
- MAX_SCENE_BACKING_QUIET_INPUT_INTERVALS
- )
- return clamp(Math.max(renderMs, inputIntervalMs * quietInputIntervals), minDelay, maxDelay)
-}
-
-export function updateSceneBackingPreviewState(r: SkiaRenderer, layer: RenderLayer): void {
- if (layer !== 'scene') return
- const previous = r.lastSceneViewport
- const viewportChanged =
- !previous || previous.panX !== r.panX || previous.panY !== r.panY || previous.zoom !== r.zoom
- if (viewportChanged) {
- const timestamp = now()
- if (r.sceneBackingLastViewportEventAt > 0) {
- const interval = timestamp - r.sceneBackingLastViewportEventAt
- r.sceneBackingAverageViewportIntervalMs = smoothAverage(
- r.sceneBackingAverageViewportIntervalMs,
- clamp(interval, 1, 500)
- )
- }
- r.sceneBackingLastViewportEventAt = timestamp
- r.sceneBackingPreviewUntil = timestamp + sceneBackingPreviewIdleMs(r)
- r.sceneBackingNeedsCrispRender = !!r.sceneBacking
- r.lastSceneViewport = { panX: r.panX, panY: r.panY, zoom: r.zoom }
- }
-}
-
function backingMetadataMatches(
r: SkiaRenderer,
sceneVersion: number,
@@ -170,7 +123,7 @@ function sceneBackingScale(r: SkiaRenderer): number {
)
}
-function sceneBackingGeometry(r: SkiaRenderer) {
+function sceneBackingGeometry(r: SkiaRenderer): SceneBackingGeometry {
const backingScale = sceneBackingScale(r)
const marginX = r.viewportWidth * ((backingScale - 1) / 2)
const marginY = r.viewportHeight * ((backingScale - 1) / 2)
@@ -257,26 +210,7 @@ export function computeRetainedSubtreeBounds(
const node = graph.getNode(nodeId)
if (!node?.visible) continue
- const stroke = strokeOverflow(node.strokes)
- const effects = effectOverflow(node.effects)
- const points = TransformMatrix.mapPoints(getWorldMatrix(node, graph), [
- -stroke - effects.left,
- -stroke - effects.top,
- node.width + stroke + effects.right,
- -stroke - effects.top,
- node.width + stroke + effects.right,
- node.height + stroke + effects.bottom,
- -stroke - effects.left,
- node.height + stroke + effects.bottom
- ])
- const xs = [points[0], points[2], points[4], points[6]]
- const ys = [points[1], points[3], points[5], points[7]]
- transformedBounds = unionVisualBounds(transformedBounds, {
- minX: Math.min(...xs),
- minY: Math.min(...ys),
- maxX: Math.max(...xs),
- maxY: Math.max(...ys)
- })
+ transformedBounds = unionVisualBounds(transformedBounds, worldNodeVisualBounds(graph, node))
pending.push(...node.childIds)
}
@@ -302,32 +236,36 @@ function cachedSubtreePicture(
}
cached?.picture.delete()
+ r.subtreePictureCache.delete(childId)
const bounds = computeRetainedSubtreeBounds(graph, childId)
if (!bounds) return null
const recorder = new r.ck.PictureRecorder()
- const recCanvas = recorder.beginRecording(
- r.ck.LTRBRect(bounds.minX, bounds.minY, bounds.maxX, bounds.maxY)
- )
const prevViewport = r.worldViewport
- r.worldViewport = {
- x: bounds.minX,
- y: bounds.minY,
- w: bounds.maxX - bounds.minX,
- h: bounds.maxY - bounds.minY
+ try {
+ const recCanvas = recorder.beginRecording(
+ r.ck.LTRBRect(bounds.minX, bounds.minY, bounds.maxX, bounds.maxY)
+ )
+ r.worldViewport = {
+ x: bounds.minX,
+ y: bounds.minY,
+ w: bounds.maxX - bounds.minX,
+ h: bounds.maxY - bounds.minY
+ }
+ r.renderNode(recCanvas, graph, childId, {})
+ const picture = recorder.finishRecordingAsPicture()
+ r.subtreePictureCache.set(childId, {
+ picture,
+ pageId: r.pageId,
+ sceneVersion,
+ positionPreviewVersion: graph.positionPreviewVersion,
+ fontGeneration: r.fontGeneration
+ })
+ return picture
+ } finally {
+ r.worldViewport = prevViewport
+ recorder.delete()
}
- r.renderNode(recCanvas, graph, childId, {})
- r.worldViewport = prevViewport
- const picture = recorder.finishRecordingAsPicture()
- recorder.delete()
- r.subtreePictureCache.set(childId, {
- picture,
- pageId: r.pageId,
- sceneVersion,
- positionPreviewVersion: graph.positionPreviewVersion,
- fontGeneration: r.fontGeneration
- })
- return picture
}
function renderBackingChild(
@@ -335,7 +273,7 @@ function renderBackingChild(
graph: SceneGraph,
surface: Surface,
childId: string,
- backing: ReturnType<typeof sceneBackingGeometry>,
+ backing: SceneBackingGeometry,
sceneVersion: number
): void {
const canvas = surface.getCanvas()
@@ -347,17 +285,35 @@ function renderBackingChild(
h: backing.worldHeight
}
canvas.save()
- canvas.scale(r.dpr, r.dpr)
- canvas.translate(backing.panX, backing.panY)
- canvas.scale(r.zoom, r.zoom)
- const picture = cachedSubtreePicture(r, graph, childId, sceneVersion)
- if (picture) canvas.drawPicture(picture)
- else r.renderNode(canvas, graph, childId, {})
- canvas.restore()
- r.worldViewport = prevViewport
+ try {
+ canvas.scale(r.dpr, r.dpr)
+ canvas.translate(backing.panX, backing.panY)
+ canvas.scale(r.zoom, r.zoom)
+ const previousRenderingSceneBacking = r.renderingSceneBacking
+ const child = graph.getNode(childId)
+ const hasCacheableEffects = child?.effects.some(
+ (effect) =>
+ effect.visible && (effect.type === 'DROP_SHADOW' || effect.type === 'INNER_SHADOW')
+ )
+ if (hasCacheableEffects) {
+ r.renderingSceneBacking = true
+ try {
+ r.renderNode(canvas, graph, childId, {})
+ } finally {
+ r.renderingSceneBacking = previousRenderingSceneBacking
+ }
+ } else {
+ const picture = cachedSubtreePicture(r, graph, childId, sceneVersion)
+ if (picture) canvas.drawPicture(picture)
+ else r.renderNode(canvas, graph, childId, {})
+ }
+ } finally {
+ canvas.restore()
+ r.worldViewport = prevViewport
+ }
}
-function sceneBackingMetrics(backing: ReturnType<typeof sceneBackingGeometry>) {
+function sceneBackingMetrics(backing: SceneBackingGeometry): SceneBackingGeometry {
return {
panX: backing.panX,
panY: backing.panY,
@@ -377,7 +333,7 @@ function installSceneBackingImage(
image: CKImage,
sceneVersion: number,
positionPreviewVersion: number,
- backing: ReturnType<typeof sceneBackingGeometry>
+ backing: SceneBackingGeometry
): void {
r.sceneBacking?.image.delete()
r.sceneBacking = {
@@ -434,9 +390,18 @@ function startSceneBackingBuild(r: SkiaRenderer, graph: SceneGraph, sceneVersion
fontGeneration: r.fontGeneration,
...sceneBackingMetrics(backing)
}
+ emitNavigationTrace('backing:build', {
+ phase: 'start',
+ childCount: r.sceneBackingBuild.childIds.length,
+ panX: backing.panX,
+ panY: backing.panY,
+ zoom: backing.zoom
+ })
}
-function sceneBackingGeometryFromBuild(build: NonNullable<SkiaRenderer['sceneBackingBuild']>) {
+function sceneBackingGeometryFromBuild(
+ build: NonNullable<SkiaRenderer['sceneBackingBuild']>
+): SceneBackingGeometry {
return {
panX: build.panX,
panY: build.panY,
@@ -470,11 +435,20 @@ function stepSceneBackingBuild(r: SkiaRenderer, sceneVersion: number): boolean {
if (build.index < build.childIds.length) return true
- build.surface.flush()
- const image = build.surface.makeImageSnapshot()
- build.surface.delete()
- r.sceneBackingBuild = null
+ let image: CKImage
+ try {
+ build.surface.flush()
+ image = build.surface.makeImageSnapshot()
+ } finally {
+ build.surface.delete()
+ r.sceneBackingBuild = null
+ }
installSceneBackingImage(r, image, build.sceneVersion, build.positionPreviewVersion, backing)
+ emitNavigationTrace('backing:crisp', {
+ buildMs: now() - build.startedAt,
+ childCount: build.childIds.length,
+ zoom: backing.zoom
+ })
r.sceneBackingAverageRecordMs = smoothAverage(
r.sceneBackingAverageRecordMs,
clamp(now() - build.startedAt, 1, 1_000)
@@ -488,21 +462,30 @@ function recordSceneBacking(r: SkiaRenderer, graph: SceneGraph, sceneVersion: nu
const surface = createSceneBackingSurface(r, backing.width, backing.height)
if (!surface) return
const canvas = surface.getCanvas()
- canvas.clear(r.ck.Color4f(r.pageColor.r, r.pageColor.g, r.pageColor.b, 1))
- const pageNode = graph.getNode(r.pageId ?? graph.rootId)
- if (pageNode) {
- for (const childId of pageNode.childIds) {
- renderBackingChild(r, graph, surface, childId, backing, sceneVersion)
+ try {
+ canvas.clear(r.ck.Color4f(r.pageColor.r, r.pageColor.g, r.pageColor.b, 1))
+ const pageNode = graph.getNode(r.pageId ?? graph.rootId)
+ if (pageNode) {
+ for (const childId of pageNode.childIds) {
+ renderBackingChild(r, graph, surface, childId, backing, sceneVersion)
+ }
}
+ surface.flush()
+ const image = surface.makeImageSnapshot()
+ installSceneBackingImage(r, image, sceneVersion, graph.positionPreviewVersion, backing)
+ const recordMs = now() - startedAt
+ emitNavigationTrace('backing:crisp', {
+ buildMs: recordMs,
+ childCount: pageNode?.childIds.length ?? 0,
+ zoom: backing.zoom
+ })
+ r.sceneBackingAverageRecordMs = smoothAverage(
+ r.sceneBackingAverageRecordMs,
+ clamp(recordMs, 1, 1_000)
+ )
+ } finally {
+ surface.delete()
}
- surface.flush()
- const image = surface.makeImageSnapshot()
- surface.delete()
- installSceneBackingImage(r, image, sceneVersion, graph.positionPreviewVersion, backing)
- r.sceneBackingAverageRecordMs = smoothAverage(
- r.sceneBackingAverageRecordMs,
- clamp(now() - startedAt, 1, 1_000)
- )
}
export function renderSceneBacking(
@@ -512,6 +495,17 @@ export function renderSceneBacking(
sceneVersion: number
): boolean {
if (r.sceneBackingAllocationFailed) return false
+ const navigationActive =
+ r.navigationPhase === 'pan' ||
+ r.navigationPhase === 'zoom' ||
+ r.navigationPhase === 'momentum' ||
+ r.navigationPhase === 'settling'
+ if (navigationActive && r.sceneBacking) {
+ r.sceneBackingBuild?.surface.delete()
+ r.sceneBackingBuild = null
+ r.sceneBackingNeedsCrispRender = true
+ return drawSceneBacking(r, canvas, sceneVersion, true, graph.positionPreviewVersion)
+ }
const positionPreviewVersion = graph.positionPreviewVersion
const allowStaleZoom = now() < r.sceneBackingPreviewUntil
const hasCoverage = backingCoverageContainsLiveViewport(
diff --git a/packages/core/src/canvas/renderer/retained-backing/preview.ts b/packages/core/src/canvas/renderer/retained-backing/preview.ts
new file mode 100644
index 000000000..fdf2be6f8
--- /dev/null
+++ b/packages/core/src/canvas/renderer/retained-backing/preview.ts
@@ -0,0 +1,60 @@
+import type { SkiaRenderer } from '#core/canvas/renderer'
+import type { RenderLayer } from '#core/canvas/renderer/pipeline'
+import { clamp, smoothAverage } from '#core/canvas/renderer/retained-backing/timing'
+import { emitNavigationTrace } from '#core/profiler'
+
+const now = typeof performance !== 'undefined' ? () => performance.now() : () => 0
+const FRAME_BUDGET_60HZ_MS = 1000 / 60
+const MIN_SCENE_BACKING_IDLE_FRAMES = 2
+const MAX_SCENE_BACKING_IDLE_FRAMES = 18
+const MAX_SCENE_BACKING_QUIET_INPUT_INTERVALS = 4
+
+function previewIdleMs(r: SkiaRenderer): number {
+ const minDelay = FRAME_BUDGET_60HZ_MS * MIN_SCENE_BACKING_IDLE_FRAMES
+ const maxDelay = FRAME_BUDGET_60HZ_MS * MAX_SCENE_BACKING_IDLE_FRAMES
+ const renderMs = clamp(r.sceneBackingAverageRecordMs, minDelay, maxDelay)
+ const inputIntervalMs = clamp(r.sceneBackingAverageViewportIntervalMs, 1, maxDelay)
+ if (inputIntervalMs > FRAME_BUDGET_60HZ_MS * MAX_SCENE_BACKING_QUIET_INPUT_INTERVALS) {
+ return renderMs
+ }
+
+ const expectedEventsDuringRender = renderMs / inputIntervalMs
+ const quietInputIntervals = clamp(
+ expectedEventsDuringRender,
+ 1,
+ MAX_SCENE_BACKING_QUIET_INPUT_INTERVALS
+ )
+ return clamp(Math.max(renderMs, inputIntervalMs * quietInputIntervals), minDelay, maxDelay)
+}
+
+/**
+ * Extends preview lifetime only when the scene viewport changes. Active navigation must present an
+ * already committed backing; rebuilding during motion reintroduces input/reversal stalls.
+ */
+export function updateSceneBackingPreviewState(r: SkiaRenderer, layer: RenderLayer): void {
+ if (layer !== 'scene') return
+ const previous = r.lastSceneViewport
+ const viewportChanged =
+ !previous || previous.panX !== r.panX || previous.panY !== r.panY || previous.zoom !== r.zoom
+ if (!viewportChanged) return
+
+ const timestamp = now()
+ if (r.sceneBackingLastViewportEventAt > 0) {
+ const interval = timestamp - r.sceneBackingLastViewportEventAt
+ r.sceneBackingAverageViewportIntervalMs = smoothAverage(
+ r.sceneBackingAverageViewportIntervalMs,
+ clamp(interval, 1, 500)
+ )
+ }
+ r.sceneBackingLastViewportEventAt = timestamp
+ r.sceneBackingPreviewUntil = timestamp + previewIdleMs(r)
+ r.sceneBackingNeedsCrispRender = !!r.sceneBacking
+ emitNavigationTrace('backing:preview', {
+ previewUntil: r.sceneBackingPreviewUntil,
+ hasBacking: !!r.sceneBacking,
+ panX: r.panX,
+ panY: r.panY,
+ zoom: r.zoom
+ })
+ r.lastSceneViewport = { panX: r.panX, panY: r.panY, zoom: r.zoom }
+}
diff --git a/packages/core/src/canvas/renderer/retained-backing/timing.ts b/packages/core/src/canvas/renderer/retained-backing/timing.ts
new file mode 100644
index 000000000..ad76d28cd
--- /dev/null
+++ b/packages/core/src/canvas/renderer/retained-backing/timing.ts
@@ -0,0 +1,7 @@
+export function clamp(value: number, min: number, max: number): number {
+ return Math.min(max, Math.max(min, value))
+}
+
+export function smoothAverage(previous: number, next: number, weight = 0.2): number {
+ return previous * (1 - weight) + next * weight
+}
diff --git a/packages/core/src/canvas/renderer/retained-backing/types.ts b/packages/core/src/canvas/renderer/retained-backing/types.ts
new file mode 100644
index 000000000..9055e7b0d
--- /dev/null
+++ b/packages/core/src/canvas/renderer/retained-backing/types.ts
@@ -0,0 +1,35 @@
+import type { Image as CKImage, Surface } from 'canvaskit-wasm'
+
+import type { SceneGraph } from '@open-pencil/scene-graph'
+
+export interface RenderContentVersion {
+ pageId: string | null
+ sceneVersion: number
+ positionPreviewVersion: number
+ fontGeneration: number
+}
+
+export interface SceneBackingGeometry {
+ panX: number
+ panY: number
+ zoom: number
+ width: number
+ height: number
+ dpr: number
+ worldX: number
+ worldY: number
+ worldWidth: number
+ worldHeight: number
+}
+
+export interface SceneBacking extends RenderContentVersion, SceneBackingGeometry {
+ image: CKImage
+}
+
+export interface SceneBackingBuild extends RenderContentVersion, SceneBackingGeometry {
+ surface: Surface
+ graph: SceneGraph
+ childIds: string[]
+ index: number
+ startedAt: number
+}
diff --git a/packages/core/src/canvas/renderer/state.ts b/packages/core/src/canvas/renderer/state.ts
index 66d1c517c..d3e37f0f9 100644
--- a/packages/core/src/canvas/renderer/state.ts
+++ b/packages/core/src/canvas/renderer/state.ts
@@ -1,5 +1,11 @@
import type { SkiaRenderer } from '#core/canvas/renderer'
+import {
+ clearEffectRasterCache,
+ deleteEffectRaster,
+ deleteEffectRasterDependencies
+} from './effect-raster-cache'
+
export function invalidateScenePicture(r: SkiaRenderer): void {
r.scenePicture?.delete()
r.scenePicture = null
@@ -22,18 +28,31 @@ export function clearSubtreePictureCache(r: SkiaRenderer): void {
export function invalidateAllPictures(r: SkiaRenderer): void {
invalidateScenePicture(r)
+ r.tiledScene.invalidateStructure()
for (const pic of r.nodePictureCache.values()) pic?.delete()
r.nodePictureCache.clear()
r.nodePictureCacheGenerations.clear()
+ r.nodePictureCacheDependencies.clear()
+ clearEffectRasterCache(r.effectRasterCache)
clearSubtreePictureCache(r)
}
export function invalidateNodePicture(r: SkiaRenderer, nodeId: string): void {
+ deleteEffectRaster(r.effectRasterCache, nodeId)
+ deleteEffectRasterDependencies(r.effectRasterCache, nodeId)
+ for (const [ownerId, dependencyIds] of r.nodePictureCacheDependencies) {
+ if (!dependencyIds.includes(nodeId)) continue
+ r.nodePictureCache.get(ownerId)?.delete()
+ r.nodePictureCache.delete(ownerId)
+ r.nodePictureCacheGenerations.delete(ownerId)
+ r.nodePictureCacheDependencies.delete(ownerId)
+ }
const pic = r.nodePictureCache.get(nodeId)
if (pic) {
pic.delete()
r.nodePictureCache.delete(nodeId)
r.nodePictureCacheGenerations.delete(nodeId)
+ r.nodePictureCacheDependencies.delete(nodeId)
}
const subtree = r.subtreePictureCache.get(nodeId)
if (subtree) {
diff --git a/packages/core/src/canvas/renderer/tiles/cache.ts b/packages/core/src/canvas/renderer/tiles/cache.ts
new file mode 100644
index 000000000..da263a37b
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/cache.ts
@@ -0,0 +1,115 @@
+import type { Image as CKImage } from 'canvaskit-wasm'
+
+import { tileKeyString, tileWorldSize, type TileKey, type TileWorldBounds } from './geometry'
+import type { RenderedTile } from './render'
+
+export interface CachedTile {
+ key: TileKey
+ image: CKImage
+ contentGeneration: number
+ lastUsed: number
+ bytes: number
+}
+
+const DEFAULT_MAX_TILE_BYTES = 128 * 1024 * 1024
+
+export class TileImageCache {
+ private readonly entries = new Map<string, CachedTile>()
+ private bytes = 0
+ private clock = 0
+
+ constructor(private readonly maxBytes = DEFAULT_MAX_TILE_BYTES) {}
+
+ get(key: TileKey): CachedTile | null {
+ const id = tileKeyString(key)
+ const entry = this.entries.get(id)
+ if (!entry) return null
+ entry.lastUsed = ++this.clock
+ this.entries.delete(id)
+ this.entries.set(id, entry)
+ return entry
+ }
+
+ getIfPresent(key: TileKey): CachedTile | null {
+ return this.entries.get(tileKeyString(key)) ?? null
+ }
+
+ install(tile: RenderedTile, contentGeneration: number): CachedTile {
+ const id = tileKeyString(tile.key)
+ this.delete(id)
+ const entry: CachedTile = {
+ key: tile.key,
+ image: tile.image,
+ contentGeneration,
+ lastUsed: ++this.clock,
+ bytes: tile.image.width() * tile.image.height() * 4
+ }
+ this.entries.set(id, entry)
+ this.bytes += entry.bytes
+ this.evict()
+ return entry
+ }
+
+ markStale(contentGeneration: number): void {
+ for (const entry of this.entries.values()) {
+ if (entry.contentGeneration >= contentGeneration)
+ entry.contentGeneration = contentGeneration - 1
+ }
+ }
+
+ invalidateBounds(pageId: string, bounds: TileWorldBounds, contentGeneration: number): number {
+ let invalidated = 0
+ for (const [id, entry] of this.entries) {
+ if (entry.key.pageId !== pageId) continue
+ const size = tileWorldSize(entry.key.level)
+ const minX = entry.key.x * size
+ const minY = entry.key.y * size
+ if (
+ minX >= bounds.maxX ||
+ minY >= bounds.maxY ||
+ minX + size <= bounds.minX ||
+ minY + size <= bounds.minY
+ ) {
+ entry.contentGeneration = contentGeneration
+ continue
+ }
+ this.delete(id)
+ invalidated++
+ }
+ return invalidated
+ }
+
+ advanceGeneration(contentGeneration: number): void {
+ for (const entry of this.entries.values()) entry.contentGeneration = contentGeneration
+ }
+
+ clear(): void {
+ for (const entry of this.entries.values()) entry.image.delete()
+ this.entries.clear()
+ this.bytes = 0
+ }
+
+ size(): number {
+ return this.entries.size
+ }
+
+ byteSize(): number {
+ return this.bytes
+ }
+
+ private delete(id: string): void {
+ const entry = this.entries.get(id)
+ if (!entry) return
+ entry.image.delete()
+ this.bytes -= entry.bytes
+ this.entries.delete(id)
+ }
+
+ private evict(): void {
+ while (this.bytes > this.maxBytes) {
+ const oldest = this.entries.keys().next().value
+ if (typeof oldest !== 'string') break
+ this.delete(oldest)
+ }
+ }
+}
diff --git a/packages/core/src/canvas/renderer/tiles/controller.ts b/packages/core/src/canvas/renderer/tiles/controller.ts
new file mode 100644
index 000000000..b2049385b
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/controller.ts
@@ -0,0 +1,339 @@
+import type { Canvas } from 'canvaskit-wasm'
+
+import type { SceneGraph } from '@open-pencil/scene-graph'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+import {
+ nodeRequiresAtomicChunk,
+ RenderChunkIndex,
+ RenderChunkPictureCache
+} from '#core/canvas/renderer/chunks'
+
+import { TileImageCache } from './cache'
+import { TILE_DEVICE_SIZE, tileLevel, tileWorldBounds, type TileWorldBounds } from './geometry'
+import { planTiles } from './planner'
+import { deleteRenderedTile, renderTile, tileChunks } from './render'
+import {
+ emptyTileSchedulerMetrics,
+ TileScheduler,
+ type TileJob,
+ type TileSchedulerMetrics
+} from './scheduler'
+import { TileSurfacePool } from './surface-pool'
+import { emitTileCoverageComplete, emitTileFrameTrace } from './telemetry'
+
+const TILE_FRAME_BUDGET_MS = 5
+const MAXIMUM_TILE_JOBS_PER_FRAME = 32
+const TILE_OVERSCAN = 1
+
+export interface TiledSceneFrameResult {
+ covered: boolean
+ pending: boolean
+ metrics: TileSchedulerMetrics
+}
+
+export class TiledSceneController {
+ private index: RenderChunkIndex | null = null
+ private pageId: string | null = null
+ private contentGeneration = -1
+ private navigationGeneration = -1
+ private navigationActive = false
+ private cancelledJobs = 0
+ private pendingInvalidations: Array<{
+ nodeId: string
+ previousBounds: TileWorldBounds[]
+ }> = []
+ private lastCoveredGeneration = ''
+ private readonly pictureCache = new RenderChunkPictureCache()
+ private readonly tileCache = new TileImageCache()
+ private readonly surfacePool = new TileSurfacePool()
+ private readonly scheduler = new TileScheduler({
+ budgetMs: TILE_FRAME_BUDGET_MS,
+ maximumJobsPerFrame: MAXIMUM_TILE_JOBS_PER_FRAME
+ })
+ private readonly measuredCosts = new Map<string, number>()
+
+ invalidateNode(nodeId: string, graph?: SceneGraph): void {
+ const chunks = this.index?.getChunksDependingOnNode(nodeId) ?? []
+ const owningChunks = this.index?.getChunksForNode(nodeId) ?? []
+ const node = graph?.getNode(nodeId)
+ if (
+ graph &&
+ node &&
+ owningChunks.some((chunk) => chunk.interruptible === nodeRequiresAtomicChunk(graph, node))
+ ) {
+ this.invalidateStructure()
+ return
+ }
+ this.pendingInvalidations.push({
+ nodeId,
+ previousBounds: chunks.map(({ minX, minY, maxX, maxY }) => ({ minX, minY, maxX, maxY }))
+ })
+ }
+
+ invalidateStructure(): void {
+ this.invalidate()
+ }
+
+ renderFrame(
+ renderer: SkiaRenderer,
+ canvas: Canvas,
+ graph: SceneGraph,
+ contentGeneration: number,
+ navigationGeneration: number
+ ): TiledSceneFrameResult {
+ this.navigationGeneration = navigationGeneration
+ this.navigationActive = this.isNavigationActive(renderer)
+ this.prepareGeneration(renderer, graph, contentGeneration, navigationGeneration)
+ const index = this.index
+ if (!index || !renderer.pageId) return this.emptyResult()
+
+ const level = tileLevel(renderer.zoom * renderer.dpr)
+ const viewport = {
+ minX: -renderer.panX / renderer.zoom,
+ minY: -renderer.panY / renderer.zoom,
+ maxX: (-renderer.panX + renderer.viewportWidth) / renderer.zoom,
+ maxY: (-renderer.panY + renderer.viewportHeight) / renderer.zoom
+ }
+ const plan = planTiles(
+ this.tileCache,
+ {
+ pageId: renderer.pageId,
+ level,
+ viewport,
+ overscanTiles: TILE_OVERSCAN,
+ navigationGeneration,
+ contentGeneration,
+ estimateCost: (key) =>
+ this.measuredCosts.get(this.costKey(key)) ??
+ tileChunks(index, key).reduce((total, chunk) => total + chunk.estimatedCost, 0),
+ globalFallbackAvailable: true
+ },
+ this.navigationActive
+ )
+ if (!this.navigationActive) this.scheduler.enqueue(plan.jobs)
+ canvas.save()
+ canvas.translate(renderer.panX, renderer.panY)
+ canvas.scale(renderer.zoom, renderer.zoom)
+ const metrics = this.navigationActive
+ ? this.deferActiveJobs(plan.jobs)
+ : this.runScheduledFrame(renderer, graph, index)
+ metrics.cancelledJobs += this.cancelledJobs
+ this.cancelledJobs = 0
+ const visibleCoverage = planTiles(
+ this.tileCache,
+ {
+ pageId: renderer.pageId,
+ level,
+ viewport,
+ overscanTiles: 0,
+ navigationGeneration,
+ contentGeneration,
+ estimateCost: () => 0
+ },
+ this.navigationActive
+ )
+ const presentedTileCount = this.navigationActive
+ ? 0
+ : this.drawVisibleTiles(renderer, canvas, visibleCoverage.visible)
+ canvas.restore()
+ const covered = visibleCoverage.visible.every(({ tile }) => tile !== null)
+ emitTileFrameTrace({
+ contentGeneration,
+ metrics,
+ tileCacheBytes: this.tileCache.byteSize(),
+ tileCacheEntries: this.tileCache.size(),
+ visibleTileCount: visibleCoverage.visible.length,
+ presentedTileCount,
+ covered
+ })
+ const settledGenerationKey = `${navigationGeneration}:${contentGeneration}`
+ if (covered && !this.navigationActive && this.lastCoveredGeneration !== settledGenerationKey) {
+ this.lastCoveredGeneration = settledGenerationKey
+ emitTileCoverageComplete(
+ level,
+ contentGeneration,
+ navigationGeneration,
+ this.tileCache.size(),
+ this.tileCache.byteSize()
+ )
+ }
+ return {
+ covered,
+ pending: this.scheduler.pending() > 0 || (!covered && !this.navigationActive),
+ metrics
+ }
+ }
+
+ invalidate(): void {
+ this.cancelledJobs += this.scheduler.clear()
+ this.index?.dispose()
+ this.index = null
+ this.pageId = null
+ this.contentGeneration = -1
+ this.lastCoveredGeneration = ''
+ this.pendingInvalidations = []
+ this.measuredCosts.clear()
+ this.pictureCache.clear()
+ this.tileCache.clear()
+ }
+
+ destroy(): void {
+ this.invalidate()
+ this.cancelledJobs = 0
+ this.navigationGeneration = -1
+ this.navigationActive = false
+ this.surfacePool.clear()
+ }
+
+ private isNavigationActive(renderer: SkiaRenderer): boolean {
+ return (
+ renderer.navigationPhase === 'pan' ||
+ renderer.navigationPhase === 'zoom' ||
+ renderer.navigationPhase === 'momentum' ||
+ renderer.navigationPhase === 'settling'
+ )
+ }
+
+ private prepareGeneration(
+ renderer: SkiaRenderer,
+ graph: SceneGraph,
+ contentGeneration: number,
+ navigationGeneration: number
+ ): void {
+ this.cancelledJobs += this.scheduler.setGeneration(navigationGeneration, contentGeneration)
+ if (
+ this.index &&
+ this.pageId === renderer.pageId &&
+ this.contentGeneration !== contentGeneration &&
+ this.pendingInvalidations.length > 0
+ ) {
+ this.applyPendingInvalidations(graph, contentGeneration)
+ }
+ if (
+ this.index &&
+ (this.pageId !== renderer.pageId || this.contentGeneration !== contentGeneration)
+ ) {
+ this.invalidate()
+ }
+ if (!this.navigationActive && this.index === null && renderer.pageId) {
+ this.ensureIndex(graph, renderer.pageId, contentGeneration)
+ }
+ }
+
+ private applyPendingInvalidations(graph: SceneGraph, contentGeneration: number): void {
+ const index = this.index
+ if (!index || !this.pageId) return
+ this.tileCache.advanceGeneration(contentGeneration)
+ for (const invalidation of this.pendingInvalidations) {
+ const before = invalidation.previousBounds
+ const chunks = index.getChunksDependingOnNode(invalidation.nodeId)
+ for (const chunk of chunks) this.pictureCache.invalidate(chunk.id)
+ for (const chunk of chunks) index.updateNode(graph, chunk.nodeId)
+ const after = index.getChunksDependingOnNode(invalidation.nodeId)
+ for (const bounds of [...before, ...after]) {
+ this.tileCache.invalidateBounds(this.pageId, bounds, contentGeneration)
+ }
+ }
+ this.pendingInvalidations = []
+ this.contentGeneration = contentGeneration
+ }
+
+ private ensureIndex(graph: SceneGraph, pageId: string | null, contentGeneration: number): void {
+ if (this.index && this.pageId === pageId && this.contentGeneration === contentGeneration) return
+ this.index?.dispose()
+ this.pictureCache.clear()
+ this.tileCache.markStale(contentGeneration)
+ this.pageId = pageId
+ this.contentGeneration = contentGeneration
+ this.index = pageId ? RenderChunkIndex.build(graph, pageId).index : null
+ }
+
+ private runScheduledFrame(
+ renderer: SkiaRenderer,
+ graph: SceneGraph,
+ index: RenderChunkIndex
+ ): TileSchedulerMetrics {
+ return this.scheduler.runFrame((job) => this.executeJob(renderer, graph, index, job))
+ }
+
+ private deferActiveJobs(jobs: TileJob[]): TileSchedulerMetrics {
+ const metrics = emptyTileSchedulerMetrics()
+ metrics.remaining = jobs.length
+ metrics.skippedWithFallback = jobs.filter((job) => job.fallbackAvailable).length
+ return metrics
+ }
+
+ private executeJob(
+ renderer: SkiaRenderer,
+ graph: SceneGraph,
+ index: RenderChunkIndex,
+ job: TileJob
+ ) {
+ const tile = renderTile(renderer, graph, index, job.key, this.pictureCache, this.surfacePool)
+ if (!tile) return { renderMs: 0, overBudget: true }
+ const previousCost = this.measuredCosts.get(this.costKey(job.key)) ?? tile.renderMs
+ this.measuredCosts.set(this.costKey(job.key), previousCost * 0.7 + tile.renderMs * 0.3)
+ if (
+ job.navigationGeneration !== this.navigationGeneration ||
+ job.contentGeneration !== this.contentGeneration
+ ) {
+ deleteRenderedTile(tile)
+ return this.jobResult(tile)
+ }
+ this.tileCache.install(tile, job.contentGeneration)
+ return this.jobResult(tile)
+ }
+
+ private jobResult(tile: NonNullable<ReturnType<typeof renderTile>>) {
+ return {
+ renderMs: tile.renderMs,
+ overBudget: tile.renderMs > TILE_FRAME_BUDGET_MS,
+ allocationMs: tile.allocationMs,
+ drawMs: tile.drawMs,
+ flushMs: tile.flushMs,
+ snapshotMs: tile.snapshotMs,
+ chunkCount: tile.chunkCount
+ }
+ }
+
+ private costKey(key: TileJob['key']): string {
+ return `${key.level}:${key.x}:${key.y}`
+ }
+
+ private drawVisibleTiles(
+ renderer: SkiaRenderer,
+ canvas: Canvas,
+ visible: ReturnType<typeof planTiles>['visible']
+ ): number {
+ let presented = 0
+ renderer.opacityPaint.setAlphaf(1)
+ renderer.opacityPaint.setBlendMode(renderer.ck.BlendMode.Src)
+ try {
+ for (const { key, tile } of visible) {
+ if (!tile) continue
+ const bounds = tileWorldBounds(key)
+ canvas.drawImageRectOptions(
+ tile.image,
+ renderer.ck.LTRBRect(0, 0, TILE_DEVICE_SIZE, TILE_DEVICE_SIZE),
+ renderer.ck.LTRBRect(bounds.minX, bounds.minY, bounds.maxX, bounds.maxY),
+ renderer.ck.FilterMode.Linear,
+ renderer.ck.MipmapMode.None,
+ renderer.opacityPaint
+ )
+ presented++
+ }
+ } finally {
+ renderer.opacityPaint.setBlendMode(renderer.ck.BlendMode.SrcOver)
+ }
+ return presented
+ }
+
+ private emptyResult(): TiledSceneFrameResult {
+ return {
+ covered: false,
+ pending: false,
+ metrics: emptyTileSchedulerMetrics()
+ }
+ }
+}
diff --git a/packages/core/src/canvas/renderer/tiles/geometry.ts b/packages/core/src/canvas/renderer/tiles/geometry.ts
new file mode 100644
index 000000000..838e5cfe4
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/geometry.ts
@@ -0,0 +1,58 @@
+export const TILE_DEVICE_SIZE = 256
+export const TILE_LEVEL_STEP = 0.25
+export const MIN_TILE_LEVEL = TILE_LEVEL_STEP / 16
+
+export interface TileKey {
+ pageId: string
+ level: number
+ x: number
+ y: number
+}
+
+export interface TileWorldBounds {
+ minX: number
+ minY: number
+ maxX: number
+ maxY: number
+}
+
+export function tileLevel(scale: number): number {
+ if (!Number.isFinite(scale) || scale <= 0) return 1
+ if (scale < TILE_LEVEL_STEP) {
+ const exponent = Math.ceil(Math.log2(TILE_LEVEL_STEP / scale))
+ return Math.max(MIN_TILE_LEVEL, TILE_LEVEL_STEP / 2 ** exponent)
+ }
+ return Math.ceil(scale / TILE_LEVEL_STEP) * TILE_LEVEL_STEP
+}
+
+export function tileWorldSize(level: number): number {
+ return TILE_DEVICE_SIZE / level
+}
+
+export function tileWorldBounds(key: TileKey): TileWorldBounds {
+ const size = tileWorldSize(key.level)
+ const minX = key.x * size
+ const minY = key.y * size
+ return { minX, minY, maxX: minX + size, maxY: minY + size }
+}
+
+export function tileKeysForWorldBounds(
+ pageId: string,
+ level: number,
+ bounds: TileWorldBounds
+): TileKey[] {
+ const size = tileWorldSize(level)
+ const minX = Math.floor(bounds.minX / size)
+ const minY = Math.floor(bounds.minY / size)
+ const maxX = Math.ceil(bounds.maxX / size) - 1
+ const maxY = Math.ceil(bounds.maxY / size) - 1
+ const keys: TileKey[] = []
+ for (let y = minY; y <= maxY; y++) {
+ for (let x = minX; x <= maxX; x++) keys.push({ pageId, level, x, y })
+ }
+ return keys
+}
+
+export function tileKeyString(key: TileKey): string {
+ return `${key.pageId}:${key.level}:${key.x}:${key.y}`
+}
diff --git a/packages/core/src/canvas/renderer/tiles/index.ts b/packages/core/src/canvas/renderer/tiles/index.ts
new file mode 100644
index 000000000..9dd29c190
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/index.ts
@@ -0,0 +1,27 @@
+export {
+ TILE_DEVICE_SIZE,
+ TILE_LEVEL_STEP,
+ tileKeyString,
+ tileKeysForWorldBounds,
+ tileLevel,
+ tileWorldBounds,
+ tileWorldSize
+} from './geometry'
+export type { TileKey, TileWorldBounds } from './geometry'
+export { TiledSceneController } from './controller'
+export type { TiledSceneFrameResult } from './controller'
+export { planTiles } from './planner'
+export type { TilePlan, TilePlanOptions } from './planner'
+export { TileImageCache } from './cache'
+export type { CachedTile } from './cache'
+export { TileScheduler } from './scheduler'
+export type {
+ TileJob,
+ TileJobPriority,
+ TileJobResult,
+ TileSchedulerMetrics,
+ TileSchedulerOptions
+} from './scheduler'
+export { TileSurfacePool } from './surface-pool'
+export { deleteRenderedTile, renderTile, tileChunks } from './render'
+export type { RenderedTile } from './render'
diff --git a/packages/core/src/canvas/renderer/tiles/planner.ts b/packages/core/src/canvas/renderer/tiles/planner.ts
new file mode 100644
index 000000000..8ded52f21
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/planner.ts
@@ -0,0 +1,86 @@
+import type { CachedTile, TileImageCache } from './cache'
+import {
+ type TileKey,
+ type TileWorldBounds,
+ tileKeysForWorldBounds,
+ tileKeyString,
+ tileWorldSize
+} from './geometry'
+import type { TileJob } from './scheduler'
+
+export interface TilePlanOptions {
+ pageId: string
+ level: number
+ viewport: TileWorldBounds
+ overscanTiles: number
+ navigationGeneration: number
+ contentGeneration: number
+ estimateCost: (key: TileKey) => number
+ globalFallbackAvailable?: boolean
+}
+
+export interface TilePlan {
+ jobs: TileJob[]
+ visible: Array<{ key: TileKey; tile: CachedTile | null }>
+}
+
+function expand(bounds: TileWorldBounds, amount: number): TileWorldBounds {
+ return {
+ minX: bounds.minX - amount,
+ minY: bounds.minY - amount,
+ maxX: bounds.maxX + amount,
+ maxY: bounds.maxY + amount
+ }
+}
+
+function planCachedVisibleTiles(cache: TileImageCache, options: TilePlanOptions): TilePlan {
+ const visible = tileKeysForWorldBounds(options.pageId, options.level, options.viewport).map(
+ (key) => ({ key, tile: cache.getIfPresent(key) })
+ )
+ return { jobs: [], visible }
+}
+
+export function planTiles(
+ cache: TileImageCache,
+ options: TilePlanOptions,
+ cachedOnly = false
+): TilePlan {
+ if (cachedOnly) return planCachedVisibleTiles(cache, options)
+ const worldTileSize = tileWorldSize(options.level)
+ const visibleKeys = tileKeysForWorldBounds(options.pageId, options.level, options.viewport)
+ const visibleIds = new Set(visibleKeys.map(tileKeyString))
+ const overscanKeys = tileKeysForWorldBounds(
+ options.pageId,
+ options.level,
+ expand(options.viewport, worldTileSize * options.overscanTiles)
+ )
+ const visible = visibleKeys.map((key) => ({ key, tile: cache.get(key) }))
+ const jobs: TileJob[] = []
+ for (const { key, tile } of visible) {
+ const fresh = tile?.contentGeneration === options.contentGeneration
+ if (fresh) continue
+ jobs.push({
+ key,
+ navigationGeneration: options.navigationGeneration,
+ contentGeneration: options.contentGeneration,
+ priority: tile || options.globalFallbackAvailable ? 'visible' : 'mandatory',
+ fallbackAvailable: tile !== null || options.globalFallbackAvailable === true,
+ estimatedCost: options.estimateCost(key)
+ })
+ }
+ if (jobs.length > 0) return { jobs, visible }
+ for (const key of overscanKeys) {
+ if (visibleIds.has(tileKeyString(key))) continue
+ const tile = cache.get(key)
+ if (tile?.contentGeneration === options.contentGeneration) continue
+ jobs.push({
+ key,
+ navigationGeneration: options.navigationGeneration,
+ contentGeneration: options.contentGeneration,
+ priority: 'overscan',
+ fallbackAvailable: tile !== null,
+ estimatedCost: options.estimateCost(key)
+ })
+ }
+ return { jobs, visible }
+}
diff --git a/packages/core/src/canvas/renderer/tiles/render.ts b/packages/core/src/canvas/renderer/tiles/render.ts
new file mode 100644
index 000000000..b3521b8c5
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/render.ts
@@ -0,0 +1,119 @@
+import type { Image as CKImage } from 'canvaskit-wasm'
+
+import type { SceneGraph } from '@open-pencil/scene-graph'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+import {
+ type RenderChunk,
+ type RenderChunkIndex,
+ type RenderChunkPictureCache,
+ drawRenderChunkDirect
+} from '#core/canvas/renderer/chunks'
+import { rendererNow } from '#core/canvas/renderer/clock'
+
+import { type TileKey, tileWorldBounds } from './geometry'
+import type { TileSurfacePool } from './surface-pool'
+
+export interface RenderedTile {
+ key: TileKey
+ image: CKImage
+ chunkCount: number
+ estimatedCost: number
+ renderMs: number
+ allocationMs: number
+ drawMs: number
+ flushMs: number
+ snapshotMs: number
+}
+
+function isBoundedAtomicBlurChunk(graph: SceneGraph, chunk: RenderChunk): boolean {
+ if (chunk.interruptible || chunk.kind !== 'subtree') return false
+ const node = graph.getNode(chunk.nodeId)
+ return (
+ node?.effects.some(
+ (effect) =>
+ effect.visible && (effect.type === 'LAYER_BLUR' || effect.type === 'FOREGROUND_BLUR')
+ ) === true
+ )
+}
+
+export function renderTile(
+ renderer: SkiaRenderer,
+ graph: SceneGraph,
+ index: RenderChunkIndex,
+ key: TileKey,
+ pictureCache: RenderChunkPictureCache,
+ surfacePool: TileSurfacePool
+): RenderedTile | null {
+ const startedAt = rendererNow()
+ const bounds = tileWorldBounds(key)
+ const chunks = index.search(bounds)
+ const allocationStartedAt = rendererNow()
+ const surface = surfacePool.acquire(renderer)
+ if (!surface) return null
+ const allocationMs = rendererNow() - allocationStartedAt
+ const canvas = surface.getCanvas()
+ canvas.save()
+ try {
+ canvas.clear(
+ renderer.ck.Color4f(
+ renderer.pageColor.r,
+ renderer.pageColor.g,
+ renderer.pageColor.b,
+ renderer.pageColor.a
+ )
+ )
+ canvas.scale(key.level, key.level)
+ canvas.translate(-bounds.minX, -bounds.minY)
+ canvas.clipRect(
+ renderer.ck.LTRBRect(bounds.minX, bounds.minY, bounds.maxX, bounds.maxY),
+ renderer.ck.ClipOp.Intersect,
+ false
+ )
+
+ const drawStartedAt = rendererNow()
+ for (const chunk of chunks) {
+ if (isBoundedAtomicBlurChunk(graph, chunk)) {
+ const previous = renderer.boundEffectLayersToViewport
+ renderer.boundEffectLayersToViewport = true
+ try {
+ drawRenderChunkDirect(renderer, canvas, graph, chunk)
+ } finally {
+ renderer.boundEffectLayersToViewport = previous
+ }
+ continue
+ }
+ const picture = pictureCache.get(renderer, graph, chunk)
+ canvas.drawPicture(picture)
+ }
+ const drawMs = rendererNow() - drawStartedAt
+ const flushStartedAt = rendererNow()
+ surface.flush()
+ const flushMs = rendererNow() - flushStartedAt
+ const snapshotStartedAt = rendererNow()
+ const image = surface.makeImageSnapshot()
+ const snapshotMs = rendererNow() - snapshotStartedAt
+ return {
+ key,
+ image,
+ chunkCount: chunks.length,
+ estimatedCost: chunks.reduce((total, chunk) => total + chunk.estimatedCost, 0),
+ renderMs: rendererNow() - startedAt,
+ allocationMs,
+ drawMs,
+ flushMs,
+ snapshotMs
+ }
+ } finally {
+ canvas.restore()
+ surfacePool.release(surface)
+ }
+}
+
+export function deleteRenderedTile(tile: RenderedTile): void {
+ tile.image.delete()
+}
+
+export function tileChunks(index: RenderChunkIndex, key: TileKey): RenderChunk[] {
+ return index.search(tileWorldBounds(key))
+}
diff --git a/packages/core/src/canvas/renderer/tiles/scheduler.ts b/packages/core/src/canvas/renderer/tiles/scheduler.ts
new file mode 100644
index 000000000..c88696b1a
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/scheduler.ts
@@ -0,0 +1,191 @@
+import { rendererNow } from '#core/canvas/renderer/clock'
+
+import type { TileKey } from './geometry'
+
+export type TileJobPriority = 'mandatory' | 'visible' | 'overscan'
+
+export interface TileJob {
+ key: TileKey
+ navigationGeneration: number
+ contentGeneration: number
+ priority: TileJobPriority
+ fallbackAvailable: boolean
+ estimatedCost: number
+}
+
+export interface TileJobResult {
+ renderMs: number
+ overBudget: boolean
+ allocationMs?: number
+ drawMs?: number
+ flushMs?: number
+ snapshotMs?: number
+ chunkCount?: number
+}
+
+export interface TileSchedulerMetrics {
+ mandatoryCompleted: number
+ interruptibleCompleted: number
+ remaining: number
+ skippedWithFallback: number
+ deadlineOverrunMs: number
+ overBudgetJobs: number
+ maximumJobRenderMs: number
+ staleJobsDiscarded: number
+ cancelledJobs: number
+ totalAllocationMs: number
+ totalDrawMs: number
+ totalFlushMs: number
+ totalSnapshotMs: number
+ totalChunks: number
+}
+
+export interface TileSchedulerOptions {
+ now?: () => number
+ budgetMs: number
+ maximumJobsPerFrame?: number
+}
+
+export function emptyTileSchedulerMetrics(): TileSchedulerMetrics {
+ return {
+ mandatoryCompleted: 0,
+ interruptibleCompleted: 0,
+ remaining: 0,
+ skippedWithFallback: 0,
+ deadlineOverrunMs: 0,
+ overBudgetJobs: 0,
+ maximumJobRenderMs: 0,
+ staleJobsDiscarded: 0,
+ cancelledJobs: 0,
+ totalAllocationMs: 0,
+ totalDrawMs: 0,
+ totalFlushMs: 0,
+ totalSnapshotMs: 0,
+ totalChunks: 0
+ }
+}
+
+function addJobMetrics(metrics: TileSchedulerMetrics, result: TileJobResult): void {
+ metrics.maximumJobRenderMs = Math.max(metrics.maximumJobRenderMs, result.renderMs)
+ metrics.totalAllocationMs += result.allocationMs ?? 0
+ metrics.totalDrawMs += result.drawMs ?? 0
+ metrics.totalFlushMs += result.flushMs ?? 0
+ metrics.totalSnapshotMs += result.snapshotMs ?? 0
+ metrics.totalChunks += result.chunkCount ?? 0
+}
+
+const PRIORITY_ORDER: Record<TileJobPriority, number> = {
+ mandatory: 0,
+ visible: 1,
+ overscan: 2
+}
+
+export class TileScheduler {
+ private navigationGeneration = 0
+ private contentGeneration = 0
+ private jobs: TileJob[] = []
+ private readonly now: () => number
+ private readonly budgetMs: number
+ private readonly maximumJobsPerFrame: number
+
+ constructor(options: TileSchedulerOptions) {
+ this.now = options.now ?? rendererNow
+ this.budgetMs = options.budgetMs
+ this.maximumJobsPerFrame = options.maximumJobsPerFrame ?? Number.POSITIVE_INFINITY
+ }
+
+ setGeneration(navigationGeneration: number, contentGeneration: number): number {
+ const previousCount = this.jobs.length
+ this.navigationGeneration = navigationGeneration
+ this.contentGeneration = contentGeneration
+ this.jobs = this.jobs.filter(
+ (job) =>
+ job.navigationGeneration === navigationGeneration &&
+ job.contentGeneration === contentGeneration
+ )
+ return previousCount - this.jobs.length
+ }
+
+ enqueue(jobs: TileJob[]): void {
+ const existing = new Set(this.jobs.map((job) => this.identity(job)))
+ for (const job of jobs) {
+ if (
+ job.navigationGeneration !== this.navigationGeneration ||
+ job.contentGeneration !== this.contentGeneration ||
+ existing.has(this.identity(job))
+ ) {
+ continue
+ }
+ this.jobs.push(job)
+ existing.add(this.identity(job))
+ }
+ this.jobs.sort((a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority])
+ }
+
+ runFrame(execute: (job: TileJob) => TileJobResult): TileSchedulerMetrics {
+ const frameStart = this.now()
+ const metrics = emptyTileSchedulerMetrics()
+
+ let jobsExecuted = 0
+ while (this.jobs.length > 0) {
+ if (jobsExecuted >= this.maximumJobsPerFrame) break
+ const job = this.jobs[0]
+ const elapsed = this.now() - frameStart
+ const mandatory = job.priority === 'mandatory' && !job.fallbackAvailable
+ if (jobsExecuted > 0 && elapsed >= this.budgetMs) break
+ if (this.isStale(job)) {
+ this.jobs.shift()
+ metrics.staleJobsDiscarded++
+ continue
+ }
+ if (!mandatory && job.fallbackAvailable && elapsed + job.estimatedCost > this.budgetMs) {
+ if (jobsExecuted === 0) {
+ const result = execute(job)
+ this.jobs.shift()
+ jobsExecuted++
+ metrics.interruptibleCompleted++
+ addJobMetrics(metrics, result)
+ if (result.overBudget || result.renderMs > this.budgetMs) metrics.overBudgetJobs++
+ const overrun = this.now() - frameStart - this.budgetMs
+ if (overrun > metrics.deadlineOverrunMs) metrics.deadlineOverrunMs = overrun
+ } else {
+ metrics.skippedWithFallback++
+ }
+ break
+ }
+ this.jobs.shift()
+ const result = execute(job)
+ jobsExecuted++
+ addJobMetrics(metrics, result)
+ if (result.overBudget || result.renderMs > this.budgetMs) metrics.overBudgetJobs++
+ if (mandatory) metrics.mandatoryCompleted++
+ else metrics.interruptibleCompleted++
+ const overrun = this.now() - frameStart - this.budgetMs
+ if (overrun > metrics.deadlineOverrunMs) metrics.deadlineOverrunMs = overrun
+ }
+ metrics.remaining = this.jobs.length
+ return metrics
+ }
+
+ clear(): number {
+ const count = this.jobs.length
+ this.jobs = []
+ return count
+ }
+
+ pending(): number {
+ return this.jobs.length
+ }
+
+ private identity(job: TileJob): string {
+ const { key } = job
+ return `${key.pageId}:${key.level}:${key.x}:${key.y}:${job.contentGeneration}`
+ }
+
+ private isStale(job: TileJob): boolean {
+ return (
+ job.navigationGeneration !== this.navigationGeneration ||
+ job.contentGeneration !== this.contentGeneration
+ )
+ }
+}
diff --git a/packages/core/src/canvas/renderer/tiles/surface-pool.ts b/packages/core/src/canvas/renderer/tiles/surface-pool.ts
new file mode 100644
index 000000000..e8d85a5d7
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/surface-pool.ts
@@ -0,0 +1,35 @@
+import type { Surface } from 'canvaskit-wasm'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+
+import { TILE_DEVICE_SIZE } from './geometry'
+
+export class TileSurfacePool {
+ private readonly available: Surface[] = []
+
+ acquire(renderer: SkiaRenderer): Surface | null {
+ return (
+ this.available.pop() ??
+ renderer.surface.makeSurface({
+ width: TILE_DEVICE_SIZE,
+ height: TILE_DEVICE_SIZE,
+ colorType: renderer.ck.ColorType.RGBA_8888,
+ alphaType: renderer.ck.AlphaType.Premul,
+ colorSpace: renderer.ck.ColorSpace.SRGB
+ })
+ )
+ }
+
+ release(surface: Surface): void {
+ this.available.push(surface)
+ }
+
+ clear(): void {
+ for (const surface of this.available) surface.delete()
+ this.available.length = 0
+ }
+
+ size(): number {
+ return this.available.length
+ }
+}
diff --git a/packages/core/src/canvas/renderer/tiles/telemetry.ts b/packages/core/src/canvas/renderer/tiles/telemetry.ts
new file mode 100644
index 000000000..aed20e0ae
--- /dev/null
+++ b/packages/core/src/canvas/renderer/tiles/telemetry.ts
@@ -0,0 +1,56 @@
+import { emitNavigationTrace } from '#core/profiler'
+
+import type { TileSchedulerMetrics } from './scheduler'
+
+export interface TileFrameTrace {
+ contentGeneration: number
+ metrics: TileSchedulerMetrics
+ tileCacheBytes: number
+ tileCacheEntries: number
+ visibleTileCount: number
+ presentedTileCount: number
+ covered: boolean
+}
+
+export function emitTileFrameTrace(frame: TileFrameTrace): void {
+ const { metrics } = frame
+ emitNavigationTrace('render:end', {
+ layer: 'tiled-scheduler',
+ sceneVersion: frame.contentGeneration,
+ mandatoryCompleted: metrics.mandatoryCompleted,
+ interruptibleCompleted: metrics.interruptibleCompleted,
+ remaining: metrics.remaining,
+ skippedWithFallback: metrics.skippedWithFallback,
+ deadlineOverrunMs: metrics.deadlineOverrunMs,
+ overBudgetJobs: metrics.overBudgetJobs,
+ maximumJobRenderMs: metrics.maximumJobRenderMs,
+ staleJobsDiscarded: metrics.staleJobsDiscarded,
+ cancelledJobs: metrics.cancelledJobs,
+ tileAllocationMs: metrics.totalAllocationMs,
+ tileDrawMs: metrics.totalDrawMs,
+ tileFlushMs: metrics.totalFlushMs,
+ tileSnapshotMs: metrics.totalSnapshotMs,
+ tileChunks: metrics.totalChunks,
+ tileCacheBytes: frame.tileCacheBytes,
+ tileCacheEntries: frame.tileCacheEntries,
+ visibleTileCount: frame.visibleTileCount,
+ presentedTileCount: frame.presentedTileCount,
+ covered: frame.covered
+ })
+}
+
+export function emitTileCoverageComplete(
+ level: number,
+ contentGeneration: number,
+ navigationGeneration: number,
+ tileCacheEntries: number,
+ tileCacheBytes: number
+): void {
+ emitNavigationTrace('tiles:coverage-complete', {
+ level,
+ sceneVersion: contentGeneration,
+ navigationGeneration,
+ tileCacheEntries,
+ tileCacheBytes
+ })
+}
diff --git a/packages/core/src/canvas/renderer/visual-bounds.ts b/packages/core/src/canvas/renderer/visual-bounds.ts
new file mode 100644
index 000000000..5b8d78fa2
--- /dev/null
+++ b/packages/core/src/canvas/renderer/visual-bounds.ts
@@ -0,0 +1,31 @@
+import type { SceneGraph, SceneNode } from '@open-pencil/scene-graph'
+import { getWorldMatrix } from '@open-pencil/scene-graph/coordinate'
+import {
+ effectOverflow,
+ strokeOverflow,
+ type VisualBounds
+} from '@open-pencil/scene-graph/geometry'
+import Matrix from '@open-pencil/scene-graph/matrix'
+
+export function worldNodeVisualBounds(graph: SceneGraph, node: SceneNode): VisualBounds {
+ const stroke = strokeOverflow(node.strokes)
+ const effects = effectOverflow(node.effects)
+ const points = Matrix.mapPoints(getWorldMatrix(node, graph), [
+ -stroke - effects.left,
+ -stroke - effects.top,
+ node.width + stroke + effects.right,
+ -stroke - effects.top,
+ node.width + stroke + effects.right,
+ node.height + stroke + effects.bottom,
+ -stroke - effects.left,
+ node.height + stroke + effects.bottom
+ ])
+ const xs = [points[0], points[2], points[4], points[6]]
+ const ys = [points[1], points[3], points[5], points[7]]
+ return {
+ minX: Math.min(...xs),
+ minY: Math.min(...ys),
+ maxX: Math.max(...xs),
+ maxY: Math.max(...ys)
+ }
+}
diff --git a/packages/core/src/canvas/scene.ts b/packages/core/src/canvas/scene.ts
index 78c0911d0..dda7c1825 100644
--- a/packages/core/src/canvas/scene.ts
+++ b/packages/core/src/canvas/scene.ts
@@ -3,11 +3,13 @@ import type { Canvas, Path } from 'canvaskit-wasm'
import {
getAbsolutePositionFull,
+ getWorldMatrix,
type SceneNode,
type SceneGraph,
type Fill
} from '@open-pencil/scene-graph'
import { computeDescendantVisualBounds } from '@open-pencil/scene-graph/geometry'
+import Matrix from '@open-pencil/scene-graph/matrix'
import type { Color } from '@open-pencil/scene-graph/primitives'
import { DROP_HIGHLIGHT_ALPHA, DROP_HIGHLIGHT_STROKE, SECTION_CORNER_RADIUS } from '#core/constants'
@@ -21,6 +23,14 @@ import { drawVectorMultiStyleFills, paintFills } from './fills'
import { drawLayoutGrids } from './layout-grids'
import { renderMaskedChildIds } from './masks'
import type { SkiaRenderer, RenderOverlays } from './renderer'
+import {
+ canCacheEffectRaster,
+ deleteEffectRaster,
+ effectRasterScale,
+ effectRasterScaleMatches,
+ installEffectRaster,
+ touchEffectRaster
+} from './renderer/effect-raster-cache'
import { makeSmoothRRectPath, nodeHasRadius, nodeHasSmoothCorners } from './shapes'
import {
configureStrokePaint,
@@ -224,6 +234,81 @@ function renderChildren(
renderChildIds(r, canvas, graph, node.childIds, overlays, absX, absY, hasTransformedAncestor)
}
}
+export function renderNodeSelf(
+ r: SkiaRenderer,
+ canvas: Canvas,
+ graph: SceneGraph,
+ nodeId: string,
+ overlays: RenderOverlays = {}
+): void {
+ const node = graph.getNode(nodeId)
+ if (
+ !node ||
+ node.internalOnly ||
+ !node.visible ||
+ node.isMask ||
+ fontManager.isNodeBlocked(nodeId)
+ ) {
+ return
+ }
+ canvas.save()
+ canvas.translate(node.x, node.y)
+ applyNodeTransforms(r, canvas, node, nodeId, overlays)
+ renderNodeContent(r, canvas, graph, node, nodeId, overlays)
+ drawLayoutGrids(r, canvas, node)
+ canvas.restore()
+}
+
+function viewportLayerBounds(
+ r: SkiaRenderer,
+ graph: SceneGraph,
+ node: SceneNode,
+ padding: number
+): Float32Array | null {
+ if (!r.boundEffectLayersToViewport) return null
+ const inverse = Matrix.invert(getWorldMatrix(node, graph))
+ if (!inverse) return null
+ const viewport = r.worldViewport
+ const points = Matrix.mapPoints(inverse, [
+ viewport.x,
+ viewport.y,
+ viewport.x + viewport.w,
+ viewport.y,
+ viewport.x + viewport.w,
+ viewport.y + viewport.h,
+ viewport.x,
+ viewport.y + viewport.h
+ ])
+ const xs = [points[0], points[2], points[4], points[6]]
+ const ys = [points[1], points[3], points[5], points[7]]
+ return r.ck.LTRBRect(
+ Math.min(...xs) - padding,
+ Math.min(...ys) - padding,
+ Math.max(...xs) + padding,
+ Math.max(...ys) + padding
+ )
+}
+
+function nodeIsolationLayerBounds(
+ r: SkiaRenderer,
+ graph: SceneGraph,
+ node: SceneNode,
+ nodeId: string,
+ absX: number,
+ absY: number
+): Float32Array {
+ const viewportBounds = viewportLayerBounds(r, graph, node, 0)
+ if (viewportBounds) return viewportBounds
+ const bounds = computeDescendantVisualBounds(
+ [nodeId],
+ (id) => graph.getNode(id) ?? undefined,
+ (id) => graph.getAbsolutePosition(id)
+ )
+ return bounds
+ ? r.ck.LTRBRect(bounds.minX - absX, bounds.minY - absY, bounds.maxX - absX, bounds.maxY - absY)
+ : r.ck.LTRBRect(0, 0, node.width, node.height)
+}
+
export function renderNode(
r: SkiaRenderer,
canvas: Canvas,
@@ -263,19 +348,7 @@ export function renderNode(
const needsNodeLayer = node.opacity < 1 || needsIsolatedBlendLayer(node.blendMode)
if (needsNodeLayer) {
- const bounds = computeDescendantVisualBounds(
- [nodeId],
- (id) => graph.getNode(id) ?? undefined,
- (id) => graph.getAbsolutePosition(id)
- )
- const layerBounds = bounds
- ? r.ck.LTRBRect(
- bounds.minX - absX,
- bounds.minY - absY,
- bounds.maxX - absX,
- bounds.maxY - absY
- )
- : r.ck.LTRBRect(0, 0, node.width, node.height)
+ const layerBounds = nodeIsolationLayerBounds(r, graph, node, nodeId, absX, absY)
r.opacityPaint.setAlphaf(node.opacity)
r.opacityPaint.setBlendMode(figmaBlendModeToSkia(r.ck, node.blendMode))
canvas.saveLayer(r.opacityPaint, layerBounds)
@@ -294,7 +367,13 @@ export function renderNode(
const blurPadding = layerBlur.radius * 2
canvas.saveLayer(
r.effectLayerPaint,
- r.ck.LTRBRect(-blurPadding, -blurPadding, node.width + blurPadding, node.height + blurPadding)
+ viewportLayerBounds(r, graph, node, blurPadding) ??
+ r.ck.LTRBRect(
+ -blurPadding,
+ -blurPadding,
+ node.width + blurPadding,
+ node.height + blurPadding
+ )
)
}
@@ -395,37 +474,123 @@ export function renderComponentSet(
r.auxStroke.setPathEffect(null)
}
+function canRasterCacheEffects(node: SceneNode): boolean {
+ const visibleEffects = node.effects.filter((effect) => effect.visible)
+ return (
+ visibleEffects.length > 0 &&
+ visibleEffects.every(
+ (effect) => effect.type === 'DROP_SHADOW' || effect.type === 'INNER_SHADOW'
+ )
+ )
+}
+
export function renderShape(
r: SkiaRenderer,
canvas: Canvas,
node: SceneNode,
graph: SceneGraph
): void {
- const hasEffects = node.effects.length > 0 && node.effects.some((e) => e.visible)
+ const hasEffects = node.effects.some((effect) => effect.visible)
+ if (!hasEffects) {
+ r.renderShapeUncached(canvas, node, graph)
+ return
+ }
+
+ const canRasterCache = r.renderingSceneBacking && canRasterCacheEffects(node)
+ const targetScale = effectRasterScale(r.zoom * r.dpr)
+ const cachedRaster = canRasterCache ? touchEffectRaster(r.effectRasterCache, node.id) : null
+ if (
+ cachedRaster &&
+ (cachedRaster.fontGeneration !== r.fontGeneration ||
+ !effectRasterScaleMatches(cachedRaster.scale, targetScale))
+ ) {
+ deleteEffectRaster(r.effectRasterCache, node.id)
+ } else if (cachedRaster) {
+ canvas.drawImageRectOptions(
+ cachedRaster.image,
+ r.ck.LTRBRect(0, 0, cachedRaster.image.width(), cachedRaster.image.height()),
+ r.ck.LTRBRect(
+ cachedRaster.left,
+ cachedRaster.top,
+ cachedRaster.left + cachedRaster.width,
+ cachedRaster.top + cachedRaster.height
+ ),
+ r.ck.FilterMode.Linear,
+ r.ck.MipmapMode.None,
+ null
+ )
+ return
+ }
- if (hasEffects) {
- const cached = r.nodePictureCache.get(node.id)
- const cachedGeneration = r.nodePictureCacheGenerations.get(node.id)
- if (cached && cachedGeneration === r.fontGeneration) {
- canvas.drawPicture(cached)
+ const margin = r.effectOverflow(node)
+ const width = node.width + margin * 2
+ const height = node.height + margin * 2
+ const scale = targetScale
+ if (canRasterCache && canCacheEffectRaster(width, height, scale)) {
+ const surface = r.surface.makeSurface({
+ width: Math.ceil(width * scale),
+ height: Math.ceil(height * scale),
+ colorType: r.ck.ColorType.RGBA_8888,
+ alphaType: r.ck.AlphaType.Premul,
+ colorSpace: r.ck.ColorSpace.SRGB
+ })
+ const rasterCanvas = surface.getCanvas()
+ try {
+ rasterCanvas.clear(r.ck.TRANSPARENT)
+ rasterCanvas.scale(scale, scale)
+ rasterCanvas.translate(margin, margin)
+ r.renderShapeUncached(rasterCanvas, node, graph)
+ surface.flush()
+ const image = surface.makeImageSnapshot()
+ installEffectRaster(r.effectRasterCache, node.id, {
+ image,
+ left: -margin,
+ top: -margin,
+ width,
+ height,
+ scale,
+ pixels: image.width() * image.height(),
+ fontGeneration: r.fontGeneration,
+ dependencyIds: node.childIds.slice(0, 1)
+ })
+ canvas.drawImageRectOptions(
+ image,
+ r.ck.LTRBRect(0, 0, image.width(), image.height()),
+ r.ck.LTRBRect(-margin, -margin, node.width + margin, node.height + margin),
+ r.ck.FilterMode.Linear,
+ r.ck.MipmapMode.None,
+ null
+ )
return
+ } finally {
+ surface.delete()
}
- if (cached) cached.delete()
- r.nodePictureCache.delete(node.id)
- r.nodePictureCacheGenerations.delete(node.id)
+ }
- const margin = r.effectOverflow(node)
- const bounds = r.ck.LTRBRect(-margin, -margin, node.width + margin, node.height + margin)
- const recorder = new r.ck.PictureRecorder()
+ const cached = r.nodePictureCache.get(node.id)
+ const cachedGeneration = r.nodePictureCacheGenerations.get(node.id)
+ if (cached && cachedGeneration === r.fontGeneration) {
+ canvas.drawPicture(cached)
+ return
+ }
+ if (cached) cached.delete()
+ r.nodePictureCache.delete(node.id)
+ r.nodePictureCacheGenerations.delete(node.id)
+ r.nodePictureCacheDependencies.delete(node.id)
+
+ const bounds = r.ck.LTRBRect(-margin, -margin, node.width + margin, node.height + margin)
+ const recorder = new r.ck.PictureRecorder()
+ try {
const recCanvas = recorder.beginRecording(bounds)
r.renderShapeUncached(recCanvas, node, graph)
const picture = recorder.finishRecordingAsPicture()
- recorder.delete()
r.nodePictureCache.set(node.id, picture)
r.nodePictureCacheGenerations.set(node.id, r.fontGeneration)
+ const shadowChild = getShadowShapeChild(node, graph)
+ r.nodePictureCacheDependencies.set(node.id, shadowChild ? [shadowChild.id] : [])
canvas.drawPicture(picture)
- } else {
- r.renderShapeUncached(canvas, node, graph)
+ } finally {
+ recorder.delete()
}
}
diff --git a/packages/core/src/editor/create.ts b/packages/core/src/editor/create.ts
index 2d4292d00..0f1fb462a 100644
--- a/packages/core/src/editor/create.ts
+++ b/packages/core/src/editor/create.ts
@@ -12,6 +12,7 @@ import { clearLazyFigImportContext } from '#core/kiwi/fig/lazy-import'
import { releaseFigPopulationWorker } from '#core/kiwi/fig/population/client'
import { releaseOriginalFigArchive } from '#core/kiwi/fig/session/original-archive'
import { setTextMeasurer } from '#core/layout'
+import { emitNavigationTrace } from '#core/profiler'
import { TextEditor } from '#core/text/editor'
import { fontManager } from '#core/text/fonts'
import { fontResolver } from '#core/text/resolver'
@@ -88,6 +89,11 @@ export function createEditor(options?: EditorOptions) {
function requestRender() {
state.renderVersion++
state.sceneVersion++
+ emitNavigationTrace('render:requested', {
+ kind: 'render',
+ renderVersion: state.renderVersion,
+ sceneVersion: state.sceneVersion
+ })
emitEditorEvent('render:requested', {
renderVersion: state.renderVersion,
sceneVersion: state.sceneVersion
@@ -96,12 +102,42 @@ export function createEditor(options?: EditorOptions) {
function requestRepaint() {
state.renderVersion++
+ emitNavigationTrace('render:requested', {
+ kind: 'repaint',
+ renderVersion: state.renderVersion,
+ sceneVersion: state.sceneVersion
+ })
emitEditorEvent('repaint:requested', {
renderVersion: state.renderVersion,
sceneVersion: state.sceneVersion
})
}
+ function setNavigationPhase(phase: EditorState['navigation']['phase'], inputAt = 0) {
+ const previous = { ...state.navigation }
+ const active = phase === 'pan' || phase === 'zoom' || phase === 'momentum'
+ const wasActive =
+ previous.phase === 'pan' || previous.phase === 'zoom' || previous.phase === 'momentum'
+ state.navigation = {
+ phase,
+ generation: active && !wasActive ? previous.generation + 1 : previous.generation,
+ lastInputAt: inputAt || previous.lastInputAt
+ }
+ if (
+ state.navigation.phase !== previous.phase ||
+ state.navigation.generation !== previous.generation ||
+ state.navigation.lastInputAt !== previous.lastInputAt
+ ) {
+ emitNavigationTrace('navigation:phase', {
+ phase: state.navigation.phase,
+ previousPhase: previous.phase,
+ generation: state.navigation.generation,
+ lastInputAt: state.navigation.lastInputAt
+ })
+ emitEditorEvent('navigation:changed', state.navigation, previous)
+ }
+ }
+
function setSelectedIds(ids: Set<string>) {
const previous = [...state.selectedIds]
state.selectedIds = ids
@@ -159,6 +195,7 @@ export function createEditor(options?: EditorOptions) {
emitEditorEvent,
setSelectedIds,
setActiveTool,
+ setNavigationPhase,
runLayoutForNode,
subscribeToGraph
}
@@ -216,6 +253,7 @@ export function createEditor(options?: EditorOptions) {
state.layoutInsertIndicator = null
state.dropTargetId = null
pages.clearPageViewports()
+ for (const renderer of _renderers) renderer.tiledScene.invalidateStructure()
emitEditorEvent('graph:replaced', _graph)
if (previousPageId !== state.currentPageId) {
emitEditorEvent('page:changed', state.currentPageId, previousPageId)
@@ -258,6 +296,7 @@ export function createEditor(options?: EditorOptions) {
requestRepaint,
onEditorEvent,
setCanvasKit,
+ setNavigationPhase,
removeCanvasRenderer,
replaceGraph,
subscribeToGraph,
diff --git a/packages/core/src/editor/graph-events.ts b/packages/core/src/editor/graph-events.ts
index 688d41c3f..ade2d627d 100644
--- a/packages/core/src/editor/graph-events.ts
+++ b/packages/core/src/editor/graph-events.ts
@@ -21,6 +21,13 @@ const GEOMETRY_CACHE_KEYS = new Set<keyof SceneNode>([
'strokeGeometry'
])
+const TILED_CHUNK_TOPOLOGY_KEYS = new Set<keyof SceneNode>([
+ 'type',
+ 'visible',
+ 'isMask',
+ 'maskType'
+])
+
const NODE_PICTURE_STABLE_PREVIEW_KEYS = new Set<keyof SceneNode>([
'x',
'y',
@@ -48,6 +55,7 @@ export function rendererInvalidationForChanges(
}
function invalidateRenderersForChange(
+ graph: SceneGraph,
renderers: Iterable<SkiaRenderer>,
id: string,
changes: Partial<SceneNode>,
@@ -57,6 +65,11 @@ function invalidateRenderersForChange(
for (const renderer of renderers) {
if (invalidation.geometryCache) renderer.invalidateVectorPath(id)
if (invalidation.nodePicture) renderer.invalidateNodePicture(id)
+ if (Object.keys(changes).some((key) => TILED_CHUNK_TOPOLOGY_KEYS.has(key as keyof SceneNode))) {
+ renderer.tiledScene.invalidateStructure()
+ } else {
+ renderer.tiledScene.invalidateNode(id, graph)
+ }
}
}
@@ -64,7 +77,7 @@ export function createGraphEventSubscription(options: GraphEventOptions) {
let unbindGraphEvents: (() => void) | null = null
function onNodeUpdated(id: string, changes: Partial<SceneNode>) {
- invalidateRenderersForChange(options.getRenderers(), id, changes, true)
+ invalidateRenderersForChange(options.getGraph(), options.getRenderers(), id, changes, true)
options.emitEditorEvent('node:updated', id, changes)
options.scheduleComponentSync(id)
options.requestRender()
@@ -72,10 +85,20 @@ export function createGraphEventSubscription(options: GraphEventOptions) {
function onNodePreviewUpdated(id: string, changes: Partial<SceneNode>) {
const { nodePicture } = rendererInvalidationForChanges(changes, { preview: true })
- invalidateRenderersForChange(options.getRenderers(), id, changes, nodePicture)
+ invalidateRenderersForChange(
+ options.getGraph(),
+ options.getRenderers(),
+ id,
+ changes,
+ nodePicture
+ )
}
function onNodeStructureChanged(nodeId: string) {
+ for (const renderer of options.getRenderers()) {
+ renderer.invalidateNodePicture(nodeId)
+ renderer.tiledScene.invalidateStructure()
+ }
options.scheduleComponentSync(nodeId)
options.requestRender()
}
diff --git a/packages/core/src/editor/state/view.ts b/packages/core/src/editor/state/view.ts
index 8f59597f0..4d96f6fb0 100644
--- a/packages/core/src/editor/state/view.ts
+++ b/packages/core/src/editor/state/view.ts
@@ -23,6 +23,7 @@ export function createDefaultEditorViewState(pageId: string): EditorViewState {
pageColor: { ...CANVAS_BG_COLOR },
panY: 0,
zoom: 1,
+ navigation: { phase: 'idle', generation: 0, lastInputAt: 0 },
renderVersion: 0,
enteredContainerId: null,
nodeEditState: null,
@@ -43,6 +44,7 @@ export function copyEditorViewState(source: EditorViewState): EditorViewState {
penState: structuredClone(source.penState),
autoLayoutHover: structuredClone(source.autoLayoutHover),
pageColor: { ...source.pageColor },
+ navigation: { ...source.navigation },
nodeEditState: structuredClone(source.nodeEditState)
}
}
diff --git a/packages/core/src/editor/types.ts b/packages/core/src/editor/types.ts
index 458487461..f224ba221 100644
--- a/packages/core/src/editor/types.ts
+++ b/packages/core/src/editor/types.ts
@@ -89,6 +89,7 @@ export interface EditorViewState {
pageColor: Color
panY: number
zoom: number
+ navigation: NavigationState
renderVersion: number
enteredContainerId: string | null
nodeEditState?: RenderOverlays['nodeEditState'] | null
@@ -96,6 +97,14 @@ export interface EditorViewState {
cursorCanvasY?: number | null
}
+export type NavigationPhase = 'idle' | 'pan' | 'zoom' | 'momentum' | 'settling'
+
+export interface NavigationState {
+ phase: NavigationPhase
+ generation: number
+ lastInputAt: number
+}
+
export interface EditorState extends EditorSharedState, EditorViewState {}
export interface ClipboardImageResolution {
@@ -123,6 +132,7 @@ export interface EditorEvents extends SceneGraphEvents {
viewport: { panX: number; panY: number; zoom: number },
previous: { panX: number; panY: number; zoom: number }
) => void
+ 'navigation:changed': (navigation: NavigationState, previous: NavigationState) => void
}
export type EditorEventName = keyof EditorEvents
@@ -165,6 +175,7 @@ export interface EditorContext {
) => void
setSelectedIds: (ids: Set<string>) => void
setActiveTool: (tool: Tool) => void
+ setNavigationPhase: (phase: NavigationPhase, inputAt?: number) => void
runLayoutForNode: (id: string) => void
subscribeToGraph: () => void
}
diff --git a/packages/core/src/editor/viewport.ts b/packages/core/src/editor/viewport.ts
index f66ba7ca9..2d5537ba0 100644
--- a/packages/core/src/editor/viewport.ts
+++ b/packages/core/src/editor/viewport.ts
@@ -1,6 +1,7 @@
import { computeBounds, computeAbsoluteBounds } from '@open-pencil/scene-graph/geometry'
import { ZOOM_DIVISOR, ZOOM_SCALE_MAX, ZOOM_SCALE_MIN } from '#core/constants'
+import { emitNavigationTrace } from '#core/profiler'
import type { EditorContext } from './types'
@@ -12,6 +13,14 @@ export function createViewportActions(ctx: EditorContext) {
function emitViewportChanged(previous: ReturnType<typeof currentViewport>) {
const next = currentViewport()
if (next.panX !== previous.panX || next.panY !== previous.panY || next.zoom !== previous.zoom) {
+ emitNavigationTrace('viewport:changed', {
+ panX: next.panX,
+ panY: next.panY,
+ zoom: next.zoom,
+ previousPanX: previous.panX,
+ previousPanY: previous.panY,
+ previousZoom: previous.zoom
+ })
ctx.emitEditorEvent('viewport:changed', next, previous)
}
}
diff --git a/packages/core/src/profiler/index.ts b/packages/core/src/profiler/index.ts
index 0b4921ef4..6ffeee4d1 100644
--- a/packages/core/src/profiler/index.ts
+++ b/packages/core/src/profiler/index.ts
@@ -4,5 +4,12 @@ export { GPUTimer } from './gpu-timer'
export { DrawCallCounter } from './draw-call-counter'
export { PhaseTimer } from './phase-timer'
export { HudRenderer } from './hud-renderer'
+export { emitNavigationTrace, subscribeNavigationTrace } from './navigation-trace'
+export type {
+ NavigationTraceEvent,
+ NavigationTraceEventName,
+ NavigationTraceListener,
+ RecordedWheelSample
+} from './navigation-trace'
export { CaptureStack, toSpeedscopeJSON } from './frame/capture'
export type { NodeProfile, FrameCapture } from './frame/capture'
diff --git a/packages/core/src/profiler/navigation-trace.ts b/packages/core/src/profiler/navigation-trace.ts
new file mode 100644
index 000000000..ed3d91320
--- /dev/null
+++ b/packages/core/src/profiler/navigation-trace.ts
@@ -0,0 +1,59 @@
+export type NavigationTraceEventName =
+ | 'wheel:received'
+ | 'wheel:flush'
+ | 'viewport:changed'
+ | 'render:requested'
+ | 'render:start'
+ | 'render:end'
+ | 'backing:preview'
+ | 'backing:build'
+ | 'backing:crisp'
+ | 'animation:frame'
+ | 'main:long-task'
+ | 'navigation:phase'
+ | 'tiles:coverage-complete'
+
+export interface NavigationTraceEvent {
+ name: NavigationTraceEventName
+ timestamp: number
+ detail: Record<string, number | string | boolean | null>
+}
+
+export interface RecordedWheelSample {
+ timeMs: number
+ deltaX: number
+ deltaY: number
+ deltaMode: number
+ ctrlKey: boolean
+ metaKey: boolean
+ shiftKey: boolean
+ clientX: number
+ clientY: number
+ cancelable: boolean
+ directionInvertedFromDevice?: boolean
+}
+
+export type NavigationTraceListener = (event: NavigationTraceEvent) => void
+
+const listeners = new Set<NavigationTraceListener>()
+
+function timestamp(): number {
+ return typeof performance === 'undefined' ? 0 : performance.now()
+}
+
+export function emitNavigationTrace(
+ name: NavigationTraceEventName,
+ detail: NavigationTraceEvent['detail'] = {}
+): void {
+ if (listeners.size === 0) return
+ const event = { name, timestamp: timestamp(), detail }
+ if (typeof performance !== 'undefined') {
+ performance.mark(`openpencil:${name}`, { detail })
+ }
+ for (const listener of listeners) listener(event)
+}
+
+export function subscribeNavigationTrace(listener: NavigationTraceListener): () => void {
+ listeners.add(listener)
+ return () => listeners.delete(listener)
+}
diff --git a/packages/docs/.vitepress/sidebars.ts b/packages/docs/.vitepress/sidebars.ts
index b0408408a..cc79dacc3 100644
--- a/packages/docs/.vitepress/sidebars.ts
+++ b/packages/docs/.vitepress/sidebars.ts
@@ -113,6 +113,8 @@ export const developmentSidebar = (
...(!prefix
? [
{ text: 'Roadmap', link: '/development/roadmap' },
+ { text: 'Navigation Performance', link: '/development/navigation-performance' },
+ { text: 'Renderer Lifecycle', link: '/development/renderer-lifecycle' },
{ text: 'Renderer Profiler', link: '/development/renderer-profiler' },
{ text: 'Vector Conversion', link: '/development/vector-conversion' },
]
diff --git a/packages/docs/development/navigation-performance.md b/packages/docs/development/navigation-performance.md
new file mode 100644
index 000000000..0530d1270
--- /dev/null
+++ b/packages/docs/development/navigation-performance.md
@@ -0,0 +1,167 @@
+# Navigation performance benchmark
+
+The navigation benchmark measures the complete wheel/trackpad-to-render pipeline. It is intentionally separate from the synchronous microbenchmark in `tests/e2e/viewport/zoom-pan.spec.ts`: accepting JavaScript calls quickly does not prove smooth navigation.
+
+## Renderer lifecycle and ownership
+
+The benchmark validates the retained and tiled renderer contracts documented in [Renderer lifecycle and ownership](./renderer-lifecycle.md). Structural renderer changes must preserve those generation, settlement, and CanvasKit ownership rules.
+
+## What it captures
+
+Every run writes `recording.json`, `metrics.json`, and `environment.json`. When tracing is enabled, it also writes `trace.json.gz`:
+
+- `trace.json.gz` (when tracing is enabled): Chromium tracing data for Perfetto or Chrome tracing tools.
+- `recording.json`: wheel samples plus OpenPencil input, viewport, render, and retained-backing events.
+- `metrics.json`: frame pacing, input latency, zoom-anchor drift, viewport jumps, exact active-renderer settlement, and tiled scheduler throughput/cancellation when enabled.
+- `environment.json`: browser, runtime, replay mode, and source gesture information.
+
+OpenPencil emits User Timing marks under `openpencil:*`, including wheel receipt/flush, viewport mutation, render start/end, backing preview/build, crisp-backing completion, and exact tiled coverage. The recording also runs a continuous `requestAnimationFrame` heartbeat and observes browser Long Tasks, so display stalls remain visible even when OpenPencil does not render.
+
+## Record a physical macOS trackpad gesture
+
+1. Start a production preview (preferred) or development server:
+
+ ```sh
+ bun run build
+ bun run preview -- --port 1420
+ ```
+
+2. Open:
+
+ ```text
+ http://localhost:1420/?test&no-chrome&no-rulers&navigation-benchmark
+ ```
+
+3. In DevTools, start recording:
+
+ ```js
+ openPencil.test.navigation.startRecording('macbook-fast-pinch-reversal')
+ ```
+
+4. Perform exactly one gesture, allow the canvas to become crisp, then stop and copy the result:
+
+ ```js
+ copy(JSON.stringify(openPencil.test.navigation.stopRecording(), null, 2))
+ ```
+
+5. Save the result under `tests/fixtures/navigation/gestures/`. Do not edit delta values or timestamps. Remove document names if they contain private information.
+
+Record at least slow pan, momentum pan, direction reversal, slow pinch, fast pinch in/out, pinch reversal, diagonal pan, and the personally observed failing gesture. Recordings from actual hardware must use `source: "macos-trackpad"`; generated fixtures use `source: "synthetic"`.
+
+## Benchmark a real `.fig` fixture
+
+Use `current-document` with an explicit browser-served fixture path. The runner waits for loading and page population, applies layout through the normal document-open path, zooms to fit, and waits on the active renderer's explicit settlement contract before recording:
+
+```sh
+bun run benchmark:navigation \
+ --url http://localhost:1420/ \
+ --gesture tests/fixtures/navigation/gestures/synthetic-pinch-reversal.json \
+ --mode dom \
+ --scenario current-document \
+ --document tests/fixtures/gold-preview.fig \
+ --no-trace \
+ --output artifacts/navigation-benchmark/gold-preview
+```
+
+`environment.json` records the resolved local document path so reports cannot silently mix generated and real-document runs. The runner serves the exact local bytes through an isolated Playwright route, so production Vite preview does not return its SPA fallback for non-public test fixtures.
+
+## Replay with Chromium tracing
+
+```sh
+bun run benchmark:navigation \
+ --url http://localhost:1420/ \
+ --gesture tests/fixtures/navigation/gestures/synthetic-pinch-reversal.json \
+ --mode cdp \
+ --scenario raster-stress \
+ --output artifacts/navigation-benchmark/current
+```
+
+`--mode cdp` sends browser input through the Chrome DevTools Protocol. `--mode dom` deterministically dispatches events inside the page and is useful for scheduler/correctness debugging. Neither mode is represented as physical WKWebView input.
+
+Use `--no-trace` for the lowest-overhead metrics pass. Run a separate diagnostic pass with tracing enabled, and add `--cpu-profile` only when stack sampling is needed: CPU profiling can perturb the timing being measured.
+
+Performance runs require a hardware-accelerated Metal/ANGLE context and fail if Chromium falls back to SwiftShader. Use `--software-gpu` only for portable correctness and CI smoke runs; never compare its timings with hardware results. Every run records the unmasked GL renderer and vendor in `environment.json`.
+
+Open the trace:
+
+```sh
+open https://ui.perfetto.dev
+```
+
+Then load `trace.json.gz` and search for `openpencil:`.
+
+## Baseline comparison
+
+Build and run the same gesture against `v0.14.0` and the candidate in separate clean worktrees, on the same machine and power state. Alternate baseline/candidate runs rather than completing every baseline run first. Use release builds, fixed 1280×800 CSS viewport and DPR 2, and at least five measured repetitions after one warmup.
+
+Do not gate shared CI on absolute timing. Dedicated benchmark hardware may gate on same-run baseline ratios and correctness invariants. Always retain raw traces for regressions.
+
+Compare two completed runs:
+
+```sh
+bun tools/navigation-benchmark/src/cli.ts compare \
+ --baseline artifacts/navigation-benchmark/v0.14.0/metrics.json \
+ --candidate artifacts/navigation-benchmark/current/metrics.json \
+ --output artifacts/navigation-benchmark/comparison.json
+```
+
+## Metrics
+
+The report includes:
+
+- Frame interval median, p95, p99, maximum, and counts over 8.33/16.67/33.33/50 ms.
+- Render CPU interval and CanvasKit flush timing.
+- Wheel-to-viewport and wheel-to-render-end latency.
+- Maximum zoom focal-point drift in screen pixels.
+- Maximum presented viewport displacement between rendered frames.
+- Final input to exact active-renderer settlement: crisp retained backing for the existing renderer or exact visible tile coverage for tiled mode.
+- Tiled scheduler frame count, maximum jobs per frame, maximum measured job submission, over-budget jobs, deadline overrun, and cancelled obsolete jobs.
+
+The runner contains no warmup or settlement sleeps. `waitForSettlement()` requires an idle navigation lifecycle and renderer-owned exact coverage; its timeout rejects the benchmark and reports renderer state.
+
+### Benchmark content mutation and cancellation
+
+Use the exact imported node ID plus a deterministic property mutation to measure selective refresh:
+
+```sh
+bun run benchmark:navigation \
+ --url 'http://localhost:1420/?renderer=tiled' \
+ --gesture tests/fixtures/navigation/gestures/synthetic-repeated-pinch-reversal.json \
+ --mode dom \
+ --scenario current-document \
+ --document tests/fixtures/gold-preview.fig \
+ --mutate-node '0:5' \
+ --mutate-opacity 0.11 \
+ --no-trace \
+ --output artifacts/navigation-benchmark/gold-preview-mutation
+```
+
+Add `--replay-after-mutation` to wait until refresh is observably pending and then replay the gesture before exact settlement. This measures generation cancellation and final-viewport prioritization without a fixed delay.
+
+Mutation-only and combined runs record their mutation parameters in `environment.json`. For tiled runs, inspect `scheduler.cancelledJobs`, `maximumJobsPerFrame`, `maximumJobRenderMs`, `overBudgetJobs`, and `maximumDeadlineOverrunMs`.
+
+Averages alone are not acceptance criteria. Inspect p95/p99, maximum stalls, contiguous missed frames, motion discontinuities, and crisp-settlement latency.
+
+## Required fixture matrix
+
+Permanent benchmark scenarios should cover:
+
+- **Light:** isolates input and scheduling overhead.
+- **Large flat:** stresses culling and traversal.
+- **Realistic:** nested frames, text, images, gradients, effects, masks, and instances.
+- **Raster stress:** expensive retained-backing creation and coverage changes.
+- **Imported `.fig`:** exercises imported-document rendering paths.
+
+Keep large or binary `.fig` fixtures in Git LFS. Synthetic fixture generation must be deterministic.
+
+## Native macOS acceptance
+
+Chromium replay does not establish WKWebView or physical trackpad behavior. Before a release with navigation changes:
+
+1. Build a release-mode Tauri application.
+2. Record the same gesture on physical target hardware.
+3. Capture Instruments **Time Profiler** and **Core Animation** traces, including OpenPencil and WebKit processes.
+4. Check input delivery, main-thread/WASM work, GPU/compositor stalls, viewport continuity, and final crisp settlement.
+5. Store the recording, metrics, hardware/macOS metadata, and Instruments trace as release artifacts.
+
+Native automation may add OS-level scroll injection, but it must preserve continuous-scroll and momentum phases before being called trackpad-equivalent. Synthetic composition or DOM wheel events are not native acceptance evidence.
diff --git a/packages/docs/development/renderer-lifecycle.md b/packages/docs/development/renderer-lifecycle.md
new file mode 100644
index 000000000..2344aa6ce
--- /dev/null
+++ b/packages/docs/development/renderer-lifecycle.md
@@ -0,0 +1,46 @@
+# Renderer lifecycle and ownership
+
+The CanvasKit renderer keeps hot drawing loops direct, but its retained and tiled paths follow explicit lifecycle contracts. Preserve these contracts when changing renderer structure or cache policy.
+
+## Navigation and settlement
+
+The default renderer presents a committed retained backing while navigation is active. It must not rebuild that backing during pan, zoom, momentum, or settling, because reconstruction can collide with direction reversals and block input delivery. Once navigation becomes idle, it builds exact content incrementally and atomically replaces the committed backing.
+
+The tiled renderer is opt-in. It also presents retained fallback pixels while navigation is active and defers tile rasterization and presentation until idle. Visible exact coverage is the settlement boundary; overscan remains background work.
+
+Generation rules:
+
+- Navigation generations cancel obsolete queued tile work.
+- Content generations invalidate affected pictures and tiles.
+- Page, scene, position-preview, and font versions all participate in retained-cache validity.
+- A stale build or raster result must be deleted rather than installed.
+
+## CanvasKit ownership
+
+CanvasKit objects are native/WASM resources and are not reclaimed reliably by JavaScript garbage collection. Ownership transfer must remain explicit.
+
+| Resource | Created by | Owner after success | Released by |
+| --- | --- | --- | --- |
+| Scene picture | Scene recorder | Renderer scene-picture state | Replacement, invalidation, renderer destruction |
+| Retained backing image | Completed backing build | Retained backing state | Replacement, invalidation, renderer destruction |
+| Retained build surface | Backing builder | Retained build state | Commit, cancellation, invalidation, renderer destruction |
+| Subtree picture | Subtree recorder | Subtree picture cache | Scope change, node invalidation, renderer destruction |
+| Chunk picture | Chunk recorder | `RenderChunkPictureCache` | Chunk invalidation or cache clear |
+| Tile image | `renderTile()` | Caller until installation, then `TileImageCache` | Stale-result discard, replacement, eviction, cache clear |
+| Tile surface | `TileSurfacePool` | Surface pool | Pool clear |
+| Effect raster image | Effect rasterizer | Effect raster cache | Node invalidation, eviction, cache clear |
+| CanvasKit path arrays | Geometry builder | Owning geometry cache | Node invalidation or renderer destruction |
+
+Do not introduce generic disposal wrappers into per-node or per-tile hot loops. Prefer narrow domain operations with obvious transfer points, and use `try/finally` around recorder, surface, paint-effect, and transform lifetimes.
+
+## Performance-preserving refactors
+
+Safe structural refactors may split modules, name state records, extract telemetry, and document transitions. They must not change:
+
+- Frame budgets, cache limits, tile size, quantized levels, or overscan policy.
+- Visible-before-overscan priority.
+- Direct CanvasKit calls and preallocated temporary buffers in hot loops.
+- Atomic isolation for masks, opacity, blend modes, and blur scopes.
+- Exact settlement acknowledgement.
+
+Validate structural changes with the `gold-preview.fig` reversal and mutation-plus-reversal benchmarks, focused renderer tests, and committed canvas snapshots. Compare production builds rather than relying on synchronous microbenchmarks.
diff --git a/packages/vue/src/canvas/surface/lifecycle.ts b/packages/vue/src/canvas/surface/lifecycle.ts
index 101f06c4f..b39750a5d 100644
--- a/packages/vue/src/canvas/surface/lifecycle.ts
+++ b/packages/vue/src/canvas/surface/lifecycle.ts
@@ -65,6 +65,8 @@ export function createCanvasSurfaceManager({
const glCtx = canvas.getContext('webgl2') ?? null
state.renderer = new SkiaRenderer(ck, surface, glCtx)
+ state.renderer.tracksSceneSettlement = options?.layer !== 'overlays'
+ state.renderer.tiledSceneEnabled = options?.sceneRenderer === 'tiled'
editor.setCanvasKit(ck, state.renderer)
canvas.dataset.ready = '1'
@@ -101,6 +103,9 @@ export function createCanvasSurfaceManager({
renderLoop.markRendered()
acknowledgePresentation()
clearSceneBackingRenderTimer()
+ if (options?.layer === 'scene' && state.renderer.tiledScenePending) {
+ renderLoop.markDirty()
+ }
if (options?.layer === 'scene' && state.renderer.sceneBackingNeedsCrispRender) {
const delay = Math.max(0, state.renderer.sceneBackingPreviewUntil - performance.now())
sceneBackingRenderTimer = setTimeout(() => renderLoop.markDirty(), delay)
diff --git a/packages/vue/src/canvas/surface/overlays.ts b/packages/vue/src/canvas/surface/overlays.ts
index 7459d1d73..6f578a35b 100644
--- a/packages/vue/src/canvas/surface/overlays.ts
+++ b/packages/vue/src/canvas/surface/overlays.ts
@@ -1,5 +1,4 @@
import type { SkiaRenderer } from '@open-pencil/core/canvas'
-import { IS_BROWSER } from '@open-pencil/core/constants'
import type { Editor } from '@open-pencil/core/editor'
import { useViewportKind } from '#vue/editor/viewport-kind/use'
@@ -9,13 +8,11 @@ export type RulerVisibilityOptions = {
}
export function createRulerVisibility(options?: RulerVisibilityOptions) {
- const params = IS_BROWSER ? new URLSearchParams(window.location.search) : new URLSearchParams()
- const noRulersParam = params.has('no-rulers')
const { isMobile } = useViewportKind()
return function shouldShowRulers() {
if (options?.showRulers === false) return false
- return !noRulersParam && !isMobile.value
+ return !isMobile.value
}
}
diff --git a/packages/vue/src/canvas/surface/types.ts b/packages/vue/src/canvas/surface/types.ts
index cd4d00f7b..035bfdcae 100644
--- a/packages/vue/src/canvas/surface/types.ts
+++ b/packages/vue/src/canvas/surface/types.ts
@@ -12,6 +12,10 @@ export interface UseCanvasOptions {
* Selects which render layer this canvas owns.
*/
layer?: CanvasRenderLayer
+ /**
+ * Enables the experimental tiled scene renderer for this surface.
+ */
+ sceneRenderer?: 'retained' | 'tiled'
/**
* Forces ruler visibility on or off for this canvas.
*
diff --git a/packages/vue/src/i18n/locales/de/dialogs.json b/packages/vue/src/i18n/locales/de/dialogs.json
index 4ea3f79c3..cea1eacdb 100644
--- a/packages/vue/src/i18n/locales/de/dialogs.json
+++ b/packages/vue/src/i18n/locales/de/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "Dadurch werden lokal gespeicherte Diagnosedaten von diesem Gerät entfernt.",
"diagnosticsCleared": "Diagnosedaten gelöscht.",
"diagnosticsCopied": "Diagnosedaten in die Zwischenablage kopiert.",
- "diagnosticsCopyFailed": "Diagnosedaten konnten nicht in die Zwischenablage kopiert werden."
+ "diagnosticsCopyFailed": "Diagnosedaten konnten nicht in die Zwischenablage kopiert werden.",
+ "settingsRendering": "Darstellung",
+ "settingsRenderingDescription": "Wähle, wie OpenPencil große Arbeitsflächen darstellt.",
+ "progressiveTiledRendering": "Progressive gekachelte Darstellung",
+ "progressiveTiledRenderingDescription": "Aktualisiert große Arbeitsflächen beim Navigieren in begrenzten Kacheln. Experimentell; Neuladen erforderlich.",
+ "rendererReloadRequired": "Lade OpenPencil neu, um diese Änderung anzuwenden.",
+ "rendererURLOverride": "Der Renderer dieser Sitzung wird durch einen URL-Parameter gesteuert. Deine gespeicherte Einstellung gilt, sobald der Parameter entfernt wird."
}
diff --git a/packages/vue/src/i18n/locales/es/dialogs.json b/packages/vue/src/i18n/locales/es/dialogs.json
index c7ec43ec4..2195efe9b 100644
--- a/packages/vue/src/i18n/locales/es/dialogs.json
+++ b/packages/vue/src/i18n/locales/es/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "Esto elimina del dispositivo los eventos de diagnóstico almacenados localmente.",
"diagnosticsCleared": "Diagnóstico borrado.",
"diagnosticsCopied": "Diagnóstico copiado al portapapeles.",
- "diagnosticsCopyFailed": "No se pudo copiar el diagnóstico al portapapeles."
+ "diagnosticsCopyFailed": "No se pudo copiar el diagnóstico al portapapeles.",
+ "settingsRendering": "Renderizado",
+ "settingsRenderingDescription": "Elige cómo presenta OpenPencil los lienzos grandes.",
+ "progressiveTiledRendering": "Renderizado progresivo por mosaicos",
+ "progressiveTiledRenderingDescription": "Actualiza los lienzos grandes en mosaicos limitados durante la navegación. Experimental; requiere recargar.",
+ "rendererReloadRequired": "Recarga OpenPencil para aplicar este cambio.",
+ "rendererURLOverride": "El renderizador de esta sesión está controlado por un parámetro de URL. Tu preferencia guardada se aplicará al eliminarlo."
}
diff --git a/packages/vue/src/i18n/locales/fr/dialogs.json b/packages/vue/src/i18n/locales/fr/dialogs.json
index a3003846e..879bf4ecd 100644
--- a/packages/vue/src/i18n/locales/fr/dialogs.json
+++ b/packages/vue/src/i18n/locales/fr/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "Cette action supprime de cet appareil les événements de diagnostic stockés localement.",
"diagnosticsCleared": "Diagnostics effacés.",
"diagnosticsCopied": "Diagnostics copiés dans le presse-papiers.",
- "diagnosticsCopyFailed": "Impossible de copier les diagnostics dans le presse-papiers."
+ "diagnosticsCopyFailed": "Impossible de copier les diagnostics dans le presse-papiers.",
+ "settingsRendering": "Rendu",
+ "settingsRenderingDescription": "Choisissez comment OpenPencil affiche les grandes zones de travail.",
+ "progressiveTiledRendering": "Rendu progressif par tuiles",
+ "progressiveTiledRenderingDescription": "Met à jour les grandes zones de travail par tuiles limitées pendant la navigation. Expérimental ; rechargement requis.",
+ "rendererReloadRequired": "Rechargez OpenPencil pour appliquer cette modification.",
+ "rendererURLOverride": "Le rendu de cette session est contrôlé par un paramètre d’URL. Votre préférence enregistrée s’appliquera après sa suppression."
}
diff --git a/packages/vue/src/i18n/locales/it/dialogs.json b/packages/vue/src/i18n/locales/it/dialogs.json
index 2076e99c1..990a060bb 100644
--- a/packages/vue/src/i18n/locales/it/dialogs.json
+++ b/packages/vue/src/i18n/locales/it/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "Questa operazione rimuove da questo dispositivo gli eventi diagnostici archiviati localmente.",
"diagnosticsCleared": "Diagnostica cancellata.",
"diagnosticsCopied": "Diagnostica copiata negli appunti.",
- "diagnosticsCopyFailed": "Impossibile copiare la diagnostica negli appunti."
+ "diagnosticsCopyFailed": "Impossibile copiare la diagnostica negli appunti.",
+ "settingsRendering": "Rendering",
+ "settingsRenderingDescription": "Scegli come OpenPencil visualizza le aree di lavoro di grandi dimensioni.",
+ "progressiveTiledRendering": "Rendering progressivo a riquadri",
+ "progressiveTiledRenderingDescription": "Aggiorna le aree di lavoro grandi in riquadri limitati durante la navigazione. Sperimentale; richiede il ricaricamento.",
+ "rendererReloadRequired": "Ricarica OpenPencil per applicare questa modifica.",
+ "rendererURLOverride": "Il renderer della sessione corrente è controllato da un parametro URL. La preferenza salvata verrà applicata quando il parametro sarà rimosso."
}
diff --git a/packages/vue/src/i18n/locales/ja/dialogs.json b/packages/vue/src/i18n/locales/ja/dialogs.json
index 0bc69eeab..619008c34 100644
--- a/packages/vue/src/i18n/locales/ja/dialogs.json
+++ b/packages/vue/src/i18n/locales/ja/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "このデバイスに保存されている診断イベントを削除します。",
"diagnosticsCleared": "診断データを消去しました。",
"diagnosticsCopied": "診断データをクリップボードにコピーしました。",
- "diagnosticsCopyFailed": "診断データをクリップボードにコピーできませんでした。"
+ "diagnosticsCopyFailed": "診断データをクリップボードにコピーできませんでした。",
+ "settingsRendering": "レンダリング",
+ "settingsRenderingDescription": "大きなキャンバスを OpenPencil で表示する方法を選択します。",
+ "progressiveTiledRendering": "プログレッシブタイルレンダリング",
+ "progressiveTiledRenderingDescription": "移動中に大きなキャンバスを限定されたタイル単位で更新します。試験機能のため、再読み込みが必要です。",
+ "rendererReloadRequired": "この変更を適用するには OpenPencil を再読み込みしてください。",
+ "rendererURLOverride": "現在のセッションのレンダラーは URL パラメーターで指定されています。保存した設定はパラメーターを削除すると適用されます。"
}
diff --git a/packages/vue/src/i18n/locales/pl/dialogs.json b/packages/vue/src/i18n/locales/pl/dialogs.json
index 9cbff2540..d9700d52d 100644
--- a/packages/vue/src/i18n/locales/pl/dialogs.json
+++ b/packages/vue/src/i18n/locales/pl/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "Spowoduje to usunięcie lokalnie zapisanych zdarzeń diagnostycznych z tego urządzenia.",
"diagnosticsCleared": "Wyczyszczono dane diagnostyczne.",
"diagnosticsCopied": "Skopiowano dane diagnostyczne do schowka.",
- "diagnosticsCopyFailed": "Nie można skopiować danych diagnostycznych do schowka."
+ "diagnosticsCopyFailed": "Nie można skopiować danych diagnostycznych do schowka.",
+ "settingsRendering": "Renderowanie",
+ "settingsRenderingDescription": "Wybierz sposób wyświetlania dużych obszarów roboczych w OpenPencil.",
+ "progressiveTiledRendering": "Progresywne renderowanie kafelkowe",
+ "progressiveTiledRenderingDescription": "Podczas nawigacji aktualizuje duże obszary robocze w ograniczonych kafelkach. Funkcja eksperymentalna; wymaga ponownego wczytania.",
+ "rendererReloadRequired": "Wczytaj ponownie OpenPencil, aby zastosować tę zmianę.",
+ "rendererURLOverride": "Renderer bieżącej sesji jest kontrolowany przez parametr URL. Zapisana preferencja zostanie użyta po usunięciu parametru."
}
diff --git a/packages/vue/src/i18n/locales/ru/dialogs.json b/packages/vue/src/i18n/locales/ru/dialogs.json
index 63f6d0d44..c82491bc8 100644
--- a/packages/vue/src/i18n/locales/ru/dialogs.json
+++ b/packages/vue/src/i18n/locales/ru/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "Локально сохранённые диагностические события будут удалены с этого устройства.",
"diagnosticsCleared": "Диагностические данные очищены.",
"diagnosticsCopied": "Диагностические данные скопированы в буфер обмена.",
- "diagnosticsCopyFailed": "Не удалось скопировать диагностические данные в буфер обмена."
+ "diagnosticsCopyFailed": "Не удалось скопировать диагностические данные в буфер обмена.",
+ "settingsRendering": "Отрисовка",
+ "settingsRenderingDescription": "Выберите способ отображения больших холстов в OpenPencil.",
+ "progressiveTiledRendering": "Прогрессивная плиточная отрисовка",
+ "progressiveTiledRenderingDescription": "При навигации обновляет большие холсты ограниченными плитками. Экспериментальная функция; требуется перезагрузка.",
+ "rendererReloadRequired": "Перезагрузите OpenPencil, чтобы применить изменение.",
+ "rendererURLOverride": "Режим отрисовки текущего сеанса задан параметром URL. Сохранённая настройка применится после удаления параметра."
}
diff --git a/packages/vue/src/i18n/locales/zh-cn/dialogs.json b/packages/vue/src/i18n/locales/zh-cn/dialogs.json
index b2a0d000d..caa05ef71 100644
--- a/packages/vue/src/i18n/locales/zh-cn/dialogs.json
+++ b/packages/vue/src/i18n/locales/zh-cn/dialogs.json
@@ -389,5 +389,11 @@
"diagnosticsClearDescription": "这会从此设备中删除本地保存的诊断事件。",
"diagnosticsCleared": "诊断数据已清除。",
"diagnosticsCopied": "诊断数据已复制到剪贴板。",
- "diagnosticsCopyFailed": "无法将诊断数据复制到剪贴板。"
+ "diagnosticsCopyFailed": "无法将诊断数据复制到剪贴板。",
+ "settingsRendering": "渲染",
+ "settingsRenderingDescription": "选择 OpenPencil 显示大型画布的方式。",
+ "progressiveTiledRendering": "渐进式分块画布渲染",
+ "progressiveTiledRenderingDescription": "导航时以有限大小的分块更新大型画布。此功能为实验性功能,需要重新加载。",
+ "rendererReloadRequired": "重新加载 OpenPencil 以应用此更改。",
+ "rendererURLOverride": "当前会话的渲染器由 URL 参数控制。移除该参数后将应用已保存的偏好设置。"
}
diff --git a/packages/vue/src/i18n/messages/dialogs.ts b/packages/vue/src/i18n/messages/dialogs.ts
index bcc63673e..60c51cd78 100644
--- a/packages/vue/src/i18n/messages/dialogs.ts
+++ b/packages/vue/src/i18n/messages/dialogs.ts
@@ -190,6 +190,14 @@ export const dialogMessageDefaults = {
snapToPixelGridDescription:
'Align vector points, moved layers, and resized edges to whole pixels.',
snapTemporaryDisableHint: 'Hold Control while dragging to temporarily disable snapping.',
+ settingsRendering: 'Rendering',
+ settingsRenderingDescription: 'Choose how OpenPencil presents large canvases.',
+ progressiveTiledRendering: 'Progressive tiled canvas rendering',
+ progressiveTiledRenderingDescription:
+ 'Updates large canvases in bounded tiles while navigating. Experimental; reload required.',
+ rendererReloadRequired: 'Reload OpenPencil to apply this change.',
+ rendererURLOverride:
+ 'The current session renderer is controlled by a URL override. Your saved preference applies when the override is removed.',
settingsAIAndAgents: 'AI & agents',
settingsUsage: 'Usage',
usageDescription: 'Local usage summaries from recorded AI requests.',
diff --git a/packages/vue/src/shared/input/wheel.ts b/packages/vue/src/shared/input/wheel.ts
index f84426ab0..138eb56a9 100644
--- a/packages/vue/src/shared/input/wheel.ts
+++ b/packages/vue/src/shared/input/wheel.ts
@@ -1,7 +1,8 @@
import { useEventListener } from '@vueuse/core'
-import type { Ref } from 'vue'
+import { onScopeDispose, type Ref } from 'vue'
import type { Editor } from '@open-pencil/core/editor'
+import { emitNavigationTrace } from '@open-pencil/core/profiler'
import { createRafScheduler } from '#vue/shared/input/raf-scheduler'
@@ -49,6 +50,7 @@ export function wheelPanDelta(event: WheelPanInput): WheelPanDelta {
}
const WHEEL_ZOOM_SPEED = 1.25
+const NAVIGATION_SETTLE_DELAY_MS = 120
function wheelDeltaModeScale(event: WheelEvent) {
if (event.deltaMode === 1) return 0.05
@@ -70,7 +72,25 @@ export function setupWheelPanZoom(canvasRef: Ref<HTMLCanvasElement | null>, edit
hasZoom: false
}
+ let settleTimer: ReturnType<typeof setTimeout> | null = null
+
+ function scheduleSettle() {
+ if (settleTimer !== null) clearTimeout(settleTimer)
+ editor.setNavigationPhase('settling')
+ settleTimer = setTimeout(() => {
+ settleTimer = null
+ editor.setNavigationPhase('idle')
+ editor.requestRepaint()
+ }, NAVIGATION_SETTLE_DELAY_MS)
+ }
+
function flushWheel() {
+ emitNavigationTrace('wheel:flush', {
+ deltaX: wheelAccum.deltaX,
+ deltaY: wheelAccum.deltaY,
+ zoomScale: wheelAccum.zoomScale,
+ zoom: wheelAccum.hasZoom
+ })
editor.setHoveredNode(null)
if (wheelAccum.hasZoom) {
editor.setZoomAroundPoint(
@@ -85,6 +105,7 @@ export function setupWheelPanZoom(canvasRef: Ref<HTMLCanvasElement | null>, edit
wheelAccum.deltaY = 0
wheelAccum.zoomScale = 1
wheelAccum.hasZoom = false
+ scheduleSettle()
}
const wheelScheduler = createRafScheduler(flushWheel)
@@ -93,6 +114,20 @@ export function setupWheelPanZoom(canvasRef: Ref<HTMLCanvasElement | null>, edit
const canvas = canvasRef.value
if (!canvas) return
+ emitNavigationTrace('wheel:received', {
+ deltaX: event.deltaX,
+ deltaY: event.deltaY,
+ deltaMode: event.deltaMode,
+ ctrlKey: event.ctrlKey,
+ metaKey: event.metaKey,
+ shiftKey: event.shiftKey,
+ clientX: event.clientX,
+ clientY: event.clientY,
+ trusted: event.isTrusted
+ })
+
+ editor.setNavigationPhase(isWheelZoom(event) ? 'zoom' : 'pan', performance.now())
+
if (isWheelZoom(event)) {
const rect = canvas.getBoundingClientRect()
wheelAccum.zoomCenterX = event.clientX - rect.left
@@ -116,4 +151,8 @@ export function setupWheelPanZoom(canvasRef: Ref<HTMLCanvasElement | null>, edit
},
{ passive: false }
)
+
+ onScopeDispose(() => {
+ if (settleTimer !== null) clearTimeout(settleTimer)
+ })
}
diff --git a/src/app/browser-bridge.ts b/src/app/browser-bridge.ts
index 60409531b..93c2c24cf 100644
--- a/src/app/browser-bridge.ts
+++ b/src/app/browser-bridge.ts
@@ -2,12 +2,16 @@ import type { ChatTransport, UIMessage } from 'ai'
import type { CollabReturn } from '@/app/collab/context'
import type { EditorStore } from '@/app/editor/session/create'
+import { createNavigationBenchmarkHooks } from '@/app/performance/navigation/hooks'
+import type { NavigationBenchmarkHooks } from '@/app/performance/navigation/hooks'
+import { appRuntimeConfig } from '@/app/runtime/config'
import { IS_BROWSER } from '@/constants'
export interface OpenPencilTestHooks {
writeCount?: () => number
mockHandle?: FileSystemFileHandle
savedOpen?: Window['open']
+ navigation?: NavigationBenchmarkHooks
collab?: Pick<
CollabReturn,
'connect' | 'disconnect' | 'updateCursor' | 'updateSelection' | 'setLocalName'
@@ -43,12 +47,17 @@ function windowAPI(): OpenPencilWindowAPI {
export function setOpenPencilStore(store: EditorStore) {
activeStore = store
- windowAPI()
+ if (!IS_BROWSER) return
+ const api = windowAPI()
+ if (appRuntimeConfig.navigationBenchmark) {
+ const testHooks = (api.test ??= {})
+ testHooks.navigation = createNavigationBenchmarkHooks(store)
+ }
}
export function exposeCollaborationActions(collab: CollabReturn) {
if (!IS_BROWSER || !import.meta.env.DEV) return
- if (!new URLSearchParams(window.location.search).has('test')) return
+ if (!appRuntimeConfig.test) return
const testHooks = (windowAPI().test ??= {})
testHooks.collab = {
connect: collab.connect,
diff --git a/src/app/collab/transport/index.ts b/src/app/collab/transport/index.ts
index 051546ba0..cb240a584 100644
--- a/src/app/collab/transport/index.ts
+++ b/src/app/collab/transport/index.ts
@@ -1,12 +1,11 @@
-import { IS_BROWSER } from '@/constants'
+import { appRuntimeConfig } from '@/app/runtime/config'
import { joinTestCollabRoom } from './test'
import { joinTrysteroCollabRoom } from './trystero'
import type { JoinCollabRoom } from './types'
function usesTestTransport(): boolean {
- if (!IS_BROWSER || !import.meta.env.DEV) return false
- return new URLSearchParams(window.location.search).get('collabTransport') === 'test'
+ return import.meta.env.DEV && appRuntimeConfig.collaborationTransport === 'test'
}
export const joinCollabRoom: JoinCollabRoom = (roomId) =>
diff --git a/src/app/collab/transport/test.ts b/src/app/collab/transport/test.ts
index f19206d36..0f2e93b6b 100644
--- a/src/app/collab/transport/test.ts
+++ b/src/app/collab/transport/test.ts
@@ -1,3 +1,4 @@
+import { appRuntimeConfig } from '@/app/runtime/config'
import { IS_BROWSER } from '@/constants'
import type { CollabAction, CollabActionReceiver, CollabRoomTransport } from './types'
@@ -48,7 +49,7 @@ function relayURL(roomId: string): URL {
if (!IS_BROWSER) {
throw new Error('Test collaboration transport requires a browser')
}
- const configured = new URLSearchParams(window.location.search).get('collabRelay')
+ const configured = appRuntimeConfig.collaborationRelayURL
if (!configured) throw new Error('Test collaboration transport requires collabRelay')
const url = new URL(configured)
url.searchParams.set('roomId', roomId)
diff --git a/src/app/editor/session/modules.ts b/src/app/editor/session/modules.ts
index 0db6c9ec6..e6fb3f7d7 100644
--- a/src/app/editor/session/modules.ts
+++ b/src/app/editor/session/modules.ts
@@ -24,6 +24,10 @@ export function defineEditorStoreAccessors(store: object, editor: Editor) {
enumerable: true,
get: () => editor.renderer
},
+ canvasRenderers: {
+ enumerable: true,
+ get: () => editor.canvasRenderers
+ },
textEditor: {
enumerable: true,
get: () => editor.textEditor
diff --git a/src/app/performance/navigation/hooks.ts b/src/app/performance/navigation/hooks.ts
new file mode 100644
index 000000000..80e7dae39
--- /dev/null
+++ b/src/app/performance/navigation/hooks.ts
@@ -0,0 +1,93 @@
+import type { EditorStore } from '@/app/editor/session/create'
+import type { NavigationRecording, NavigationRecorder } from '@/app/performance/navigation/recorder'
+import { startNavigationRecorder } from '@/app/performance/navigation/recorder'
+
+export interface NavigationBenchmarkHooks {
+ startRecording: (name: string) => void
+ waitForSettlement: (timeoutMs?: number) => Promise<void>
+ stopRecording: () => NavigationRecording
+}
+
+let recorder: NavigationRecorder | null = null
+
+export function createNavigationBenchmarkHooks(store: EditorStore): NavigationBenchmarkHooks {
+ return {
+ startRecording(name) {
+ if (recorder) throw new Error('A navigation recording is already active')
+ const canvas = document.querySelector<HTMLCanvasElement>('[data-test-id="canvas-element"]')
+ if (!canvas) throw new Error('Canvas element not found')
+ recorder = startNavigationRecorder(
+ canvas,
+ name,
+ {
+ panX: store.state.panX,
+ panY: store.state.panY,
+ zoom: store.state.zoom
+ },
+ store.canvasRenderers.some(
+ (renderer) => renderer.tracksSceneSettlement && renderer.tiledSceneEnabled
+ )
+ ? 'tiled'
+ : 'retained'
+ )
+ },
+ async waitForSettlement(timeoutMs = 30_000) {
+ await new Promise<void>((resolve, reject) => {
+ let frameId: number | null = null
+ let finished = false
+ const finish = (result: 'resolve' | 'reject', error?: Error) => {
+ if (finished) return
+ finished = true
+ if (frameId !== null) cancelAnimationFrame(frameId)
+ clearTimeout(timeout)
+ if (result === 'resolve') resolve()
+ else reject(error ?? new Error('Navigation settlement failed'))
+ }
+ const timeout = setTimeout(() => {
+ const state = store.canvasRenderers
+ .filter((renderer) => renderer.tracksSceneSettlement && renderer.pageId !== null)
+ .map((renderer) => ({
+ tiled: renderer.tiledSceneEnabled,
+ covered: renderer.tiledSceneCovered,
+ pending: renderer.tiledScenePending,
+ backingCrisp: !renderer.sceneBackingNeedsCrispRender
+ }))
+ finish(
+ 'reject',
+ new Error(
+ `Navigation renderer did not settle within ${timeoutMs} ms: ${JSON.stringify({
+ navigationPhase: store.state.navigation.phase,
+ renderers: state
+ })}`
+ )
+ )
+ }, timeoutMs)
+ const check = () => {
+ const renderers = store.canvasRenderers.filter(
+ (renderer) => renderer.tracksSceneSettlement && renderer.pageId !== null
+ )
+ const settled =
+ store.state.navigation.phase === 'idle' &&
+ renderers.length > 0 &&
+ renderers.every((renderer) =>
+ renderer.tiledSceneEnabled
+ ? renderer.tiledSceneCovered && !renderer.tiledScenePending
+ : !renderer.sceneBackingNeedsCrispRender
+ )
+ if (settled) {
+ finish('resolve')
+ return
+ }
+ frameId = requestAnimationFrame(check)
+ }
+ frameId = requestAnimationFrame(check)
+ })
+ },
+ stopRecording() {
+ if (!recorder) throw new Error('No navigation recording is active')
+ const result = recorder.stop()
+ recorder = null
+ return result
+ }
+ }
+}
diff --git a/src/app/performance/navigation/recorder.ts b/src/app/performance/navigation/recorder.ts
new file mode 100644
index 000000000..1bbce8748
--- /dev/null
+++ b/src/app/performance/navigation/recorder.ts
@@ -0,0 +1,110 @@
+import type { NavigationTraceEvent, RecordedWheelSample } from '@open-pencil/core/profiler'
+import { subscribeNavigationTrace } from '@open-pencil/core/profiler'
+
+export interface NavigationRecording {
+ schemaVersion: 1
+ name: string
+ source: 'macos-trackpad' | 'synthetic'
+ recordedAt: string
+ environment: {
+ userAgent: string
+ platform: string
+ devicePixelRatio: number
+ viewportWidth: number
+ viewportHeight: number
+ canvasWidth: number
+ canvasHeight: number
+ }
+ sceneRenderer: 'retained' | 'tiled'
+ initialViewport: { panX: number; panY: number; zoom: number }
+ wheel: RecordedWheelSample[]
+ trace: NavigationTraceEvent[]
+}
+
+type Viewport = NavigationRecording['initialViewport']
+
+export interface NavigationRecorder {
+ stop: () => NavigationRecording
+}
+
+export function startNavigationRecorder(
+ canvas: HTMLCanvasElement,
+ name: string,
+ initialViewport: Viewport,
+ sceneRenderer: NavigationRecording['sceneRenderer']
+): NavigationRecorder {
+ const startedAt = performance.now()
+ const wheel: RecordedWheelSample[] = []
+ const trace: NavigationTraceEvent[] = []
+ let frameId: number | null = null
+ const recordAnimationFrame = (timestamp: number) => {
+ trace.push({ name: 'animation:frame', timestamp: timestamp - startedAt, detail: {} })
+ frameId = requestAnimationFrame(recordAnimationFrame)
+ }
+ frameId = requestAnimationFrame(recordAnimationFrame)
+
+ const longTaskObserver =
+ typeof PerformanceObserver !== 'undefined' &&
+ PerformanceObserver.supportedEntryTypes.includes('longtask')
+ ? new PerformanceObserver((list) => {
+ for (const entry of list.getEntries()) {
+ trace.push({
+ name: 'main:long-task',
+ timestamp: entry.startTime - startedAt,
+ detail: { durationMs: entry.duration }
+ })
+ }
+ })
+ : null
+ longTaskObserver?.observe({ entryTypes: ['longtask'] })
+
+ const recordWheel = (event: WheelEvent) => {
+ const extended = event as WheelEvent & { webkitDirectionInvertedFromDevice?: boolean }
+ wheel.push({
+ timeMs: performance.now() - startedAt,
+ deltaX: event.deltaX,
+ deltaY: event.deltaY,
+ deltaMode: event.deltaMode,
+ ctrlKey: event.ctrlKey,
+ metaKey: event.metaKey,
+ shiftKey: event.shiftKey,
+ clientX: event.clientX,
+ clientY: event.clientY,
+ cancelable: event.cancelable,
+ directionInvertedFromDevice: extended.webkitDirectionInvertedFromDevice
+ })
+ }
+ canvas.addEventListener('wheel', recordWheel, { capture: true, passive: true })
+ const unsubscribeTrace = subscribeNavigationTrace((event) => {
+ trace.push({ ...event, timestamp: event.timestamp - startedAt })
+ })
+
+ return {
+ stop() {
+ canvas.removeEventListener('wheel', recordWheel, { capture: true })
+ if (frameId !== null) cancelAnimationFrame(frameId)
+ longTaskObserver?.disconnect()
+ unsubscribeTrace()
+ const rect = canvas.getBoundingClientRect()
+ return {
+ schemaVersion: 1,
+ name,
+ source: 'macos-trackpad',
+ recordedAt: new Date().toISOString(),
+ environment: {
+ userAgent: navigator.userAgent,
+ platform: navigator.platform,
+ devicePixelRatio: window.devicePixelRatio,
+ viewportWidth: window.innerWidth,
+ viewportHeight: window.innerHeight,
+ canvasWidth: rect.width,
+ canvasHeight: rect.height
+ },
+ sceneRenderer,
+ initialViewport,
+ wheel,
+ trace
+ }
+ }
+ }
+}
diff --git a/src/app/runtime/config.ts b/src/app/runtime/config.ts
new file mode 100644
index 000000000..5be9fca60
--- /dev/null
+++ b/src/app/runtime/config.ts
@@ -0,0 +1,43 @@
+import { appPreferences, type CanvasRenderingMode } from '@/app/settings/preferences/store'
+import { IS_BROWSER } from '@/constants'
+
+export type SceneRendererMode = CanvasRenderingMode
+export type CollaborationTransportMode = 'default' | 'test'
+
+export interface AppRuntimeConfig {
+ test: boolean
+ navigationBenchmark: boolean
+ recentFiles: boolean
+ showChrome: boolean
+ showRulers: boolean
+ sceneRenderer: SceneRendererMode
+ sceneRendererOverride: boolean
+ collaborationTransport: CollaborationTransportMode
+ collaborationRelayURL: string | null
+}
+
+export function parseAppRuntimeConfig(
+ search: string,
+ preferredRenderer: SceneRendererMode = 'retained'
+): AppRuntimeConfig {
+ const params = new URLSearchParams(search)
+ const renderer = params.get('renderer')
+ const sceneRenderer =
+ renderer === 'tiled' || renderer === 'retained' ? renderer : preferredRenderer
+ return {
+ test: params.has('test'),
+ navigationBenchmark: params.has('navigation-benchmark'),
+ recentFiles: params.has('recent-files'),
+ showChrome: !params.has('no-chrome'),
+ showRulers: !params.has('no-rulers'),
+ sceneRenderer,
+ sceneRendererOverride: renderer === 'tiled' || renderer === 'retained',
+ collaborationTransport: params.get('collabTransport') === 'test' ? 'test' : 'default',
+ collaborationRelayURL: params.get('collabRelay')
+ }
+}
+
+export const appRuntimeConfig = parseAppRuntimeConfig(
+ IS_BROWSER ? window.location.search : '',
+ appPreferences.value.rendering.canvasMode
+)
diff --git a/src/app/settings/preferences/store.ts b/src/app/settings/preferences/store.ts
index fb5185a2e..2a97d26ad 100644
--- a/src/app/settings/preferences/store.ts
+++ b/src/app/settings/preferences/store.ts
@@ -2,6 +2,8 @@ import { useLocalStorage } from '@vueuse/core'
import { DEFAULT_SNAPPING_PREFERENCES, type SnappingPreferences } from '@open-pencil/core/editor'
+export type CanvasRenderingMode = 'retained' | 'tiled'
+
export interface AppPreferences {
version: 1
recovery: {
@@ -10,6 +12,9 @@ export interface AppPreferences {
editing: {
snapping: SnappingPreferences
}
+ rendering: {
+ canvasMode: CanvasRenderingMode
+ }
}
export const DEFAULT_APP_PREFERENCES: Readonly<AppPreferences> = {
@@ -17,7 +22,8 @@ export const DEFAULT_APP_PREFERENCES: Readonly<AppPreferences> = {
recovery: { enabled: true },
editing: {
snapping: { ...DEFAULT_SNAPPING_PREFERENCES }
- }
+ },
+ rendering: { canvasMode: 'retained' }
}
const STORAGE_KEY = 'open-pencil:preferences:v1'
@@ -35,6 +41,7 @@ interface StoredSnappingPreferences {
interface StoredAppPreferences {
recovery?: { enabled?: unknown }
editing?: { snapping?: StoredSnappingPreferences }
+ rendering?: { canvasMode?: unknown }
}
function isStoredAppPreferences(value: unknown): value is StoredAppPreferences {
@@ -65,6 +72,9 @@ function normalizePreferences(value: unknown): AppPreferences {
DEFAULT_APP_PREFERENCES.editing.snapping.pixelGrid
)
}
+ },
+ rendering: {
+ canvasMode: stored?.rendering?.canvasMode === 'tiled' ? 'tiled' : 'retained'
}
}
}
@@ -81,6 +91,13 @@ export function updateRecoveryEnabled(enabled: boolean): void {
appPreferences.value = preferences
}
+export function updateCanvasRenderingMode(canvasMode: CanvasRenderingMode): void {
+ appPreferences.value = {
+ ...appPreferences.value,
+ rendering: { canvasMode }
+ }
+}
+
export function updateSnappingPreferences(changes: Partial<SnappingPreferences>): void {
appPreferences.value = {
...appPreferences.value,
diff --git a/src/components/EditorCanvas.vue b/src/components/EditorCanvas.vue
index 2ac184b9b..985d9c65d 100644
--- a/src/components/EditorCanvas.vue
+++ b/src/components/EditorCanvas.vue
@@ -23,6 +23,7 @@ import {
} from '@open-pencil/vue'
import { useCollabInjected } from '@/app/collab/use'
import { useEditorStore } from '@/app/editor/active-store'
+import { appRuntimeConfig } from '@/app/runtime/config'
import { useCanvasCollaborationAwareness } from '@/app/editor/canvas/collaboration-awareness'
import { createCanvasContextSelection } from '@/app/editor/canvas/context-selection'
import IconLucidePanelBottom from '~icons/lucide/panel-bottom'
@@ -69,6 +70,7 @@ const shouldSuspendRender = () =>
useCanvas(sceneCanvasRef, store, {
layer: 'scene',
+ sceneRenderer: appRuntimeConfig.sceneRenderer,
shouldSuspendRender,
showRulers: false,
getRenderState,
diff --git a/src/components/editor/EditorWorkspace.vue b/src/components/editor/EditorWorkspace.vue
index 2e7fad084..9747c5333 100644
--- a/src/components/editor/EditorWorkspace.vue
+++ b/src/components/editor/EditorWorkspace.vue
@@ -1,11 +1,11 @@
<script setup lang="ts">
import { tv } from 'tailwind-variants'
-import { useUrlSearchParams } from '@vueuse/core'
import { SplitterGroup, SplitterPanel, SplitterResizeHandle } from 'reka-ui'
import { formatShortcut, useI18n, useViewportKind } from '@open-pencil/vue'
import { useEditorStore } from '@/app/editor/active-store'
+import { appRuntimeConfig } from '@/app/runtime/config'
import { appMenuShortcut } from '@/app/shell/menu/shortcut'
import { activeTab } from '@/app/tabs'
import CanvasSplitRoot from '@/components/canvas/CanvasSplitRoot.vue'
@@ -20,8 +20,7 @@ import Toolbar from '@/components/Toolbar/Toolbar.vue'
import { loadEditorLayout, saveEditorLayout } from '@/app/shell/layout-storage'
import splitterTheme from '@/theme/splitter'
-const params = useUrlSearchParams('history')
-const showChrome = !('no-chrome' in params)
+const showChrome = appRuntimeConfig.showChrome
const store = useEditorStore()
const { dialogs } = useI18n()
const { isMobile } = useViewportKind()
diff --git a/src/components/settings/diagnostics/DiagnosticsSettingsPanel.vue b/src/components/settings/diagnostics/DiagnosticsSettingsPanel.vue
index 2d879d5bd..f55a0c094 100644
--- a/src/components/settings/diagnostics/DiagnosticsSettingsPanel.vue
+++ b/src/components/settings/diagnostics/DiagnosticsSettingsPanel.vue
@@ -16,6 +16,8 @@ import { toast } from '@/app/shell/ui'
import { AppConfirmationDialog } from '@/components/ui/dialog'
import AppButton from '@/components/ui/AppButton.vue'
import AppSwitch from '@/components/ui/AppSwitch.vue'
+import SettingsGroup from '@/components/settings/layout/SettingsGroup.vue'
+import SettingsSectionHeader from '@/components/settings/layout/SettingsSectionHeader.vue'
const { dialogs } = useI18n()
const recentEvents = ref<DiagnosticEventSummary[]>([])
@@ -75,11 +77,11 @@ async function exportDiagnostics() {
<template>
<section class="flex flex-col gap-4" data-test-id="settings-diagnostics-panel">
- <div>
- <h3 class="text-xs font-semibold text-surface">{{ dialogs.diagnosticsTitle }}</h3>
- <p class="mt-1 text-[11px] text-muted">{{ dialogs.diagnosticsDescription }}</p>
- </div>
- <div class="flex flex-col divide-y divide-border rounded border border-border">
+ <SettingsSectionHeader>
+ {{ dialogs.diagnosticsTitle }}
+ <template #description>{{ dialogs.diagnosticsDescription }}</template>
+ </SettingsSectionHeader>
+ <SettingsGroup>
<label class="flex items-center justify-between gap-4 px-3 py-2.5">
<span
><span class="block text-xs text-surface">{{ dialogs.localDiagnostics }}</span
@@ -120,7 +122,7 @@ async function exportDiagnostics() {
>
</SegmentedControlRoot>
</div>
- </div>
+ </SettingsGroup>
<div
v-if="recentEvents.length"
class="flex max-h-64 flex-col overflow-y-auto divide-y divide-border rounded border border-border"
diff --git a/src/components/settings/general/GeneralSettingsPanel.vue b/src/components/settings/general/GeneralSettingsPanel.vue
index 0228560a9..c19369bff 100644
--- a/src/components/settings/general/GeneralSettingsPanel.vue
+++ b/src/components/settings/general/GeneralSettingsPanel.vue
@@ -7,6 +7,9 @@ import { setSnappingPreference } from '@/app/settings/preferences/apply'
import { appPreferences } from '@/app/settings/preferences/store'
import AppSelect from '@/components/ui/AppSelect.vue'
import AppSwitch from '@/components/ui/AppSwitch.vue'
+import RenderingSettingsSection from '@/components/settings/general/RenderingSettingsSection.vue'
+import SettingsGroup from '@/components/settings/layout/SettingsGroup.vue'
+import SettingsSectionHeader from '@/components/settings/layout/SettingsSectionHeader.vue'
const { availableLocales, dialogs, locale, localeLabels, menu, setLocale } = useI18n()
@@ -61,12 +64,12 @@ const snapToPixelGrid = computed({
</label>
</div>
- <div>
- <h3 class="text-xs font-semibold text-surface">{{ dialogs.settingsRecovery }}</h3>
- <p class="mt-1 text-[11px] text-muted">{{ dialogs.settingsRecoveryDescription }}</p>
- </div>
+ <SettingsSectionHeader>
+ {{ dialogs.settingsRecovery }}
+ <template #description>{{ dialogs.settingsRecoveryDescription }}</template>
+ </SettingsSectionHeader>
- <div class="flex flex-col rounded border border-border">
+ <SettingsGroup>
<label class="flex items-center justify-between gap-4 px-3 py-2.5">
<span>
<span class="block text-xs text-surface">{{ dialogs.preserveUnsavedWork }}</span>
@@ -80,14 +83,14 @@ const snapToPixelGrid = computed({
data-test-id="settings-recovery-enabled"
/>
</label>
- </div>
+ </SettingsGroup>
- <div>
- <h3 class="text-xs font-semibold text-surface">{{ dialogs.settingsEditing }}</h3>
- <p class="mt-1 text-[11px] text-muted">{{ dialogs.settingsSnappingDescription }}</p>
- </div>
+ <SettingsSectionHeader>
+ {{ dialogs.settingsEditing }}
+ <template #description>{{ dialogs.settingsSnappingDescription }}</template>
+ </SettingsSectionHeader>
- <div class="flex flex-col divide-y divide-border rounded border border-border">
+ <SettingsGroup>
<label class="flex items-center justify-between gap-4 px-3 py-2.5">
<span>
<span class="block text-xs text-surface">{{ dialogs.snapToGeometry }}</span>
@@ -121,8 +124,10 @@ const snapToPixelGrid = computed({
data-test-id="settings-snap-pixel-grid"
/>
</label>
- </div>
+ </SettingsGroup>
<p class="text-[10px] text-muted">{{ dialogs.snapTemporaryDisableHint }}</p>
+
+ <RenderingSettingsSection />
</section>
</template>
diff --git a/src/components/settings/general/RenderingSettingsSection.vue b/src/components/settings/general/RenderingSettingsSection.vue
new file mode 100644
index 000000000..bf6c335a3
--- /dev/null
+++ b/src/components/settings/general/RenderingSettingsSection.vue
@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useI18n } from '@open-pencil/vue'
+
+import { appRuntimeConfig } from '@/app/runtime/config'
+import { appPreferences, updateCanvasRenderingMode } from '@/app/settings/preferences/store'
+import AppSwitch from '@/components/ui/AppSwitch.vue'
+import SettingsGroup from '@/components/settings/layout/SettingsGroup.vue'
+import SettingsSectionHeader from '@/components/settings/layout/SettingsSectionHeader.vue'
+
+const { dialogs } = useI18n()
+const hasURLOverride = appRuntimeConfig.sceneRendererOverride
+const tiledRendering = computed(() => appPreferences.value.rendering.canvasMode === 'tiled')
+const changed = computed(
+ () => appPreferences.value.rendering.canvasMode !== appRuntimeConfig.sceneRenderer
+)
+
+function setTiledRendering(enabled: boolean): void {
+ updateCanvasRenderingMode(enabled ? 'tiled' : 'retained')
+}
+</script>
+
+<template>
+ <SettingsSectionHeader>
+ {{ dialogs.settingsRendering }}
+ <template #description>{{ dialogs.settingsRenderingDescription }}</template>
+ </SettingsSectionHeader>
+
+ <SettingsGroup>
+ <label class="flex items-center justify-between gap-4 px-3 py-2.5">
+ <span>
+ <span class="block text-xs text-surface">{{ dialogs.progressiveTiledRendering }}</span>
+ <span class="block text-[10px] text-muted">{{
+ dialogs.progressiveTiledRenderingDescription
+ }}</span>
+ </span>
+ <AppSwitch
+ :model-value="tiledRendering"
+ :label="dialogs.progressiveTiledRendering"
+ data-test-id="settings-progressive-tiled-rendering"
+ @update:model-value="setTiledRendering"
+ />
+ </label>
+ </SettingsGroup>
+
+ <p v-if="hasURLOverride" class="text-[10px] text-muted">
+ {{ dialogs.rendererURLOverride }}
+ </p>
+ <p v-else-if="changed" class="text-[10px] text-muted">
+ {{ dialogs.rendererReloadRequired }}
+ </p>
+</template>
diff --git a/src/components/settings/layout/SettingsGroup.vue b/src/components/settings/layout/SettingsGroup.vue
new file mode 100644
index 000000000..4e8620ba2
--- /dev/null
+++ b/src/components/settings/layout/SettingsGroup.vue
@@ -0,0 +1,5 @@
+<template>
+ <div class="flex flex-col divide-y divide-border rounded border border-border">
+ <slot />
+ </div>
+</template>
diff --git a/src/components/settings/layout/SettingsSectionHeader.vue b/src/components/settings/layout/SettingsSectionHeader.vue
new file mode 100644
index 000000000..5caf370ec
--- /dev/null
+++ b/src/components/settings/layout/SettingsSectionHeader.vue
@@ -0,0 +1,8 @@
+<template>
+ <div>
+ <h3 class="text-xs font-semibold text-surface"><slot /></h3>
+ <p v-if="$slots.description" class="mt-1 text-[11px] text-muted">
+ <slot name="description" />
+ </p>
+ </div>
+</template>
diff --git a/src/views/WorkspaceView.vue b/src/views/WorkspaceView.vue
index d5123871f..7dd0ab1b6 100644
--- a/src/views/WorkspaceView.vue
+++ b/src/views/WorkspaceView.vue
@@ -1,10 +1,11 @@
<script setup lang="ts">
import { onMounted, onUnmounted, provide, ref } from 'vue'
-import { useEventListener, useUrlSearchParams } from '@vueuse/core'
+import { useEventListener } from '@vueuse/core'
import { useHead } from '@unhead/vue'
import { useRoute } from 'vue-router'
import { exposeCollaborationActions } from '@/app/browser-bridge'
+import { appRuntimeConfig } from '@/app/runtime/config'
import { startMCPRuntime, stopMCPRuntime } from '@/app/automation/mcp/runtime'
import { COLLAB_KEY, useCollab } from '@/app/collab/use'
import { createDemoShapes } from '@/app/demo/document'
@@ -27,17 +28,16 @@ import EditorWorkspace from '@/components/editor/EditorWorkspace.vue'
import HomeWorkspace from '@/components/home/HomeWorkspace.vue'
const route = useRoute()
-const params = useUrlSearchParams('history')
const createdInitialTab = tabCount() === 0
const shouldCreateHome =
route.path === '/' &&
- !('test' in params) &&
+ !appRuntimeConfig.test &&
!route.meta.demo &&
- (isTauri() || 'recent-files' in params)
+ (isTauri() || appRuntimeConfig.recentFiles)
let firstTab = activeTab.value
if (!firstTab) firstTab = shouldCreateHome ? createHomeTab() : createTab()
-if (createdInitialTab && route.meta.demo && !('test' in params)) {
+if (createdInitialTab && route.meta.demo && !appRuntimeConfig.test) {
void createDemoShapes(firstTab.store)
}
diff --git a/tests/e2e/canvas/demo-effects.spec.ts-snapshots/demo-effects-section-openpencil-darwin.png b/tests/e2e/canvas/demo-effects.spec.ts-snapshots/demo-effects-section-openpencil-darwin.png
index 67bf7a342..7bf6a2704 100644
Binary files a/tests/e2e/canvas/demo-effects.spec.ts-snapshots/demo-effects-section-openpencil-darwin.png and b/tests/e2e/canvas/demo-effects.spec.ts-snapshots/demo-effects-section-openpencil-darwin.png differ
diff --git a/tests/e2e/canvas/tiled-large-blur-visual.spec.ts b/tests/e2e/canvas/tiled-large-blur-visual.spec.ts
new file mode 100644
index 000000000..89e952fbc
--- /dev/null
+++ b/tests/e2e/canvas/tiled-large-blur-visual.spec.ts
@@ -0,0 +1,104 @@
+import { readFileSync } from 'node:fs'
+
+import type { RecordedWheelSample } from '@open-pencil/core/profiler'
+
+import { expect, test, useEditorSetup } from '#tests/e2e/fixtures'
+
+const editor = useEditorSetup('/?test&no-chrome&no-rulers&renderer=tiled&navigation-benchmark')
+const reversal = JSON.parse(
+ readFileSync('tests/fixtures/navigation/gestures/synthetic-repeated-pinch-reversal.json', 'utf8')
+) as { wheel: RecordedWheelSample[] }
+
+async function waitForTiledSettlement() {
+ await editor.page.evaluate(() => window.openPencil?.test?.navigation?.waitForSettlement())
+}
+
+async function setLargeBlurRadius(radius: number) {
+ await editor.page.evaluate((nextRadius) => {
+ const store = window.openPencil?.getStore?.()
+ if (!store) throw new Error('OpenPencil store not initialized')
+ const node = [...store.graph.getAllNodes()].find(
+ (candidate) =>
+ candidate.name === 'Group' &&
+ candidate.width === 2100 &&
+ candidate.height === 658 &&
+ candidate.effects.some((effect) => effect.visible && effect.type === 'FOREGROUND_BLUR')
+ )
+ if (!node) throw new Error('Canonical large blur group not found')
+ node.effects = node.effects.map((effect) =>
+ effect.type === 'FOREGROUND_BLUR' ? { ...effect, radius: nextRadius } : effect
+ )
+ store.graph.updateNode(node.id, { effects: node.effects })
+ store.clearSelection()
+ }, radius)
+}
+
+async function replayReversal() {
+ await editor.page.getByTestId('canvas-element').evaluate(async (canvas, samples) => {
+ const startedAt = performance.now()
+ for (const sample of samples) {
+ const delay = sample.timeMs - (performance.now() - startedAt)
+ if (delay > 0) {
+ await new Promise<void>((resolve) => {
+ setTimeout(resolve, delay)
+ })
+ }
+ canvas.dispatchEvent(
+ new WheelEvent('wheel', {
+ bubbles: true,
+ cancelable: true,
+ deltaX: sample.deltaX,
+ deltaY: sample.deltaY,
+ deltaMode: sample.deltaMode,
+ ctrlKey: sample.ctrlKey,
+ metaKey: sample.metaKey,
+ shiftKey: sample.shiftKey,
+ clientX: sample.clientX,
+ clientY: sample.clientY
+ })
+ )
+ }
+ }, reversal.wheel)
+}
+
+test('large blur remains seamless after tiled mutation and zoom reversal', async () => {
+ test.setTimeout(120_000)
+ await editor.page.evaluate(() =>
+ window.openPencil?.openFile?.('/tests/fixtures/gold-preview.fig')
+ )
+ await editor.page.waitForFunction(() => {
+ const store = window.openPencil?.getStore?.()
+ return (
+ store != null &&
+ !store.state.loading &&
+ [...store.graph.getAllNodes()].some(
+ (node) =>
+ node.name === 'Group' &&
+ node.width === 2100 &&
+ node.height === 658 &&
+ node.effects.some((effect) => effect.visible && effect.type === 'FOREGROUND_BLUR')
+ )
+ )
+ })
+ await editor.page.evaluate(() => {
+ const store = window.openPencil?.getStore?.()
+ if (!store) throw new Error('OpenPencil store not initialized')
+ store.zoomToFit()
+ })
+ await waitForTiledSettlement()
+
+ await setLargeBlurRadius(210)
+ await waitForTiledSettlement()
+ editor.canvas.assertNoErrors()
+ const settledMutation = await editor.canvas.canvas.screenshot()
+ expect(settledMutation).toMatchSnapshot('tiled-large-blur-mutation-settled.png')
+
+ await setLargeBlurRadius(200)
+ await waitForTiledSettlement()
+ await setLargeBlurRadius(210)
+ await replayReversal()
+ await waitForTiledSettlement()
+ editor.canvas.assertNoErrors()
+ const settledAfterReversal = await editor.canvas.canvas.screenshot()
+ expect(settledAfterReversal.equals(settledMutation)).toBe(true)
+})
diff --git a/tests/e2e/canvas/tiled-large-blur-visual.spec.ts-snapshots/tiled-large-blur-mutation-settled-openpencil-darwin.png b/tests/e2e/canvas/tiled-large-blur-visual.spec.ts-snapshots/tiled-large-blur-mutation-settled-openpencil-darwin.png
new file mode 100644
index 000000000..3f5f7cb1c
Binary files /dev/null and b/tests/e2e/canvas/tiled-large-blur-visual.spec.ts-snapshots/tiled-large-blur-mutation-settled-openpencil-darwin.png differ
diff --git a/tests/e2e/settings/general.spec.ts b/tests/e2e/settings/general.spec.ts
index f57d36422..33d01bf9d 100644
--- a/tests/e2e/settings/general.spec.ts
+++ b/tests/e2e/settings/general.spec.ts
@@ -61,6 +61,53 @@ test('general snapping preferences persist and apply to editor sessions', async
await pixelGrid.click()
})
+test('progressive tiled rendering preference persists and URL overrides take precedence', async ({
+ page
+}) => {
+ await page.goto('/?test')
+ const canvas = new CanvasHelper(page)
+ await canvas.waitForInit()
+
+ await page.getByTestId('app-settings-trigger').click()
+ const tiled = page.getByRole('switch', { name: 'Progressive tiled canvas rendering' })
+ await expect(tiled).not.toBeChecked()
+ await tiled.click()
+ await expect(page.getByText('Reload OpenPencil to apply this change.')).toBeVisible()
+
+ await page.reload()
+ await canvas.waitForInit()
+ await page.getByTestId('app-settings-trigger').click()
+ await expect(tiled).toBeChecked()
+ await expect(
+ page.evaluate(() =>
+ window.openPencil
+ ?.getStore?.()
+ .canvasRenderers.some(
+ (renderer) => renderer.tracksSceneSettlement && renderer.tiledSceneEnabled
+ )
+ )
+ ).resolves.toBe(true)
+
+ await page.goto('/?test&renderer=retained')
+ await canvas.waitForInit()
+ await page.getByTestId('app-settings-trigger').click()
+ await expect(tiled).toBeChecked()
+ await expect(
+ page.getByText(/current session renderer is controlled by a URL override/i)
+ ).toBeVisible()
+ await expect(
+ page.evaluate(() =>
+ window.openPencil
+ ?.getStore?.()
+ .canvasRenderers.every(
+ (renderer) => !renderer.tracksSceneSettlement || !renderer.tiledSceneEnabled
+ )
+ )
+ ).resolves.toBe(true)
+
+ await tiled.click()
+})
+
test('Preferences menu snapping controls use the same preferences', async ({ page }) => {
await page.goto('/?test')
const canvas = new CanvasHelper(page)
diff --git a/tests/engine/app/runtime/config.test.ts b/tests/engine/app/runtime/config.test.ts
new file mode 100644
index 000000000..ed951cec4
--- /dev/null
+++ b/tests/engine/app/runtime/config.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test'
+
+import { parseAppRuntimeConfig } from '@/app/runtime/config'
+
+describe('app runtime configuration', () => {
+ test('parses supported development and presentation flags once', () => {
+ expect(
+ parseAppRuntimeConfig(
+ '?test&navigation-benchmark&recent-files&no-chrome&no-rulers&renderer=tiled&collabTransport=test&collabRelay=ws%3A%2F%2Flocalhost%3A4000'
+ )
+ ).toEqual({
+ test: true,
+ navigationBenchmark: true,
+ recentFiles: true,
+ showChrome: false,
+ showRulers: false,
+ sceneRenderer: 'tiled',
+ sceneRendererOverride: true,
+ collaborationTransport: 'test',
+ collaborationRelayURL: 'ws://localhost:4000'
+ })
+ })
+
+ test('uses a persisted renderer preference when no URL override is present', () => {
+ expect(parseAppRuntimeConfig('', 'tiled').sceneRenderer).toBe('tiled')
+ expect(parseAppRuntimeConfig('?renderer=unknown', 'tiled').sceneRenderer).toBe('tiled')
+ })
+
+ test('valid renderer URL overrides take precedence over preferences', () => {
+ expect(parseAppRuntimeConfig('?renderer=retained', 'tiled').sceneRenderer).toBe('retained')
+ expect(parseAppRuntimeConfig('?renderer=tiled', 'retained').sceneRenderer).toBe('tiled')
+ })
+
+ test('uses production-safe defaults for absent or unknown values', () => {
+ expect(parseAppRuntimeConfig('?renderer=unknown')).toEqual({
+ test: false,
+ navigationBenchmark: false,
+ recentFiles: false,
+ showChrome: true,
+ showRulers: true,
+ sceneRenderer: 'retained',
+ sceneRendererOverride: false,
+ collaborationTransport: 'default',
+ collaborationRelayURL: null
+ })
+ })
+})
diff --git a/tests/engine/editor/graph/events-integration.test.ts b/tests/engine/editor/graph/events-integration.test.ts
new file mode 100644
index 000000000..e87b6646b
--- /dev/null
+++ b/tests/engine/editor/graph/events-integration.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+import { createGraphEventSubscription } from '#core/editor/graph-events'
+
+function createRenderer() {
+ const invalidated: string[] = []
+ const renderer: Pick<
+ SkiaRenderer,
+ 'invalidateVectorPath' | 'invalidateNodePicture' | 'tiledScene'
+ > & {
+ invalidated: string[]
+ } = {
+ invalidateVectorPath: () => undefined,
+ invalidateNodePicture: (nodeId: string) => invalidated.push(nodeId),
+ tiledScene: {
+ invalidateNode: mock(),
+ invalidateStructure: mock()
+ } as SkiaRenderer['tiledScene'],
+ invalidated
+ }
+ return renderer
+}
+
+function setup() {
+ const graph = new SceneGraph()
+ const renderer = createRenderer()
+ const subscription = createGraphEventSubscription({
+ getGraph: () => graph,
+ getRenderers: () => [renderer],
+ scheduleComponentSync: () => undefined,
+ requestRender: () => undefined,
+ emitEditorEvent: () => undefined
+ })
+ subscription.subscribeToGraph()
+ return { graph, renderer }
+}
+
+describe('graph event picture invalidation integration', () => {
+ test('updates and deletes invalidate cached raster ownership', () => {
+ const { graph, renderer } = setup()
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ const node = graph.createNode('RECTANGLE', page.id, { width: 100, height: 100 })
+
+ renderer.invalidated.length = 0
+ graph.updateNode(node.id, {
+ effects: [
+ {
+ type: 'DROP_SHADOW',
+ color: { r: 0, g: 0, b: 0, a: 0.5 },
+ offset: { x: 4, y: 4 },
+ radius: 8,
+ spread: 0,
+ visible: true
+ }
+ ]
+ })
+ expect(renderer.invalidated).toContain(node.id)
+
+ renderer.invalidated.length = 0
+ graph.deleteNode(node.id)
+ expect(renderer.invalidated).toContain(node.id)
+ })
+
+ test('isolation changes are evaluated against live tiled chunk topology', () => {
+ const { graph, renderer } = setup()
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ const node = graph.createNode('RECTANGLE', page.id)
+ ;(renderer.tiledScene.invalidateNode as ReturnType<typeof mock>).mockClear()
+
+ graph.updateNode(node.id, {
+ effects: [
+ {
+ type: 'LAYER_BLUR',
+ visible: true,
+ radius: 10,
+ spread: 0,
+ offset: { x: 0, y: 0 },
+ color: { r: 0, g: 0, b: 0, a: 1 }
+ }
+ ]
+ })
+
+ expect(renderer.tiledScene.invalidateNode).toHaveBeenCalledWith(node.id, graph)
+ })
+
+ test('reparenting invalidates the moved subtree root', () => {
+ const { graph, renderer } = setup()
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ const first = graph.createNode('FRAME', page.id)
+ const second = graph.createNode('FRAME', page.id)
+ const child = graph.createNode('RECTANGLE', first.id)
+
+ renderer.invalidated.length = 0
+ graph.reparentNode(child.id, second.id)
+ expect(renderer.invalidated).toContain(child.id)
+ })
+})
diff --git a/tests/engine/editor/graph-events.test.ts b/tests/engine/editor/graph/events.test.ts
similarity index 100%
rename from tests/engine/editor/graph-events.test.ts
rename to tests/engine/editor/graph/events.test.ts
diff --git a/tests/engine/editor/graph/replacement.test.ts b/tests/engine/editor/graph/replacement.test.ts
new file mode 100644
index 000000000..61e490eb2
--- /dev/null
+++ b/tests/engine/editor/graph/replacement.test.ts
@@ -0,0 +1,21 @@
+import { expect, mock, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+import { createEditor } from '#core/editor'
+
+test('graph replacement clears tiled state even when page IDs are reused', () => {
+ const editor = createEditor()
+ const renderer = {
+ tiledScene: { invalidateStructure: mock() },
+ measureTextNode: undefined
+ } as SkiaRenderer
+ editor.setCanvasKit({} as Parameters<typeof editor.setCanvasKit>[0], renderer)
+ const replacement = new SceneGraph()
+
+ editor.replaceGraph(replacement)
+
+ expect(renderer.tiledScene.invalidateStructure).toHaveBeenCalledTimes(1)
+ expect(editor.graph).toBe(replacement)
+})
diff --git a/tests/engine/editor/navigation-lifecycle.test.ts b/tests/engine/editor/navigation-lifecycle.test.ts
new file mode 100644
index 000000000..46af8a66b
--- /dev/null
+++ b/tests/engine/editor/navigation-lifecycle.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, test } from 'bun:test'
+
+import { createEditor } from '@open-pencil/core/editor'
+
+describe('navigation lifecycle', () => {
+ test('increments generation when a new gesture starts but not during one gesture', () => {
+ const editor = createEditor()
+ const events: Array<{ phase: string; generation: number }> = []
+ const off = editor.onEditorEvent('navigation:changed', (navigation) => {
+ events.push({ phase: navigation.phase, generation: navigation.generation })
+ })
+
+ editor.setNavigationPhase('zoom', 10)
+ editor.setNavigationPhase('zoom', 20)
+ editor.setNavigationPhase('settling', 20)
+ editor.setNavigationPhase('zoom', 30)
+ editor.setNavigationPhase('idle', 40)
+
+ expect(events).toEqual([
+ { phase: 'zoom', generation: 1 },
+ { phase: 'zoom', generation: 1 },
+ { phase: 'settling', generation: 1 },
+ { phase: 'zoom', generation: 2 },
+ { phase: 'idle', generation: 2 }
+ ])
+ off()
+ editor.dispose()
+ })
+})
diff --git a/tests/engine/editor/view-state.test.ts b/tests/engine/editor/view-state.test.ts
index a573f940f..3e451fcb6 100644
--- a/tests/engine/editor/view-state.test.ts
+++ b/tests/engine/editor/view-state.test.ts
@@ -27,9 +27,11 @@ describe('editor state ownership', () => {
copy.selectedIds.add('pane-only')
copy.snapGuides.length = 0
copy.pageColor.r = 0.5
+ copy.navigation.phase = 'zoom'
expect(source.selectedIds).toEqual(new Set(['selected']))
expect(source.snapGuides).toHaveLength(1)
expect(source.pageColor.r).not.toBe(0.5)
+ expect(source.navigation.phase).toBe('idle')
})
})
diff --git a/tests/engine/render/canvas/chunks/cache.test.ts b/tests/engine/render/canvas/chunks/cache.test.ts
new file mode 100644
index 000000000..88f7adcdf
--- /dev/null
+++ b/tests/engine/render/canvas/chunks/cache.test.ts
@@ -0,0 +1,44 @@
+import { beforeAll, describe, expect, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import { initCanvasKit } from '#cli/headless'
+import { SkiaRenderer } from '#core/canvas'
+import { RenderChunkIndex, RenderChunkPictureCache } from '#core/canvas/renderer/chunks'
+
+import { expectDefined } from '#tests/helpers/assert'
+
+let ck: Awaited<ReturnType<typeof initCanvasKit>>
+
+beforeAll(async () => {
+ ck = await initCanvasKit()
+})
+
+describe('render chunk picture cache', () => {
+ test('removes a deleted stale picture before replacement recording can fail', () => {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ const node = graph.createNode('RECTANGLE', page.id, { width: 20, height: 20 })
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ const chunk = expectDefined(index.getChunksForNode(node.id)[0], 'chunk')
+ const surface = expectDefined(ck.MakeSurface(32, 32), 'surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ const cache = new RenderChunkPictureCache()
+ try {
+ const stale = cache.get(renderer, graph, chunk)
+ renderer.fontGeneration++
+ const original = renderer.renderNode
+ renderer.renderNode = () => {
+ throw new Error('replacement failed')
+ }
+ expect(() => cache.get(renderer, graph, chunk)).toThrow('replacement failed')
+ expect(cache.size()).toBe(0)
+ renderer.renderNode = original
+ expect(cache.get(renderer, graph, chunk)).not.toBe(stale)
+ } finally {
+ cache.clear()
+ index.dispose()
+ renderer.destroy()
+ }
+ })
+})
diff --git a/tests/engine/render/canvas/chunks/context.test.ts b/tests/engine/render/canvas/chunks/context.test.ts
new file mode 100644
index 000000000..992e64651
--- /dev/null
+++ b/tests/engine/render/canvas/chunks/context.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import { RenderChunkIndex } from '#core/canvas/renderer/chunks'
+
+function defaultPage(graph: SceneGraph) {
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ return page
+}
+
+function addChildren(graph: SceneGraph, parentId: string, count: number) {
+ for (let index = 0; index < count; index++) {
+ graph.createNode('RECTANGLE', parentId, { x: index * 12, width: 10, height: 10 })
+ }
+}
+
+describe('render chunk context', () => {
+ test('preserves ancestor transform and clipping dependencies for split descendants', () => {
+ const graph = new SceneGraph()
+ const page = defaultPage(graph)
+ const clippingParent = graph.createNode('FRAME', page.id, {
+ x: 100,
+ y: 200,
+ width: 500,
+ height: 500,
+ rotation: 15,
+ clipsContent: true
+ })
+ const oversized = graph.createNode('FRAME', clippingParent.id, { x: 20, y: 30 })
+ addChildren(graph, oversized.id, 40)
+
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ const child = graph.getChildren(oversized.id)[0]
+ if (!child) throw new Error('Expected child')
+ const chunk = index.getChunksForNode(child.id)[0]
+
+ expect(chunk?.context.ancestorClipIds).toContain(clippingParent.id)
+ expect(chunk?.context.parentTransform).not.toEqual([1, 0, 0, 0, 1, 0, 0, 0, 1])
+ index.dispose()
+ })
+
+ test('keeps opacity and blend isolation subtrees atomic', () => {
+ const graph = new SceneGraph()
+ const page = defaultPage(graph)
+ const frame = graph.createNode('FRAME', page.id, {
+ opacity: 0.5,
+ blendMode: 'MULTIPLY'
+ })
+ addChildren(graph, frame.id, 40)
+
+ const { index, stats } = RenderChunkIndex.build(graph, page.id)
+ const chunk = index.getChunksForNode(frame.id)[0]
+
+ expect(chunk?.kind).toBe('subtree')
+ expect(chunk?.interruptible).toBe(false)
+ expect(chunk?.nodeCount).toBe(41)
+ expect(stats.oversizedAtomicChunks).toBe(1)
+ index.dispose()
+ })
+
+ test('keeps mask groups atomic', () => {
+ const graph = new SceneGraph()
+ const page = defaultPage(graph)
+ const frame = graph.createNode('FRAME', page.id)
+ const mask = graph.createNode('RECTANGLE', frame.id, { isMask: true })
+ graph.updateNode(mask.id, { maskType: 'ALPHA' })
+ addChildren(graph, frame.id, 40)
+
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ const chunk = index.getChunksForNode(frame.id)[0]
+
+ expect(chunk?.interruptible).toBe(false)
+ expect(chunk?.kind).toBe('subtree')
+ index.dispose()
+ })
+})
diff --git a/tests/engine/render/canvas/chunks/gold-preview.test.ts b/tests/engine/render/canvas/chunks/gold-preview.test.ts
new file mode 100644
index 000000000..1338c27a0
--- /dev/null
+++ b/tests/engine/render/canvas/chunks/gold-preview.test.ts
@@ -0,0 +1,42 @@
+import { beforeAll, expect, setDefaultTimeout, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+
+import { initCodec, parseFigFile } from '@open-pencil/core'
+
+import { RenderChunkIndex } from '#core/canvas/renderer/chunks'
+
+import { expectDefined } from '#tests/helpers/assert'
+import { repoPath } from '#tests/helpers/paths'
+import { HEAVY_TEST_TIMEOUT_MS } from '#tests/helpers/test-utils'
+
+setDefaultTimeout(HEAVY_TEST_TIMEOUT_MS)
+
+let graph: Awaited<ReturnType<typeof parseFigFile>>
+
+beforeAll(async () => {
+ await initCodec()
+ const bytes = readFileSync(repoPath('tests/fixtures/gold-preview.fig'))
+ graph = await parseFigFile(bytes.buffer as ArrayBuffer, { populate: 'all' })
+}, 60_000)
+
+test('gold-preview render chunks stay bounded and spatial queries stay selective', () => {
+ const page = expectDefined(graph.getPages()[0], 'gold-preview page')
+ const { index, stats } = RenderChunkIndex.build(graph, page.id)
+
+ const bounds = graph.getChildren(page.id)[0]
+ const found = bounds
+ ? index.search({
+ minX: bounds.x,
+ minY: bounds.y,
+ maxX: bounds.x + Math.min(bounds.width, 1_000),
+ maxY: bounds.y + Math.min(bounds.height, 800)
+ })
+ : []
+
+ expect(stats.nodesVisited).toBeGreaterThan(300)
+ expect(stats.maximumChunkNodes).toBeLessThanOrEqual(32)
+ expect(stats.chunksBuilt).toBeLessThan(stats.nodesVisited)
+ expect(stats.oversizedAtomicChunks).toBe(0)
+ expect(found.length).toBeLessThan(stats.chunksBuilt)
+ index.dispose()
+})
diff --git a/tests/engine/render/canvas/chunks/index.test.ts b/tests/engine/render/canvas/chunks/index.test.ts
new file mode 100644
index 000000000..a91c8d3da
--- /dev/null
+++ b/tests/engine/render/canvas/chunks/index.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import { RenderChunkIndex } from '#core/canvas/renderer/chunks'
+
+function graphWithNodes(count: number): { graph: SceneGraph; pageId: string } {
+ const graph = new SceneGraph()
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ const frame = graph.createNode('FRAME', page.id, {
+ x: 0,
+ y: 0,
+ width: count * 20,
+ height: 20
+ })
+ for (let index = 0; index < count; index++) {
+ graph.createNode('RECTANGLE', frame.id, {
+ x: index * 20,
+ y: 0,
+ width: 10,
+ height: 10
+ })
+ }
+ return { graph, pageId: page.id }
+}
+
+describe('render chunk spatial index', () => {
+ test('splits oversized top-level subtrees into bounded chunks', () => {
+ const { graph, pageId } = graphWithNodes(1_000)
+ const { index, stats } = RenderChunkIndex.build(graph, pageId)
+
+ expect(stats.nodesVisited).toBe(1_001)
+ expect(stats.chunksBuilt).toBe(1_001)
+ expect(stats.maximumChunkNodes).toBe(1)
+ expect(index.size()).toBe(1_001)
+ expect(index.getChunksForNode(graph.getChildren(pageId)[0]?.id ?? '')[0]?.kind).toBe('self')
+ index.dispose()
+ })
+
+ test('queries only chunks intersecting a world-space rectangle in painter order', () => {
+ const { graph, pageId } = graphWithNodes(1_000)
+ const { index } = RenderChunkIndex.build(graph, pageId)
+ const found = index.search({ minX: 1_000, minY: -1, maxX: 1_090, maxY: 11 })
+
+ expect(found.length).toBeLessThan(10)
+ expect(found.map((chunk) => chunk.painterOrder)).toEqual(
+ [...found].map((chunk) => chunk.painterOrder).sort((a, b) => a - b)
+ )
+ expect(found.every((chunk) => chunk.maxX >= 1_000 && chunk.minX <= 1_090)).toBe(true)
+ index.dispose()
+ })
+
+ test('updates an owning chunk bounds without rebuilding the index', () => {
+ const { graph, pageId } = graphWithNodes(1_000)
+ const { index } = RenderChunkIndex.build(graph, pageId)
+ const frame = graph.getChildren(pageId)[0]
+ if (!frame) throw new Error('Expected frame')
+ graph.updateNode(frame.id, { x: 400 })
+
+ expect(index.updateNode(graph, frame.id)).toBe(1)
+ expect(index.getChunksForNode(frame.id)[0]?.minX).toBe(400)
+ index.dispose()
+ })
+
+ test('indexes subtree descendants and transform ancestors as chunk dependencies', () => {
+ const graph = new SceneGraph()
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ const ancestor = graph.createNode('FRAME', page.id, { x: 20, y: 20 })
+ const root = graph.createNode('FRAME', ancestor.id)
+ const child = graph.createNode('RECTANGLE', root.id)
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ try {
+ expect(index.getChunksDependingOnNode(child.id).map((chunk) => chunk.nodeId)).toContain(
+ ancestor.id
+ )
+ expect(index.getChunksDependingOnNode(ancestor.id).length).toBeGreaterThan(0)
+ } finally {
+ index.dispose()
+ }
+ })
+
+ test('keeps a small top-level subtree as one retained chunk', () => {
+ const { graph, pageId } = graphWithNodes(20)
+ const { index, stats } = RenderChunkIndex.build(graph, pageId)
+
+ expect(stats.chunksBuilt).toBe(1)
+ expect(stats.maximumChunkNodes).toBe(21)
+ expect(index.size()).toBe(1)
+ index.dispose()
+ })
+})
diff --git a/tests/engine/render/canvas/chunks/record.test.ts b/tests/engine/render/canvas/chunks/record.test.ts
new file mode 100644
index 000000000..4de0b4170
--- /dev/null
+++ b/tests/engine/render/canvas/chunks/record.test.ts
@@ -0,0 +1,199 @@
+import { beforeAll, describe, expect, mock, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import { initCanvasKit } from '#cli/headless'
+import { SkiaRenderer } from '#core/canvas'
+import type { RenderChunk } from '#core/canvas/renderer/chunks'
+import {
+ deleteRecordedRenderChunks,
+ recordRenderChunk,
+ RenderChunkIndex
+} from '#core/canvas/renderer/chunks'
+
+import { expectDefined } from '#tests/helpers/assert'
+
+let ck: Awaited<ReturnType<typeof initCanvasKit>>
+
+beforeAll(async () => {
+ ck = await initCanvasKit()
+})
+
+function renderPixels(renderer: SkiaRenderer, graph: SceneGraph, pageId: string, chunked: boolean) {
+ const canvas = renderer.surface.getCanvas()
+ canvas.clear(ck.WHITE)
+ if (chunked) {
+ const { index } = RenderChunkIndex.build(graph, pageId)
+ const chunks = index.search({ minX: 0, minY: 0, maxX: 320, maxY: 240 })
+ const recorded = chunks.map((chunk) => recordRenderChunk(renderer, graph, chunk))
+ for (const chunk of chunks) {
+ const picture = recorded.find((entry) => entry.chunk.id === chunk.id)?.picture
+ if (picture) canvas.drawPicture(picture)
+ }
+ deleteRecordedRenderChunks(recorded)
+ index.dispose()
+ } else {
+ renderer.renderSceneToCanvas(canvas, graph, pageId)
+ }
+ renderer.surface.flush()
+ const image = renderer.surface.makeImageSnapshot()
+ const pixels = image.readPixels(0, 0, {
+ width: 320,
+ height: 240,
+ colorType: ck.ColorType.RGBA_8888,
+ alphaType: ck.AlphaType.Unpremul,
+ colorSpace: ck.ColorSpace.SRGB
+ })
+ image.delete()
+ return expectDefined(pixels, 'rendered chunk pixels')
+}
+
+function differenceRatio(a: Uint8Array, b: Uint8Array, tolerance = 8) {
+ let different = 0
+ for (let index = 0; index < a.length; index++) {
+ if (Math.abs(a[index] - b[index]) > tolerance) different++
+ }
+ return different / a.length
+}
+
+function renderPair(graph: SceneGraph, pageId: string) {
+ const directSurface = expectDefined(ck.MakeSurface(320, 240), 'direct surface')
+ const chunkSurface = expectDefined(ck.MakeSurface(320, 240), 'chunk surface')
+ const direct = new SkiaRenderer(ck, directSurface)
+ const chunked = new SkiaRenderer(ck, chunkSurface)
+ try {
+ const expected = renderPixels(direct, graph, pageId, false)
+ const actual = renderPixels(chunked, graph, pageId, true)
+ return differenceRatio(expected, actual)
+ } finally {
+ direct.destroy()
+ chunked.destroy()
+ }
+}
+
+function color(r: number, g: number, b: number) {
+ return [{ type: 'SOLID' as const, color: { r, g, b, a: 1 }, opacity: 1, visible: true }]
+}
+
+describe('recorded render chunks', () => {
+ test('deletes the native picture recorder when chunk rendering throws', () => {
+ const recorder = {
+ beginRecording: mock(() => ({ save: mock(), concat: mock() })),
+ finishRecordingAsPicture: mock(),
+ delete: mock()
+ }
+ const renderer = {
+ ck: {
+ PictureRecorder: function PictureRecorder() {
+ return recorder
+ },
+ LTRBRect: mock(() => new Float32Array(4))
+ },
+ worldViewport: { x: 0, y: 0, w: 10, h: 10 },
+ renderNode: mock(() => {
+ throw new Error('render failed')
+ })
+ } as SkiaRenderer
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ const node = graph.createNode('RECTANGLE', page.id)
+ const chunk: RenderChunk = {
+ id: `${node.id}:subtree`,
+ nodeId: node.id,
+ kind: 'subtree',
+ context: { parentTransform: [1, 0, 0, 0, 1, 0, 0, 0, 1], ancestorClipIds: [] },
+ interruptible: true,
+ painterOrder: 0,
+ minX: 0,
+ minY: 0,
+ maxX: 10,
+ maxY: 10,
+ nodeCount: 1,
+ estimatedCost: 1
+ }
+
+ expect(() => recordRenderChunk(renderer, graph, chunk)).toThrow('render failed')
+ expect(recorder.delete).toHaveBeenCalledTimes(1)
+ })
+
+ test('match direct rendering for split nested transforms and rounded clips', () => {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ const clip = graph.createNode('FRAME', page.id, {
+ x: 60,
+ y: 40,
+ width: 180,
+ height: 140,
+ rotation: 8,
+ cornerRadius: 18,
+ clipsContent: true,
+ fills: color(0.9, 0.9, 0.95)
+ })
+ const frame = graph.createNode('FRAME', clip.id, { x: 20, y: 15, width: 300, height: 100 })
+ for (let index = 0; index < 40; index++) {
+ graph.createNode('RECTANGLE', frame.id, {
+ x: index * 12,
+ y: index % 2 === 0 ? 10 : 45,
+ width: 18,
+ height: 18,
+ fills: color(0.1, 0.4 + (index % 3) * 0.15, 0.8)
+ })
+ }
+
+ expect(renderPair(graph, page.id)).toBeLessThan(0.01)
+ })
+
+ test('records atomic chunks as indivisible destination-dependent command pictures', () => {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ const group = graph.createNode('FRAME', page.id, { opacity: 0.5 })
+ for (let index = 0; index < 40; index++) {
+ graph.createNode('RECTANGLE', group.id, { width: 10, height: 10 })
+ }
+ const surface = expectDefined(ck.MakeSurface(320, 240), 'atomic surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ try {
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ const chunk = index.getChunksForNode(group.id)[0]
+ if (!chunk) throw new Error('Expected atomic chunk')
+ const recorded = recordRenderChunk(renderer, graph, chunk)
+ expect(recorded.picture).toBeDefined()
+ recorded.picture.delete()
+ index.dispose()
+ } finally {
+ renderer.destroy()
+ }
+ })
+
+ test('match direct rendering for atomic opacity and blend isolation', () => {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ graph.createNode('RECTANGLE', page.id, {
+ x: 20,
+ y: 20,
+ width: 240,
+ height: 180,
+ fills: color(0.9, 0.2, 0.2)
+ })
+ const group = graph.createNode('FRAME', page.id, {
+ x: 40,
+ y: 30,
+ width: 220,
+ height: 160,
+ opacity: 0.6,
+ blendMode: 'MULTIPLY',
+ fills: []
+ })
+ for (let index = 0; index < 40; index++) {
+ graph.createNode('ELLIPSE', group.id, {
+ x: (index % 10) * 18,
+ y: Math.floor(index / 10) * 28,
+ width: 28,
+ height: 28,
+ fills: color(0.2, 0.7, 0.9)
+ })
+ }
+
+ expect(renderPair(graph, page.id)).toBeLessThan(0.01)
+ })
+})
diff --git a/tests/engine/render/canvas/effect-raster-cache.test.ts b/tests/engine/render/canvas/effect-raster-cache.test.ts
new file mode 100644
index 000000000..a7a428a63
--- /dev/null
+++ b/tests/engine/render/canvas/effect-raster-cache.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import {
+ canCacheEffectRaster,
+ clearEffectRasterCache,
+ deleteEffectRaster,
+ deleteEffectRasterDependencies,
+ effectRasterScale,
+ effectRasterScaleMatches,
+ installEffectRaster,
+ touchEffectRaster,
+ type EffectRasterCacheEntry
+} from '#core/canvas/renderer/effect-raster-cache'
+
+function entry(pixels: number): EffectRasterCacheEntry {
+ return {
+ image: { delete: mock(), width: () => 10, height: () => 10 } as never,
+ left: 0,
+ top: 0,
+ width: 10,
+ height: 10,
+ scale: 2,
+ pixels,
+ fontGeneration: 0,
+ dependencyIds: []
+ }
+}
+
+describe('effect raster cache', () => {
+ test('quantizes target scale upward and detects replacement boundaries', () => {
+ expect(effectRasterScale(1.01)).toBe(1.25)
+ expect(effectRasterScale(2)).toBe(2)
+ expect(effectRasterScale(10)).toBe(4)
+ expect(effectRasterScaleMatches(2, 1.9)).toBe(true)
+ expect(effectRasterScaleMatches(2, 2.01)).toBe(true)
+ expect(effectRasterScaleMatches(2, 2.5)).toBe(false)
+ expect(effectRasterScaleMatches(2, 1.5)).toBe(false)
+ })
+
+ test('bounds individual raster allocations', () => {
+ expect(canCacheEffectRaster(500, 500, 2)).toBe(true)
+ expect(canCacheEffectRaster(501, 500, 2)).toBe(false)
+ expect(canCacheEffectRaster(0, 100, 2)).toBe(false)
+ })
+
+ test('replaces entries and disposes native images', () => {
+ const cache = new Map<string, EffectRasterCacheEntry>()
+ const first = entry(100)
+ const second = entry(100)
+ installEffectRaster(cache, 'node', first)
+ installEffectRaster(cache, 'node', second)
+ expect(first.image.delete).toHaveBeenCalledTimes(1)
+ expect(cache.get('node')).toBe(second)
+
+ deleteEffectRaster(cache, 'node')
+ expect(second.image.delete).toHaveBeenCalledTimes(1)
+ expect(cache.size).toBe(0)
+ })
+
+ test('invalidates an owning raster when a geometry dependency changes', () => {
+ const cache = new Map<string, EffectRasterCacheEntry>()
+ const parent = { ...entry(100), dependencyIds: ['child'] }
+ installEffectRaster(cache, 'parent', parent)
+
+ deleteEffectRasterDependencies(cache, 'child')
+
+ expect(parent.image.delete).toHaveBeenCalledTimes(1)
+ expect(cache.has('parent')).toBe(false)
+ })
+
+ test('evicts least-recently-used entries within the pixel budget', () => {
+ const cache = new Map<string, EffectRasterCacheEntry>()
+ const first = entry(12_000_000)
+ const second = entry(8_000_000)
+ const third = entry(8_000_000)
+ installEffectRaster(cache, 'first', first)
+ installEffectRaster(cache, 'second', second)
+ expect(touchEffectRaster(cache, 'first')).toBe(first)
+ installEffectRaster(cache, 'third', third)
+
+ expect(second.image.delete).toHaveBeenCalledTimes(1)
+ expect(cache.has('second')).toBe(false)
+ expect(cache.has('first')).toBe(true)
+ expect(cache.has('third')).toBe(true)
+
+ clearEffectRasterCache(cache)
+ expect(first.image.delete).toHaveBeenCalledTimes(1)
+ expect(third.image.delete).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/tests/engine/render/canvas/effect-raster-integration.test.ts b/tests/engine/render/canvas/effect-raster-integration.test.ts
new file mode 100644
index 000000000..82ef5d50e
--- /dev/null
+++ b/tests/engine/render/canvas/effect-raster-integration.test.ts
@@ -0,0 +1,172 @@
+import { beforeAll, describe, expect, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import { initCanvasKit } from '#cli/headless'
+import { SkiaRenderer } from '#core/canvas'
+
+import { expectDefined } from '#tests/helpers/assert'
+
+let ck: Awaited<ReturnType<typeof initCanvasKit>>
+
+beforeAll(async () => {
+ ck = await initCanvasKit()
+})
+
+function createEffectGraph(effectType: 'DROP_SHADOW' | 'BACKGROUND_BLUR') {
+ const graph = new SceneGraph()
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ const effect =
+ effectType === 'DROP_SHADOW'
+ ? {
+ type: 'DROP_SHADOW' as const,
+ color: { r: 0.05, g: 0.1, b: 0.2, a: 0.7 },
+ offset: { x: 8, y: 10 },
+ radius: 12,
+ spread: 2,
+ visible: true
+ }
+ : {
+ type: 'BACKGROUND_BLUR' as const,
+ color: { r: 0, g: 0, b: 0, a: 0 },
+ offset: { x: 0, y: 0 },
+ radius: 12,
+ spread: 0,
+ visible: true
+ }
+ graph.createNode('RECTANGLE', page.id, {
+ x: 50,
+ y: 50,
+ width: 100,
+ height: 80,
+ fills: [
+ {
+ type: 'SOLID',
+ color: { r: 0.3, g: 0.6, b: 0.9, a: 1 },
+ opacity: 1,
+ visible: true
+ }
+ ],
+ effects: [effect]
+ })
+ return { graph, pageId: page.id }
+}
+
+function renderPixels(renderer: SkiaRenderer, graph: SceneGraph): Uint8Array {
+ renderer.render(graph, new Set(), {}, 1, 'scene')
+ const image = renderer.surface.makeImageSnapshot()
+ const pixels = image.readPixels(0, 0, {
+ width: 256,
+ height: 192,
+ colorType: ck.ColorType.RGBA_8888,
+ alphaType: ck.AlphaType.Unpremul,
+ colorSpace: ck.ColorSpace.SRGB
+ })
+ image.delete()
+ return expectDefined(pixels, 'retained backing pixels')
+}
+
+function differingChannels(a: Uint8Array, b: Uint8Array, tolerance: number): number {
+ let different = 0
+ for (let index = 0; index < a.length; index++) {
+ if (Math.abs(a[index] - b[index]) > tolerance) different++
+ }
+ return different
+}
+
+describe('retained effect raster integration', () => {
+ test('settled drop-shadow backing closely matches direct rendering', () => {
+ const { graph, pageId } = createEffectGraph('DROP_SHADOW')
+ const directSurface = expectDefined(ck.MakeSurface(256, 192), 'direct surface')
+ const backingSurface = expectDefined(ck.MakeSurface(256, 192), 'backing surface')
+ const direct = new SkiaRenderer(ck, directSurface)
+ const retained = new SkiaRenderer(ck, backingSurface)
+ for (const renderer of [direct, retained]) {
+ renderer.viewportWidth = 256
+ renderer.viewportHeight = 192
+ renderer.pageId = pageId
+ renderer.pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ renderer.dpr = 1
+ renderer.zoom = 1
+ }
+
+ try {
+ direct.renderingSceneBacking = false
+ direct.surface.getCanvas().clear(ck.WHITE)
+ direct.renderSceneToCanvas(direct.surface.getCanvas(), graph, pageId)
+ direct.surface.flush()
+ const directImage = direct.surface.makeImageSnapshot()
+ const directPixels = expectDefined(
+ directImage.readPixels(0, 0, {
+ width: 256,
+ height: 192,
+ colorType: ck.ColorType.RGBA_8888,
+ alphaType: ck.AlphaType.Unpremul,
+ colorSpace: ck.ColorSpace.SRGB
+ }),
+ 'direct pixels'
+ )
+ directImage.delete()
+
+ const retainedPixels = renderPixels(retained, graph)
+ expect(retained.effectRasterCache.size).toBe(1)
+ expect(differingChannels(directPixels, retainedPixels, 12)).toBeLessThan(
+ directPixels.length * 0.02
+ )
+ } finally {
+ direct.destroy()
+ retained.destroy()
+ }
+ })
+
+ test('nested shadow subtrees retain the single-picture backing path', () => {
+ const graph = new SceneGraph()
+ const page = graph.getPages()[0]
+ if (!page) throw new Error('Expected default page')
+ const frame = graph.createNode('FRAME', page.id, { width: 200, height: 160 })
+ graph.createNode('RECTANGLE', frame.id, {
+ x: 20,
+ y: 20,
+ width: 100,
+ height: 80,
+ effects: [
+ {
+ type: 'DROP_SHADOW',
+ color: { r: 0, g: 0, b: 0, a: 0.5 },
+ offset: { x: 4, y: 6 },
+ radius: 8,
+ spread: 0,
+ visible: true
+ }
+ ]
+ })
+ const surface = expectDefined(ck.MakeSurface(256, 192), 'nested shadow surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ renderer.viewportWidth = 256
+ renderer.viewportHeight = 192
+ renderer.pageId = page.id
+ try {
+ renderPixels(renderer, graph)
+ expect(renderer.effectRasterCache.size).toBe(0)
+ expect(renderer.subtreePictureCache.has(frame.id)).toBe(true)
+ } finally {
+ renderer.destroy()
+ }
+ })
+
+ test('backdrop-dependent blur remains on the picture fallback', () => {
+ const { graph, pageId } = createEffectGraph('BACKGROUND_BLUR')
+ const surface = expectDefined(ck.MakeSurface(256, 192), 'blur surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ renderer.viewportWidth = 256
+ renderer.viewportHeight = 192
+ renderer.pageId = pageId
+ try {
+ renderPixels(renderer, graph)
+ expect(renderer.effectRasterCache.size).toBe(0)
+ } finally {
+ renderer.destroy()
+ }
+ })
+})
diff --git a/tests/engine/render/canvas/picture-invalidation.test.ts b/tests/engine/render/canvas/picture-invalidation.test.ts
new file mode 100644
index 000000000..c72765085
--- /dev/null
+++ b/tests/engine/render/canvas/picture-invalidation.test.ts
@@ -0,0 +1,67 @@
+import { expect, mock, test } from 'bun:test'
+
+import type { SkiaRenderer } from '#core/canvas/renderer'
+import { invalidateAllPictures, invalidateNodePicture } from '#core/canvas/renderer/state'
+
+function deletable() {
+ return { delete: mock() }
+}
+
+test('full picture invalidation resets tiled font-dependent resources', () => {
+ const scenePicture = deletable()
+ const backingImage = deletable()
+ const nodePicture = deletable()
+ const subtreePicture = deletable()
+ const renderer = {
+ scenePicture,
+ scenePictureVersion: 1,
+ scenePictureFontGeneration: 1,
+ sceneBacking: { image: backingImage },
+ sceneBackingBuild: null,
+ nodePictureCache: new Map([['node', nodePicture]]),
+ nodePictureCacheGenerations: new Map([['node', 1]]),
+ nodePictureCacheDependencies: new Map([['node', []]]),
+ effectRasterCache: new Map(),
+ subtreePictureCache: new Map([['subtree', { picture: subtreePicture }]]),
+ subtreePictureCachePageId: 'page',
+ subtreePictureCacheSceneVersion: 1,
+ subtreePictureCachePositionPreviewVersion: 1,
+ subtreePictureCacheFontGeneration: 1,
+ tiledScene: { invalidateStructure: mock() }
+ } as SkiaRenderer
+
+ invalidateAllPictures(renderer)
+
+ expect(renderer.tiledScene.invalidateStructure).toHaveBeenCalledTimes(1)
+ expect(scenePicture.delete).toHaveBeenCalledTimes(1)
+ expect(backingImage.delete).toHaveBeenCalledTimes(1)
+ expect(nodePicture.delete).toHaveBeenCalledTimes(1)
+ expect(subtreePicture.delete).toHaveBeenCalledTimes(1)
+})
+
+test('node picture invalidation removes pictures that depend on a changed child', () => {
+ const parentPicture = deletable()
+ const childPicture = deletable()
+ const renderer = {
+ nodePictureCache: new Map([
+ ['parent', parentPicture],
+ ['child', childPicture]
+ ]),
+ nodePictureCacheGenerations: new Map([
+ ['parent', 1],
+ ['child', 1]
+ ]),
+ nodePictureCacheDependencies: new Map([
+ ['parent', ['child']],
+ ['child', []]
+ ]),
+ effectRasterCache: new Map(),
+ subtreePictureCache: new Map()
+ } as SkiaRenderer
+
+ invalidateNodePicture(renderer, 'child')
+
+ expect(parentPicture.delete).toHaveBeenCalledTimes(1)
+ expect(childPicture.delete).toHaveBeenCalledTimes(1)
+ expect(renderer.nodePictureCache.size).toBe(0)
+})
diff --git a/tests/engine/render/canvas/renderer-lifecycle.test.ts b/tests/engine/render/canvas/renderer-lifecycle.test.ts
index 63d7cd416..8dadef15a 100644
--- a/tests/engine/render/canvas/renderer-lifecycle.test.ts
+++ b/tests/engine/render/canvas/renderer-lifecycle.test.ts
@@ -50,11 +50,13 @@ function createRenderer() {
imageFilterCache: new Map(),
maskFilterCache: new Map(),
nodePictureCache: new Map(),
- labelParagraphCache: { clear: mock() } as SkiaRenderer['labelParagraphCache'],
+ effectRasterCache: new Map(),
subtreePictureCache: new Map(),
scenePicture: null,
sceneBacking: null,
sceneBackingBuild: null,
+ tiledScene: { destroy: mock() } as SkiaRenderer['tiledScene'],
+ labelParagraphCache: { clear: mock() } as SkiaRenderer['labelParagraphCache'],
_flashPaint: null,
profiler: { destroy: mock() } as Partial<SkiaRenderer['profiler']> as SkiaRenderer['profiler'],
surface: deletable<Surface>()
@@ -62,6 +64,19 @@ function createRenderer() {
return renderer as SkiaRenderer
}
+test('destroyRenderer releases tiled resources before deleting the main surface', () => {
+ const renderer = createRenderer()
+ const teardown: string[] = []
+ renderer.tiledScene.destroy = mock(() => teardown.push('tiled'))
+ renderer.surface.delete = mock(() => teardown.push('surface')) as typeof renderer.surface.delete
+
+ destroyRenderer(renderer)
+
+ expect(renderer.tiledScene.destroy).toHaveBeenCalledTimes(1)
+ expect(renderer.surface.delete).toHaveBeenCalledTimes(1)
+ expect(teardown).toEqual(['tiled', 'surface'])
+})
+
test('destroyRenderer deletes all renderer-owned paints and label fonts', () => {
const renderer = createRenderer()
const parentOutlinePaint = renderer.parentOutlinePaint
diff --git a/tests/engine/render/canvas/silhouette-autopsy.test.ts b/tests/engine/render/canvas/silhouette-autopsy.test.ts
deleted file mode 100644
index e3eadae24..000000000
--- a/tests/engine/render/canvas/silhouette-autopsy.test.ts
+++ /dev/null
@@ -1,564 +0,0 @@
-/**
- * AUTOMATED VERIFICATION: Silhouette Shadow Autopsy Claims
- *
- * This file proves or disproves every factual claim made in
- * scratch/silhouette-shadow-autopsy-20260502/ by testing against
- * the actual running code.
- *
- * Run: bun run tests/engine/verify-silhouette-autopsy.ts
- *
- * Claims are numbered to match the autopsy documents.
- * Each test either PASSES (claim confirmed) or FAILS (claim disproved
- * or code changed since autopsy was written).
- */
-import { beforeAll, describe, expect, test } from 'bun:test'
-import { readFileSync } from 'node:fs'
-
-import { SceneGraph } from '@open-pencil/scene-graph'
-
-import { initCanvasKit } from '#cli/headless'
-import { SkiaRenderer } from '#core/canvas'
-import { fontManager } from '#core/text'
-
-import { expectDefined } from '#tests/helpers/assert'
-import {
- coreSourcePath,
- publicPath,
- repoPath,
- testPath as repoTestPath
-} from '#tests/helpers/paths'
-
-// === CLAIM EXTRACTION ===
-// Each claim is: [doc_section, claim_text, verification_strategy]
-
-// We load the relevant source files to verify the claims by static analysis
-// AND runtime behavior where applicable.
-const shadowsPath = coreSourcePath('canvas/shadows.ts')
-const effectsPath = coreSourcePath('canvas/effects.ts')
-const scenePath = coreSourcePath('canvas/scene.ts')
-const rendererPath = coreSourcePath('canvas/renderer.ts')
-const sgTypesPath = repoPath('packages/scene-graph/src/types.ts')
-const nodeExportPath = repoPath('packages/fig/src/node-change/export-node.ts')
-const convertPath = repoPath('packages/fig/src/node-change/paint.ts')
-const schemaPath = repoPath('packages/kiwi/src/fig/schema/fig.kiwi')
-const codecPath = repoPath('packages/kiwi/src/fig/codec.ts')
-const lifecyclePath = coreSourcePath('canvas/renderer/lifecycle.ts')
-
-function readSource(path: string): string {
- return readFileSync(path, 'utf-8')
-}
-
-// ============================================================
-// DOCUMENT 01: THE CURRENT ENGINE — VERIFICATION
-// ============================================================
-
-describe('Doc 01 — The Current Engine: Static Code Claims', () => {
- test('C01-01: Effect type defines 5 values (scene-graph/types.ts:138)', () => {
- const src = readSource(sgTypesPath)
- // Verify all 5 effect type strings are present in the file
- for (const type of [
- 'DROP_SHADOW',
- 'INNER_SHADOW',
- 'LAYER_BLUR',
- 'BACKGROUND_BLUR',
- 'FOREGROUND_BLUR'
- ]) {
- expect(src).toContain(type)
- }
- })
-
- test('C01-02: Kiwi EffectType enum has only 4 values, missing LAYER_BLUR (kiwi/fig/codec/schema.ts:132-137)', () => {
- const src = readSource(schemaPath)
- expect(src).toContain('INNER_SHADOW = 0')
- expect(src).toContain('DROP_SHADOW = 1')
- expect(src).toContain('FOREGROUND_BLUR = 2')
- expect(src).toContain('BACKGROUND_BLUR = 3')
- expect(src).not.toContain('LAYER_BLUR =')
- })
-
- test('C01-03: Kiwi codec Effect interface also has 5 types (kiwi/fig/codec/index.ts:212)', () => {
- const src = readSource(codecPath)
- // The codec.ts file defines an Effect interface — verify all 5 types present
- // Use a targeted search near the Effect interface definition
- const effectInterfaceMatch = src.match(/interface Effect\s*\{([^}]+)\}/)
- expect(effectInterfaceMatch).toBeTruthy()
- const effectBody = expectDefined(effectInterfaceMatch, 'effectInterfaceMatch')[1]
- for (const type of [
- 'DROP_SHADOW',
- 'INNER_SHADOW',
- 'LAYER_BLUR',
- 'BACKGROUND_BLUR',
- 'FOREGROUND_BLUR'
- ]) {
- expect(effectBody).toContain(type)
- }
- })
-
- test('C01-04: export-node.ts maps LAYER_BLUR → FOREGROUND_BLUR on export (node-change/export-node.ts:75)', () => {
- const src = readSource(nodeExportPath)
- expect(src).toContain("effect.type === 'LAYER_BLUR' ? 'FOREGROUND_BLUR'")
- })
-
- test('C01-05: convertEffects passes through type as-is on import (node-change/paint.ts:115)', () => {
- const src = readSource(convertPath)
- // The convertEffects function should map e.type directly without
- // checking for LAYER_BLUR or remapping FOREGROUND_BLUR back
- expect(src).toContain('type: e.type')
- // Confirm there is NO reverse mapping (FOREGROUND_BLUR → LAYER_BLUR)
- expect(src).not.toContain("'FOREGROUND_BLUR' ? 'LAYER_BLUR'")
- })
-
- test('C01-06: renderShapeUncached order = behind effects → fills → strokes → front effects', () => {
- const src = readSource(scenePath)
- const renderShapeUncachedMatch = src.match(
- /export function renderShapeUncached[\s\S]*?(?=\nexport function|\n$)/
- )
- expect(renderShapeUncachedMatch).toBeTruthy()
- const body = expectDefined(renderShapeUncachedMatch, 'renderShapeUncachedMatch')[0]
-
- // Find indices of key calls
- const behindIdx = body.indexOf("'behind'")
- const fillIdx = body.indexOf('drawNodeFill')
- // Strokes paint through paintNodeStrokes, which path text calls earlier
- // (stroke-first); the default order is asserted from its second call site.
- const strokeIdx = body.lastIndexOf('paintNodeStrokes')
- const frontIdx = body.indexOf("'front'")
-
- expect(behindIdx).toBeGreaterThan(-1)
- expect(fillIdx).toBeGreaterThan(-1)
- expect(strokeIdx).toBeGreaterThan(-1)
- expect(frontIdx).toBeGreaterThan(-1)
-
- // Verify order: behind < fill < stroke < front
- expect(behindIdx).toBeLessThan(fillIdx)
- expect(fillIdx).toBeLessThan(strokeIdx)
- expect(strokeIdx).toBeLessThan(frontIdx)
- })
-
- test('C01-07: renderNode has opacity layer → blur layer → content → children (scene.ts:106-158)', () => {
- const src = readSource(scenePath)
- const renderNodeMatch = src.match(
- /export function renderNode[\s\S]*?(?=\nexport function|\nexport const)/
- )
- expect(renderNodeMatch).toBeTruthy()
- const body = expectDefined(renderNodeMatch, 'renderNodeMatch')[0]
-
- // Verify opacity saveLayer comes before layerBlur saveLayer
- const opacityLayerIdx = body.indexOf('opacity < 1')
- const layerBlurCheckIdx = body.indexOf('layerBlur')
- expect(opacityLayerIdx).toBeGreaterThan(-1)
- expect(layerBlurCheckIdx).toBeGreaterThan(-1)
- expect(opacityLayerIdx).toBeLessThan(layerBlurCheckIdx)
- })
-
- test('C01-08: drawShapeDropShadow uses auxFill.setMaskFilter (MaskFilter approach)', () => {
- const src = readSource(shadowsPath)
- expect(src).toContain('auxFill.setMaskFilter')
- })
-
- test('C01-09: drawShapeDropShadow uses drawRect/drawOval/drawRRect for shadow shape', () => {
- const src = readSource(shadowsPath)
- expect(src).toContain('drawRect')
- expect(src).toContain('drawOval')
- expect(src).toContain('drawRRect')
- })
-
- test('C01-10: text drop shadow uses MakeDropShadowOnly (effects.ts:15)', () => {
- const src = readSource(effectsPath)
- expect(src).toContain('MakeDropShadowOnly')
- })
-
- test('C01-11: renderDropShadow checks shapeNode.type !== "TEXT" to branch', () => {
- const src = readSource(shadowsPath)
- expect(src).toContain("shapeNode.type !== 'TEXT'")
- })
-
- test('C01-12: drawTextInnerShadow implements the exact formula with 4 saveLayer calls', () => {
- const src = readSource(shadowsPath)
- const drawTextInnerShadowMatch = src.match(
- /function drawTextInnerShadow[\s\S]*?(?=\nfunction |\nexport )/
- )
- expect(drawTextInnerShadowMatch).toBeTruthy()
- const body = expectDefined(drawTextInnerShadowMatch, 'drawTextInnerShadowMatch')[0]
-
- // Count saveLayer calls — there are 4 (Master, Restrictive, Blur, DstOut)
- // plus 2 canvas.save() calls (child transform + offset transform)
- const saveLayerCount = (body.match(/canvas\.saveLayer/g) || []).length
- const saveCount = (body.match(/canvas\.save\(\)/g) || []).length
- expect(saveLayerCount).toBe(4)
- expect(saveCount).toBe(2)
-
- // Verify the formula operations are present
- expect(body).toContain('BlendMode.SrcIn') // SrcIn (Tint layer)
- expect(body).toContain('MakeBlend') // ColorFilter tint
- expect(body).toContain('getCachedDecalBlur') // Blur
- expect(body).toContain('translate') // Offset
- expect(body).toContain('drawRect') // SolidRect
- expect(body).toContain('BlendMode.DstOut') // DstOut
- })
-
- test('C01-13: drawShapeInnerShadow uses PathOp.Difference', () => {
- const src = readSource(shadowsPath)
- expect(src).toContain('PathOp.Difference')
- })
-
- test('C01-14: renderShape caches effects nodes via nodePictureCache (scene.ts:230-248)', () => {
- const src = readSource(scenePath)
- const renderShapeMatch = src.match(
- /export function renderShape[\s\S]*?(?=\nexport function|\nexport const)/
- )
- expect(renderShapeMatch).toBeTruthy()
- const body = expectDefined(renderShapeMatch, 'renderShapeMatch')[0]
- expect(body).toContain('nodePictureCache')
- expect(body).toContain('PictureRecorder')
- })
-
- test('C01-15: getShadowShapeChild accesses node.childIds twice (guard + read)', () => {
- const src = readSource(scenePath)
- // Should take the first child — no loop over children
- expect(src).toContain('const child = graph.getNode(node.childIds[0])')
- // Verify it's a single-child function, not multi-child
- const getShadowShapeChildFn = src.match(
- /function getShadowShapeChild[\s\S]*?(?=\nfunction |\nexport )/
- )
- expect(getShadowShapeChildFn).toBeTruthy()
- const body = expectDefined(getShadowShapeChildFn, 'getShadowShapeChildFn')[0]
- // No for loop over children
- expect(body).not.toMatch(/for\s*\(.*childIds/)
- // Accesses childIds twice: once for .length guard, once for [0] read
- const childRefCount = (body.match(/childIds/g) || []).length
- expect(childRefCount).toBe(2) // .length guard + [0] access
- })
-})
-
-// ============================================================
-// DOCUMENT 02: FORMULA DECONSTRUCTION — VERIFICATION
-// ============================================================
-
-describe('Doc 02 — Formula Deconstruction: Static Code Claims', () => {
- test('C02-01: ColorFilter.MakeBlend is captured and explicitly .delete()d (GAP-01 fix)', () => {
- const src = readSource(shadowsPath)
- // MakeBlend is used (tintFilter + solidBlackFilter)
- expect(src).toContain('ColorFilter.MakeBlend')
- // solidBlackFilter is captured and deleted (GAP-01 fix)
- expect(src).toContain('solidBlackFilter.delete()')
- // tintFilter is also captured and deleted
- expect(src).toContain('tintFilter.delete()')
- })
-
- test('C02-02: The DstOut layer stack uses 4 saveLayer calls (drawTextInnerShadow)', () => {
- const src = readSource(shadowsPath)
- const drawTextInnerShadowMatch = src.match(
- /function drawTextInnerShadow[\s\S]*?(?=\nfunction |\nexport )/
- )
- expect(drawTextInnerShadowMatch).toBeTruthy()
- const body = expectDefined(drawTextInnerShadowMatch, 'drawTextInnerShadowMatch')[0]
-
- // 4 saveLayer: Master, Restrictive, Blur, DstOut
- // 2 save: child transform, offset transform
- // 6 restore: one per save/saveLayer
- const saveLayers = (body.match(/canvas\.saveLayer/g) || []).length
- const saves = (body.match(/canvas\.save\(\)/g) || []).length
- const restoreInLoop = body.includes('while (restoreCount > 0)')
- const restoreCountIncrements = (body.match(/restoreCount\+\+/g) || []).length
- expect(saveLayers).toBe(4)
- expect(saves).toBe(2)
- expect(restoreInLoop).toBe(true)
- expect(restoreCountIncrements).toBe(6) // 4 saveLayer + 2 save = 6 restores
- })
-
- test('C02-03: DecalBlur is used (not Clamp) for inner shadow (shadows.ts:184)', () => {
- const src = readSource(shadowsPath)
- // The drawTextInnerShadow function should use getCachedDecalBlur
- expect(src).toContain('getCachedDecalBlur')
- })
-
- test('C02-04: fillPaint is NOT mutated — solid mask via ColorFilter on layer (GAP-03/05 fix)', () => {
- const src = readSource(shadowsPath)
- // ColorFilter.MakeBlend(black, SrcIn) on DstOut layer replaces fillPaint mutation
- // No fillPaint.setColor(black) in drawTextInnerShadow
- expect(src).toContain('solidBlackFilter')
- // ColorFilter approach verified
- expect(src).toContain('ColorFilter.MakeBlend')
- })
-
- test('C02-05: effects.ts has both getCachedBlur (Clamp) and getCachedDecalBlur (Decal)', () => {
- const src = readSource(effectsPath)
- expect(src).toContain('TileMode.Clamp')
- expect(src).toContain('TileMode.Decal')
- })
-
- test('C02-06: SkiaRenderer has imageFilterCache but no colorFilterCache', () => {
- const rendererSrc = readSource(rendererPath)
- expect(rendererSrc).toContain('imageFilterCache')
- expect(rendererSrc).toContain('maskFilterCache')
- expect(rendererSrc).not.toContain('colorFilterCache')
- })
-})
-
-// ============================================================
-// DOCUMENT 03: ARTIFACT ANALYSIS — VERIFICATION
-// ============================================================
-
-describe('Doc 03 — Artifact Analysis: Static + Runtime Verification', () => {
- test('C03-01: render visual inner-shadow counter script exists and checks for right-edge shadow', () => {
- const visualTestPath = repoTestPath('engine/render/canvas/visual/inner-shadow-counter.ts')
- const src = readFileSync(visualTestPath, 'utf-8')
- expect(src).toContain('hasShadowOnRightInnerEdge')
- expect(src).toContain("t.color === 'black'")
- })
-
- test('C03-02: The giant rect uses local expand, not rotation-aware expand (shadows.ts:188-194)', () => {
- const src = readSource(shadowsPath)
- const drawTextInnerShadowMatch = src.match(
- /function drawTextInnerShadow[\s\S]*?(?=\nfunction |\nexport )/
- )
- expect(drawTextInnerShadowMatch).toBeTruthy()
- const body = expectDefined(drawTextInnerShadowMatch, 'drawTextInnerShadowMatch')[0]
-
- // Check the expand calculation
- expect(body).toContain('const expand')
- // The expand should use shapeNode.width/height directly, not a rotated bbox
- expect(body).toContain('shapeNode.width')
- expect(body).toContain('shapeNode.height')
- })
-
- test('C03-03: getShadowShapeChild only considers first child — no iteration', () => {
- const src = readSource(scenePath)
- const match = src.match(/function getShadowShapeChild[\s\S]*?(?=\nfunction |\nexport )/)
- expect(match).toBeTruthy()
- const body = expectDefined(match, 'match')[0]
- // Verify it returns early after first child
- expect(body).toContain('return child')
- // Verify no array accumulation
- expect(body).not.toContain('.push(')
- expect(body).not.toContain('children')
- })
-})
-
-// ============================================================
-// RUNTIME BEHAVIOR VERIFICATION
-// ============================================================
-
-describe('Doc 01/03 — Runtime Behavior Verification', () => {
- // These tests require CanvasKit initialization
- let ck: Awaited<ReturnType<typeof initCanvasKit>>
- let renderer: SkiaRenderer
- let graph: SceneGraph
- let pageId: string
-
- beforeAll(async () => {
- ck = await initCanvasKit()
- const fontProvider = ck.TypefaceFontProvider.Make()
- fontManager.attachProvider(ck, fontProvider)
-
- // Load Inter font for text tests
- const fontPath = publicPath('Inter-SemiBold.ttf')
- try {
- const fontData = readFileSync(fontPath)
- fontManager.markLoaded(
- 'Inter',
- 'SemiBold',
- fontData.buffer.slice(fontData.byteOffset, fontData.byteOffset + fontData.byteLength)
- )
- } catch {
- void fontPath
- }
-
- const surface = expectDefined(ck.MakeSurface(200, 200), 'CanvasKit surface')
- renderer = new SkiaRenderer(ck, surface)
- renderer.fontProvider = fontProvider
- renderer.fontsLoaded = true
-
- graph = new SceneGraph()
- pageId = graph.getPages()[0].id
- })
-
- test('C-RT01: Drop shadow renders behind fills (behavioral order verification)', () => {
- // Create a node with fill + drop shadow
- const node = graph.createNode('RECTANGLE', pageId, {
- x: 10,
- y: 10,
- width: 50,
- height: 50,
- fills: [{ type: 'SOLID', color: { r: 1, g: 0, b: 0, a: 1 }, visible: true, opacity: 1 }],
- effects: [
- {
- type: 'DROP_SHADOW',
- visible: true,
- color: { r: 0, g: 0, b: 0, a: 1 },
- offset: { x: 5, y: 5 },
- radius: 10,
- spread: 0
- }
- ]
- })
-
- // Verify the node was created with effects
- expect(node.effects).toHaveLength(1)
- expect(node.effects[0].type).toBe('DROP_SHADOW')
-
- // Verify the render order by examining renderShapeUncached source
- const callOrder: string[] = []
- const origRenderEffects = renderer.renderEffects.bind(renderer)
- const origDrawNodeFill = renderer.drawNodeFill.bind(renderer)
-
- renderer.renderEffects = (...args: Parameters<typeof renderer.renderEffects>) => {
- callOrder.push(`effects:${args[4]}`)
- origRenderEffects(...args)
- }
- renderer.drawNodeFill = (...args: Parameters<typeof renderer.drawNodeFill>) => {
- callOrder.push('fill')
- origDrawNodeFill(...args)
- }
-
- renderer.renderShapeUncached(renderer['surface'].getCanvas(), node, graph)
-
- const behindIdx = callOrder.indexOf('effects:behind')
- const fillIdx = callOrder.indexOf('fill')
- const frontIdx = callOrder.indexOf('effects:front')
-
- expect(behindIdx).toBeGreaterThan(-1)
- expect(fillIdx).toBeGreaterThan(-1)
- expect(behindIdx).toBeLessThan(fillIdx)
- expect(fillIdx).toBeLessThan(frontIdx)
- })
-
- test('C-RT02: effectOverflow computes correct margin for drop shadow', () => {
- const node = {
- x: 0,
- y: 0,
- width: 100,
- height: 100,
- effects: [
- {
- visible: true,
- type: 'DROP_SHADOW' as const,
- radius: 10,
- spread: 0,
- offset: { x: 5, y: 5 },
- color: { r: 0, g: 0, b: 0, a: 1 }
- }
- ]
- }
-
- const overflow = renderer.effectOverflow(node)
- // radius 10 + offset 5 = 15 margin needed
- expect(overflow).toBeGreaterThanOrEqual(10)
- expect(overflow).toBeLessThanOrEqual(20) // some implementations might differ slightly
- })
-
- test('C-RT03: Inner shadow on text uses the DstOut formula (trace verification)', () => {
- // Trace that drawTextInnerShadow is called when TEXT + INNER_SHADOW
- // We verify this by creating a text node with inner shadow and checking
- // that the renderEffects call reaches the front pass with TEXT type
- const textNode = graph.createNode('TEXT', pageId, {
- x: 10,
- y: 10,
- width: 100,
- height: 30,
- text: 'TEST',
- fontSize: 24,
- fontFamily: 'Inter',
- fontWeight: 600,
- fills: [{ type: 'SOLID', color: { r: 1, g: 1, b: 1, a: 1 }, visible: true, opacity: 1 }],
- effects: [
- {
- type: 'INNER_SHADOW' as const,
- visible: true,
- color: { r: 0, g: 0, b: 0, a: 1 },
- offset: { x: 4, y: 4 },
- radius: 8,
- spread: 0
- }
- ]
- })
-
- expect(textNode.effects).toHaveLength(1)
- expect(textNode.effects[0].type).toBe('INNER_SHADOW')
-
- // Verify the node exists and renderEffects('front') will be called
- // The actual rendering is verified by the behavioral test
- const effectTypes = textNode.effects.map((e) => e.type)
- expect(effectTypes).toContain('INNER_SHADOW')
- })
-
- test('C-RT05: GAP-01 fixed — ColorFilter MakeBlend is captured and .delete()d', () => {
- const src = readSource(shadowsPath)
- const drawTextInnerShadowMatch = src.match(
- /function drawTextInnerShadow[\s\S]*?(?=\nfunction |\nexport )/
- )
- expect(drawTextInnerShadowMatch).toBeTruthy()
- const body = expectDefined(drawTextInnerShadowMatch, 'drawTextInnerShadowMatch')[0]
-
- // MakeBlend IS called (for tintFilter and solidBlackFilter)
- expect(body).toContain('MakeBlend')
- // FIX: solidBlackFilter is captured to a variable and .delete()d
- expect(body).toContain('solidBlackFilter.delete()')
- // FIX: tintFilter is captured to a variable and .delete()d
- expect(body).toContain('tintFilter.delete()')
- })
-})
-
-// ============================================================
-// ROUND-TRIP LOSS VERIFICATION (LAYER_BLUR)
-// ============================================================
-
-describe('Doc 01 — LAYER_BLUR Round-Trip Loss Verification', () => {
- test('C-RT-LOSS-01: convertEffects maps e.type directly (no FOREGROUND_BLUR → LAYER_BLUR)', () => {
- // Dynamically import to verify the runtime behavior
- const src = readSource(convertPath)
- // The function should just do: type: e.type
- expect(src).toMatch(/type:\s*e\.type/)
- })
-
- test('C-RT-LOSS-02: Kiwi EffectType enum preserves modern Figma values without LAYER_BLUR', () => {
- const src = readSource(schemaPath)
- const effectTypeBlock = src.match(/enum EffectType\s*\{([^}]*)\}/)
- expect(effectTypeBlock).toBeTruthy()
- const body = expectDefined(effectTypeBlock, 'effectTypeBlock')[1]
- const valueCount = (body.match(/=\s*\d+\s*;/g) || []).length
- expect(valueCount).toBe(10)
- expect(body).toContain('FOREGROUND_BLUR = 2')
- expect(body).not.toContain('LAYER_BLUR')
- })
-})
-
-// ============================================================
-// CACHE INFRASTRUCTURE VERIFICATION
-// ============================================================
-
-describe('Doc 02/03 — Cache Infrastructure Verification', () => {
- test('C-CACHE-01: imageFilterCache exists and caches DropShadow + Blur filters', () => {
- const rendererSrc = readSource(rendererPath)
- expect(rendererSrc).toContain('imageFilterCache')
- })
-
- test('C-CACHE-02: maskFilterCache exists', () => {
- const rendererSrc = readSource(rendererPath)
- expect(rendererSrc).toContain('maskFilterCache')
- })
-
- test('C-CACHE-03: No colorFilterCache — MakeBlend is uncached', () => {
- const rendererSrc = readSource(rendererPath)
- expect(rendererSrc).not.toContain('colorFilterCache')
- })
-
- test('C-CACHE-04: destroy() cleans up imageFilterCache and maskFilterCache', () => {
- const rendererSrc = readSource(rendererPath)
- const destroyMatch = rendererSrc.match(/destroy\(\)[\s\S]*?(?=\n \w|\n\})/)
- expect(destroyMatch).toBeTruthy()
- const body = expectDefined(destroyMatch, 'destroyMatch')[0]
- // destroy() delegates to destroyRenderer — verify the lifecycle module cleans caches
- expect(body).toContain('destroyRenderer')
- const lifecycleSrc = readSource(lifecyclePath)
- expect(lifecycleSrc).toContain('imageFilterCache')
- expect(lifecycleSrc).toContain('maskFilterCache')
- })
-
- test('C-CACHE-05: nodePictureCache exists for effect caching', () => {
- const rendererSrc = readSource(rendererPath)
- expect(rendererSrc).toContain('nodePictureCache')
- expect(rendererSrc).toContain('scenePicture')
- })
-})
diff --git a/tests/engine/render/canvas/surface-replacement.test.ts b/tests/engine/render/canvas/surface-replacement.test.ts
new file mode 100644
index 000000000..37f8fac19
--- /dev/null
+++ b/tests/engine/render/canvas/surface-replacement.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import type { Surface } from 'canvaskit-wasm'
+
+import { SkiaRenderer } from '#core/canvas/renderer'
+
+function surface() {
+ return { delete: mock() } as Surface & { delete: ReturnType<typeof mock> }
+}
+
+describe('renderer surface replacement', () => {
+ test('clears context-owned tiled resources before replacing the main surface', () => {
+ const previous = surface()
+ const next = surface()
+ const renderer: Pick<
+ SkiaRenderer,
+ | 'surface'
+ | 'tiledScene'
+ | 'sceneBackingAllocationFailed'
+ | 'invalidateScenePicture'
+ | 'replaceSurface'
+ > = {
+ surface: previous,
+ tiledScene: { destroy: mock() } as SkiaRenderer['tiledScene'],
+ sceneBackingAllocationFailed: true,
+ invalidateScenePicture: mock(),
+ replaceSurface: SkiaRenderer.prototype.replaceSurface
+ }
+
+ renderer.replaceSurface.call(renderer as SkiaRenderer, next)
+
+ expect(renderer.tiledScene.destroy).toHaveBeenCalledTimes(1)
+ expect(previous.delete).toHaveBeenCalledTimes(1)
+ expect(renderer.surface).toBe(next)
+ expect(renderer.sceneBackingAllocationFailed).toBe(false)
+ expect(renderer.invalidateScenePicture).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/tests/engine/render/canvas/tiles/cache.test.ts b/tests/engine/render/canvas/tiles/cache.test.ts
new file mode 100644
index 000000000..f0beecdf8
--- /dev/null
+++ b/tests/engine/render/canvas/tiles/cache.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import type { Image as CKImage } from 'canvaskit-wasm'
+
+import { TileImageCache, type RenderedTile } from '#core/canvas/renderer/tiles'
+
+function tile(x: number): RenderedTile {
+ const image: Pick<CKImage, 'width' | 'height' | 'delete'> = {
+ width: () => 256,
+ height: () => 256,
+ delete: mock()
+ }
+ return {
+ key: { pageId: 'page', level: 1, x, y: 0 },
+ image,
+ chunkCount: 1,
+ estimatedCost: 1,
+ renderMs: 1,
+ allocationMs: 0,
+ drawMs: 1,
+ flushMs: 0,
+ snapshotMs: 0
+ }
+}
+
+describe('tile image cache', () => {
+ test('replaces native images and reports memory', () => {
+ const cache = new TileImageCache()
+ const first = tile(0)
+ const second = tile(0)
+ cache.install(first, 1)
+ cache.install(second, 2)
+
+ expect(first.image.delete).toHaveBeenCalledTimes(1)
+ expect(cache.size()).toBe(1)
+ expect(cache.byteSize()).toBe(256 * 256 * 4)
+ cache.clear()
+ expect(second.image.delete).toHaveBeenCalledTimes(1)
+ })
+
+ test('invalidates intersecting tiles and advances unaffected generations', () => {
+ const cache = new TileImageCache()
+ const first = tile(0)
+ const second = tile(1)
+ cache.install(first, 1)
+ cache.install(second, 1)
+
+ expect(cache.invalidateBounds('page', { minX: 300, minY: 10, maxX: 340, maxY: 40 }, 2)).toBe(1)
+ expect(cache.get(first.key)?.contentGeneration).toBe(2)
+ expect(cache.get(second.key)).toBeNull()
+ expect(second.image.delete).toHaveBeenCalledTimes(1)
+ cache.clear()
+ })
+
+ test('evicts least recently used tiles within its byte budget', () => {
+ const bytes = 256 * 256 * 4
+ const cache = new TileImageCache(bytes * 2)
+ const first = tile(0)
+ const second = tile(1)
+ const third = tile(2)
+ cache.install(first, 1)
+ cache.install(second, 1)
+ cache.get(first.key)
+ cache.install(third, 1)
+
+ expect(second.image.delete).toHaveBeenCalledTimes(1)
+ expect(cache.get(first.key)).not.toBeNull()
+ expect(cache.get(third.key)).not.toBeNull()
+ cache.clear()
+ })
+})
diff --git a/tests/engine/render/canvas/tiles/geometry.test.ts b/tests/engine/render/canvas/tiles/geometry.test.ts
new file mode 100644
index 000000000..967dc5507
--- /dev/null
+++ b/tests/engine/render/canvas/tiles/geometry.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+ TILE_DEVICE_SIZE,
+ TILE_LEVEL_STEP,
+ tileKeyString,
+ tileKeysForWorldBounds,
+ tileLevel,
+ tileWorldBounds,
+ tileWorldSize
+} from '#core/canvas/renderer/tiles'
+
+describe('tile geometry', () => {
+ test('quantizes scale upward and keeps fixed device-pixel targets', () => {
+ expect(tileLevel(1)).toBe(1)
+ expect(tileLevel(1.01)).toBe(1.25)
+ expect(tileLevel(1.26)).toBe(1.5)
+ expect(tileWorldSize(2)).toBe(TILE_DEVICE_SIZE / 2)
+ })
+
+ test('adds lower levels to bound visible tile counts at very low zoom', () => {
+ const level = tileLevel(0.04)
+ const keys = tileKeysForWorldBounds('page', level, {
+ minX: 0,
+ minY: 0,
+ maxX: 1920 / 0.02,
+ maxY: 1080 / 0.02
+ })
+
+ expect(level).toBeLessThan(TILE_LEVEL_STEP)
+ expect(keys.length).toBeLessThan(500)
+ })
+
+ test('maps negative and positive world bounds to stable tile keys', () => {
+ const keys = tileKeysForWorldBounds('page', 2, {
+ minX: -10,
+ minY: -10,
+ maxX: 260,
+ maxY: 130
+ })
+
+ expect(keys).toHaveLength(12)
+ expect(keys.map(tileKeyString)).toEqual([
+ 'page:2:-1:-1',
+ 'page:2:0:-1',
+ 'page:2:1:-1',
+ 'page:2:2:-1',
+ 'page:2:-1:0',
+ 'page:2:0:0',
+ 'page:2:1:0',
+ 'page:2:2:0',
+ 'page:2:-1:1',
+ 'page:2:0:1',
+ 'page:2:1:1',
+ 'page:2:2:1'
+ ])
+ })
+
+ test('produces adjacent non-overlapping world bounds', () => {
+ const first = tileWorldBounds({ pageId: 'page', level: 2, x: 0, y: 0 })
+ const second = tileWorldBounds({ pageId: 'page', level: 2, x: 1, y: 0 })
+ expect(first.maxX).toBe(second.minX)
+ expect(first.minY).toBe(second.minY)
+ })
+})
diff --git a/tests/engine/render/canvas/tiles/gold-preview.test.ts b/tests/engine/render/canvas/tiles/gold-preview.test.ts
new file mode 100644
index 000000000..a1662344f
--- /dev/null
+++ b/tests/engine/render/canvas/tiles/gold-preview.test.ts
@@ -0,0 +1,70 @@
+import { beforeAll, expect, setDefaultTimeout, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+
+import { initCodec, parseFigFile } from '@open-pencil/core'
+
+import { initCanvasKit } from '#cli/headless'
+import { SkiaRenderer } from '#core/canvas'
+import { RenderChunkIndex, RenderChunkPictureCache } from '#core/canvas/renderer/chunks'
+import {
+ deleteRenderedTile,
+ renderTile,
+ tileChunks,
+ tileLevel,
+ TileSurfacePool
+} from '#core/canvas/renderer/tiles'
+
+import { expectDefined } from '#tests/helpers/assert'
+import { repoPath } from '#tests/helpers/paths'
+import { HEAVY_TEST_TIMEOUT_MS } from '#tests/helpers/test-utils'
+
+setDefaultTimeout(HEAVY_TEST_TIMEOUT_MS)
+
+let graph: Awaited<ReturnType<typeof parseFigFile>>
+let ck: Awaited<ReturnType<typeof initCanvasKit>>
+
+beforeAll(async () => {
+ ck = await initCanvasKit()
+ await initCodec()
+ const bytes = readFileSync(repoPath('tests/fixtures/gold-preview.fig'))
+ graph = await parseFigFile(bytes.buffer as ArrayBuffer, { populate: 'all' })
+}, 60_000)
+
+test('renders one gold-preview tile from a selective chunk query', () => {
+ const page = expectDefined(graph.getPages()[0], 'gold-preview page')
+ const root = expectDefined(graph.getChildren(page.id)[0], 'gold-preview root')
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ const surface = expectDefined(ck.MakeSurface(320, 240), 'tile benchmark surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ const pictureCache = new RenderChunkPictureCache()
+ const surfacePool = new TileSurfacePool()
+ try {
+ const level = tileLevel(1)
+ const worldSize = 256 / level
+ const key = {
+ pageId: page.id,
+ level,
+ x: Math.floor(root.x / worldSize),
+ y: Math.floor(root.y / worldSize)
+ }
+ const cold = expectDefined(
+ renderTile(renderer, graph, index, key, pictureCache, surfacePool),
+ 'cold tile'
+ )
+ const warm = expectDefined(
+ renderTile(renderer, graph, index, key, pictureCache, surfacePool),
+ 'warm tile'
+ )
+
+ expect(cold.chunkCount).toBeLessThan(index.size())
+ expect(tileChunks(index, key)).toHaveLength(cold.chunkCount)
+ expect(pictureCache.size()).toBeGreaterThan(0)
+ deleteRenderedTile(cold)
+ deleteRenderedTile(warm)
+ } finally {
+ surfacePool.clear()
+ pictureCache.clear()
+ index.dispose()
+ renderer.destroy()
+ }
+})
diff --git a/tests/engine/render/canvas/tiles/planner.test.ts b/tests/engine/render/canvas/tiles/planner.test.ts
new file mode 100644
index 000000000..7055201f2
--- /dev/null
+++ b/tests/engine/render/canvas/tiles/planner.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import type { Image as CKImage } from 'canvaskit-wasm'
+
+import {
+ planTiles,
+ TileImageCache,
+ type RenderedTile,
+ type TileKey,
+ type TilePlanOptions
+} from '#core/canvas/renderer/tiles'
+
+function renderedTile(key: TileKey): RenderedTile {
+ const image: Pick<CKImage, 'width' | 'height' | 'delete'> = {
+ width: () => 256,
+ height: () => 256,
+ delete: mock()
+ }
+ return {
+ key,
+ image,
+ chunkCount: 1,
+ estimatedCost: 1,
+ renderMs: 1,
+ allocationMs: 0,
+ drawMs: 1,
+ flushMs: 0,
+ snapshotMs: 0
+ }
+}
+
+function rendered(x: number): RenderedTile {
+ return renderedTile({ pageId: 'page', level: 1, x, y: 0 })
+}
+
+function baseOptions(overrides: Partial<TilePlanOptions> = {}): TilePlanOptions {
+ return {
+ pageId: 'page',
+ level: 1,
+ viewport: { minX: 0, minY: 0, maxX: 512, maxY: 256 },
+ overscanTiles: 0,
+ navigationGeneration: 3,
+ contentGeneration: 2,
+ estimateCost: () => 1,
+ ...overrides
+ }
+}
+
+describe('tile planner', () => {
+ test('classifies stale visible jobs before overscan', () => {
+ const cache = new TileImageCache()
+ cache.install(rendered(0), 1)
+ cache.install(rendered(1), 2)
+ const plan = planTiles(cache, baseOptions({ overscanTiles: 1 }))
+
+ expect(plan.visible).toHaveLength(2)
+ expect(plan.jobs.find((job) => job.key.x === 0)?.priority).toBe('visible')
+ expect(plan.jobs.find((job) => job.key.x === 0)?.fallbackAvailable).toBe(true)
+ expect(plan.jobs.some((job) => job.key.x === 1 && job.key.y === 0)).toBe(false)
+ expect(plan.jobs.some((job) => job.priority === 'overscan')).toBe(false)
+ cache.clear()
+ })
+
+ test('defers overscan until visible exact coverage is complete', () => {
+ const cache = new TileImageCache()
+ const options = baseOptions({ overscanTiles: 1 })
+ const first = planTiles(cache, options)
+ expect(first.jobs.some((job) => job.priority === 'overscan')).toBe(false)
+
+ for (const { key } of first.visible) cache.install(renderedTile(key), options.contentGeneration)
+ const covered = planTiles(cache, options)
+ expect(covered.jobs.some((job) => job.priority === 'overscan')).toBe(true)
+ cache.clear()
+ })
+
+ test('marks visible holes mandatory and carries generations', () => {
+ const cache = new TileImageCache()
+ const plan = planTiles(
+ cache,
+ baseOptions({
+ level: 2,
+ viewport: { minX: 0, minY: 0, maxX: 128, maxY: 128 },
+ navigationGeneration: 5,
+ contentGeneration: 7,
+ estimateCost: () => 12
+ })
+ )
+
+ expect(plan.jobs).toHaveLength(1)
+ expect(plan.jobs[0]).toMatchObject({
+ priority: 'mandatory',
+ fallbackAvailable: false,
+ navigationGeneration: 5,
+ contentGeneration: 7,
+ estimatedCost: 12
+ })
+ })
+})
diff --git a/tests/engine/render/canvas/tiles/render.test.ts b/tests/engine/render/canvas/tiles/render.test.ts
new file mode 100644
index 000000000..457995403
--- /dev/null
+++ b/tests/engine/render/canvas/tiles/render.test.ts
@@ -0,0 +1,450 @@
+import { beforeAll, describe, expect, test } from 'bun:test'
+
+import { SceneGraph } from '@open-pencil/scene-graph'
+
+import { initCanvasKit } from '#cli/headless'
+import { SkiaRenderer } from '#core/canvas'
+import { RenderChunkIndex, RenderChunkPictureCache } from '#core/canvas/renderer/chunks'
+import {
+ deleteRenderedTile,
+ renderTile,
+ TiledSceneController,
+ TILE_DEVICE_SIZE,
+ TileSurfacePool,
+ tileKeysForWorldBounds,
+ tileWorldBounds
+} from '#core/canvas/renderer/tiles'
+
+import { expectDefined } from '#tests/helpers/assert'
+
+let ck: Awaited<ReturnType<typeof initCanvasKit>>
+
+beforeAll(async () => {
+ ck = await initCanvasKit()
+})
+
+function color(r: number, g: number, b: number) {
+ return [{ type: 'SOLID' as const, color: { r, g, b, a: 1 }, opacity: 1, visible: true }]
+}
+
+function pixels(image: ReturnType<typeof ck.MakeImageFromEncoded>, width: number, height: number) {
+ if (!image) throw new Error('Expected image')
+ return expectDefined(
+ image.readPixels(0, 0, {
+ width,
+ height,
+ colorType: ck.ColorType.RGBA_8888,
+ alphaType: ck.AlphaType.Unpremul,
+ colorSpace: ck.ColorSpace.SRGB
+ }),
+ 'tile pixels'
+ )
+}
+
+function differenceRatio(a: Uint8Array, b: Uint8Array, tolerance = 8) {
+ let different = 0
+ for (let index = 0; index < a.length; index++) {
+ if (Math.abs(a[index] - b[index]) > tolerance) different++
+ }
+ return different / a.length
+}
+
+function squareCommandsBlob(): Uint8Array {
+ const blob = new Uint8Array(1 + 4 * 9 + 1)
+ const view = new DataView(blob.buffer)
+ let offset = 0
+ for (const [command, x, y] of [
+ [1, 0, 0],
+ [2, 1, 0],
+ [2, 1, 1],
+ [2, 0, 1]
+ ] as const) {
+ blob[offset] = command
+ view.setFloat32(offset + 1, x, true)
+ view.setFloat32(offset + 5, y, true)
+ offset += 9
+ }
+ blob[offset] = 0
+ return blob
+}
+
+function testImageBytes(): Uint8Array {
+ const surface = expectDefined(ck.MakeSurface(8, 8), 'test image surface')
+ const canvas = surface.getCanvas()
+ canvas.clear(ck.Color4f(0.95, 0.75, 0.1, 1))
+ const paint = new ck.Paint()
+ paint.setColor(ck.Color4f(0.1, 0.3, 0.95, 1))
+ canvas.drawRect(ck.LTRBRect(0, 0, 4, 8), paint)
+ surface.flush()
+ const image = surface.makeImageSnapshot()
+ const bytes = expectDefined(image.encodeToBytes(ck.ImageFormat.PNG, 100), 'test image PNG')
+ image.delete()
+ paint.delete()
+ surface.delete()
+ return bytes
+}
+
+function createParityGraph() {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ const clip = graph.createNode('FRAME', page.id, {
+ x: 40,
+ y: 30,
+ width: 260,
+ height: 180,
+ clipsContent: true,
+ cornerRadius: 20,
+ fills: color(0.95, 0.95, 0.98)
+ })
+ const frame = graph.createNode('FRAME', clip.id, { width: 360, height: 160, fills: [] })
+ for (let index = 0; index < 48; index++) {
+ graph.createNode(index % 2 === 0 ? 'RECTANGLE' : 'ELLIPSE', frame.id, {
+ x: (index % 12) * 28,
+ y: Math.floor(index / 12) * 36,
+ width: 32,
+ height: 32,
+ fills: color((index % 3) * 0.35, 0.3, 0.85 - (index % 2) * 0.3)
+ })
+ }
+ const translucent = graph.createNode('FRAME', page.id, {
+ x: 210,
+ y: 55,
+ width: 100,
+ height: 120,
+ opacity: 0.55,
+ blendMode: 'MULTIPLY',
+ fills: [],
+ effects: [
+ {
+ type: 'FOREGROUND_BLUR',
+ visible: true,
+ radius: 12,
+ spread: 0,
+ offset: { x: 0, y: 0 },
+ color: { r: 0, g: 0, b: 0, a: 1 }
+ }
+ ]
+ })
+ graph.createNode('RECTANGLE', translucent.id, {
+ x: 5,
+ y: 5,
+ width: 80,
+ height: 90,
+ fills: color(0.9, 0.2, 0.4),
+ effects: [
+ {
+ type: 'DROP_SHADOW',
+ visible: true,
+ color: { r: 0.1, g: 0.1, b: 0.2, a: 0.7 },
+ offset: { x: 18, y: 6 },
+ radius: 16,
+ spread: 3
+ }
+ ]
+ })
+ const masked = graph.createNode('FRAME', page.id, {
+ x: 105,
+ y: 150,
+ width: 130,
+ height: 80,
+ fills: []
+ })
+ graph.createNode('ELLIPSE', masked.id, {
+ x: 0,
+ y: 0,
+ width: 90,
+ height: 70,
+ isMask: true,
+ fills: color(0, 0, 0)
+ })
+ graph.createNode('RECTANGLE', masked.id, {
+ x: -15,
+ y: -5,
+ width: 150,
+ height: 90,
+ fills: color(0.1, 0.8, 0.35)
+ })
+ const imageHash = 'tile-parity-image'
+ graph.images.set(imageHash, testImageBytes())
+ graph.createNode('RECTANGLE', page.id, {
+ x: 238,
+ y: 176,
+ width: 68,
+ height: 52,
+ rotation: -7,
+ fills: [
+ {
+ type: 'IMAGE',
+ imageHash,
+ imageScaleMode: 'FILL',
+ opacity: 1,
+ visible: true
+ }
+ ]
+ })
+ graph.createNode('TEXT', page.id, {
+ x: 245,
+ y: 15,
+ width: 64,
+ height: 34,
+ rotation: 9,
+ text: 'tile',
+ fontFamily: '__MissingFont__',
+ fontSize: 22,
+ fills: color(0.15, 0.1, 0.75),
+ derivedTextGlyphs: [
+ { commandsBlob: squareCommandsBlob(), x: 0, y: 22, fontSize: 18 },
+ { commandsBlob: squareCommandsBlob(), x: 20, y: 22, fontSize: 18 },
+ { commandsBlob: squareCommandsBlob(), x: 40, y: 22, fontSize: 18 }
+ ]
+ })
+ return { graph, page }
+}
+
+describe('tile rendering', () => {
+ test('restores pooled tile canvas transforms before the surface is reused', () => {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ graph.createNode('RECTANGLE', page.id, {
+ x: 20,
+ y: 20,
+ width: 80,
+ height: 80,
+ fills: color(1, 0, 0)
+ })
+ const surface = expectDefined(ck.MakeSurface(320, 240), 'renderer surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ renderer.pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ const pictureCache = new RenderChunkPictureCache()
+ const surfacePool = new TileSurfacePool()
+ const key = { pageId: page.id, level: 1, x: 0, y: 0 }
+ try {
+ const first = expectDefined(
+ renderTile(renderer, graph, index, key, pictureCache, surfacePool),
+ 'first tile'
+ )
+ const second = expectDefined(
+ renderTile(renderer, graph, index, key, pictureCache, surfacePool),
+ 'second tile'
+ )
+ const firstPixels = pixels(first.image, TILE_DEVICE_SIZE, TILE_DEVICE_SIZE)
+ const secondPixels = pixels(second.image, TILE_DEVICE_SIZE, TILE_DEVICE_SIZE)
+ expect(firstPixels.every((value, index) => value === secondPixels[index])).toBe(true)
+ deleteRenderedTile(first)
+ deleteRenderedTile(second)
+ } finally {
+ surfacePool.clear()
+ pictureCache.clear()
+ index.dispose()
+ renderer.destroy()
+ }
+ })
+
+ test('cancels obsolete refresh jobs and performs no exact work during navigation', () => {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ for (let index = 0; index < 48; index++) {
+ graph.createNode('RECTANGLE', page.id, {
+ x: (index % 12) * 100,
+ y: Math.floor(index / 12) * 100,
+ width: 80,
+ height: 80,
+ fills: color(0.2, 0.4, 0.8)
+ })
+ }
+ const surface = expectDefined(ck.MakeSurface(1280, 800), 'cancellation surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ const controller = new TiledSceneController()
+ renderer.pageId = page.id
+ renderer.pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ renderer.viewportWidth = 1280
+ renderer.viewportHeight = 800
+ renderer.dpr = 1
+ renderer.zoom = 1
+ renderer.navigationPhase = 'idle'
+ try {
+ const initial = controller.renderFrame(renderer, surface.getCanvas(), graph, 1, 0)
+ expect(initial.pending).toBe(true)
+
+ renderer.navigationPhase = 'zoom'
+ renderer.navigationGeneration = 1
+ const navigating = controller.renderFrame(renderer, surface.getCanvas(), graph, 1, 1)
+ expect(navigating.metrics.cancelledJobs).toBeGreaterThan(0)
+ expect(navigating.metrics.mandatoryCompleted).toBe(0)
+ expect(navigating.metrics.interruptibleCompleted).toBe(0)
+ } finally {
+ controller.destroy()
+ renderer.destroy()
+ }
+ })
+
+ test('refreshes only tiles intersecting an updated isolated chunk', () => {
+ const graph = new SceneGraph()
+ const page = expectDefined(graph.getPages()[0], 'page')
+ const changed = graph.createNode('RECTANGLE', page.id, {
+ x: 20,
+ y: 20,
+ width: 40,
+ height: 40,
+ fills: color(1, 0, 0)
+ })
+ graph.createNode('RECTANGLE', page.id, {
+ x: 540,
+ y: 20,
+ width: 40,
+ height: 40,
+ fills: color(0, 0, 1)
+ })
+ const surface = expectDefined(ck.MakeSurface(640, 240), 'selective invalidation surface')
+ const renderer = new SkiaRenderer(ck, surface)
+ const controller = new TiledSceneController()
+ renderer.pageId = page.id
+ renderer.pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ renderer.viewportWidth = 640
+ renderer.viewportHeight = 240
+ renderer.dpr = 1
+ renderer.zoom = 1
+ renderer.navigationPhase = 'idle'
+ try {
+ let initial = controller.renderFrame(renderer, surface.getCanvas(), graph, 1, 0)
+ for (let frame = 0; frame < 10 && initial.pending; frame++) {
+ initial = controller.renderFrame(renderer, surface.getCanvas(), graph, 1, 0)
+ }
+ expect(initial.covered).toBe(true)
+
+ controller.invalidateNode(changed.id)
+ graph.updateNode(changed.id, { x: 30, fills: color(0, 1, 0) })
+ const refreshed = controller.renderFrame(renderer, surface.getCanvas(), graph, 2, 0)
+ expect(refreshed.metrics.interruptibleCompleted).toBe(1)
+ expect(refreshed.covered).toBe(true)
+ } finally {
+ controller.destroy()
+ renderer.destroy()
+ }
+ })
+
+ test('live controller progressively replaces fallback pixels without changing the scene', () => {
+ const { graph, page } = createParityGraph()
+ const directSurface = expectDefined(ck.MakeSurface(320, 240), 'direct controller surface')
+ const tiledSurface = expectDefined(ck.MakeSurface(320, 240), 'tiled controller surface')
+ const direct = new SkiaRenderer(ck, directSurface)
+ const tiled = new SkiaRenderer(ck, tiledSurface)
+ const controller = new TiledSceneController()
+ const pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ for (const renderer of [direct, tiled]) {
+ renderer.pageId = page.id
+ renderer.pageColor = pageColor
+ renderer.viewportWidth = 320
+ renderer.viewportHeight = 240
+ renderer.dpr = 1
+ renderer.zoom = 1
+ renderer.navigationPhase = 'idle'
+ renderer.nodeFontReadiness = () => 'exhausted'
+ }
+
+ try {
+ direct.surface.getCanvas().clear(ck.WHITE)
+ direct.renderSceneToCanvas(direct.surface.getCanvas(), graph, page.id)
+ direct.surface.flush()
+ const directImage = direct.surface.makeImageSnapshot()
+
+ let result = { covered: false, pending: true }
+ for (let frame = 0; frame < 20 && result.pending; frame++) {
+ const canvas = tiled.surface.getCanvas()
+ canvas.clear(ck.WHITE)
+ tiled.renderSceneToCanvas(canvas, graph, page.id)
+ result = controller.renderFrame(tiled, canvas, graph, 1, 0)
+ tiled.surface.flush()
+ }
+ expect(result.covered).toBe(true)
+ expect(result.pending).toBe(false)
+
+ const tiledImage = tiled.surface.makeImageSnapshot()
+ expect(
+ differenceRatio(pixels(directImage, 320, 240), pixels(tiledImage, 320, 240))
+ ).toBeLessThan(0.01)
+ directImage.delete()
+ tiledImage.delete()
+ } finally {
+ controller.destroy()
+ direct.destroy()
+ tiled.destroy()
+ }
+ })
+
+ test('composes multiple queried tiles to match direct scene rendering', () => {
+ const { graph, page } = createParityGraph()
+
+ const directSurface = expectDefined(ck.MakeSurface(320, 240), 'direct surface')
+ const tiledSurface = expectDefined(ck.MakeSurface(320, 240), 'tiled surface')
+ const tileFactorySurface = expectDefined(ck.MakeSurface(320, 240), 'tile factory surface')
+ const direct = new SkiaRenderer(ck, directSurface)
+ const tiled = new SkiaRenderer(ck, tiledSurface)
+ const tileFactory = new SkiaRenderer(ck, tileFactorySurface)
+ direct.pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ tiled.pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ tileFactory.pageColor = { r: 1, g: 1, b: 1, a: 1 }
+ direct.nodeFontReadiness = () => 'exhausted'
+ tiled.nodeFontReadiness = () => 'exhausted'
+ tileFactory.nodeFontReadiness = () => 'exhausted'
+ const { index } = RenderChunkIndex.build(graph, page.id)
+ const level = 1
+ const keys = tileKeysForWorldBounds(page.id, level, {
+ minX: 0,
+ minY: 0,
+ maxX: 320,
+ maxY: 240
+ })
+ const pictureCache = new RenderChunkPictureCache()
+ const surfacePool = new TileSurfacePool()
+ try {
+ direct.surface.getCanvas().clear(ck.WHITE)
+ direct.renderSceneToCanvas(direct.surface.getCanvas(), graph, page.id)
+ direct.surface.flush()
+ const directImage = direct.surface.makeImageSnapshot()
+
+ const tiledCanvas = tiled.surface.getCanvas()
+ tiledCanvas.clear(ck.WHITE)
+ const rendered = keys.map((key) =>
+ expectDefined(
+ renderTile(tileFactory, graph, index, key, pictureCache, surfacePool),
+ 'rendered tile'
+ )
+ )
+ const tilePaint = new ck.Paint()
+ tilePaint.setBlendMode(ck.BlendMode.Src)
+ for (const tile of rendered) {
+ const bounds = tileWorldBounds(tile.key)
+ tiledCanvas.drawImageRectOptions(
+ tile.image,
+ ck.LTRBRect(0, 0, TILE_DEVICE_SIZE, TILE_DEVICE_SIZE),
+ ck.LTRBRect(bounds.minX, bounds.minY, bounds.maxX, bounds.maxY),
+ ck.FilterMode.Nearest,
+ ck.MipmapMode.None,
+ tilePaint
+ )
+ }
+ tilePaint.delete()
+ tiled.surface.flush()
+ const tiledImage = tiled.surface.makeImageSnapshot()
+
+ expect(
+ differenceRatio(pixels(directImage, 320, 240), pixels(tiledImage, 320, 240))
+ ).toBeLessThan(0.01)
+ expect(rendered.every((tile) => tile.chunkCount < index.size())).toBe(true)
+ expect(rendered.every((tile) => tile.image.width() === TILE_DEVICE_SIZE)).toBe(true)
+
+ directImage.delete()
+ tiledImage.delete()
+ for (const tile of rendered) deleteRenderedTile(tile)
+ } finally {
+ surfacePool.clear()
+ pictureCache.clear()
+ index.dispose()
+ direct.destroy()
+ tiled.destroy()
+ tileFactory.destroy()
+ }
+ })
+})
diff --git a/tests/engine/render/canvas/tiles/scheduler.test.ts b/tests/engine/render/canvas/tiles/scheduler.test.ts
new file mode 100644
index 000000000..c5740f0d2
--- /dev/null
+++ b/tests/engine/render/canvas/tiles/scheduler.test.ts
@@ -0,0 +1,133 @@
+import { describe, expect, test } from 'bun:test'
+
+import { TileScheduler, type TileJob } from '#core/canvas/renderer/tiles'
+
+function job(x: number, priority: TileJob['priority'], options: Partial<TileJob> = {}): TileJob {
+ return {
+ key: { pageId: 'page', level: 1, x, y: 0 },
+ navigationGeneration: 1,
+ contentGeneration: 1,
+ priority,
+ fallbackAvailable: false,
+ estimatedCost: 1,
+ ...options
+ }
+}
+
+describe('tile scheduler', () => {
+ test('runs mandatory holes before visible refresh and overscan', () => {
+ let clock = 0
+ const scheduler = new TileScheduler({ budgetMs: 5, now: () => clock })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue([job(2, 'overscan'), job(1, 'visible'), job(0, 'mandatory')])
+ const order: number[] = []
+ const metrics = scheduler.runFrame((item) => {
+ order.push(item.key.x)
+ clock += 2
+ return { renderMs: 2, overBudget: false }
+ })
+
+ expect(order).toEqual([0, 1, 2])
+ expect(metrics.mandatoryCompleted).toBe(1)
+ expect(metrics.interruptibleCompleted).toBe(2)
+ })
+
+ test('stops interruptible work at the deadline', () => {
+ let clock = 0
+ const scheduler = new TileScheduler({ budgetMs: 4, now: () => clock })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue([job(0, 'visible'), job(1, 'visible'), job(2, 'overscan')])
+ const first = scheduler.runFrame(() => {
+ clock += 3
+ return { renderMs: 3, overBudget: false }
+ })
+
+ expect(first.interruptibleCompleted).toBe(2)
+ expect(first.remaining).toBe(1)
+ expect(scheduler.pending()).toBe(1)
+ })
+
+ test('runs one estimated over-budget fallback refresh and keeps later work queued', () => {
+ let clock = 0
+ const scheduler = new TileScheduler({ budgetMs: 5, now: () => clock })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue([
+ job(0, 'visible', { fallbackAvailable: true, estimatedCost: 10 }),
+ job(1, 'visible', { fallbackAvailable: true, estimatedCost: 10 })
+ ])
+ const metrics = scheduler.runFrame(() => {
+ clock += 8
+ return { renderMs: 8, overBudget: true }
+ })
+
+ expect(metrics.interruptibleCompleted).toBe(1)
+ expect(metrics.overBudgetJobs).toBe(1)
+ expect(metrics.remaining).toBe(1)
+ })
+
+ test('spreads multiple mandatory holes across frames after an over-budget job', () => {
+ let clock = 0
+ const scheduler = new TileScheduler({ budgetMs: 5, now: () => clock })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue([job(0, 'mandatory'), job(1, 'mandatory')])
+ const metrics = scheduler.runFrame(() => {
+ clock += 8
+ return { renderMs: 8, overBudget: true }
+ })
+
+ expect(metrics.mandatoryCompleted).toBe(1)
+ expect(metrics.remaining).toBe(1)
+ })
+
+ test('allows a mandatory visible hole and reports deadline overrun', () => {
+ let clock = 0
+ const scheduler = new TileScheduler({ budgetMs: 5, now: () => clock })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue([job(0, 'mandatory', { estimatedCost: 12 })])
+ const metrics = scheduler.runFrame(() => {
+ clock += 12
+ return { renderMs: 12, overBudget: true }
+ })
+
+ expect(metrics.mandatoryCompleted).toBe(1)
+ expect(metrics.overBudgetJobs).toBe(1)
+ expect(metrics.deadlineOverrunMs).toBe(7)
+ })
+
+ test('uses the measured deadline rather than an arbitrary cheap-job cap', () => {
+ let now = 0
+ const scheduler = new TileScheduler({ budgetMs: 5, maximumJobsPerFrame: 32, now: () => now })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue(
+ Array.from({ length: 40 }, (_, x) =>
+ job(x, 'visible', { fallbackAvailable: true, estimatedCost: 0.2 })
+ )
+ )
+
+ const metrics = scheduler.runFrame(() => {
+ now += 0.2
+ return { renderMs: 0.2, overBudget: false }
+ })
+
+ expect(metrics.interruptibleCompleted).toBe(24)
+ expect(metrics.remaining).toBe(16)
+ expect(metrics.deadlineOverrunMs).toBe(0)
+ })
+ test('clears queued work explicitly for same-generation structural replacement', () => {
+ const scheduler = new TileScheduler({ budgetMs: 5, now: () => 0 })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue([job(0, 'visible'), job(1, 'visible')])
+
+ expect(scheduler.clear()).toBe(2)
+ expect(scheduler.pending()).toBe(0)
+ })
+
+ test('cancels queued work from obsolete navigation generations', () => {
+ const scheduler = new TileScheduler({ budgetMs: 5, now: () => 0 })
+ scheduler.setGeneration(1, 1)
+ scheduler.enqueue([job(0, 'visible'), job(1, 'visible')])
+ expect(scheduler.setGeneration(2, 1)).toBe(2)
+
+ expect(scheduler.pending()).toBe(0)
+ })
+})
diff --git a/tests/fixtures/navigation/gestures/synthetic-momentum-pan-reversal.json b/tests/fixtures/navigation/gestures/synthetic-momentum-pan-reversal.json
new file mode 100644
index 000000000..961f9e475
--- /dev/null
+++ b/tests/fixtures/navigation/gestures/synthetic-momentum-pan-reversal.json
@@ -0,0 +1,211 @@
+{
+ "schemaVersion": 1,
+ "name": "synthetic-momentum-pan-reversal",
+ "source": "synthetic",
+ "recordedAt": "2026-01-01T00:00:00.000Z",
+ "environment": {
+ "userAgent": "synthetic",
+ "platform": "MacIntel",
+ "devicePixelRatio": 2,
+ "viewportWidth": 1280,
+ "viewportHeight": 800,
+ "canvasWidth": 1280,
+ "canvasHeight": 800
+ },
+ "initialViewport": { "panX": 0, "panY": 0, "zoom": 1 },
+ "wheel": [
+ {
+ "timeMs": 0,
+ "deltaX": 1.5,
+ "deltaY": 2.5,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 8,
+ "deltaX": 4,
+ "deltaY": 7,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 16,
+ "deltaX": 9,
+ "deltaY": 15,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 24,
+ "deltaX": 15,
+ "deltaY": 24,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 33,
+ "deltaX": 19,
+ "deltaY": 30,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 42,
+ "deltaX": 16,
+ "deltaY": 26,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 51,
+ "deltaX": 12,
+ "deltaY": 19,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 60,
+ "deltaX": 8,
+ "deltaY": 13,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 69,
+ "deltaX": 5,
+ "deltaY": 8,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 78,
+ "deltaX": 3,
+ "deltaY": 5,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 96,
+ "deltaX": -2,
+ "deltaY": -4,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 105,
+ "deltaX": -6,
+ "deltaY": -10,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 114,
+ "deltaX": -10,
+ "deltaY": -16,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 123,
+ "deltaX": -7,
+ "deltaY": -11,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 132,
+ "deltaX": -4,
+ "deltaY": -7,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 142,
+ "deltaX": -2,
+ "deltaY": -3,
+ "deltaMode": 0,
+ "ctrlKey": false,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ }
+ ],
+ "trace": []
+}
diff --git a/tests/fixtures/navigation/gestures/synthetic-pinch-reversal.json b/tests/fixtures/navigation/gestures/synthetic-pinch-reversal.json
new file mode 100644
index 000000000..0d3bee7b8
--- /dev/null
+++ b/tests/fixtures/navigation/gestures/synthetic-pinch-reversal.json
@@ -0,0 +1,127 @@
+{
+ "schemaVersion": 1,
+ "name": "synthetic-pinch-reversal",
+ "source": "synthetic",
+ "recordedAt": "2026-01-01T00:00:00.000Z",
+ "environment": {
+ "userAgent": "synthetic",
+ "platform": "MacIntel",
+ "devicePixelRatio": 2,
+ "viewportWidth": 1280,
+ "viewportHeight": 800,
+ "canvasWidth": 1280,
+ "canvasHeight": 800
+ },
+ "initialViewport": { "panX": 0, "panY": 0, "zoom": 1 },
+ "wheel": [
+ {
+ "timeMs": 0,
+ "deltaX": 0,
+ "deltaY": -1.2,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 8,
+ "deltaX": 0,
+ "deltaY": -2.4,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 17,
+ "deltaX": 0,
+ "deltaY": -3.8,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 26,
+ "deltaX": 0,
+ "deltaY": -4.1,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 35,
+ "deltaX": 0,
+ "deltaY": -2.2,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 58,
+ "deltaX": 0,
+ "deltaY": 1.1,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 67,
+ "deltaX": 0,
+ "deltaY": 2.7,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 76,
+ "deltaX": 0,
+ "deltaY": 3.2,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 86,
+ "deltaX": 0,
+ "deltaY": 1.5,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ }
+ ],
+ "trace": []
+}
diff --git a/tests/fixtures/navigation/gestures/synthetic-repeated-pinch-reversal.json b/tests/fixtures/navigation/gestures/synthetic-repeated-pinch-reversal.json
new file mode 100644
index 000000000..553f9a0be
--- /dev/null
+++ b/tests/fixtures/navigation/gestures/synthetic-repeated-pinch-reversal.json
@@ -0,0 +1,312 @@
+{
+ "schemaVersion": 1,
+ "name": "synthetic-repeated-pinch-reversal",
+ "source": "synthetic",
+ "recordedAt": "2026-08-21T00:00:00.000Z",
+ "environment": {
+ "userAgent": "synthetic",
+ "platform": "MacIntel",
+ "devicePixelRatio": 2,
+ "viewportWidth": 1280,
+ "viewportHeight": 800,
+ "canvasWidth": 1280,
+ "canvasHeight": 800
+ },
+ "initialViewport": { "panX": 0, "panY": 0, "zoom": 1 },
+ "wheel": [
+ {
+ "timeMs": 0,
+ "deltaX": 0,
+ "deltaY": -3,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 8,
+ "deltaX": 0,
+ "deltaY": -5,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 16,
+ "deltaX": 0,
+ "deltaY": -6,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 24,
+ "deltaX": 0,
+ "deltaY": -4,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+
+ {
+ "timeMs": 82,
+ "deltaX": 0,
+ "deltaY": 4,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 90,
+ "deltaX": 0,
+ "deltaY": 6,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 98,
+ "deltaX": 0,
+ "deltaY": 5,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 106,
+ "deltaX": 0,
+ "deltaY": 3,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+
+ {
+ "timeMs": 164,
+ "deltaX": 0,
+ "deltaY": -4,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 172,
+ "deltaX": 0,
+ "deltaY": -6,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 180,
+ "deltaX": 0,
+ "deltaY": -5,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 188,
+ "deltaX": 0,
+ "deltaY": -3,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+
+ {
+ "timeMs": 246,
+ "deltaX": 0,
+ "deltaY": 4,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 254,
+ "deltaX": 0,
+ "deltaY": 6,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 262,
+ "deltaX": 0,
+ "deltaY": 5,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 270,
+ "deltaX": 0,
+ "deltaY": 3,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+
+ {
+ "timeMs": 328,
+ "deltaX": 0,
+ "deltaY": -4,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 336,
+ "deltaX": 0,
+ "deltaY": -6,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 344,
+ "deltaX": 0,
+ "deltaY": -5,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 352,
+ "deltaX": 0,
+ "deltaY": -3,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+
+ {
+ "timeMs": 410,
+ "deltaX": 0,
+ "deltaY": 4,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 418,
+ "deltaX": 0,
+ "deltaY": 6,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 426,
+ "deltaX": 0,
+ "deltaY": 5,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ },
+ {
+ "timeMs": 434,
+ "deltaX": 0,
+ "deltaY": 3,
+ "deltaMode": 0,
+ "ctrlKey": true,
+ "metaKey": false,
+ "shiftKey": false,
+ "clientX": 640,
+ "clientY": 400,
+ "cancelable": true
+ }
+ ],
+ "trace": []
+}
diff --git a/tools/navigation-benchmark/package.json b/tools/navigation-benchmark/package.json
new file mode 100644
index 000000000..9203717dc
--- /dev/null
+++ b/tools/navigation-benchmark/package.json
@@ -0,0 +1,8 @@
+{
+ "name": "@open-pencil/navigation-benchmark",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "test": "bun test tests"
+ }
+}
diff --git a/tools/navigation-benchmark/src/chromium-trace.ts b/tools/navigation-benchmark/src/chromium-trace.ts
new file mode 100644
index 000000000..ad6e454d6
--- /dev/null
+++ b/tools/navigation-benchmark/src/chromium-trace.ts
@@ -0,0 +1,54 @@
+import { writeFile } from 'node:fs/promises'
+import { gzipSync } from 'node:zlib'
+
+import type { Page } from '@playwright/test'
+
+const TRACE_CATEGORIES = [
+ 'devtools.timeline',
+ 'disabled-by-default-devtools.timeline',
+ 'blink.user_timing',
+ 'latencyInfo',
+ 'input',
+ 'toplevel',
+ 'cc',
+ 'gpu',
+ 'v8'
+]
+
+export interface ChromiumTraceCapture {
+ stop: (path: string) => Promise<void>
+}
+
+export interface ChromiumTraceOptions {
+ cpuProfile?: boolean
+}
+
+export async function startChromiumTrace(
+ page: Page,
+ options: ChromiumTraceOptions = {}
+): Promise<ChromiumTraceCapture> {
+ const categories = options.cpuProfile
+ ? [...TRACE_CATEGORIES, 'disabled-by-default-v8.cpu_profiler']
+ : TRACE_CATEGORIES
+ const session = await page.context().newCDPSession(page)
+ const chunks: string[] = []
+ session.on('Tracing.dataCollected', ({ value }) => chunks.push(...value.map(JSON.stringify)))
+ await session.send('Tracing.start', {
+ categories: categories.join(','),
+ transferMode: 'ReportEvents',
+ options: 'sampling-frequency=10000'
+ })
+
+ return {
+ async stop(path) {
+ const complete = new Promise<void>((resolve) => {
+ session.once('Tracing.tracingComplete', () => resolve())
+ })
+ await session.send('Tracing.end')
+ await complete
+ const trace = `{"traceEvents":[${chunks.join(',')}],"displayTimeUnit":"ms"}`
+ await writeFile(path, gzipSync(trace))
+ await session.detach()
+ }
+ }
+}
diff --git a/tools/navigation-benchmark/src/cli.ts b/tools/navigation-benchmark/src/cli.ts
new file mode 100644
index 000000000..5f1fe5b13
--- /dev/null
+++ b/tools/navigation-benchmark/src/cli.ts
@@ -0,0 +1,221 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+import { chromium } from '@playwright/test'
+
+import { startChromiumTrace } from './chromium-trace'
+import { compareNavigationMetrics } from './compare'
+import { computeNavigationMetrics } from './metrics'
+import { readRecording } from './recording'
+import { replay, type ReplayMode } from './replay'
+import { setupScenario, type NavigationScenario } from './scenario'
+import type { NavigationMetrics, NavigationRecordingFile } from './types'
+
+function argument(name: string, fallback?: string): string {
+ const index = process.argv.indexOf(name)
+ const value = index === -1 ? fallback : process.argv[index + 1]
+ if (!value) throw new Error(`Missing ${name}`)
+ return value
+}
+
+const command = process.argv[2]
+if (command === 'compare') {
+ const baseline = JSON.parse(await readFile(argument('--baseline'), 'utf8')) as NavigationMetrics
+ const candidate = JSON.parse(await readFile(argument('--candidate'), 'utf8')) as NavigationMetrics
+ const comparison = compareNavigationMetrics(baseline, candidate)
+ const comparisonOutput = process.argv.includes('--output') ? argument('--output') : null
+ if (comparisonOutput) await writeFile(comparisonOutput, JSON.stringify(comparison, null, 2))
+ console.log(JSON.stringify(comparison, null, 2))
+ process.exit(0)
+}
+if (command !== 'run') {
+ console.log(
+ 'Usage: bun tools/navigation-benchmark/src/cli.ts run --url URL --gesture FILE [--mode cdp|dom] [--scenario light|large-flat|raster-stress|current-document] [--document FILE] [--no-trace] [--cpu-profile] [--software-gpu] [--output DIR]\n bun tools/navigation-benchmark/src/cli.ts compare --baseline METRICS --candidate METRICS [--output FILE]'
+ )
+ process.exit(command ? 1 : 0)
+}
+
+const url = argument('--url')
+const gesturePath = argument('--gesture')
+const mode = argument('--mode', 'cdp') as ReplayMode
+const scenario = argument('--scenario', 'light') as NavigationScenario
+const documentPath = process.argv.includes('--document') ? resolve(argument('--document')) : null
+const mutationNodeId = process.argv.includes('--mutate-node') ? argument('--mutate-node') : null
+const mutationOpacity = process.argv.includes('--mutate-opacity')
+ ? Number(argument('--mutate-opacity'))
+ : null
+const replayAfterMutation = process.argv.includes('--replay-after-mutation')
+const traceEnabled = !process.argv.includes('--no-trace')
+const cpuProfile = process.argv.includes('--cpu-profile')
+const softwareGpu = process.argv.includes('--software-gpu')
+const output = resolve(argument('--output', 'artifacts/navigation-benchmark'))
+if (mode !== 'cdp' && mode !== 'dom') throw new Error(`Unsupported replay mode: ${mode}`)
+if (!['light', 'large-flat', 'raster-stress', 'current-document'].includes(scenario)) {
+ throw new Error(`Unsupported scenario: ${scenario}`)
+}
+
+if (scenario === 'current-document' && !documentPath) {
+ throw new Error('--document is required with --scenario current-document')
+}
+if (scenario !== 'current-document' && documentPath) {
+ throw new Error('--document requires --scenario current-document')
+}
+
+if (mutationOpacity !== null && (!Number.isFinite(mutationOpacity) || !mutationNodeId)) {
+ throw new Error('--mutate-opacity requires a finite value and --mutate-node')
+}
+
+await mkdir(output, { recursive: true })
+const input = await readRecording(gesturePath)
+function hardwareGpuArgs(): string[] {
+ const base = ['--ignore-gpu-blocklist', '--enable-gpu']
+ return process.platform === 'darwin' ? [...base, '--use-angle=metal'] : base
+}
+
+const browser = await chromium.launch({
+ headless: true,
+ args: softwareGpu ? ['--enable-unsafe-swiftshader'] : hardwareGpuArgs()
+})
+const context = await browser.newContext({
+ viewport: { width: 1280, height: 800 },
+ deviceScaleFactor: 2
+})
+const page = await context.newPage()
+const documentURLPath = '/__navigation-benchmark-document.fig'
+if (documentPath) {
+ const documentBytes = await readFile(documentPath)
+ await page.route(`**${documentURLPath}`, (route) =>
+ route.fulfill({
+ status: 200,
+ contentType: 'application/octet-stream',
+ body: documentBytes
+ })
+ )
+}
+
+try {
+ await page.goto(
+ `${url}${url.includes('?') ? '&' : '?'}test&no-chrome&no-rulers&navigation-benchmark`
+ )
+ const glInfo = await page.evaluate(() => {
+ const canvas = document.createElement('canvas')
+ const gl = canvas.getContext('webgl2')
+ if (!gl) return { renderer: 'unavailable', vendor: 'unavailable' }
+ const debugInfo = gl.getExtension('WEBGL_debug_renderer_info')
+ return {
+ renderer: String(
+ gl.getParameter(debugInfo?.UNMASKED_RENDERER_WEBGL ?? gl.RENDERER) ?? 'unknown'
+ ),
+ vendor: String(gl.getParameter(debugInfo?.UNMASKED_VENDOR_WEBGL ?? gl.VENDOR) ?? 'unknown')
+ }
+ })
+ if (!softwareGpu && /SwiftShader/i.test(glInfo.renderer)) {
+ throw new Error(`Hardware GPU benchmark requested but Chromium uses ${glInfo.renderer}`)
+ }
+ await page.locator('[data-test-id="canvas-element"][data-ready="1"]').waitFor({ timeout: 30_000 })
+ if (documentPath) {
+ await page.evaluate((path) => window.openPencil?.openFile?.(path), documentURLPath)
+ await page.waitForFunction(
+ () => {
+ const store = window.openPencil?.getStore?.()
+ return (
+ store != null &&
+ !store.state.loading &&
+ store.graph.getChildren(store.state.currentPageId).length > 0
+ )
+ },
+ undefined,
+ { timeout: 90_000 }
+ )
+ await page.evaluate(() => {
+ const store = window.openPencil?.getStore?.()
+ if (!store) throw new Error('OpenPencil store not available after opening benchmark document')
+ store.zoomToFit()
+ })
+ } else {
+ await setupScenario(page, scenario)
+ }
+ await page.evaluate(() => window.openPencil?.test?.navigation?.waitForSettlement())
+ if (!documentPath) {
+ await page.evaluate((viewport) => {
+ const store = window.openPencil?.getStore?.()
+ if (!store) throw new Error('OpenPencil store not available')
+ store.state.panX = viewport.panX
+ store.state.panY = viewport.panY
+ store.state.zoom = viewport.zoom
+ store.requestRepaint()
+ }, input.initialViewport)
+ }
+ await page.evaluate(() => window.openPencil?.test?.navigation?.waitForSettlement())
+ await page.evaluate(
+ (name) => window.openPencil?.test?.navigation?.startRecording(name),
+ input.name
+ )
+
+ const trace = traceEnabled ? await startChromiumTrace(page, { cpuProfile }) : null
+ if (mutationNodeId && mutationOpacity !== null) {
+ const previousSceneVersion = await page.evaluate(
+ () => window.openPencil?.getStore?.().state.sceneVersion ?? -1
+ )
+ await page.evaluate(
+ ({ nodeId, opacity }) => {
+ const store = window.openPencil?.getStore?.()
+ if (!store) throw new Error('OpenPencil store not available for benchmark mutation')
+ if (!store.graph.getNode(nodeId))
+ throw new Error(`Benchmark mutation node not found: ${nodeId}`)
+ store.graph.updateNode(nodeId, { opacity })
+ },
+ { nodeId: mutationNodeId, opacity: mutationOpacity }
+ )
+ if (replayAfterMutation) {
+ await page.waitForFunction((sceneVersion) => {
+ const store = window.openPencil?.getStore?.()
+ return (
+ store != null &&
+ store.state.sceneVersion > sceneVersion &&
+ store.canvasRenderers.some(
+ (renderer) => renderer.tracksSceneSettlement && renderer.tiledScenePending
+ )
+ )
+ }, previousSceneVersion)
+ await replay(page, input, mode)
+ }
+ } else {
+ await replay(page, input, mode)
+ }
+ await page.evaluate(() => window.openPencil?.test?.navigation?.waitForSettlement())
+ await trace?.stop(resolve(output, 'trace.json.gz'))
+
+ const recording = await page.evaluate(
+ () => window.openPencil?.test?.navigation?.stopRecording() as NavigationRecordingFile
+ )
+ const metrics = computeNavigationMetrics(recording)
+ const environment = {
+ url,
+ mode,
+ scenario,
+ traceEnabled,
+ cpuProfile,
+ softwareGpu,
+ glInfo,
+ documentPath,
+ mutationNodeId,
+ mutationOpacity,
+ replayAfterMutation,
+ gesturePath: resolve(gesturePath),
+ browserVersion: await browser.version(),
+ platform: process.platform,
+ arch: process.arch,
+ bunVersion: Bun.version,
+ recordedAt: new Date().toISOString()
+ }
+ await Promise.all([
+ writeFile(resolve(output, 'recording.json'), JSON.stringify(recording, null, 2)),
+ writeFile(resolve(output, 'metrics.json'), JSON.stringify(metrics, null, 2)),
+ writeFile(resolve(output, 'environment.json'), JSON.stringify(environment, null, 2))
+ ])
+ console.log(JSON.stringify(metrics, null, 2))
+} finally {
+ await context.close()
+ await browser.close()
+}
diff --git a/tools/navigation-benchmark/src/compare.ts b/tools/navigation-benchmark/src/compare.ts
new file mode 100644
index 000000000..4f87548bd
--- /dev/null
+++ b/tools/navigation-benchmark/src/compare.ts
@@ -0,0 +1,50 @@
+import type { NavigationMetrics } from './types'
+
+export interface MetricComparison {
+ baseline: number | null
+ candidate: number | null
+ delta: number | null
+ ratio: number | null
+}
+
+export interface NavigationComparison {
+ displayFrameP95Ms: MetricComparison
+ displayFrameP99Ms: MetricComparison
+ renderP95Ms: MetricComparison
+ inputToRenderP95Ms: MetricComparison
+ zoomAnchorDriftMaxPx: MetricComparison
+ maximumJumpPx: MetricComparison
+ finalInputToCrispMs: MetricComparison
+ longTaskTotalMs: MetricComparison
+}
+
+function compare(baseline: number | null, candidate: number | null): MetricComparison {
+ return {
+ baseline,
+ candidate,
+ delta: baseline === null || candidate === null ? null : candidate - baseline,
+ ratio: baseline === null || candidate === null || baseline === 0 ? null : candidate / baseline
+ }
+}
+
+export function compareNavigationMetrics(
+ baseline: NavigationMetrics,
+ candidate: NavigationMetrics
+): NavigationComparison {
+ return {
+ displayFrameP95Ms: compare(
+ baseline.displayFrameIntervalsMs.p95,
+ candidate.displayFrameIntervalsMs.p95
+ ),
+ displayFrameP99Ms: compare(
+ baseline.displayFrameIntervalsMs.p99,
+ candidate.displayFrameIntervalsMs.p99
+ ),
+ renderP95Ms: compare(baseline.renderDurationsMs.p95, candidate.renderDurationsMs.p95),
+ inputToRenderP95Ms: compare(baseline.eventToRenderEndMs.p95, candidate.eventToRenderEndMs.p95),
+ zoomAnchorDriftMaxPx: compare(baseline.zoomAnchorDriftPx.max, candidate.zoomAnchorDriftPx.max),
+ maximumJumpPx: compare(baseline.maximumJumpPx, candidate.maximumJumpPx),
+ finalInputToCrispMs: compare(baseline.finalInputToCrispMs, candidate.finalInputToCrispMs),
+ longTaskTotalMs: compare(baseline.longTasks.totalMs, candidate.longTasks.totalMs)
+ }
+}
diff --git a/tools/navigation-benchmark/src/metrics.ts b/tools/navigation-benchmark/src/metrics.ts
new file mode 100644
index 000000000..b16e62469
--- /dev/null
+++ b/tools/navigation-benchmark/src/metrics.ts
@@ -0,0 +1,189 @@
+import type { Distribution, NavigationMetrics, NavigationRecordingFile, TraceEvent } from './types'
+
+function round(value: number): number {
+ return Math.round(value * 1000) / 1000
+}
+
+function percentile(sorted: readonly number[], fraction: number): number {
+ if (sorted.length === 0) return 0
+ const index = Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1)
+ return sorted[index] ?? 0
+}
+
+export function distribution(values: readonly number[]): Distribution {
+ if (values.length === 0) {
+ return { count: 0, min: 0, median: 0, p95: 0, p99: 0, max: 0, mean: 0 }
+ }
+ const sorted = [...values].sort((a, b) => a - b)
+ return {
+ count: sorted.length,
+ min: round(sorted[0] ?? 0),
+ median: round(percentile(sorted, 0.5)),
+ p95: round(percentile(sorted, 0.95)),
+ p99: round(percentile(sorted, 0.99)),
+ max: round(sorted.at(-1) ?? 0),
+ mean: round(sorted.reduce((sum, value) => sum + value, 0) / sorted.length)
+ }
+}
+
+function events(trace: readonly TraceEvent[], name: string): TraceEvent[] {
+ return trace.filter((event) => event.name === name)
+}
+
+function nextTimestamp(trace: readonly TraceEvent[], after: number, name: string): number | null {
+ return trace.find((event) => event.timestamp >= after && event.name === name)?.timestamp ?? null
+}
+
+function numeric(event: TraceEvent, key: string): number | null {
+ const value = event.detail[key]
+ return typeof value === 'number' ? value : null
+}
+
+function renderPairs(trace: readonly TraceEvent[]): Array<{ start: TraceEvent; end: TraceEvent }> {
+ const pending: TraceEvent[] = []
+ const pairs: Array<{ start: TraceEvent; end: TraceEvent }> = []
+ for (const event of trace) {
+ if (event.name === 'render:start') pending.push(event)
+ if (event.name === 'render:end' && event.detail.layer !== 'tiled-scheduler') {
+ const start = pending.shift()
+ if (start) pairs.push({ start, end: event })
+ }
+ }
+ return pairs
+}
+
+function zoomAnchorDrift(
+ trace: readonly TraceEvent[],
+ recording: NavigationRecordingFile
+): number[] {
+ const zoomEvents = recording.wheel.filter((event) => event.ctrlKey || event.metaKey)
+ const center = zoomEvents.at(-1)
+ if (!center) return []
+ const viewports = events(trace, 'viewport:changed').filter((event) => {
+ const zoom = numeric(event, 'zoom')
+ const previousZoom = numeric(event, 'previousZoom')
+ return zoom !== null && previousZoom !== null && zoom !== previousZoom
+ })
+ return viewports.map((event) => {
+ const panX = numeric(event, 'panX') ?? 0
+ const panY = numeric(event, 'panY') ?? 0
+ const zoom = numeric(event, 'zoom') ?? 1
+ const previousPanX = numeric(event, 'previousPanX') ?? 0
+ const previousPanY = numeric(event, 'previousPanY') ?? 0
+ const previousZoom = numeric(event, 'previousZoom') ?? 1
+ const worldX = (center.clientX - previousPanX) / previousZoom
+ const worldY = (center.clientY - previousPanY) / previousZoom
+ const projectedX = worldX * zoom + panX
+ const projectedY = worldY * zoom + panY
+ return Math.hypot(projectedX - center.clientX, projectedY - center.clientY)
+ })
+}
+
+function navigationRenderEvents(trace: readonly TraceEvent[]): TraceEvent[] {
+ return events(trace, 'render:end').filter((event) => event.detail.layer !== 'tiled-scheduler')
+}
+
+function maximumViewportJump(trace: readonly TraceEvent[]): number {
+ return navigationRenderEvents(trace).reduce((maximum, event, index, rendered) => {
+ const previous = rendered[index - 1]
+ if (!previous) return maximum
+ const panX = numeric(event, 'panX') ?? 0
+ const panY = numeric(event, 'panY') ?? 0
+ const previousPanX = numeric(previous, 'panX') ?? 0
+ const previousPanY = numeric(previous, 'panY') ?? 0
+ return Math.max(maximum, Math.hypot(panX - previousPanX, panY - previousPanY))
+ }, 0)
+}
+
+function intervalCounts(intervals: readonly number[]) {
+ return {
+ over8Ms: intervals.filter((duration) => duration > 1000 / 120).length,
+ over16Ms: intervals.filter((duration) => duration > 1000 / 60).length,
+ over33Ms: intervals.filter((duration) => duration > 1000 / 30).length,
+ over50Ms: intervals.filter((duration) => duration > 50).length
+ }
+}
+
+export function computeNavigationMetrics(recording: NavigationRecordingFile): NavigationMetrics {
+ const trace = [...recording.trace].sort((a, b) => a.timestamp - b.timestamp)
+ const rendered = navigationRenderEvents(trace)
+ const received = events(trace, 'wheel:received')
+ const finalInput = received.at(-1)?.timestamp ?? recording.wheel.at(-1)?.timeMs ?? 0
+ const interactionFrames = rendered.filter((event) => event.timestamp <= finalInput + 50)
+ const renderFrameIntervals = interactionFrames.slice(1).map((event, index) => {
+ const previous = interactionFrames[index]
+ return previous ? event.timestamp - previous.timestamp : 0
+ })
+ const animationFrames = events(trace, 'animation:frame').filter(
+ (event) => event.timestamp <= finalInput + 50
+ )
+ const displayFrameIntervals = animationFrames.slice(1).map((event, index) => {
+ const previous = animationFrames[index]
+ return previous ? event.timestamp - previous.timestamp : 0
+ })
+ const pairs = renderPairs(trace)
+ const renderDurations = pairs.map(({ start, end }) => end.timestamp - start.timestamp)
+ const eventToViewport = received.flatMap((event) => {
+ const next = nextTimestamp(trace, event.timestamp, 'viewport:changed')
+ return next === null ? [] : [next - event.timestamp]
+ })
+ const eventToRenderEnd = received.flatMap((event) => {
+ const next = nextTimestamp(rendered, event.timestamp, 'render:end')
+ return next === null ? [] : [next - event.timestamp]
+ })
+ const crispCandidates = (
+ recording.sceneRenderer === 'tiled'
+ ? events(trace, 'tiles:coverage-complete')
+ : [
+ ...events(trace, 'backing:crisp'),
+ ...rendered.filter((event) => event.detail.backingCrisp === true)
+ ]
+ ).sort((a, b) => a.timestamp - b.timestamp)
+ const crisp = crispCandidates.find((event) => event.timestamp >= finalInput)
+ const schedulerEvents = events(trace, 'render:end').filter(
+ (event) => event.detail.layer === 'tiled-scheduler'
+ )
+ const schedulerNumbers = (key: string) =>
+ schedulerEvents.flatMap((event) => {
+ const value = numeric(event, key)
+ return value === null ? [] : [value]
+ })
+ const schedulerCompleted = schedulerEvents.map(
+ (event) =>
+ (numeric(event, 'mandatoryCompleted') ?? 0) + (numeric(event, 'interruptibleCompleted') ?? 0)
+ )
+ const longTaskDurations = events(trace, 'main:long-task').flatMap((event) => {
+ const duration = numeric(event, 'durationMs')
+ return duration === null ? [] : [duration]
+ })
+
+ return {
+ durationMs: round((trace.at(-1)?.timestamp ?? 0) - (trace[0]?.timestamp ?? 0)),
+ eventCount: received.length || recording.wheel.length,
+ viewportUpdateCount: events(trace, 'viewport:changed').length,
+ renderCount: rendered.length,
+ displayFrameIntervalsMs: distribution(displayFrameIntervals),
+ renderFrameIntervalsMs: distribution(renderFrameIntervals),
+ renderDurationsMs: distribution(renderDurations),
+ eventToViewportMs: distribution(eventToViewport),
+ eventToRenderEndMs: distribution(eventToRenderEnd),
+ zoomAnchorDriftPx: distribution(zoomAnchorDrift(trace, recording)),
+ maximumJumpPx: round(maximumViewportJump(trace)),
+ finalInputToCrispMs: crisp ? round(crisp.timestamp - finalInput) : null,
+ scheduler: {
+ frameCount: schedulerEvents.length,
+ maximumJobsPerFrame: Math.max(0, ...schedulerCompleted),
+ maximumJobRenderMs: round(Math.max(0, ...schedulerNumbers('maximumJobRenderMs'))),
+ overBudgetJobs: schedulerNumbers('overBudgetJobs').reduce((sum, value) => sum + value, 0),
+ maximumDeadlineOverrunMs: round(Math.max(0, ...schedulerNumbers('deadlineOverrunMs'))),
+ cancelledJobs: schedulerNumbers('cancelledJobs').reduce((sum, value) => sum + value, 0)
+ },
+ longTasks: {
+ count: longTaskDurations.length,
+ totalMs: round(longTaskDurations.reduce((sum, duration) => sum + duration, 0)),
+ maximumMs: round(Math.max(0, ...longTaskDurations))
+ },
+ missedDisplayFrames: intervalCounts(displayFrameIntervals),
+ renderGaps: intervalCounts(renderFrameIntervals)
+ }
+}
diff --git a/tools/navigation-benchmark/src/recording.ts b/tools/navigation-benchmark/src/recording.ts
new file mode 100644
index 000000000..70a8fe3cf
--- /dev/null
+++ b/tools/navigation-benchmark/src/recording.ts
@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises'
+
+import * as v from 'valibot'
+
+import type { NavigationRecordingFile } from './types'
+
+const wheelSampleSchema = v.object({
+ timeMs: v.pipe(v.number(), v.minValue(0)),
+ deltaX: v.number(),
+ deltaY: v.number(),
+ deltaMode: v.number(),
+ ctrlKey: v.optional(v.boolean(), false),
+ metaKey: v.optional(v.boolean(), false),
+ shiftKey: v.optional(v.boolean(), false),
+ clientX: v.number(),
+ clientY: v.number(),
+ cancelable: v.optional(v.boolean(), true),
+ directionInvertedFromDevice: v.optional(v.boolean())
+})
+
+const traceEventSchema = v.object({
+ name: v.string(),
+ timestamp: v.number(),
+ detail: v.record(v.string(), v.union([v.number(), v.string(), v.boolean(), v.null()]))
+})
+
+const recordingSchema = v.object({
+ schemaVersion: v.literal(1),
+ name: v.pipe(v.string(), v.nonEmpty()),
+ source: v.picklist(['macos-trackpad', 'synthetic']),
+ recordedAt: v.string(),
+ environment: v.record(v.string(), v.union([v.string(), v.number()])),
+ sceneRenderer: v.optional(v.picklist(['existing', 'retained', 'tiled']), 'retained'),
+ initialViewport: v.object({ panX: v.number(), panY: v.number(), zoom: v.number() }),
+ wheel: v.array(wheelSampleSchema),
+ trace: v.array(traceEventSchema)
+})
+
+export function parseRecording(value: unknown): NavigationRecordingFile {
+ const data = v.parse(recordingSchema, value)
+ const normalized = {
+ ...data,
+ sceneRenderer: data.sceneRenderer === 'existing' ? ('retained' as const) : data.sceneRenderer
+ }
+ for (let index = 1; index < data.wheel.length; index++) {
+ const current = data.wheel[index]
+ const previous = data.wheel[index - 1]
+ if (current && previous && current.timeMs < previous.timeMs) {
+ throw new Error('Wheel samples must be ordered by timeMs')
+ }
+ }
+ return normalized
+}
+
+export async function readRecording(path: string): Promise<NavigationRecordingFile> {
+ return parseRecording(JSON.parse(await readFile(path, 'utf8')))
+}
diff --git a/tools/navigation-benchmark/src/replay.ts b/tools/navigation-benchmark/src/replay.ts
new file mode 100644
index 000000000..5ba2cb775
--- /dev/null
+++ b/tools/navigation-benchmark/src/replay.ts
@@ -0,0 +1,82 @@
+import type { Page } from '@playwright/test'
+
+import type { NavigationRecordingFile, WheelSample } from './types'
+
+export type ReplayMode = 'dom' | 'cdp'
+
+async function waitUntil(startedAt: number, timeMs: number): Promise<void> {
+ const elapsed = performance.now() - startedAt
+ const delay = timeMs - elapsed
+ if (delay > 0) {
+ await new Promise((resolve) => {
+ setTimeout(resolve, delay)
+ })
+ }
+}
+
+export async function replayDOM(page: Page, recording: NavigationRecordingFile): Promise<void> {
+ await page.evaluate(async (samples: WheelSample[]) => {
+ const canvas = document.querySelector<HTMLCanvasElement>('[data-test-id="canvas-element"]')
+ if (!canvas) throw new Error('Canvas element not found')
+ const startedAt = performance.now()
+ for (const sample of samples) {
+ const delay = sample.timeMs - (performance.now() - startedAt)
+ if (delay > 0) {
+ await new Promise((resolve) => {
+ setTimeout(resolve, delay)
+ })
+ }
+ canvas.dispatchEvent(
+ new WheelEvent('wheel', {
+ deltaX: sample.deltaX,
+ deltaY: sample.deltaY,
+ deltaMode: sample.deltaMode,
+ ctrlKey: sample.ctrlKey,
+ metaKey: sample.metaKey,
+ shiftKey: sample.shiftKey,
+ clientX: sample.clientX,
+ clientY: sample.clientY,
+ cancelable: sample.cancelable,
+ bubbles: true
+ })
+ )
+ }
+ }, recording.wheel)
+}
+
+export async function replayCDP(page: Page, recording: NavigationRecordingFile): Promise<void> {
+ const session = await page.context().newCDPSession(page)
+ const startedAt = performance.now()
+ const pending: Array<Promise<unknown>> = []
+ try {
+ for (const sample of recording.wheel) {
+ await waitUntil(startedAt, sample.timeMs)
+ let modifiers = 0
+ if (sample.shiftKey) modifiers |= 8
+ if (sample.ctrlKey) modifiers |= 2
+ if (sample.metaKey) modifiers |= 4
+ pending.push(
+ session.send('Input.dispatchMouseEvent', {
+ type: 'mouseWheel',
+ x: sample.clientX,
+ y: sample.clientY,
+ deltaX: sample.deltaX,
+ deltaY: sample.deltaY,
+ modifiers
+ })
+ )
+ }
+ await Promise.all(pending)
+ } finally {
+ await session.detach()
+ }
+}
+
+export async function replay(
+ page: Page,
+ recording: NavigationRecordingFile,
+ mode: ReplayMode
+): Promise<void> {
+ if (mode === 'dom') await replayDOM(page, recording)
+ else await replayCDP(page, recording)
+}
diff --git a/tools/navigation-benchmark/src/scenario.ts b/tools/navigation-benchmark/src/scenario.ts
new file mode 100644
index 000000000..3e9594472
--- /dev/null
+++ b/tools/navigation-benchmark/src/scenario.ts
@@ -0,0 +1,65 @@
+import type { Page } from '@playwright/test'
+
+export type NavigationScenario = 'light' | 'large-flat' | 'raster-stress' | 'current-document'
+
+export async function setupScenario(page: Page, scenario: NavigationScenario): Promise<void> {
+ if (scenario === 'current-document') return
+ await page.evaluate((selectedScenario) => {
+ const store = window.openPencil?.getStore?.()
+ if (!store) throw new Error('OpenPencil store not available')
+ const pageId = store.state.currentPageId
+ const existing = store.graph.getNode(pageId)?.childIds ?? []
+ for (const id of existing) store.graph.deleteNode(id)
+
+ let count = 1_000
+ if (selectedScenario === 'light') count = 80
+ else if (selectedScenario === 'large-flat') count = 5_000
+ const columns = Math.ceil(Math.sqrt(count))
+ for (let index = 0; index < count; index++) {
+ const row = Math.floor(index / columns)
+ const column = index % columns
+ const type = index % 3 === 0 ? 'ELLIPSE' : 'RECTANGLE'
+ store.graph.createNode(type, pageId, {
+ x: column * 96,
+ y: row * 96,
+ width: 80,
+ height: 80,
+ cornerRadius: type === 'RECTANGLE' ? index % 16 : 0,
+ fills: [
+ {
+ type: 'SOLID',
+ color: {
+ r: 0.2 + (index % 5) * 0.12,
+ g: 0.25 + (index % 4) * 0.12,
+ b: 0.45 + (index % 3) * 0.15,
+ a: 1
+ },
+ visible: true,
+ opacity: 1
+ }
+ ],
+ effects:
+ selectedScenario === 'raster-stress' && index % 4 === 0
+ ? [
+ {
+ type: 'DROP_SHADOW',
+ color: { r: 0, g: 0, b: 0, a: 0.35 },
+ offset: { x: 8, y: 12 },
+ radius: 16,
+ spread: 2,
+ visible: true,
+ blendMode: 'NORMAL'
+ }
+ ]
+ : []
+ })
+ }
+ store.requestRender()
+ }, scenario)
+ await page.evaluate(
+ () =>
+ new Promise<void>((resolve) => {
+ requestAnimationFrame(() => resolve())
+ })
+ )
+}
diff --git a/tools/navigation-benchmark/src/types.ts b/tools/navigation-benchmark/src/types.ts
new file mode 100644
index 000000000..af7badeb6
--- /dev/null
+++ b/tools/navigation-benchmark/src/types.ts
@@ -0,0 +1,57 @@
+import type { RecordedWheelSample } from '@open-pencil/core/profiler'
+
+export type WheelSample = RecordedWheelSample
+
+export interface TraceEvent {
+ name: string
+ timestamp: number
+ detail: Record<string, number | string | boolean | null>
+}
+
+export interface NavigationRecordingFile {
+ schemaVersion: 1
+ name: string
+ source: 'macos-trackpad' | 'synthetic'
+ recordedAt: string
+ environment: Record<string, string | number>
+ sceneRenderer: 'retained' | 'tiled'
+ initialViewport: { panX: number; panY: number; zoom: number }
+ wheel: WheelSample[]
+ trace: TraceEvent[]
+}
+
+export interface NavigationMetrics {
+ durationMs: number
+ eventCount: number
+ viewportUpdateCount: number
+ renderCount: number
+ displayFrameIntervalsMs: Distribution
+ renderFrameIntervalsMs: Distribution
+ renderDurationsMs: Distribution
+ eventToViewportMs: Distribution
+ eventToRenderEndMs: Distribution
+ zoomAnchorDriftPx: Distribution
+ maximumJumpPx: number
+ finalInputToCrispMs: number | null
+ scheduler: {
+ frameCount: number
+ maximumJobsPerFrame: number
+ maximumJobRenderMs: number
+ overBudgetJobs: number
+ maximumDeadlineOverrunMs: number
+ cancelledJobs: number
+ }
+ longTasks: { count: number; totalMs: number; maximumMs: number }
+ missedDisplayFrames: { over8Ms: number; over16Ms: number; over33Ms: number; over50Ms: number }
+ renderGaps: { over8Ms: number; over16Ms: number; over33Ms: number; over50Ms: number }
+}
+
+export interface Distribution {
+ count: number
+ min: number
+ median: number
+ p95: number
+ p99: number
+ max: number
+ mean: number
+}
diff --git a/tools/navigation-benchmark/tests/compare.test.ts b/tools/navigation-benchmark/tests/compare.test.ts
new file mode 100644
index 000000000..9d37e6e43
--- /dev/null
+++ b/tools/navigation-benchmark/tests/compare.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test'
+
+import { compareNavigationMetrics } from '../src/compare'
+import type { NavigationMetrics } from '../src/types'
+
+function metrics(displayP95: number, crispMs: number): NavigationMetrics {
+ const distribution = { count: 1, min: 1, median: 1, p95: displayP95, p99: 1, max: 1, mean: 1 }
+ return {
+ durationMs: 1,
+ eventCount: 1,
+ viewportUpdateCount: 1,
+ renderCount: 1,
+ displayFrameIntervalsMs: distribution,
+ renderFrameIntervalsMs: distribution,
+ renderDurationsMs: distribution,
+ eventToViewportMs: distribution,
+ eventToRenderEndMs: distribution,
+ zoomAnchorDriftPx: distribution,
+ maximumJumpPx: 1,
+ finalInputToCrispMs: crispMs,
+ scheduler: {
+ frameCount: 0,
+ maximumJobsPerFrame: 0,
+ maximumJobRenderMs: 0,
+ overBudgetJobs: 0,
+ maximumDeadlineOverrunMs: 0,
+ cancelledJobs: 0
+ },
+ longTasks: { count: 0, totalMs: 0, maximumMs: 0 },
+ missedDisplayFrames: { over8Ms: 0, over16Ms: 0, over33Ms: 0, over50Ms: 0 },
+ renderGaps: { over8Ms: 0, over16Ms: 0, over33Ms: 0, over50Ms: 0 }
+ }
+}
+
+describe('navigation benchmark comparison', () => {
+ test('reports absolute and relative candidate regressions', () => {
+ const comparison = compareNavigationMetrics(metrics(10, 40), metrics(15, 60))
+ expect(comparison.displayFrameP95Ms).toEqual({
+ baseline: 10,
+ candidate: 15,
+ delta: 5,
+ ratio: 1.5
+ })
+ expect(comparison.finalInputToCrispMs.ratio).toBe(1.5)
+ })
+})
diff --git a/tools/navigation-benchmark/tests/metrics.test.ts b/tools/navigation-benchmark/tests/metrics.test.ts
new file mode 100644
index 000000000..452c63aaf
--- /dev/null
+++ b/tools/navigation-benchmark/tests/metrics.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, test } from 'bun:test'
+
+import { computeNavigationMetrics, distribution } from '../src/metrics'
+import type { NavigationRecordingFile } from '../src/types'
+
+describe('navigation benchmark metrics', () => {
+ test('computes nearest-rank distributions', () => {
+ expect(distribution([1, 2, 3, 4, 100])).toEqual({
+ count: 5,
+ min: 1,
+ median: 3,
+ p95: 100,
+ p99: 100,
+ max: 100,
+ mean: 22
+ })
+ })
+
+ test('uses tiled coverage rather than fallback backing for tiled settlement', () => {
+ const recording: NavigationRecordingFile = {
+ schemaVersion: 1,
+ name: 'tiled',
+ source: 'synthetic',
+ recordedAt: '',
+ environment: {},
+ sceneRenderer: 'tiled',
+ initialViewport: { panX: 0, panY: 0, zoom: 1 },
+ wheel: [],
+ trace: [
+ { name: 'wheel:received', timestamp: 10, detail: {} },
+ { name: 'backing:crisp', timestamp: 20, detail: {} },
+ { name: 'tiles:coverage-complete', timestamp: 140, detail: {} }
+ ]
+ }
+
+ expect(computeNavigationMetrics(recording).finalInputToCrispMs).toBe(130)
+ })
+
+ test('correlates input, viewport, render, and crisp backing events', () => {
+ const recording: NavigationRecordingFile = {
+ schemaVersion: 1,
+ name: 'test',
+ source: 'synthetic',
+ recordedAt: '',
+ environment: {},
+ sceneRenderer: 'retained',
+ initialViewport: { panX: 0, panY: 0, zoom: 1 },
+ wheel: [
+ {
+ timeMs: 0,
+ deltaX: 0,
+ deltaY: -1,
+ deltaMode: 0,
+ ctrlKey: true,
+ metaKey: false,
+ shiftKey: false,
+ clientX: 100,
+ clientY: 100,
+ cancelable: true
+ }
+ ],
+ trace: [
+ { name: 'animation:frame', timestamp: 0, detail: {} },
+ { name: 'wheel:received', timestamp: 0, detail: {} },
+ {
+ name: 'viewport:changed',
+ timestamp: 4,
+ detail: {
+ panX: -10,
+ panY: -10,
+ zoom: 1.1,
+ previousPanX: 0,
+ previousPanY: 0,
+ previousZoom: 1
+ }
+ },
+ { name: 'render:start', timestamp: 6, detail: {} },
+ {
+ name: 'render:end',
+ timestamp: 10,
+ detail: { layer: 'scene', panX: -10, panY: -10, zoom: 1.1 }
+ },
+ { name: 'animation:frame', timestamp: 16, detail: {} },
+ { name: 'render:start', timestamp: 20, detail: {} },
+ {
+ name: 'render:end',
+ timestamp: 30,
+ detail: { layer: 'scene', panX: -12, panY: -10, zoom: 1.1 }
+ },
+ { name: 'animation:frame', timestamp: 32, detail: {} },
+ { name: 'main:long-task', timestamp: 33, detail: { durationMs: 60 } },
+ {
+ name: 'render:end',
+ timestamp: 35,
+ detail: {
+ layer: 'tiled-scheduler',
+ mandatoryCompleted: 0,
+ interruptibleCompleted: 4,
+ maximumJobRenderMs: 1.5,
+ overBudgetJobs: 0,
+ deadlineOverrunMs: 0,
+ cancelledJobs: 3
+ }
+ },
+ { name: 'backing:crisp', timestamp: 40, detail: {} }
+ ]
+ }
+
+ const metrics = computeNavigationMetrics(recording)
+ expect(metrics.eventToViewportMs.median).toBe(4)
+ expect(metrics.eventToRenderEndMs.median).toBe(10)
+ expect(metrics.renderDurationsMs.mean).toBe(7)
+ expect(metrics.renderFrameIntervalsMs.median).toBe(20)
+ expect(metrics.displayFrameIntervalsMs.median).toBe(16)
+ expect(metrics.longTasks).toEqual({ count: 1, totalMs: 60, maximumMs: 60 })
+ expect(metrics.zoomAnchorDriftPx.max).toBe(0)
+ expect(metrics.maximumJumpPx).toBe(2)
+ expect(metrics.finalInputToCrispMs).toBe(40)
+ expect(metrics.scheduler).toEqual({
+ frameCount: 1,
+ maximumJobsPerFrame: 4,
+ maximumJobRenderMs: 1.5,
+ overBudgetJobs: 0,
+ maximumDeadlineOverrunMs: 0,
+ cancelledJobs: 3
+ })
+ })
+})
diff --git a/tools/navigation-benchmark/tests/recording.test.ts b/tools/navigation-benchmark/tests/recording.test.ts
new file mode 100644
index 000000000..964a160fc
--- /dev/null
+++ b/tools/navigation-benchmark/tests/recording.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test'
+
+import { parseRecording } from '../src/recording'
+
+describe('navigation recording validation', () => {
+ test('rejects negative sample timestamps', () => {
+ expect(() =>
+ parseRecording({
+ schemaVersion: 1,
+ name: 'negative',
+ source: 'synthetic',
+ recordedAt: '',
+ environment: {},
+ initialViewport: { panX: 0, panY: 0, zoom: 1 },
+ trace: [],
+ wheel: [{ timeMs: -1, deltaX: 0, deltaY: 1, deltaMode: 0, clientX: 0, clientY: 0 }]
+ })
+ ).toThrow()
+ })
+
+ test('normalizes legacy schema-v1 renderer names', () => {
+ const recording = parseRecording({
+ schemaVersion: 1,
+ name: 'legacy',
+ source: 'synthetic',
+ recordedAt: '',
+ environment: {},
+ sceneRenderer: 'existing',
+ initialViewport: { panX: 0, panY: 0, zoom: 1 },
+ trace: [],
+ wheel: []
+ })
+
+ expect(recording.sceneRenderer).toBe('retained')
+ })
+
+ test('rejects unordered samples', () => {
+ expect(() =>
+ parseRecording({
+ schemaVersion: 1,
+ name: 'bad',
+ source: 'synthetic',
+ recordedAt: '',
+ environment: {},
+ sceneRenderer: 'retained',
+ initialViewport: { panX: 0, panY: 0, zoom: 1 },
+ trace: [],
+ wheel: [
+ { timeMs: 2, deltaX: 0, deltaY: 1, deltaMode: 0, clientX: 0, clientY: 0 },
+ { timeMs: 1, deltaX: 0, deltaY: 1, deltaMode: 0, clientX: 0, clientY: 0 }
+ ]
+ })
+ ).toThrow('ordered')
+ })
+})