Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
26631c1
refactor(canvas): centralize viewport lifecycle and framing (#11420)
christian-byrne Oct 2, 2026
a9fbc4b
fix(backport): detect visible fixed-position canvases
christian-byrne Oct 3, 2026
addca6b
fix(backport): fit the first subgraph visit on the next frame
christian-byrne Oct 3, 2026
9c7878a
fix(backport): give the canvas stubs a ds for the new viewport source
christian-byrne Oct 3, 2026
7cddcf2
fix(backport): separate a template load that never started from one t…
christian-byrne Oct 3, 2026
78d92b8
fix(backport): drop preview assertions this release line cannot satisfy
christian-byrne Oct 3, 2026
b045cbf
fix(backport): drop the HUD inset compensation this backport supersedes
christian-byrne Oct 3, 2026
b22e974
fix(backport): carry viewport fixture updates and drop orphaned load …
christian-byrne Oct 3, 2026
37cef73
fix: guard superseded loads before cleanup
christian-byrne Oct 3, 2026
dfb70ac
fix: ignore superseded load outcomes
christian-byrne Oct 3, 2026
0c4e60b
fix: stop superseded loads after awaits
christian-byrne Oct 3, 2026
cbac0a0
fix: compare pending camera workflow paths
christian-byrne Oct 3, 2026
74533b7
fix(canvas): make scheduler flush reentrant-safe
christian-byrne Oct 3, 2026
37c6859
fix(subgraph): refresh viewport before deferred fit
christian-byrne Oct 3, 2026
6df902d
fix: restore DPR scaling after viewport measurement
christian-byrne Oct 3, 2026
dbcacea
fix: preserve canvas CSS resize semantics
christian-byrne Oct 3, 2026
74fc5d9
fix: use canvas DPR for link hit testing
christian-byrne Oct 3, 2026
ed38df3
fix(backport): harden cached and constrained viewports
christian-byrne Oct 3, 2026
6e447bd
fix(backport): deduplicate viewport fixture imports
christian-byrne Oct 3, 2026
dee3b76
fix(backport): restore template education oracle
christian-byrne Oct 3, 2026
607b4bf
test(canvas): cover release viewport integration seams
christian-byrne Oct 3, 2026
f80b299
test(canvas): prove deferred saved camera restore
christian-byrne Oct 3, 2026
bf9a6c4
test(canvas): size the resize fixture off the expected result
christian-byrne Oct 3, 2026
62524b1
fix(backport): fence deferred subgraph fits by arrival
christian-byrne Oct 3, 2026
0f1e9ab
Merge branch 'core/1.54' into backport-11420-to-core-1.54
christian-byrne Oct 3, 2026
382be7d
Merge branch 'core/1.54' into backport-11420-to-core-1.54
christian-byrne Oct 3, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions browser_tests/fixtures/components/SidebarTab.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,8 @@ export class NodeLibrarySidebarTabV2 extends SidebarTab {
public readonly essentialsTab: Locator
public readonly sortButton: Locator
public readonly nodePreview: Locator
public readonly nodePreviewInputs: Locator
public readonly nodePreviewBody: Locator

constructor(public override readonly page: Page) {
super(page, 'node-library')
Expand All @@ -98,6 +100,12 @@ export class NodeLibrarySidebarTabV2 extends SidebarTab {
this.essentialsTab = this.getTab('Essentials')
this.sortButton = this.sidebarContent.getByRole('button', { name: 'Sort' })
this.nodePreview = page.getByTestId(TestIds.sidebar.nodePreviewCard)
this.nodePreviewInputs = this.nodePreview.getByTestId(
TestIds.sidebar.nodePreviewInputs
)
this.nodePreviewBody = this.nodePreview.getByTestId(
TestIds.sidebar.nodePreviewBody
)
}

getTab(name: string) {
Expand Down
15 changes: 15 additions & 0 deletions browser_tests/fixtures/helpers/CanvasHelper.ts
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,21 @@ export class CanvasHelper {
)
}

async getElementWidth(): Promise<number> {
return this.page.evaluate(() => window.app!.canvasEl.width)
}

async getVisibleNodeCount(): Promise<number> {
return this.page.evaluate(() => {
const { canvas } = window.app!
if (!canvas.graph) return 0
canvas.ds.computeVisibleArea(canvas.viewport)
return canvas.graph.nodes.filter((node) =>
canvas.ds.visible_area.overlaps(node.boundingRect)
).length
})
}

async waitForViewToSettle(): Promise<void> {
await this.page.waitForFunction(
() =>
Expand Down
14 changes: 14 additions & 0 deletions browser_tests/fixtures/helpers/TemplateHelper.ts
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,20 @@ export class TemplateHelper {
)
}

/** Serves in-memory workflow data as the named template's graph. */
async mockWorkflowData(name: string, workflow: unknown): Promise<void> {
await this.page.route(`**/templates/${name}.json`, (route) =>
route.fulfill({
status: 200,
body: JSON.stringify(workflow),
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'no-store'
}
})
)
}

/** Opens the template browser and loads the named template. */
async load(name: string): Promise<void> {
await this.page.evaluate(() => {
Expand Down
2 changes: 2 additions & 0 deletions browser_tests/fixtures/selectors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ export const TestIds = {
nodeLibrary: 'node-library-tree',
nodeLibrarySearch: 'node-library-search',
nodePreviewCard: 'node-preview-card',
nodePreviewInputs: 'node-preview-inputs',
nodePreviewBody: 'node-preview-body',
workflows: 'workflows-sidebar',
workflowsRefreshButton: 'workflows-refresh-button',
modeToggle: 'mode-toggle',
Expand Down
22 changes: 22 additions & 0 deletions browser_tests/fixtures/utils/appModeTemplate.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
import { makeTemplate } from '@e2e/fixtures/data/templateFixtures'
import { withTemplates } from '@e2e/fixtures/helpers/TemplateHelper'
import type { TemplateHelper } from '@e2e/fixtures/helpers/TemplateHelper'
import linearBasicApp from '@e2e/assets/linear-basic-app-1.json' with { type: 'json' }

export const APP_MODE_TEMPLATE = 'viewport-app-template'

export async function mockAppModeTemplate(
templates: TemplateHelper
): Promise<void> {
templates.configure(
withTemplates([
makeTemplate({ name: APP_MODE_TEMPLATE, title: 'App Template' })
])
)
await templates.mock()
const appModeWorkflow = {
...structuredClone(linearBasicApp),
extra: { ...linearBasicApp.extra, linearMode: true }
}
await templates.mockWorkflowData(APP_MODE_TEMPLATE, appModeWorkflow)
}
46 changes: 46 additions & 0 deletions browser_tests/tests/appModeTemplateViewport.product.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import { mergeTests } from '@playwright/test'

import {
comfyExpect as expect,
comfyPageFixture
} from '@e2e/fixtures/ComfyPage'
import { templateApiFixture } from '@e2e/fixtures/templateApiFixture'
import {
APP_MODE_TEMPLATE,
mockAppModeTemplate
} from '@e2e/fixtures/utils/appModeTemplate'

const test = mergeTests(comfyPageFixture, templateApiFixture)

test.describe('App mode template viewport', { tag: ['@canvas'] }, () => {
test('frames a template after the hidden canvas becomes visible', async ({
comfyPage,
templateApi
}) => {
const { appMode, canvasOps, workflow } = comfyPage
await mockAppModeTemplate(templateApi)

await test.step('hide the canvas in app mode', async () => {
await appMode.enterAppModeWithInputs([['3', 'seed']])
await expect(appMode.centerPanel).toBeVisible()
await expect.poll(() => canvasOps.getElementWidth()).toBe(0)
})

await test.step('load the template through the template browser path', async () => {
await templateApi.load(APP_MODE_TEMPLATE)
await expect
.poll(() => workflow.getActiveWorkflowPath())
.toContain(APP_MODE_TEMPLATE)
await workflow.waitForWorkflowIdle()
await expect.poll(() => canvasOps.getElementWidth()).toBe(0)
})

await test.step('show the canvas and apply the queued camera', async () => {
await appMode.toggleAppMode()
await expect.poll(() => canvasOps.getElementWidth()).toBeGreaterThan(0)
await canvasOps.waitForViewToSettle()

expect(await canvasOps.getVisibleNodeCount()).toBe(7)
})
})
})
77 changes: 37 additions & 40 deletions browser_tests/tests/interaction.spec.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import type { Locator } from '@playwright/test'
import { expect } from '@playwright/test'
import type { Position } from '@vueuse/core'

Expand Down Expand Up @@ -1083,58 +1082,56 @@ test.describe('Viewport settings', () => {
offset: await comfyPage.canvasOps.getOffset()
})

const changeTab = async (tab: Locator) => {
await tab.click()
await comfyPage.nextFrame()
const changeTab = async (workflowName: string) => {
await comfyPage.menu.topbar.getWorkflowTab(workflowName).click()
await expect
.poll(() => comfyPage.workflow.getActiveWorkflowPath())
.toBe(`workflows/${workflowName}.json`)
await comfyPage.canvasOps.waitForViewToSettle()
await comfyMouse.move(DefaultGraphPositions.emptySpace)

// If tooltip is visible, wait for it to hide
await expect(
comfyPage.page.locator('.workflow-popover-fade')
).toHaveCount(0)
}

// Screenshot the canvas element
await comfyPage.settings.setSetting('Comfy.Graph.CanvasMenu', true)

const toggleButton = comfyPage.page.getByTestId(
TestIds.canvas.toggleMinimapButton
)
await toggleButton.click()
await comfyPage.settings.setSetting('Comfy.Graph.CanvasMenu', false)

await comfyPage.menu.topbar.saveWorkflow('Workflow A')
await comfyPage.nextFrame()

// Save workflow as a new file, then zoom out before screen shot
await comfyPage.menu.topbar.saveWorkflowAs('Workflow B')

await comfyPage.nextFrame()
const tabA = comfyPage.menu.topbar.getWorkflowTab('Workflow A')
await changeTab(tabA)

const viewportA = await getViewport()
await test.step('Save two workflow tabs', async () => {
await comfyPage.settings.setSetting('Comfy.Graph.CanvasMenu', true)
await comfyPage.page
.getByTestId(TestIds.canvas.toggleMinimapButton)
.click()
await comfyPage.settings.setSetting('Comfy.Graph.CanvasMenu', false)

const tabB = comfyPage.menu.topbar.getWorkflowTab('Workflow B')
await changeTab(tabB)
await comfyPage.menu.topbar.saveWorkflow('Workflow A')
await comfyPage.nextFrame()
await comfyPage.menu.topbar.saveWorkflowAs('Workflow B')
await comfyPage.nextFrame()
})

await comfyMouse.move(DefaultGraphPositions.emptySpace)
for (let i = 0; i < 4; i++) {
await comfyMouse.wheel(0, 60)
}
const { viewportA, viewportB } =
await test.step('Give each workflow a distinct viewport', async () => {
await changeTab('Workflow A')
const viewportA = await getViewport()

await comfyPage.nextFrame()
const viewportB = await getViewport()
await changeTab('Workflow B')
await comfyMouse.wheel(0, 60)
await expect.poll(getViewport).not.toEqual(viewportA)
await comfyPage.canvasOps.waitForViewToSettle()

expect(viewportB).not.toEqual(viewportA)
const viewportB = await getViewport()
expect(viewportB).not.toEqual(viewportA)
return { viewportA, viewportB }
})

// Go back to Workflow A
await changeTab(tabA)
await expect.poll(getViewport).toEqual(viewportA)
await test.step('Restore Workflow A viewport', async () => {
await changeTab('Workflow A')
await expect.poll(getViewport).toEqual(viewportA)
})

// And back to Workflow B
await changeTab(tabB)
await expect.poll(getViewport).toEqual(viewportB)
await test.step('Restore Workflow B viewport', async () => {
await changeTab('Workflow B')
await expect.poll(getViewport).toEqual(viewportB)
})
})
})

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 6 additions & 1 deletion browser_tests/tests/sidebar/blueprintDynamicCombo.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,16 @@ test.describe('Blueprint dynamic combo preview', { tag: '@ui' }, () => {
await tab.getNode('Dynamic combo blueprint').hover()
await expect(tab.nodePreview).toBeVisible()
await expect(
tab.nodePreview.getByText('boundary_model', { exact: true })
tab.nodePreviewInputs.getByText('boundary_model', { exact: true })
).toBeVisible()
await expect(
tab.nodePreview.getByText('COMFY_DYNAMICCOMBO_V3', { exact: true })
).toBeVisible()
await expect(tab.nodePreviewBody).toBeVisible()
// The preview body renders a COMBO widget for a COMFY_DYNAMICCOMBO_V3
// input only where `dynamicComboOptionKeys` exists, which arrived on main
// after this release line branched and is not part of #11420. Asserting
// that widget here would pin a capability 1.54 does not ship.
expect(await comfyPage.page.pageErrors()).toEqual([])
})
})
82 changes: 82 additions & 0 deletions docs/adr/CANVAS-VIEWPORT-0009-canvas-viewport-system.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# ADR-CANVAS-VIEWPORT-0009: Canvas Viewport System

Date: 2026-09-28

## Status

Proposed

## Context

LGraphCanvas uses a dual-canvas architecture: a foreground canvas (the DOM element) renders nodes, and a background canvas (offscreen) renders the grid, links, and groups. `drawFrontCanvas()` composites the background onto the foreground by dividing the background canvas dimensions by `devicePixelRatio` — assuming both canvases were DPR-scaled. `drawBackCanvas()` reinforces this assumption by applying `ctx.setTransform(scale, 0, 0, scale, 0, 0)` using DPR. Both canvases must have identical physical (DPR-scaled) dimensions for compositing to produce correct results.

Two independent resize paths exist today:

- **`resizeCanvas()` in app.ts** is DPR-aware for the foreground canvas: it multiplies CSS pixels by `devicePixelRatio` to set that canvas's physical dimensions and scales its context. The background canvas is sized and transformed later by `drawBackCanvas()`.
- **`LGraphCanvas.resize()`** is DPR-unaware: it sets both canvases to CSS pixel dimensions directly, producing canvases at 1× regardless of display density.

Neither path documents that it depends on the other, creating implicit temporal coupling. Code that calls one without the other produces a background/foreground size mismatch.

The original bug: when switching from app mode (canvas hidden via `v-show`) to graph mode, `resize()` was called to force dimensions onto the newly-visible canvas. Because `resize()` is DPR-unaware, the background canvas received CSS pixel dimensions while `drawFrontCanvas()` divided those dimensions by DPR (expecting physical pixels), producing a scaled-down composite. This change introduces a canvas scheduler (`useCanvasScheduler`) to solve the hidden-canvas lifecycle problem by deferring work until the canvas is visible, together with the viewport system to remove the DPR mismatch when that work runs.

`window.devicePixelRatio` is read at 6+ call sites across LGraphCanvas (`drawFrontCanvas`, `drawBackCanvas`, `centerOnNode`, `renderInfo`, `processMouseDown` hit testing, font scaling) and 3+ call sites in app.ts/renderer code. Each reads independently with no shared source of truth, so any change to DPR handling requires auditing every call site.

## Decision

Introduce a `CanvasViewport` — a plain, frozen snapshot of the dimensions and DPR used for one canvas-sizing operation:

```ts
interface CanvasViewport {
readonly cssWidth: number
readonly cssHeight: number
readonly dpr: number
readonly physicalWidth: number // cssWidth * dpr
readonly physicalHeight: number // cssHeight * dpr
}
```

Viewport measurement normalizes every finite positive DPR to at least `1`, preserving at least one backing pixel per CSS pixel so browser zoom values below `1` do not blur the canvas. Physical dimensions use this normalized DPR rather than the raw browser value.

Two functions operate on this type:

- **`measureViewport(cssWidth, cssHeight, rawDpr)`** — a pure function that produces a new `CanvasViewport` from numeric dimensions and DPR. `measureViewportFromElement(element, rawDpr?)` is the DOM adapter used by canvas lifecycle code.
- **`applyViewport(viewport, fgCanvas, bgCanvas, consumer?)`** — a side-effecting function that atomically sizes both foreground and background canvases to the viewport's physical dimensions, scales their 2D contexts, and updates an optional viewport consumer such as `LGraphCanvas` with both the applied DPR and CSS dimensions. Both canvases and the consumer are updated in a single call, eliminating the possibility of a partial resize or a later layout read to recover the CSS size.

The existing `LGraphCanvas.resize()` method and `resizeCanvas()` in app.ts both delegate their sizing work to the viewport system. Both paths follow the same sequence: measure → apply → draw.

`LGraphCanvas` caches the active DPR in its `dpr` property. `applyViewport()` updates the consumer's DPR and CSS viewport size atomically; the three viewport callers pass `LGraphCanvas` as that consumer. Most internal consumers (`drawFrontCanvas`, `drawBackCanvas`, `centerOnNode`, `renderInfo`, `processMouseDown` hit testing, and LOD threshold calculation) read the cache. Direct browser-DPR readers remain in `LGraphCanvas.setCanvas()`, `LGraphCanvas.resize()` during measurement, `DragAndScale.getViewportSize()`, and `useBoundingBoxes`; viewport measurement functions also read the browser value, while `layoutStore` retains a browser fallback for legacy callers. The viewport system therefore coordinates canvas sizing but does not yet own a single DPR read boundary.

The new `CanvasScheduler` and viewport system have separate responsibilities: the scheduler handles **when** by queuing work while the canvas is hidden and flushing it from `resizeCanvas()` once the canvas ResizeObserver applies a visible viewport, while the viewport handles **what** by applying correct DPR-scaled dimensions atomically to both canvases.

### Design Principles

Following the principles established in [ADR-ECS-0008](ECS-0008-entity-component-system.md):

- `CanvasViewport` is a **plain data component** — no methods, no back-references, frozen after creation.
- `measureViewport` is a **pure system function** — testable without DOM (accepts dimension inputs).
- `applyViewport` is a **side-effecting system** — testable with mock canvas objects.
- No methods are added to `LGraphCanvas` or any other entity class.

### Alternatives Considered

1. **Reactive derivation (Vue `computed`)** — rejected because it would require Vue reactivity inside litegraph internals, crossing a hard architectural boundary between the Vue application layer and the litegraph rendering layer.
2. **Transaction/batch-commit pattern** — rejected as overkill for a single async boundary (the hidden canvas becoming visible). The measure/apply split achieves the same atomicity guarantee with less machinery.
3. **Just fixing `resizeCanvas()` to also update bgcanvas** — rejected because it doesn't address the scattered DPR reads or prevent future divergence. A point fix solves today's bug but leaves the same class of bug latent at every other DPR read site.

## Consequences

### Positive

- Applying one viewport snapshot to both canvases eliminates an entire class of sizing bugs where foreground and background canvases diverge.
- Phase separation (measure vs apply) makes the resize lifecycle explicit and testable.
- Pure functions (`measureViewport`) are trivially testable without DOM fixtures.
- Separates hidden-canvas scheduling from the dimensions and transforms applied when scheduled work runs.

### Negative

- Adds a new abstraction layer that all canvas-sizing code must flow through.
- `LGraphCanvas.setCanvas()`, `LGraphCanvas.resize()`, `DragAndScale.getViewportSize()`, and `useBoundingBoxes` still read `window.devicePixelRatio` directly. `layoutStore` accepts a caller-supplied `dpr` and falls back to the browser value for legacy callers. A future refactor could consolidate these reads behind one boundary.

## Notes

- References [ADR-ECS-0008](ECS-0008-entity-component-system.md) for the design principles (plain data components, pure system functions, no methods on entities).
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ An Architecture Decision Record captures an important architectural decision mad
| [AUTH-BILLING-0014](AUTH-BILLING-0014-billing-attempt-context-and-workspace-scope.md) | Billing Attempt Context and Workspace Scope | Proposed | 2026-07-28 |
| [AUTH-CREDENTIALS-0011](AUTH-CREDENTIALS-0011-cloud-credential-lifecycle-invariants.md) | Cloud Credential Lifecycle Invariants | Proposed | 2026-07-09 |
| [BILLING-CHECKOUT-0031](BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md) | Checkout Journey Instrumentation Contract | Proposed | 2026-09-09 |
| [CANVAS-VIEWPORT-0009](CANVAS-VIEWPORT-0009-canvas-viewport-system.md) | Canvas Viewport System | Proposed | 2026-09-28 |
| [CRDT-AUTHORITY-0035](CRDT-AUTHORITY-0035-human-canvas-authority-and-draft-reconciliation.md) | Human Canvas Authority and Draft Reconciliation | Proposed | 2026-09-19 |
| [CRDT-FOLLOWER-0025](CRDT-FOLLOWER-0025-in-app-agent-crdt-follower-and-distribution-resolved-boundaries.md) | In-App Agent CRDT Follower and Distribution-Resolved Boundaries | Proposed | 2026-08-21 |
| [CRDT-INPUTS-0030](CRDT-INPUTS-0030-preserve-named-input-targets.md) | Project Document Inputs onto Reordered Live Nodes by Name | Proposed | 2026-09-09 |
Expand Down
1 change: 1 addition & 0 deletions src/components/node/NodePreviewCard.vue
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@
<div
v-if="inputs.length > 0 && showInputsAndOutputs"
class="flex flex-col gap-1"
data-testid="node-preview-inputs"
>
<h4
class="m-0 text-2xs font-semibold tracking-wide text-muted-foreground uppercase"
Expand Down
5 changes: 5 additions & 0 deletions src/components/rightSidePanel/errors/ErrorGroupList.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { useMissingModelStore } from '@/platform/missingModel/missingModelStore'
import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
import { app } from '@/scripts/app'
import { useExecutionErrorStore } from '@/stores/executionErrorStore'
import { createTestDragAndScale } from '@/utils/__tests__/canvasTestUtils'
import { isLGraphNode } from '@/utils/litegraphUtil'
import { getNodeByExecutionId } from '@/utils/graphTraversalUtil'
import { Rectangle } from '@/lib/litegraph/src/infrastructure/Rectangle'
Expand Down Expand Up @@ -156,6 +157,10 @@ function createCanvasFixture(pinia: Pinia, graph = ROOT_GRAPH) {
read_only: false,
subgraph: undefined,
canvas: canvasElement,
// Focus framing reads the applied CSS viewport off `ds`, so the fixture
// needs a `DragAndScale` matching the element's 900x700 viewport.
dpr: 1,
ds: createTestDragAndScale(900, 700),
animateToBounds: vi.fn()
})
canvas.setGraph = vi.fn((nextGraph) => {
Expand Down
3 changes: 1 addition & 2 deletions src/components/sidebar/SideToolbar.vue
Original file line number Diff line number Diff line change
Expand Up @@ -269,11 +269,10 @@ onMounted(() => {
await nextTick()
const sidebarRight =
sideToolbarRef.value?.getBoundingClientRect()?.right
// The release line's renderInfo keeps a 5px text inset that main removed; drop the - 5 when that litegraph change lands here.
canvasStore.canvas.fpsInfoLocation = [
sidebarRight === undefined
? undefined
: sidebarRight + canvasGutter() - 5,
: sidebarRight + canvasGutter(),
null
]
} else {
Expand Down
Loading
Loading