fix: remove broken throttle from VirtualGrid scroll tracking (#12781)

## Summary

Every `VirtualGrid` consumer (assets sidebar, manager dialog, widget
select dropdown) is blind to discrete mouse-wheel scrolling:
`useScroll`'s `throttle: 64` never reports scroll position, so the
virtualization window stays frozen — users see blank space below the
first viewport of items and `approach-end` (infinite scroll) never
fires. Trackpad scrolling masks the bug by emitting events faster than
the throttle window.

## Changes

- **What**: drop the `throttle` option from `useScroll` in `VirtualGrid`
and remove the `scrollThrottle` prop (no consumer passes it). Scroll
events are frame-aligned and the handler is cheap, so the throttle
bought nothing even when it worked.
- **Root cause**: VueUse ≥14 `throttleFilter` with `leading=false` (what
`useScroll` uses) marks spaced-out events as executed without executing
them — each event re-arms an `isLeading` restore timer that makes the
next event skip its invoke, and the trailing branch is unreachable when
`elapsed > duration`. Regression of vueuse#2390; still present on vueuse
`main`.

## Review Focus

- Verified live against staging: with the throttle, sidebar scrolled to
`scrollTop` 1250 while `scrollY` stayed 0 and the render window stayed
at `[0..3)` of 27 (blank viewport); with this fix, `scrollY` tracks 1:1
and the window advances. Bare-vs-throttled `useScroll` compared
side-by-side on the same element to isolate the cause.
- Unblocks wheel-scroll for #12780's dropdown infinite scroll with no
changes there.

- Fixes FE-990

🤖 Generated with [Claude Code](https://claude.com/claude-code)

apps/website/public/site.webmanifest

@@ -1,23 +1,23 @@
 {
   "name": "Comfy",
   "short_name": "Comfy",
-  "id": "/",
-  "start_url": "/",
   "icons": [
     {
       "src": "/web-app-manifest-192x192.png",
       "sizes": "192x192",
       "type": "image/png",
-      "purpose": "any"
+      "purpose": "any maskable"
     },
     {
       "src": "/web-app-manifest-512x512.png",
       "sizes": "512x512",
       "type": "image/png",
-      "purpose": "any"
+      "purpose": "any maskable"
     }
   ],
   "theme_color": "#211927",
   "background_color": "#211927",
-  "display": "standalone"
+  "display": "standalone",
+  "id": "/",
+  "start_url": "/"
 }

apps/website/src/components/product/local/DownloadLocalButton.vue

@@ -8,6 +8,7 @@ import {
   useDownloadUrl
 } from '../../../composables/useDownloadUrl'
 import { t } from '../../../i18n/translations'
+import { captureDownloadClick } from '../../../scripts/posthog'
 import BrandButton from '../../common/BrandButton.vue'
 
 const { locale = 'en', class: customClass = '' } = defineProps<{
@@ -69,6 +70,7 @@ const buttons = computed<ButtonSpec[]>(() => {
     size="lg"
     :class="customClass"
     :aria-label="btn.ariaLabel"
+    @click="captureDownloadClick(btn.key)"
   >
     <span class="inline-flex items-center gap-2">
       <img

apps/website/src/layouts/BaseLayout.astro

@@ -73,7 +73,7 @@ const websiteJsonLd = {
 
     <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <link rel="shortcut icon" href="/favicon.ico" />
+    <link rel="shortcut icon" href="/favicon.ico" sizes="48x48" />
     <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
     <link rel="manifest" href="/site.webmanifest" />
     <meta name="theme-color" content="#211927" />

apps/website/src/scripts/posthog.test.ts

@@ -53,3 +53,28 @@ describe('initPostHog', () => {
     expect(result.$set_once).toHaveProperty('plan', 'free')
   })
 })
+
+describe('captureDownloadClick', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.resetModules()
+  })
+
+  it('captures the download event with the platform', async () => {
+    const { initPostHog, captureDownloadClick } = await import('./posthog')
+    initPostHog()
+    captureDownloadClick('mac')
+
+    expect(hoisted.mockCapture).toHaveBeenCalledWith(
+      'website:download_button_clicked',
+      { platform: 'mac' }
+    )
+  })
+
+  it('does not capture before PostHog is initialized', async () => {
+    const { captureDownloadClick } = await import('./posthog')
+    captureDownloadClick('windows')
+
+    expect(hoisted.mockCapture).not.toHaveBeenCalled()
+  })
+})

apps/website/src/scripts/posthog.ts

@@ -38,3 +38,12 @@ export function capturePageview() {
     console.error('PostHog pageview capture failed', error)
   }
 }
+
+export function captureDownloadClick(platform: string) {
+  if (!initialized) return
+  try {
+    posthog.capture('website:download_button_clicked', { platform })
+  } catch (error) {
+    console.error('PostHog download click capture failed', error)
+  }
+}

packages/shared-frontend-utils/src/formatUtil.test.ts

@@ -111,6 +111,7 @@ describe('formatUtil', () => {
         expect(getMediaTypeFromFilename('scene.fbx')).toBe('3D')
         expect(getMediaTypeFromFilename('asset.gltf')).toBe('3D')
         expect(getMediaTypeFromFilename('binary.glb')).toBe('3D')
+        expect(getMediaTypeFromFilename('print.stl')).toBe('3D')
         expect(getMediaTypeFromFilename('apple.usdz')).toBe('3D')
         expect(getMediaTypeFromFilename('scan.ply')).toBe('3D')
       })

packages/shared-frontend-utils/src/formatUtil.ts

@@ -591,7 +591,15 @@ const IMAGE_EXTENSIONS = [
 ] as const
 const VIDEO_EXTENSIONS = ['mp4', 'm4v', 'webm', 'mov', 'avi', 'mkv'] as const
 const AUDIO_EXTENSIONS = ['mp3', 'wav', 'ogg', 'flac'] as const
-const THREE_D_EXTENSIONS = ['obj', 'fbx', 'gltf', 'glb', 'usdz', 'ply'] as const
+const THREE_D_EXTENSIONS = [
+  'obj',
+  'fbx',
+  'gltf',
+  'glb',
+  'stl',
+  'usdz',
+  'ply'
+] as const
 const TEXT_EXTENSIONS = [
   'txt',
   'md',

src/components/common/VirtualGrid.vue

@@ -33,7 +33,6 @@ const {
   items,
   gridStyle,
   bufferRows = 1,
-  scrollThrottle = 64,
   resizeDebounce = 64,
   defaultItemHeight = 200,
   defaultItemWidth = 200,
@@ -42,7 +41,6 @@ const {
   items: (T & { key: string })[]
   gridStyle: CSSProperties
   bufferRows?: number
-  scrollThrottle?: number
   resizeDebounce?: number
   defaultItemHeight?: number
   defaultItemWidth?: number
@@ -61,7 +59,6 @@ const itemWidth = ref(defaultItemWidth)
 const container = ref<HTMLElement | null>(null)
 const { width, height } = useElementSize(container)
 const { y: scrollY } = useScroll(container, {
-  throttle: scrollThrottle,
   eventListenerOptions: { passive: true }
 })
 

src/components/load3d/Load3D.vue

@@ -23,6 +23,8 @@
         :can-use-gizmo="canUseGizmo"
         :can-use-lighting="canUseLighting"
         :can-export="canExport"
+        :can-use-hdri="canUseHdri"
+        :can-use-background-image="canUseBackgroundImage"
         :material-modes="materialModes"
         :has-skeleton="hasSkeleton"
         @update-background-image="handleBackgroundImageUpdate"
@@ -86,7 +88,7 @@
       />
 
       <RecordingControls
-        v-if="!isPreview"
+        v-if="canUseRecording && !isPreview"
         v-model:is-recording="isRecording"
         v-model:has-recording="hasRecording"
         v-model:recording-duration="recordingDuration"
@@ -117,9 +119,18 @@ import { resolveNode } from '@/utils/litegraphUtil'
 import type { ComponentWidget } from '@/scripts/domWidget'
 import type { SimplifiedWidget } from '@/types/simplifiedWidget'
 
-const props = defineProps<{
+const {
+  widget,
+  nodeId,
+  canUseRecording = true,
+  canUseHdri = true,
+  canUseBackgroundImage = true
+} = defineProps<{
   widget: ComponentWidget<string[]> | SimplifiedWidget
   nodeId?: NodeId
+  canUseRecording?: boolean
+  canUseHdri?: boolean
+  canUseBackgroundImage?: boolean
 }>()
 
 function isComponentWidget(
@@ -130,11 +141,11 @@ function isComponentWidget(
 
 const node = ref<LGraphNode | null>(null)
 
-if (isComponentWidget(props.widget)) {
-  node.value = props.widget.node
-} else if (props.nodeId) {
+if (isComponentWidget(widget)) {
+  node.value = widget.node
+} else if (nodeId) {
   onMounted(() => {
-    node.value = resolveNode(props.nodeId!) ?? null
+    node.value = resolveNode(nodeId) ?? null
   })
 }
 

src/components/load3d/Load3DAdvanced.test.ts

@@ -0,0 +1,47 @@
+import { render } from '@testing-library/vue'
+import { describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, ref } from 'vue'
+
+const lastProps = ref<Record<string, unknown> | null>(null)
+
+vi.mock('@/components/load3d/Load3D.vue', () => ({
+  default: defineComponent({
+    name: 'Load3D',
+    props: {
+      widget: { type: null, required: false, default: undefined },
+      nodeId: { type: null, required: false, default: undefined },
+      canUseRecording: { type: Boolean, default: true },
+      canUseHdri: { type: Boolean, default: true },
+      canUseBackgroundImage: { type: Boolean, default: true }
+    },
+    setup(props: Record<string, unknown>) {
+      lastProps.value = { ...props }
+      return () => h('div', { 'data-testid': 'load3d-stub' })
+    }
+  })
+}))
+
+import Load3DAdvanced from '@/components/load3d/Load3DAdvanced.vue'
+
+describe('Load3DAdvanced', () => {
+  it('renders the inner Load3D with all expressive features disabled', () => {
+    const MOCK_NODE = { id: 'node', type: 'Load3DAdvanced' }
+    render(Load3DAdvanced, {
+      props: {
+        widget: { node: MOCK_NODE } as never
+      }
+    })
+    expect(lastProps.value).toMatchObject({
+      canUseRecording: false,
+      canUseHdri: false,
+      canUseBackgroundImage: false
+    })
+  })
+
+  it('forwards widget and nodeId to the inner Load3D', () => {
+    const widget = { node: { id: 'a', type: 'Load3DAdvanced' } }
+    render(Load3DAdvanced, { props: { widget: widget as never, nodeId: 'a' } })
+    expect(lastProps.value?.widget).toEqual(widget)
+    expect(lastProps.value?.nodeId).toBe('a')
+  })
+})

src/components/load3d/Load3DAdvanced.vue

@@ -0,0 +1,21 @@
+<template>
+  <Load3D
+    :widget="widget"
+    :node-id="nodeId"
+    :can-use-recording="false"
+    :can-use-hdri="false"
+    :can-use-background-image="false"
+  />
+</template>
+
+<script setup lang="ts">
+import Load3D from '@/components/load3d/Load3D.vue'
+import type { NodeId } from '@/platform/workflow/validation/schemas/workflowSchema'
+import type { ComponentWidget } from '@/scripts/domWidget'
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+
+defineProps<{
+  widget: ComponentWidget<string[]> | SimplifiedWidget
+  nodeId?: NodeId
+}>()
+</script>

src/components/load3d/Load3DControls.vue

@@ -52,6 +52,7 @@
         v-model:background-image="sceneConfig!.backgroundImage"
         v-model:background-render-mode="sceneConfig!.backgroundRenderMode"
         v-model:fov="cameraConfig!.fov"
+        :show-background-image="canUseBackgroundImage"
         :hdri-active="
           !!lightConfig?.hdri?.hdriPath && !!lightConfig?.hdri?.enabled
         "
@@ -81,6 +82,7 @@
         />
 
         <HDRIControls
+          v-if="canUseHdri"
           v-model:hdri-config="lightConfig!.hdri"
           :has-background-image="!!sceneConfig?.backgroundImage"
           @update-hdri-file="handleHDRIFileUpdate"
@@ -129,12 +131,16 @@ const {
   canUseGizmo = true,
   canUseLighting = true,
   canExport = true,
+  canUseHdri = true,
+  canUseBackgroundImage = true,
   materialModes = ['original', 'normal', 'wireframe'],
   hasSkeleton = false
 } = defineProps<{
   canUseGizmo?: boolean
   canUseLighting?: boolean
   canExport?: boolean
+  canUseHdri?: boolean
+  canUseBackgroundImage?: boolean
   materialModes?: readonly MaterialMode[]
   hasSkeleton?: boolean
 }>()

src/components/load3d/controls/SceneControls.vue

@@ -37,7 +37,7 @@
         </Button>
       </div>
 
-      <div v-if="!hasBackgroundImage">
+      <div v-if="showBackgroundImage && !hasBackgroundImage">
         <Button
           v-tooltip.right="{
             value: $t('load3d.uploadBackgroundImage'),
@@ -61,7 +61,7 @@
       </div>
     </template>
 
-    <div v-if="hasBackgroundImage">
+    <div v-if="showBackgroundImage && hasBackgroundImage">
       <Button
         v-tooltip.right="{
           value: $t('load3d.panoramaMode'),
@@ -83,12 +83,16 @@
     </div>
 
     <PopupSlider
-      v-if="hasBackgroundImage && backgroundRenderMode === 'panorama'"
+      v-if="
+        showBackgroundImage &&
+        hasBackgroundImage &&
+        backgroundRenderMode === 'panorama'
+      "
       v-model="fov"
       :tooltip-text="$t('load3d.fov')"
     />
 
-    <div v-if="hasBackgroundImage">
+    <div v-if="showBackgroundImage && hasBackgroundImage">
       <Button
         v-tooltip.right="{
           value: $t('load3d.removeBackgroundImage'),
@@ -114,8 +118,9 @@ import Button from '@/components/ui/button/Button.vue'
 import type { BackgroundRenderModeType } from '@/extensions/core/load3d/interfaces'
 import { cn } from '@comfyorg/tailwind-utils'
 
-const { hdriActive = false } = defineProps<{
+const { hdriActive = false, showBackgroundImage = true } = defineProps<{
   hdriActive?: boolean
+  showBackgroundImage?: boolean
 }>()
 
 const emit = defineEmits<{

src/extensions/core/load3d.ts

@@ -22,6 +22,7 @@ import {
   LOAD3D_NONE_MODEL,
   SUPPORTED_EXTENSIONS_ACCEPT
 } from '@/extensions/core/load3d/constants'
+import { snapshotLoad3dState } from '@/extensions/core/load3d/load3dSerialize'
 import Load3dUtils from '@/extensions/core/load3d/Load3dUtils'
 import { t } from '@/i18n'
 import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
@@ -413,16 +414,10 @@ useExtensionService().registerExtension({
             if (cached) return cached
           }
 
-          const cameraConfig: CameraConfig = (node.properties[
-            'Camera Config'
-          ] as CameraConfig | undefined) || {
-            cameraType: currentLoad3d.getCurrentCameraType(),
-            fov: currentLoad3d.cameraManager.perspectiveCamera.fov
-          }
-          cameraConfig.state = currentLoad3d.getCameraState()
-          node.properties['Camera Config'] = cameraConfig
-
-          currentLoad3d.stopRecording()
+          const { camera_info, model_3d_info } = snapshotLoad3dState(
+            node,
+            currentLoad3d
+          )
 
           const {
             scene: imageData,
@@ -441,16 +436,11 @@ useExtensionService().registerExtension({
 
           currentLoad3d.handleResize()
 
-          const modelInfo = currentLoad3d.getModelInfo()
-          const model_3d_info: Model3DInfo = modelInfo ? [modelInfo] : []
-
           const returnVal: Load3dCachedOutput = {
             image: `threed/${data.name} [temp]`,
             mask: `threed/${dataMask.name} [temp]`,
             normal: `threed/${dataNormal.name} [temp]`,
-            camera_info:
-              (node.properties['Camera Config'] as CameraConfig | undefined)
-                ?.state || null,
+            camera_info,
             recording: '',
             model_3d_info
           }

src/extensions/core/load3d/MeshModelAdapter.test.ts

@@ -23,6 +23,7 @@ const mtlLoaderStub = {
 const objLoaderStub = {
   setWorkerUrl: vi.fn(),
   setMaterials: vi.fn(),
+  setBaseObject3d: vi.fn(),
   loadAsync: vi.fn<(url: string) => Promise<THREE.Object3D>>()
 }
 
@@ -58,6 +59,7 @@ vi.mock('wwobjloader2', () => ({
   OBJLoader2Parallel: class {
     setWorkerUrl = objLoaderStub.setWorkerUrl
     setMaterials = objLoaderStub.setMaterials
+    setBaseObject3d = objLoaderStub.setBaseObject3d
     loadAsync = objLoaderStub.loadAsync
   },
   MtlObjBridge: {
@@ -247,6 +249,24 @@ describe('MeshModelAdapter', () => {
 
       expect(ctx.registerOriginalMaterial).toHaveBeenCalledTimes(1)
     })
+
+    it('resets baseObject3d on every load so meshes do not accumulate across calls', async () => {
+      objLoaderStub.loadAsync.mockResolvedValue(makeFbxLikeGroup())
+
+      const adapter = new MeshModelAdapter()
+      const ctx = makeContext('wireframe')
+      await adapter.load(ctx, '/api/view/', 'first.obj')
+      await adapter.load(ctx, '/api/view/', 'second.obj')
+
+      expect(objLoaderStub.setBaseObject3d).toHaveBeenCalledTimes(2)
+      const bases = objLoaderStub.setBaseObject3d.mock.calls.map(
+        ([base]) => base
+      )
+      expect(bases[0]).toBeInstanceOf(THREE.Object3D)
+      expect(bases[1]).toBeInstanceOf(THREE.Object3D)
+      // Each call should hand the loader a fresh container, not the same one.
+      expect(bases[0]).not.toBe(bases[1])
+    })
   })
 
   describe('GLTF loader path', () => {

src/extensions/core/load3d/MeshModelAdapter.ts

@@ -102,6 +102,8 @@ export class MeshModelAdapter implements ModelAdapter {
     path: string,
     filename: string
   ): Promise<THREE.Object3D> {
+    this.objLoader.setBaseObject3d(new THREE.Object3D())
+
     if (ctx.materialMode === 'original') {
       try {
         this.mtlLoader.setPath(path)

src/extensions/core/load3d/load3dSerialize.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type Load3d from '@/extensions/core/load3d/Load3d'
+import { snapshotLoad3dState } from '@/extensions/core/load3d/load3dSerialize'
+import type { CameraState } from '@/extensions/core/load3d/interfaces'
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
+
+function makeNode(props: Record<string, unknown> = {}): LGraphNode {
+  return { properties: { ...props } } as unknown as LGraphNode
+}
+
+const baseCameraState: CameraState = {
+  position: { x: 1, y: 2, z: 3 },
+  target: { x: 0, y: 0, z: 0 },
+  zoom: 1,
+  cameraType: 'perspective'
+} as unknown as CameraState
+
+function makeLoad3d({
+  cameraType = 'perspective',
+  fov = 35,
+  modelInfo = { transform: { position: [0, 0, 0] } } as unknown
+}: {
+  cameraType?: string
+  fov?: number
+  modelInfo?: unknown
+} = {}) {
+  return {
+    getCurrentCameraType: vi.fn(() => cameraType),
+    cameraManager: { perspectiveCamera: { fov } },
+    getCameraState: vi.fn(() => baseCameraState),
+    stopRecording: vi.fn(),
+    getModelInfo: vi.fn(() => modelInfo)
+  } as unknown as Load3d
+}
+
+describe('snapshotLoad3dState', () => {
+  it('returns only camera_info and model_3d_info', () => {
+    const result = snapshotLoad3dState(makeNode(), makeLoad3d())
+    expect(Object.keys(result).sort()).toEqual(['camera_info', 'model_3d_info'])
+  })
+
+  it('writes the camera state into properties["Camera Config"]', () => {
+    const node = makeNode()
+    snapshotLoad3dState(node, makeLoad3d({ fov: 42 }))
+    const cfg = node.properties['Camera Config'] as Record<string, unknown>
+    expect(cfg).toMatchObject({
+      cameraType: 'perspective',
+      fov: 42,
+      state: baseCameraState
+    })
+  })
+
+  it('preserves an existing Camera Config object instead of replacing it', () => {
+    const existing = { cameraType: 'orthographic', fov: 99 }
+    const node = makeNode({ 'Camera Config': existing })
+    snapshotLoad3dState(node, makeLoad3d())
+    // Same object reference (mutated in place), with state attached.
+    expect(node.properties['Camera Config']).toBe(existing)
+    expect(
+      (node.properties['Camera Config'] as Record<string, unknown>).state
+    ).toBe(baseCameraState)
+  })
+
+  it('stops in-progress recording as a side effect', () => {
+    const load3d = makeLoad3d()
+    snapshotLoad3dState(makeNode(), load3d)
+    expect(load3d.stopRecording).toHaveBeenCalledOnce()
+  })
+
+  it('returns model_3d_info as a single-element list when a model is loaded', () => {
+    const info = { transform: { position: [1, 2, 3] } }
+    const result = snapshotLoad3dState(
+      makeNode(),
+      makeLoad3d({ modelInfo: info })
+    )
+    expect(result.model_3d_info).toEqual([info])
+  })
+
+  it('returns an empty model_3d_info list when no model is loaded', () => {
+    const result = snapshotLoad3dState(
+      makeNode(),
+      makeLoad3d({ modelInfo: null })
+    )
+    expect(result.model_3d_info).toEqual([])
+  })
+})

src/extensions/core/load3d/load3dSerialize.ts

@@ -0,0 +1,36 @@
+import type Load3d from '@/extensions/core/load3d/Load3d'
+import type {
+  CameraConfig,
+  CameraState,
+  Model3DInfo
+} from '@/extensions/core/load3d/interfaces'
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
+
+export type Load3dSerializedBase = {
+  camera_info: CameraState | null
+  model_3d_info: Model3DInfo
+}
+
+export function snapshotLoad3dState(
+  node: LGraphNode,
+  load3d: Load3d
+): Load3dSerializedBase {
+  const cameraConfig: CameraConfig = (node.properties['Camera Config'] as
+    | CameraConfig
+    | undefined) || {
+    cameraType: load3d.getCurrentCameraType(),
+    fov: load3d.cameraManager.perspectiveCamera.fov
+  }
+  cameraConfig.state = load3d.getCameraState()
+  node.properties['Camera Config'] = cameraConfig
+
+  load3d.stopRecording()
+
+  const modelInfo = load3d.getModelInfo()
+  const model_3d_info: Model3DInfo = modelInfo ? [modelInfo] : []
+
+  return {
+    camera_info: cameraConfig.state ?? null,
+    model_3d_info
+  }
+}

src/extensions/core/load3d/nodeTypes.ts

@@ -9,7 +9,12 @@ const LOAD3D_PREVIEW_NODES = new Set([
   'PreviewPointCloud'
 ])
 
-const LOAD3D_ALL_NODES = new Set([...LOAD3D_PREVIEW_NODES, 'Load3D', 'SaveGLB'])
+const LOAD3D_ALL_NODES = new Set([
+  ...LOAD3D_PREVIEW_NODES,
+  'Load3D',
+  'Load3DAdvanced',
+  'SaveGLB'
+])
 
 export const isLoad3dPreviewNode = (nodeType: string): boolean =>
   LOAD3D_PREVIEW_NODES.has(nodeType)

src/extensions/core/load3dAdvanced.ts

@@ -0,0 +1,103 @@
+import { nextTick } from 'vue'
+
+import Load3DAdvanced from '@/components/load3d/Load3DAdvanced.vue'
+import { nodeToLoad3dMap, useLoad3d } from '@/composables/useLoad3d'
+import { createExportMenuItems } from '@/extensions/core/load3d/exportMenuHelper'
+import type { CameraConfig } from '@/extensions/core/load3d/interfaces'
+import Load3DConfiguration from '@/extensions/core/load3d/Load3DConfiguration'
+import { snapshotLoad3dState } from '@/extensions/core/load3d/load3dSerialize'
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
+import type { IContextMenuValue } from '@/lib/litegraph/src/interfaces'
+import type { CustomInputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import { ComponentWidgetImpl, addWidget } from '@/scripts/domWidget'
+import { useExtensionService } from '@/services/extensionService'
+import { useLoad3dService } from '@/services/load3dService'
+
+const inputSpecLoad3DAdvanced: CustomInputSpec = {
+  name: 'viewport_state',
+  type: 'LOAD_3D_ADVANCED',
+  isPreview: false
+}
+
+useExtensionService().registerExtension({
+  name: 'Comfy.Load3DAdvanced',
+
+  beforeRegisterNodeDef(_nodeType, nodeData) {
+    if (nodeData.name !== 'Load3DAdvanced') return
+    if (!nodeData.input?.required) return
+    nodeData.input.required.viewport_state = ['LOAD_3D_ADVANCED', {}]
+  },
+
+  getNodeMenuItems(node: LGraphNode): (IContextMenuValue | null)[] {
+    if (node.constructor.comfyClass !== 'Load3DAdvanced') return []
+
+    const load3d = useLoad3dService().getLoad3d(node)
+    if (!load3d) return []
+
+    return createExportMenuItems(load3d)
+  },
+
+  getCustomWidgets() {
+    return {
+      LOAD_3D_ADVANCED(node) {
+        const widget = new ComponentWidgetImpl({
+          node,
+          name: 'viewport_state',
+          component: Load3DAdvanced,
+          inputSpec: inputSpecLoad3DAdvanced,
+          options: {}
+        })
+
+        widget.type = 'load3DAdvanced'
+
+        addWidget(node, widget)
+
+        return { widget }
+      }
+    }
+  },
+
+  async nodeCreated(node: LGraphNode) {
+    if (node.constructor.comfyClass !== 'Load3DAdvanced') return
+
+    const [oldWidth, oldHeight] = node.size
+    node.setSize([Math.max(oldWidth, 300), Math.max(oldHeight, 600)])
+
+    await nextTick()
+
+    useLoad3d(node).onLoad3dReady((load3d) => {
+      const modelWidget = node.widgets?.find((w) => w.name === 'model_file')
+      const width = node.widgets?.find((w) => w.name === 'width')
+      const height = node.widgets?.find((w) => w.name === 'height')
+      if (!modelWidget || !width || !height) return
+
+      const cameraConfig = node.properties['Camera Config'] as
+        | CameraConfig
+        | undefined
+      const cameraState = cameraConfig?.state
+
+      const config = new Load3DConfiguration(load3d, node.properties)
+      config.configure({
+        loadFolder: 'input',
+        modelWidget,
+        cameraState,
+        width,
+        height
+      })
+    })
+
+    useLoad3d(node).waitForLoad3d(() => {
+      const sceneWidget = node.widgets?.find((w) => w.name === 'viewport_state')
+      if (!sceneWidget) return
+
+      sceneWidget.serializeValue = async () => {
+        const currentLoad3d = nodeToLoad3dMap.get(node)
+        if (!currentLoad3d) {
+          console.error('No load3d instance found for node')
+          return null
+        }
+        return snapshotLoad3dState(node, currentLoad3d)
+      }
+    })
+  }
+})

src/extensions/core/load3dLazy.ts

@@ -37,6 +37,7 @@ async function loadLoad3dExtensions(): Promise<ComfyExtension[]> {
     // Import extensions - they self-register via useExtensionService()
     await Promise.all([
       import('./load3d'),
+      import('./load3dAdvanced'),
       import('./load3dPreviewExtensions'),
       import('./saveMesh')
     ])
@@ -66,6 +67,12 @@ useExtensionService().registerExtension({
           modelFile[1].mesh_upload = true
           modelFile[1].upload_subfolder = '3d'
         }
+      } else if (nodeData.name === 'Load3DAdvanced') {
+        const modelFile = nodeData.input?.required?.model_file
+        if (modelFile?.[1]) {
+          modelFile[1].mesh_upload = true
+          modelFile[1].upload_subfolder = ''
+        }
       }
 
       // Load the 3D extensions and replay their beforeRegisterNodeDef hooks,

src/platform/assets/schemas/assetSchema.ts

@@ -22,7 +22,7 @@ const zAsset = z.object({
 })
 
 const zAssetResponse = zListAssetsResponse
-  .pick({ total: true, has_more: true })
+  .pick({ total: true, has_more: true, next_cursor: true })
   .extend({
     assets: z.array(zAsset)
   })

src/platform/assets/services/assetService.test.ts

@@ -53,6 +53,7 @@ const fetchApiMock = vi.mocked(api.fetchApi)
 type AssetListResponseOptions = {
   hasMore?: AssetResponse['has_more']
   total?: AssetResponse['total']
+  nextCursor?: AssetResponse['next_cursor']
 }
 
 function buildResponse(
@@ -68,9 +69,18 @@ function buildResponse(
 
 function buildAssetListResponse(
   assets: AssetItem[],
-  { hasMore = false, total = assets.length }: AssetListResponseOptions = {}
+  {
+    hasMore = false,
+    total = assets.length,
+    nextCursor
+  }: AssetListResponseOptions = {}
 ): Response {
-  return buildResponse({ assets, total, has_more: hasMore })
+  return buildResponse({
+    assets,
+    total,
+    has_more: hasMore,
+    ...(nextCursor === undefined ? {} : { next_cursor: nextCursor })
+  })
 }
 
 function validAsset(overrides: Partial<AssetItem> = {}): AssetItem {
@@ -512,7 +522,7 @@ describe(assetService.getAllAssetsByTag, () => {
     vi.clearAllMocks()
   })
 
-  it('paginates tagged asset requests with include_public=true', async () => {
+  it('walks pages by keyset cursor with include_public=true', async () => {
     fetchApiMock
       .mockResolvedValueOnce(
         buildAssetListResponse(
@@ -520,7 +530,7 @@ describe(assetService.getAllAssetsByTag, () => {
             validAsset({ id: 'a', tags: ['input'] }),
             validAsset({ id: 'b', tags: ['input'] })
           ],
-          { hasMore: true }
+          { hasMore: true, nextCursor: 'cursor-page-2' }
         )
       )
       .mockResolvedValueOnce(
@@ -538,6 +548,8 @@ describe(assetService.getAllAssetsByTag, () => {
     expect(firstParams.get('include_public')).toBe('true')
     expect(firstParams.get('exclude_tags')).toBe(MISSING_TAG)
     expect(firstParams.get('limit')).toBe('2')
+    // First page carries neither a cursor nor an offset.
+    expect(firstParams.has('after')).toBe(false)
     expect(firstParams.has('offset')).toBe(false)
 
     const secondUrl = fetchApiMock.mock.calls[1]?.[0] as string
@@ -545,7 +557,9 @@ describe(assetService.getAllAssetsByTag, () => {
     expect(secondParams.get('include_public')).toBe('true')
     expect(secondParams.get('exclude_tags')).toBe(MISSING_TAG)
     expect(secondParams.get('limit')).toBe('2')
-    expect(secondParams.get('offset')).toBe('2')
+    // Subsequent pages resume from the prior response's next_cursor, never offset.
+    expect(secondParams.get('after')).toBe('cursor-page-2')
+    expect(secondParams.has('offset')).toBe(false)
   })
 
   it('honors has_more when walking tagged asset pages', async () => {
@@ -556,7 +570,7 @@ describe(assetService.getAllAssetsByTag, () => {
             validAsset({ id: 'first', tags: ['input'] }),
             validAsset({ id: 'second', tags: ['input'] })
           ],
-          { hasMore: true }
+          { hasMore: true, nextCursor: 'cursor-next' }
         )
       )
       .mockResolvedValueOnce(
@@ -577,7 +591,45 @@ describe(assetService.getAllAssetsByTag, () => {
       throw new Error('Expected a second asset request URL')
     }
     const secondParams = new URL(secondUrl, 'http://localhost').searchParams
-    expect(secondParams.get('offset')).toBe('2')
+    expect(secondParams.get('after')).toBe('cursor-next')
+  })
+
+  it('stops walking when next_cursor is absent even if has_more is true', async () => {
+    fetchApiMock.mockResolvedValueOnce(
+      buildAssetListResponse([validAsset({ id: 'only', tags: ['input'] })], {
+        hasMore: true
+      })
+    )
+
+    const assets = await assetService.getAllAssetsByTag('input', true, {
+      limit: 2
+    })
+
+    expect(assets.map((a) => a.id)).toEqual(['only'])
+    expect(fetchApiMock).toHaveBeenCalledOnce()
+  })
+
+  it('stops walking when the server returns a non-advancing cursor', async () => {
+    fetchApiMock
+      .mockResolvedValueOnce(
+        buildAssetListResponse([validAsset({ id: 'a', tags: ['input'] })], {
+          hasMore: true,
+          nextCursor: 'stuck'
+        })
+      )
+      .mockResolvedValueOnce(
+        buildAssetListResponse([validAsset({ id: 'b', tags: ['input'] })], {
+          hasMore: true,
+          nextCursor: 'stuck'
+        })
+      )
+
+    const assets = await assetService.getAllAssetsByTag('input', true, {
+      limit: 1
+    })
+
+    expect(assets.map((a) => a.id)).toEqual(['a', 'b'])
+    expect(fetchApiMock).toHaveBeenCalledTimes(2)
   })
 
   it.for([
@@ -636,7 +688,7 @@ describe(assetService.getAllAssetsByTag, () => {
           validAsset({ id: 'a', tags: ['input'] }),
           validAsset({ id: 'b', tags: ['input'] })
         ],
-        { hasMore: true }
+        { hasMore: true, nextCursor: 'cursor-page-2' }
       )
     })
 

src/platform/assets/services/assetService.ts

@@ -31,6 +31,11 @@ export interface PaginationOptions {
 }
 
 interface AssetPaginationOptions extends PaginationOptions {
+  /**
+   * Opaque keyset cursor from a prior response's `next_cursor`. When set, the
+   * server resumes after that cursor and `offset` is ignored.
+   */
+  after?: string
   signal?: AbortSignal
 }
 
@@ -38,6 +43,7 @@ interface AssetRequestOptions extends PaginationOptions {
   includeTags: string[]
   excludeTags?: string[]
   includePublic?: boolean
+  after?: string
   signal?: AbortSignal
 }
 
@@ -286,6 +292,7 @@ function createAssetService() {
       excludeTags = DEFAULT_EXCLUDED_ASSET_TAGS,
       limit = DEFAULT_LIMIT,
       offset,
+      after,
       includePublic,
       signal
     } = options
@@ -299,7 +306,11 @@ function createAssetService() {
     if (normalizedExcludeTags.length > 0) {
       queryParams.set('exclude_tags', normalizedExcludeTags.join(','))
     }
-    if (offset !== undefined && offset > 0) {
+    // `after` (keyset cursor) takes precedence over `offset`; the server ignores
+    // `offset` when a cursor is supplied, so we avoid sending a redundant param.
+    if (after) {
+      queryParams.set('after', after)
+    } else if (offset !== undefined && offset > 0) {
       queryParams.set('offset', offset.toString())
     }
     if (includePublic !== undefined) {
@@ -481,11 +492,17 @@ function createAssetService() {
   async function getAssetsByTag(
     tag: string,
     includePublic: boolean = true,
-    { limit = DEFAULT_LIMIT, offset = 0, signal }: AssetPaginationOptions = {}
+    {
+      limit = DEFAULT_LIMIT,
+      offset = 0,
+      after,
+      signal
+    }: AssetPaginationOptions = {}
   ): Promise<AssetItem[]> {
     const data = await getAssetsPageByTag(tag, includePublic, {
       limit,
       offset,
+      after,
       signal
     })
 
@@ -498,17 +515,27 @@ function createAssetService() {
   async function getAssetsPageByTag(
     tag: string,
     includePublic: boolean = true,
-    { limit = DEFAULT_LIMIT, offset = 0, signal }: AssetPaginationOptions = {}
+    {
+      limit = DEFAULT_LIMIT,
+      offset = 0,
+      after,
+      signal
+    }: AssetPaginationOptions = {}
   ): Promise<AssetResponse> {
     return await handleAssetRequest(
-      { includeTags: [tag], limit, offset, includePublic, signal },
+      { includeTags: [tag], limit, offset, after, includePublic, signal },
       `assets for tag ${tag}`
     )
   }
 
   /**
    * Gets every asset for a tag by walking paginated asset API responses.
-   * Pagination follows the required server-provided `has_more` flag.
+   *
+   * Uses keyset (cursor) pagination: each page is fetched with the prior
+   * response's `next_cursor`, which is stable under concurrent inserts/deletes
+   * and avoids the duplicate/skip drift that offset paging exhibits when the
+   * underlying set changes mid-walk. Falls back to terminating on `has_more`
+   * when the server omits `next_cursor`.
    *
    * @param tag - The tag to filter by (e.g., 'models', 'input')
    * @param includePublic - Whether to include public assets (default: true)
@@ -520,18 +547,21 @@ function createAssetService() {
   async function getAllAssetsByTag(
     tag: string,
     includePublic: boolean = true,
-    { limit = DEFAULT_LIMIT, signal }: AssetPaginationOptions = {}
+    {
+      limit = DEFAULT_LIMIT,
+      signal
+    }: Pick<AssetPaginationOptions, 'limit' | 'signal'> = {}
   ): Promise<AssetItem[]> {
     const assets: AssetItem[] = []
     const pageSize = limit > 0 ? limit : DEFAULT_LIMIT
-    let offset = 0
+    let after: string | undefined
 
     while (true) {
       if (signal?.aborted) throw createAbortError()
 
       const data = await getAssetsPageByTag(tag, includePublic, {
         limit: pageSize,
-        offset,
+        after,
         signal
       })
       const batch = data.assets
@@ -541,11 +571,12 @@ function createAssetService() {
 
       assets.push(...batch)
 
-      if (!data.has_more) {
+      // A server that returns a non-advancing cursor would loop forever.
+      if (!data.has_more || !data.next_cursor || data.next_cursor === after) {
         return assets
       }
 
-      offset += batch.length
+      after = data.next_cursor
     }
   }
 

src/platform/updates/common/releaseService.test.ts

@@ -53,7 +53,8 @@ describe('useReleaseService', () => {
           project: 'comfyui',
           current_version: '1.0.0'
         },
-        signal: undefined
+        signal: undefined,
+        headers: undefined
       })
 
       expect(result).toEqual(mockReleases)
@@ -76,7 +77,8 @@ describe('useReleaseService', () => {
           current_version: '1.0.0',
           form_factor: 'desktop-windows'
         },
-        signal: undefined
+        signal: undefined,
+        headers: undefined
       })
 
       expect(result).toEqual(mockReleases)
@@ -86,11 +88,30 @@ describe('useReleaseService', () => {
       const abortController = new AbortController()
       mockAxiosInstance.get.mockResolvedValue({ data: mockReleases })
 
-      await service.getReleases({ project: 'comfyui' }, abortController.signal)
+      await service.getReleases(
+        { project: 'comfyui' },
+        { signal: abortController.signal }
+      )
 
       expect(mockAxiosInstance.get).toHaveBeenCalledWith('/releases', {
         params: { project: 'comfyui' },
-        signal: abortController.signal
+        signal: abortController.signal,
+        headers: undefined
+      })
+    })
+
+    it('should send Comfy-Env header when deployEnvironment is provided', async () => {
+      mockAxiosInstance.get.mockResolvedValue({ data: mockReleases })
+
+      await service.getReleases(
+        { project: 'comfyui' },
+        { deployEnvironment: 'local-desktop' }
+      )
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/releases', {
+        params: { project: 'comfyui' },
+        signal: undefined,
+        headers: { 'Comfy-Env': 'local-desktop' }
       })
     })
 

src/platform/updates/common/releaseService.ts

@@ -98,8 +98,9 @@ export const useReleaseService = () => {
   // Fetch release notes from API
   const getReleases = async (
     params: GetReleasesParams,
-    signal?: AbortSignal
+    options: { signal?: AbortSignal; deployEnvironment?: string } = {}
   ): Promise<ReleaseNote[] | null> => {
+    const { signal, deployEnvironment } = options
     const endpoint = '/releases'
     const errorContext = 'Failed to get releases'
     const routeSpecificErrors = {
@@ -110,7 +111,10 @@ export const useReleaseService = () => {
       () =>
         releaseApiClient.get<ReleaseNote[]>(endpoint, {
           params,
-          signal
+          signal,
+          headers: deployEnvironment
+            ? { 'Comfy-Env': deployEnvironment }
+            : undefined
         }),
       errorContext,
       routeSpecificErrors

src/platform/updates/common/releaseStore.test.ts

@@ -228,12 +228,15 @@ describe('useReleaseStore', () => {
 
         await store.initialize()
 
-        expect(releaseService.getReleases).toHaveBeenCalledWith({
-          project: 'comfyui',
-          current_version: '1.0.0',
-          form_factor: 'git-windows',
-          locale: 'en'
-        })
+        expect(releaseService.getReleases).toHaveBeenCalledWith(
+          {
+            project: 'comfyui',
+            current_version: '1.0.0',
+            form_factor: 'git-windows',
+            locale: 'en'
+          },
+          { deployEnvironment: undefined }
+        )
       })
     })
 
@@ -300,12 +303,15 @@ describe('useReleaseStore', () => {
 
       await store.initialize()
 
-      expect(releaseService.getReleases).toHaveBeenCalledWith({
-        project: 'comfyui',
-        current_version: '1.0.0',
-        form_factor: 'git-windows',
-        locale: 'en'
-      })
+      expect(releaseService.getReleases).toHaveBeenCalledWith(
+        {
+          project: 'comfyui',
+          current_version: '1.0.0',
+          form_factor: 'git-windows',
+          locale: 'en'
+        },
+        { deployEnvironment: undefined }
+      )
       expect(store.releases).toEqual([mockRelease])
     })
 
@@ -318,12 +324,30 @@ describe('useReleaseStore', () => {
 
       await store.initialize()
 
-      expect(releaseService.getReleases).toHaveBeenCalledWith({
-        project: 'comfyui',
-        current_version: '1.0.0',
-        form_factor: 'desktop-mac',
-        locale: 'en'
-      })
+      expect(releaseService.getReleases).toHaveBeenCalledWith(
+        {
+          project: 'comfyui',
+          current_version: '1.0.0',
+          form_factor: 'desktop-mac',
+          locale: 'en'
+        },
+        { deployEnvironment: undefined }
+      )
+    })
+
+    it('should pass deploy_environment from system stats', async () => {
+      const store = useReleaseStore()
+      const releaseService = useReleaseService()
+      const systemStatsStore = useSystemStatsStore()
+      systemStatsStore.systemStats!.system.deploy_environment = 'local-desktop'
+      vi.mocked(releaseService.getReleases).mockResolvedValue([mockRelease])
+
+      await store.initialize()
+
+      expect(releaseService.getReleases).toHaveBeenCalledWith(
+        expect.anything(),
+        { deployEnvironment: 'local-desktop' }
+      )
     })
 
     it('should skip fetching when --disable-api-nodes is present', async () => {

src/platform/updates/common/releaseStore.ts

@@ -266,12 +266,18 @@ export const useReleaseStore = defineStore('release', () => {
         await until(systemStatsStore.isInitialized)
       }
 
-      const fetchedReleases = await releaseService.getReleases({
-        project: isCloud ? 'cloud' : 'comfyui',
-        current_version: currentVersion.value,
-        form_factor: systemStatsStore.getFormFactor(),
-        locale: stringToLocale(locale.value)
-      })
+      const fetchedReleases = await releaseService.getReleases(
+        {
+          project: isCloud ? 'cloud' : 'comfyui',
+          current_version: currentVersion.value,
+          form_factor: systemStatsStore.getFormFactor(),
+          locale: stringToLocale(locale.value)
+        },
+        {
+          deployEnvironment:
+            systemStatsStore.systemStats?.system?.deploy_environment
+        }
+      )
 
       if (fetchedReleases !== null) {
         releases.value = fetchedReleases

src/renderer/extensions/vueNodes/widgets/registry/widgetRegistry.ts

@@ -51,6 +51,9 @@ const AudioPreviewPlayer = defineAsyncComponent(
 const Load3D = defineAsyncComponent(
   () => import('@/components/load3d/Load3D.vue')
 )
+const Load3DAdvanced = defineAsyncComponent(
+  () => import('@/components/load3d/Load3DAdvanced.vue')
+)
 const WidgetImageCrop = defineAsyncComponent(
   () => import('@/components/imagecrop/WidgetImageCrop.vue')
 )
@@ -169,6 +172,14 @@ const coreWidgetDefinitions: Array<[string, WidgetDefinition]> = [
     }
   ],
   ['load3D', { component: Load3D, aliases: ['LOAD_3D'], essential: false }],
+  [
+    'load3DAdvanced',
+    {
+      component: Load3DAdvanced,
+      aliases: ['LOAD_3D_ADVANCED'],
+      essential: false
+    }
+  ],
   [
     'imagecrop',
     {
@@ -243,6 +254,7 @@ const EXPANDING_TYPES = [
   'textarea',
   'markdown',
   'load3D',
+  'load3DAdvanced',
   'curve',
   'painter',
   'imagecompare',

src/schemas/apiSchema.ts

@@ -252,6 +252,7 @@ const zSystemStats = z.object({
     python_version: z.string(),
     embedded_python: z.boolean(),
     comfyui_version: z.string(),
+    deploy_environment: z.string().optional(),
     pytorch_version: z.string(),
     required_frontend_version: z.string().optional(),
     argv: z.array(z.string()),

src/scripts/api.ts

@@ -108,6 +108,11 @@ interface QueuePromptRequestBody {
      * ```
      */
     api_key_comfy_org?: string
+    /**
+     * Identifies the client submitting the prompt. Forwarded by the backend
+     * to API nodes' upstream requests via the Comfy-Usage-Source header.
+     */
+    comfy_usage_source?: string
     /**
      * Override the preview method for this prompt execution.
      * 'default' uses the server's CLI setting.
@@ -867,6 +872,7 @@ export class ComfyApi extends EventTarget {
       extra_data: {
         auth_token_comfy_org: this.authToken,
         api_key_comfy_org: this.apiKey,
+        comfy_usage_source: 'comfyui-frontend',
         extra_pnginfo: { workflow },
         ...(options?.previewMethod &&
           options.previewMethod !== 'default' && {