Merge branch 'main' into test/fe-741-grid-thumbnail-e2e

## Summary

Adds an Arrange popover to the multi-select toolbox that repositions
selected nodes into vertical, horizontal, or grid layouts, with a
follow-up slider to tune the spacing.



https://github.com/user-attachments/assets/f9a55ef9-2619-462b-a83f-2b86eb076fe3


## Changes

- **What**: New `ArrangeButton` placed between the color picker and
frame icons. Three layouts (vertical, horizontal, grid) sort selected
nodes by current position and lay them out from the smallest-`x+y`
anchor with a 12-unit gap. Visual bounds account for
`LiteGraph.NODE_TITLE_HEIGHT` so titles don't overlap stacked bodies.
After picking a layout, the popover swaps to a 0–48 spacing slider —
drag previews live (rAF-throttled, no undo capture), release commits one
undo entry. Closing the popover ends the session.
- **Breaking**: none
- **Dependencies**: none

## Review Focus

- `useArrangeNodes.computeArrangement` — pure layout math separated from
side effects; covered by 8 unit tests including the title-height
handling and `TitleMode.NO_TITLE` case.
- `useArrangeSession` — owns the slider's state machine. rAF-throttled
`previewGap` collapses rapid drag events into one frame; `commitGap`
cancels any pending preview before capturing undo. Covered by 5 unit
tests.
- Position mutations go through `useLayoutMutations().batchMoveNodes`
(single batched layout-store transaction) followed by
`changeTracker.captureCanvasState()` for undo — same pattern as drag and
other selection-toolbox actions.
- Anchor selection uses smallest `pos.x + pos.y` rather than min-x or
min-y alone, to keep the layout origin stable across re-runs (slider
drags).

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-12068-feat-add-Arrange-action-to-multi-select-toolbox-3596d73d365081e58c25ffac41dc0b2a)
by [Unito](https://www.unito.io)

---------

Co-authored-by: AustinMroz <austin@comfy.org>

apps/website/src/components/common/Badge.vue

@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { cn } from '@comfyorg/tailwind-utils'
+
+import type { BadgeVariants } from './badge.variants'
+import { badgeVariants } from './badge.variants'
+
+const { variant, class: className } = defineProps<{
+  variant?: BadgeVariants['variant']
+  class?: string
+}>()
+</script>
+
+<template>
+  <span :class="cn(badgeVariants({ variant }), className)">
+    <slot />
+  </span>
+</template>

apps/website/src/components/common/CallToActionSection.vue

@@ -0,0 +1,53 @@
+<script setup lang="ts">
+import type { Locale, TranslationKey } from '../../i18n/translations'
+
+import { t } from '../../i18n/translations'
+import BrandButton from './BrandButton.vue'
+
+const {
+  locale = 'en',
+  headingKey,
+  primaryLabelKey,
+  primaryHref,
+  secondaryLabelKey,
+  secondaryHref
+} = defineProps<{
+  locale?: Locale
+  headingKey: TranslationKey
+  primaryLabelKey: TranslationKey
+  primaryHref?: string
+  secondaryLabelKey?: TranslationKey
+  secondaryHref?: string
+}>()
+</script>
+
+<template>
+  <section class="max-w-9xl mx-auto px-6 py-20 lg:py-32">
+    <div class="flex flex-col items-center text-center">
+      <h2
+        class="text-primary-comfy-canvas max-w-5xl text-3xl font-light tracking-tight lg:text-5xl"
+      >
+        {{ t(headingKey, locale) }}
+      </h2>
+      <div class="mt-10 flex flex-wrap items-center justify-center gap-3">
+        <BrandButton
+          :href="primaryHref"
+          variant="solid"
+          size="xs"
+          class="uppercase"
+        >
+          {{ t(primaryLabelKey, locale) }}
+        </BrandButton>
+        <BrandButton
+          v-if="secondaryLabelKey"
+          :href="secondaryHref"
+          variant="outline"
+          size="xs"
+          class="uppercase"
+        >
+          {{ t(secondaryLabelKey, locale) }}
+        </BrandButton>
+      </div>
+    </div>
+  </section>
+</template>

apps/website/src/components/common/EventsSection.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+import type {
+  Locale,
+  LocalizedText,
+  TranslationKey
+} from '../../i18n/translations'
+
+import { t } from '../../i18n/translations'
+import BrandButton from './BrandButton.vue'
+
+export type EventItem = {
+  label: LocalizedText
+  title: LocalizedText
+  cta: LocalizedText
+  href: string
+}
+
+const {
+  locale = 'en',
+  headingKey,
+  descriptionKey,
+  notifyLabelKey,
+  notifyHref,
+  events
+} = defineProps<{
+  locale?: Locale
+  headingKey: TranslationKey
+  descriptionKey: TranslationKey
+  notifyLabelKey: TranslationKey
+  notifyHref?: string
+  events: readonly EventItem[]
+}>()
+</script>
+
+<template>
+  <section class="max-w-9xl mx-auto px-6 py-12">
+    <div
+      class="bg-transparency-white-t4 rounded-4xl px-6 py-12 lg:px-16 lg:py-20"
+    >
+      <div class="grid grid-cols-1 gap-12 lg:grid-cols-2 lg:gap-16">
+        <div class="flex flex-col gap-8">
+          <h2
+            class="text-primary-comfy-canvas text-4xl font-light tracking-tight lg:text-6xl"
+          >
+            {{ t(headingKey, locale) }}
+          </h2>
+          <p
+            class="text-primary-comfy-canvas max-w-sm text-sm/relaxed lg:text-base"
+          >
+            {{ t(descriptionKey, locale) }}
+          </p>
+          <div>
+            <BrandButton
+              :href="notifyHref"
+              variant="outline"
+              size="xs"
+              class="uppercase"
+            >
+              {{ t(notifyLabelKey, locale) }}
+            </BrandButton>
+          </div>
+        </div>
+
+        <div class="flex flex-col">
+          <a
+            v-for="(event, i) in events"
+            :key="i"
+            :href="event.href"
+            class="group border-primary-comfy-canvas/15 flex items-center gap-4 border-b py-6 lg:gap-8"
+          >
+            <span
+              class="text-primary-comfy-canvas shrink-0 text-sm font-medium"
+            >
+              {{ event.label[locale] }}
+            </span>
+            <span class="text-primary-warm-gray flex-1 text-sm">
+              {{ event.title[locale] }}
+            </span>
+            <span
+              class="text-primary-comfy-yellow flex shrink-0 items-center gap-2 text-sm"
+            >
+              {{ event.cta[locale] }}
+              <svg
+                class="size-4 transition-transform group-hover:translate-x-0.5"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                aria-hidden="true"
+              >
+                <line x1="5" y1="12" x2="19" y2="12" />
+                <polyline points="12 5 19 12 12 19" />
+              </svg>
+            </span>
+          </a>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>

apps/website/src/components/common/MaskRevealButton.stories.ts

@@ -0,0 +1,165 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+
+import MaskRevealButton from './MaskRevealButton.vue'
+
+const meta: Meta<typeof MaskRevealButton> = {
+  title: 'Website/Common/MaskRevealButton',
+  component: MaskRevealButton,
+  tags: ['autodocs'],
+  decorators: [
+    () => ({
+      template: '<div class="bg-primary-comfy-ink p-12"><story /></div>'
+    })
+  ],
+  argTypes: {
+    href: { control: 'text' },
+    target: { control: 'text' },
+    rel: { control: 'text' },
+    type: {
+      control: { type: 'select' },
+      options: ['button', 'submit', 'reset']
+    },
+    disabled: { control: 'boolean' },
+    ariaLabel: { control: 'text' },
+    variant: {
+      control: { type: 'select' },
+      options: ['solid', 'ghost']
+    },
+    size: {
+      control: { type: 'select' },
+      options: ['sm', 'md', 'lg']
+    },
+    iconPosition: {
+      control: { type: 'select' },
+      options: ['right', 'left']
+    },
+    hideLabel: { control: 'boolean' }
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { href: '#' },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template: `<MaskRevealButton v-bind="args">Try Workflow</MaskRevealButton>`
+  })
+}
+
+export const Ghost: Story = {
+  args: { href: '#', variant: 'ghost' },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template: '<MaskRevealButton v-bind="args">Read More</MaskRevealButton>'
+  })
+}
+
+export const IconLeft: Story = {
+  args: { href: '#', iconPosition: 'left' },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template: '<MaskRevealButton v-bind="args">Go Back</MaskRevealButton>'
+  })
+}
+
+export const SmallSolid: Story = {
+  args: { href: '#', size: 'sm' },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template: '<MaskRevealButton v-bind="args">Try Workflow</MaskRevealButton>'
+  })
+}
+
+export const LargeSolid: Story = {
+  args: { href: '#', size: 'lg' },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template: `<MaskRevealButton v-bind="args">Let's Collaborate</MaskRevealButton>`
+  })
+}
+
+export const WithCustomIcon: Story = {
+  args: { href: '#' },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template: `
+      <MaskRevealButton v-bind="args">
+        Next Step
+        <template #icon>
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2.5"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="size-4"
+          >
+            <polyline points="9 6 15 12 9 18" />
+          </svg>
+        </template>
+      </MaskRevealButton>
+    `
+  })
+}
+
+export const LabelVisible: Story = {
+  args: { href: '#', hideLabel: false },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template:
+      '<MaskRevealButton v-bind="args">Always Visible</MaskRevealButton>'
+  })
+}
+
+export const Disabled: Story = {
+  args: { disabled: true },
+  render: (args) => ({
+    components: { MaskRevealButton },
+    setup: () => ({ args }),
+    template: '<MaskRevealButton v-bind="args">Unavailable</MaskRevealButton>'
+  })
+}
+
+export const AllVariants: Story = {
+  render: () => ({
+    components: { MaskRevealButton },
+    template: `
+      <div class="flex flex-col gap-8">
+        <div class="flex flex-col gap-3">
+          <span class="text-primary-comfy-canvas text-xs uppercase tracking-wider">Solid</span>
+          <div class="flex flex-wrap items-center gap-4">
+            <MaskRevealButton href="#" variant="solid" size="sm">Small</MaskRevealButton>
+            <MaskRevealButton href="#" variant="solid" size="md">Medium</MaskRevealButton>
+            <MaskRevealButton href="#" variant="solid" size="lg">Large</MaskRevealButton>
+          </div>
+        </div>
+        <div class="flex flex-col gap-3">
+          <span class="text-primary-comfy-canvas text-xs uppercase tracking-wider">Ghost</span>
+          <div class="flex flex-wrap items-center gap-4">
+            <MaskRevealButton href="#" variant="ghost" size="sm">Small</MaskRevealButton>
+            <MaskRevealButton href="#" variant="ghost" size="md">Medium</MaskRevealButton>
+            <MaskRevealButton href="#" variant="ghost" size="lg">Large</MaskRevealButton>
+          </div>
+        </div>
+        <div class="flex flex-col gap-3">
+          <span class="text-primary-comfy-canvas text-xs uppercase tracking-wider">Icon Left</span>
+          <div class="flex flex-wrap items-center gap-4">
+            <MaskRevealButton href="#" iconPosition="left" size="sm">Small</MaskRevealButton>
+            <MaskRevealButton href="#" iconPosition="left" size="md">Medium</MaskRevealButton>
+            <MaskRevealButton href="#" iconPosition="left" size="lg">Large</MaskRevealButton>
+          </div>
+        </div>
+      </div>
+    `
+  })
+}

apps/website/src/components/common/MaskRevealButton.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+import { cn } from '@comfyorg/tailwind-utils'
+
+import type { HTMLAttributes } from 'vue'
+
+import type { MaskRevealButtonVariants } from './maskRevealButton.variants'
+import {
+  maskRevealButtonBadgeVariants,
+  maskRevealButtonVariants,
+  maskRevealLabelVariants
+} from './maskRevealButton.variants'
+
+const {
+  href,
+  target,
+  rel,
+  type = 'button',
+  disabled,
+  ariaLabel,
+  variant,
+  size,
+  iconPosition,
+  hideLabel = true,
+  class: customClass = ''
+} = defineProps<{
+  href?: string
+  target?: string
+  rel?: string
+  type?: 'button' | 'submit' | 'reset'
+  disabled?: boolean
+  ariaLabel?: string
+  variant?: MaskRevealButtonVariants['variant']
+  size?: MaskRevealButtonVariants['size']
+  iconPosition?: MaskRevealButtonVariants['iconPosition']
+  hideLabel?: boolean
+  class?: HTMLAttributes['class']
+}>()
+</script>
+
+<template>
+  <component
+    :is="href ? 'a' : 'button'"
+    :href="href || undefined"
+    :target="href ? target : undefined"
+    :rel="href ? rel : undefined"
+    :type="!href ? type : undefined"
+    :disabled="!href ? disabled : undefined"
+    :aria-label="ariaLabel"
+    :class="
+      cn(maskRevealButtonVariants({ variant, size, iconPosition }), customClass)
+    "
+  >
+    <span
+      :data-icon-position="iconPosition ?? 'right'"
+      :data-hidden="hideLabel ? 'true' : 'false'"
+      :class="maskRevealLabelVariants()"
+    >
+      <slot />
+    </span>
+    <span
+      :class="maskRevealButtonBadgeVariants({ variant, size, iconPosition })"
+      aria-hidden="true"
+    >
+      <span class="inline-flex transition-transform duration-500">
+        <slot name="icon">
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="size-4"
+          >
+            <path d="M7 17 17 7" />
+            <path d="M7 7h10v10" />
+          </svg>
+        </slot>
+      </span>
+    </span>
+  </component>
+</template>

apps/website/src/components/common/PillButton.stories.ts

@@ -0,0 +1,165 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+
+import PillButton from './PillButton.vue'
+
+const meta: Meta<typeof PillButton> = {
+  title: 'Website/Common/PillButton',
+  component: PillButton,
+  tags: ['autodocs'],
+  decorators: [
+    () => ({
+      template: '<div class="bg-primary-comfy-ink p-12"><story /></div>'
+    })
+  ],
+  argTypes: {
+    href: { control: 'text' },
+    target: { control: 'text' },
+    rel: { control: 'text' },
+    type: {
+      control: { type: 'select' },
+      options: ['button', 'submit', 'reset']
+    },
+    disabled: { control: 'boolean' },
+    ariaLabel: { control: 'text' },
+    variant: {
+      control: { type: 'select' },
+      options: ['solid', 'ghost']
+    },
+    size: {
+      control: { type: 'select' },
+      options: ['sm', 'md', 'lg']
+    },
+    iconPosition: {
+      control: { type: 'select' },
+      options: ['right', 'left']
+    },
+    hideLabel: { control: 'boolean' }
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const AsAnchor: Story = {
+  args: { href: '#' },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: `<PillButton v-bind="args">Let's Collaborate</PillButton>`
+  })
+}
+
+export const AsButton: Story = {
+  args: { type: 'button' },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: '<PillButton v-bind="args">Submit</PillButton>'
+  })
+}
+
+export const Ghost: Story = {
+  args: { href: '#', variant: 'ghost' },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: '<PillButton v-bind="args">Read More</PillButton>'
+  })
+}
+
+export const SmallSolid: Story = {
+  args: { href: '#', size: 'sm' },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: '<PillButton v-bind="args">Try Workflow</PillButton>'
+  })
+}
+
+export const LargeSolid: Story = {
+  args: { href: '#', size: 'lg' },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: `<PillButton v-bind="args">Let's Collaborate</PillButton>`
+  })
+}
+
+export const WithCustomIcon: Story = {
+  args: { href: '#' },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: `
+      <PillButton v-bind="args">
+        Next Step
+        <template #icon>
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2.5"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="size-4"
+          >
+            <polyline points="9 6 15 12 9 18" />
+          </svg>
+        </template>
+      </PillButton>
+    `
+  })
+}
+
+export const IconLeft: Story = {
+  args: { href: '#', iconPosition: 'left' },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: '<PillButton v-bind="args">Go Back</PillButton>'
+  })
+}
+
+export const RevealLabelOnHover: Story = {
+  args: { href: '#', hideLabel: true },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: '<PillButton v-bind="args">Try Workflow</PillButton>'
+  })
+}
+
+export const Disabled: Story = {
+  args: { disabled: true },
+  render: (args) => ({
+    components: { PillButton },
+    setup: () => ({ args }),
+    template: '<PillButton v-bind="args">Unavailable</PillButton>'
+  })
+}
+
+export const AllVariants: Story = {
+  render: () => ({
+    components: { PillButton },
+    template: `
+      <div class="flex flex-col gap-8">
+        <div class="flex flex-col gap-3">
+          <span class="text-primary-comfy-canvas text-xs uppercase tracking-wider">Solid</span>
+          <div class="flex flex-wrap items-center gap-4">
+            <PillButton href="#" variant="solid" size="sm">Small</PillButton>
+            <PillButton href="#" variant="solid" size="md">Medium</PillButton>
+            <PillButton href="#" variant="solid" size="lg">Large</PillButton>
+          </div>
+        </div>
+        <div class="flex flex-col gap-3">
+          <span class="text-primary-comfy-canvas text-xs uppercase tracking-wider">Ghost</span>
+          <div class="flex flex-wrap items-center gap-4">
+            <PillButton href="#" variant="ghost" size="sm">Small</PillButton>
+            <PillButton href="#" variant="ghost" size="md">Medium</PillButton>
+            <PillButton href="#" variant="ghost" size="lg">Large</PillButton>
+          </div>
+        </div>
+      </div>
+    `
+  })
+}

apps/website/src/components/common/PillButton.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import { cn } from '@comfyorg/tailwind-utils'
+
+import type { HTMLAttributes } from 'vue'
+
+import type { PillButtonVariants } from './pillButton.variants'
+import {
+  pillButtonBadgeVariants,
+  pillButtonVariants
+} from './pillButton.variants'
+
+const {
+  href,
+  target,
+  rel,
+  type = 'button',
+  disabled,
+  ariaLabel,
+  variant,
+  size,
+  iconPosition,
+  hideLabel = false,
+  class: customClass = ''
+} = defineProps<{
+  href?: string
+  target?: string
+  rel?: string
+  type?: 'button' | 'submit' | 'reset'
+  disabled?: boolean
+  ariaLabel?: string
+  variant?: PillButtonVariants['variant']
+  size?: PillButtonVariants['size']
+  iconPosition?: PillButtonVariants['iconPosition']
+  hideLabel?: boolean
+  class?: HTMLAttributes['class']
+}>()
+</script>
+
+<template>
+  <component
+    :is="href ? 'a' : 'button'"
+    :href="href || undefined"
+    :target="href ? target : undefined"
+    :rel="href ? rel : undefined"
+    :type="!href ? type : undefined"
+    :disabled="!href ? disabled : undefined"
+    :aria-label="ariaLabel"
+    :class="
+      cn(pillButtonVariants({ variant, size, iconPosition }), customClass)
+    "
+  >
+    <span
+      :class="
+        cn(
+          'relative leading-none transition-all duration-500',
+          hideLabel && 'opacity-0 group-hover:opacity-100'
+        )
+      "
+    >
+      <slot />
+    </span>
+    <span
+      :class="pillButtonBadgeVariants({ variant, size, iconPosition })"
+      aria-hidden="true"
+    >
+      <span class="inline-flex transition-transform duration-500">
+        <slot name="icon">
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="size-4"
+          >
+            <path d="M7 17 17 7" />
+            <path d="M7 7h10v10" />
+          </svg>
+        </slot>
+      </span>
+    </span>
+  </component>
+</template>

apps/website/src/components/common/SiteFooter.vue

@@ -43,6 +43,7 @@ const topColumns: { title: string; links: FooterLink[] }[] = [
   {
     title: t('footer.resources', locale),
     links: [
+      { label: t('nav.learning', locale), href: routes.learning },
       {
         label: t('footer.blog', locale),
         href: externalLinks.blog,

apps/website/src/components/common/SiteNav.vue

@@ -52,6 +52,7 @@ const navLinks: NavLink[] = [
   {
     label: t('nav.resources', locale),
     items: [
+      { label: t('nav.learning', locale), href: routes.learning },
       {
         label: t('nav.blogs', locale),
         href: externalLinks.blog,

apps/website/src/components/common/badge.variants.ts

@@ -0,0 +1,17 @@
+import type { VariantProps } from 'cva'
+import { cva } from 'cva'
+
+export const badgeVariants = cva({
+  base: 'text-primary-warm-gray focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-4 py-1 text-xs font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] [&>svg]:pointer-events-none [&>svg]:size-3',
+  variants: {
+    variant: {
+      default: 'bg-transparency-ink-t80',
+      subtle: 'bg-transparency-white-t4 text-primary-comfy-canvas'
+    }
+  },
+  defaultVariants: {
+    variant: 'default'
+  }
+})
+
+export type BadgeVariants = VariantProps<typeof badgeVariants>

apps/website/src/components/common/maskRevealButton.variants.ts

@@ -0,0 +1,110 @@
+import type { VariantProps } from 'cva'
+import { cva } from 'cva'
+
+export const maskRevealButtonVariants = cva({
+  base: 'group relative uppercase inline-flex w-fit cursor-pointer items-center overflow-hidden rounded-lg p-1 font-bold text-nowrap transition-all duration-500 disabled:cursor-not-allowed disabled:opacity-50',
+  variants: {
+    variant: {
+      solid: 'bg-primary-comfy-yellow text-primary-comfy-ink',
+      ghost: 'text-primary-comfy-yellow bg-transparent'
+    },
+    size: {
+      sm: 'h-10 text-xs',
+      md: 'h-12 text-sm',
+      lg: 'h-14 text-base'
+    },
+    iconPosition: {
+      right: '',
+      left: ''
+    }
+  },
+  compoundVariants: [
+    { size: 'sm', iconPosition: 'right', class: 'ps-12 pe-4' },
+    { size: 'md', iconPosition: 'right', class: 'ps-14 pe-6' },
+    { size: 'lg', iconPosition: 'right', class: 'ps-16 pe-8' },
+    { size: 'sm', iconPosition: 'left', class: 'ps-4 pe-12' },
+    { size: 'md', iconPosition: 'left', class: 'ps-6 pe-14' },
+    { size: 'lg', iconPosition: 'left', class: 'ps-8 pe-16' }
+  ],
+  defaultVariants: {
+    variant: 'solid',
+    size: 'md',
+    iconPosition: 'right'
+  }
+})
+
+export const maskRevealButtonBadgeVariants = cva({
+  base: 'absolute z-10 flex items-center justify-center rounded-lg transition-all duration-500',
+  variants: {
+    variant: {
+      solid: 'bg-primary-comfy-ink text-primary-comfy-yellow',
+      ghost: 'bg-primary-comfy-yellow text-primary-comfy-ink'
+    },
+    size: {
+      sm: 'size-8',
+      md: 'size-10',
+      lg: 'size-12'
+    },
+    iconPosition: {
+      right: '',
+      left: ''
+    }
+  },
+  compoundVariants: [
+    {
+      size: 'sm',
+      iconPosition: 'right',
+      class: 'right-1 group-hover:right-[calc(100%-36px)]'
+    },
+    {
+      size: 'md',
+      iconPosition: 'right',
+      class: 'right-1 group-hover:right-[calc(100%-44px)]'
+    },
+    {
+      size: 'lg',
+      iconPosition: 'right',
+      class: 'right-1 group-hover:right-[calc(100%-52px)]'
+    },
+    {
+      size: 'sm',
+      iconPosition: 'left',
+      class: 'left-1 group-hover:left-[calc(100%-36px)]'
+    },
+    {
+      size: 'md',
+      iconPosition: 'left',
+      class: 'left-1 group-hover:left-[calc(100%-44px)]'
+    },
+    {
+      size: 'lg',
+      iconPosition: 'left',
+      class: 'left-1 group-hover:left-[calc(100%-52px)]'
+    }
+  ],
+  defaultVariants: {
+    variant: 'solid',
+    size: 'md',
+    iconPosition: 'right'
+  }
+})
+
+export const maskRevealLabelVariants = cva({
+  base: [
+    'relative inline-block align-baseline',
+    '[will-change:mask-size,-webkit-mask-size]',
+    '[mask-image:linear-gradient(black,black)] [-webkit-mask-image:linear-gradient(black,black)]',
+    'mask-no-repeat [-webkit-mask-repeat:no-repeat]',
+    'transition-[mask-size,-webkit-mask-size] duration-500 ease-in-out',
+    'data-[icon-position=right]:[mask-position:100%_0] data-[icon-position=right]:[-webkit-mask-position:100%_0]',
+    'data-[icon-position=left]:[mask-position:0_0] data-[icon-position=left]:[-webkit-mask-position:0_0]',
+    'data-[hidden=true]:[mask-size:0%_100%] data-[hidden=true]:[-webkit-mask-size:0%_100%]',
+    'data-[hidden=false]:[mask-size:100%_100%] data-[hidden=false]:[-webkit-mask-size:100%_100%]',
+    'group-hover:data-[hidden=true]:[mask-size:calc(100%_+_1px)_100%] group-hover:data-[hidden=true]:[-webkit-mask-size:calc(100%_+_1px)_100%]',
+    'group-focus-visible:data-[hidden=true]:[mask-size:calc(100%_+_1px)_100%] group-focus-visible:data-[hidden=true]:[-webkit-mask-size:calc(100%_+_1px)_100%]'
+  ].join(' ')
+})
+
+export type MaskRevealButtonVariants = VariantProps<
+  typeof maskRevealButtonVariants
+>

apps/website/src/components/common/pillButton.variants.ts

@@ -0,0 +1,116 @@
+import type { VariantProps } from 'cva'
+import { cva } from 'cva'
+
+export const pillButtonVariants = cva({
+  base: 'group relative inline-flex w-fit cursor-pointer items-center overflow-hidden rounded-lg p-1 font-bold text-nowrap transition-all duration-500 disabled:cursor-not-allowed disabled:opacity-50',
+  variants: {
+    variant: {
+      solid: 'bg-primary-comfy-yellow text-primary-comfy-ink',
+      ghost: 'text-primary-comfy-yellow bg-transparent'
+    },
+    size: {
+      sm: 'h-10 text-xs',
+      md: 'h-12 text-sm',
+      lg: 'h-14 text-base'
+    },
+    iconPosition: {
+      right: '',
+      left: ''
+    }
+  },
+  compoundVariants: [
+    {
+      size: 'sm',
+      iconPosition: 'right',
+      class: 'ps-4 pe-12 hover:ps-12 hover:pe-4'
+    },
+    {
+      size: 'md',
+      iconPosition: 'right',
+      class: 'ps-6 pe-14 hover:ps-14 hover:pe-6'
+    },
+    {
+      size: 'lg',
+      iconPosition: 'right',
+      class: 'ps-8 pe-16 hover:ps-16 hover:pe-8'
+    },
+    {
+      size: 'sm',
+      iconPosition: 'left',
+      class: 'ps-12 pe-4 hover:ps-4 hover:pe-12'
+    },
+    {
+      size: 'md',
+      iconPosition: 'left',
+      class: 'ps-14 pe-6 hover:ps-6 hover:pe-14'
+    },
+    {
+      size: 'lg',
+      iconPosition: 'left',
+      class: 'ps-16 pe-8 hover:ps-8 hover:pe-16'
+    }
+  ],
+  defaultVariants: {
+    variant: 'solid',
+    size: 'md',
+    iconPosition: 'right'
+  }
+})
+
+export const pillButtonBadgeVariants = cva({
+  base: 'absolute z-10 flex items-center justify-center rounded-lg transition-all duration-500',
+  variants: {
+    variant: {
+      solid: 'bg-primary-comfy-ink text-primary-comfy-yellow',
+      ghost: 'bg-primary-comfy-yellow text-primary-comfy-ink'
+    },
+    size: {
+      sm: 'size-8',
+      md: 'size-10',
+      lg: 'size-12'
+    },
+    iconPosition: {
+      right: '',
+      left: ''
+    }
+  },
+  compoundVariants: [
+    {
+      size: 'sm',
+      iconPosition: 'right',
+      class: 'right-1 group-hover:right-[calc(100%-36px)]'
+    },
+    {
+      size: 'md',
+      iconPosition: 'right',
+      class: 'right-1 group-hover:right-[calc(100%-44px)]'
+    },
+    {
+      size: 'lg',
+      iconPosition: 'right',
+      class: 'right-1 group-hover:right-[calc(100%-52px)]'
+    },
+    {
+      size: 'sm',
+      iconPosition: 'left',
+      class: 'left-1 group-hover:left-[calc(100%-36px)]'
+    },
+    {
+      size: 'md',
+      iconPosition: 'left',
+      class: 'left-1 group-hover:left-[calc(100%-44px)]'
+    },
+    {
+      size: 'lg',
+      iconPosition: 'left',
+      class: 'left-1 group-hover:left-[calc(100%-52px)]'
+    }
+  ],
+  defaultVariants: {
+    variant: 'solid',
+    size: 'md',
+    iconPosition: 'right'
+  }
+})
+
+export type PillButtonVariants = VariantProps<typeof pillButtonVariants>

apps/website/src/components/learning/FeaturedWorkflowSection.vue

@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import type { Locale } from '../../i18n/translations'
+
+import { t } from '../../i18n/translations'
+import Badge from '../common/Badge.vue'
+import BrandButton from '../common/BrandButton.vue'
+import VideoPlayer from '../common/VideoPlayer.vue'
+
+const { locale = 'en' } = defineProps<{ locale?: Locale }>()
+
+const tags = ['Seadance 2.0', 'Image To Video']
+const demoVideoSrc =
+  'https://media.comfy.org/website/learning/skyreplacement_smaller_v06.mp4'
+const demoVideoPoster =
+  'https://media.comfy.org/website/learning/skyreplacement_smaller_v06_thumbnail.jpg'
+</script>
+
+<template>
+  <section class="max-w-9xl mx-auto px-6 py-16 lg:py-24">
+    <div class="grid grid-cols-1 items-center gap-12 lg:grid-cols-2 lg:gap-16">
+      <div class="flex flex-col gap-8">
+        <div>
+          <h2
+            class="text-primary-comfy-canvas text-4xl font-light tracking-tight lg:text-6xl"
+          >
+            {{ t('learning.featured.title', locale) }}
+          </h2>
+          <p class="text-primary-warm-gray mt-4 text-sm lg:text-base">
+            {{ t('learning.featured.author', locale) }}
+          </p>
+        </div>
+
+        <p
+          class="text-primary-comfy-canvas max-w-md text-sm/relaxed lg:text-base"
+        >
+          {{ t('learning.featured.description', locale) }}
+        </p>
+
+        <div class="flex flex-wrap gap-3">
+          <BrandButton
+            variant="outline"
+            size="xs"
+            class="uppercase"
+            href="https://comfy.org/workflows/537cf7f1f745-537cf7f1f745/"
+          >
+            {{ t('cta.tryWorkflow', locale) }}
+          </BrandButton>
+        </div>
+
+        <ul class="mt-2 flex flex-wrap gap-3">
+          <li v-for="tag in tags" :key="tag">
+            <Badge variant="subtle">{{ tag }}</Badge>
+          </li>
+        </ul>
+      </div>
+
+      <div class="border-primary-warm-gray rounded-4.5xl border p-4">
+        <VideoPlayer
+          :locale
+          :src="demoVideoSrc"
+          :poster="demoVideoPoster"
+          minimal
+        />
+      </div>
+    </div>
+  </section>
+</template>

apps/website/src/components/learning/HeroSection.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import type { Locale } from '../../i18n/translations'
+
+import { t } from '../../i18n/translations'
+
+const { locale = 'en' } = defineProps<{ locale?: Locale }>()
+</script>
+
+<template>
+  <section
+    class="max-w-9xl mx-auto flex flex-col items-center px-6 pt-24 pb-12 text-center"
+  >
+    <h1
+      class="text-primary-comfy-canvas max-w-4xl text-3xl leading-[110%] font-light tracking-tight lg:text-5xl"
+    >
+      {{ t('learning.heroTitle.before', locale) }}
+      <span class="text-primary-comfy-yellow">ComfyUI</span
+      >{{ t('learning.heroTitle.after', locale) }}
+      <br />
+      {{ t('learning.heroTitle.line2', locale) }}
+    </h1>
+  </section>
+</template>

apps/website/src/components/learning/TutorialDetailDialog.vue

@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted, useTemplateRef, watch } from 'vue'
+
+import type { LearningTutorial } from '../../data/learningTutorials'
+import type { Locale } from '../../i18n/translations'
+
+import { lockScroll, unlockScroll } from '../../composables/scrollLock'
+import { t } from '../../i18n/translations'
+
+const { tutorial, locale = 'en' } = defineProps<{
+  tutorial: LearningTutorial
+  locale?: Locale
+}>()
+
+const emit = defineEmits<{ close: [] }>()
+
+const dialogRef = useTemplateRef<HTMLDialogElement>('dialogRef')
+const videoRef = useTemplateRef<HTMLVideoElement>('videoRef')
+
+const playFromStart = () => {
+  const video = videoRef.value
+  if (!video) return
+  video.currentTime = 0
+  void video.play().catch(() => {})
+}
+
+watch(
+  () => tutorial.id,
+  () => {
+    playFromStart()
+  }
+)
+
+function handleBackdropClick(e: MouseEvent) {
+  if (e.target === e.currentTarget) emit('close')
+}
+
+function handleKeydown(e: KeyboardEvent) {
+  if (e.key === 'Escape') emit('close')
+}
+
+onMounted(() => {
+  lockScroll()
+  dialogRef.value?.showModal()
+  playFromStart()
+})
+
+onUnmounted(() => {
+  unlockScroll()
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <dialog
+      ref="dialogRef"
+      :aria-label="tutorial.title[locale]"
+      class="fixed inset-0 z-50 flex size-full max-h-none max-w-none flex-col items-center justify-center border-0 bg-transparent px-4 py-8 backdrop-blur-xl backdrop:bg-transparent lg:px-20 lg:py-8"
+      @click="handleBackdropClick"
+      @keydown="handleKeydown"
+      @close="emit('close')"
+    >
+      <button
+        :aria-label="t('gallery.detail.close', locale)"
+        class="border-primary-comfy-yellow bg-primary-comfy-ink hover:bg-primary-comfy-yellow group absolute top-8 right-10 z-10 flex size-10 cursor-pointer items-center justify-center rounded-2xl border-2 transition-colors lg:right-26"
+        @click="emit('close')"
+      >
+        <span
+          class="bg-primary-comfy-yellow group-hover:bg-primary-comfy-ink size-5 transition-colors"
+          style="mask: url('/icons/close.svg') center / contain no-repeat"
+        />
+      </button>
+
+      <div
+        class="border-primary-comfy-yellow bg-primary-comfy-ink rounded-5xl flex w-full max-w-7xl items-center justify-center overflow-hidden border-2 p-3 lg:p-4"
+      >
+        <video
+          ref="videoRef"
+          :src="tutorial.videoSrc"
+          :poster="tutorial.poster"
+          class="aspect-video w-full rounded-3xl object-contain lg:rounded-4xl"
+          controls
+          autoplay
+          playsinline
+        ></video>
+      </div>
+
+      <h2
+        class="text-primary-comfy-canvas mt-6 text-center text-lg font-medium lg:text-xl"
+      >
+        {{ t('learning.tutorials.titlePrefix', locale) }}
+        {{ tutorial.title[locale] }}
+      </h2>
+    </dialog>
+  </Teleport>
+</template>

apps/website/src/components/learning/TutorialsSection.vue

@@ -0,0 +1,120 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+import type { Locale } from '../../i18n/translations'
+
+import {
+  getTutorialPosterSrc,
+  learningTutorials
+} from '../../data/learningTutorials'
+import { t } from '../../i18n/translations'
+import Badge from '../common/Badge.vue'
+import MaskRevealButton from '../common/MaskRevealButton.vue'
+import TutorialDetailDialog from './TutorialDetailDialog.vue'
+
+const { locale = 'en' } = defineProps<{ locale?: Locale }>()
+
+const activeTutorialId = ref<string | null>(null)
+const activeTutorial = () =>
+  learningTutorials.find((tutorial) => tutorial.id === activeTutorialId.value)
+</script>
+
+<template>
+  <section class="max-w-9xl mx-auto px-6 py-16 lg:py-24">
+    <h2
+      class="text-primary-comfy-canvas mb-12 text-4xl font-light tracking-tight lg:mb-16 lg:text-6xl"
+    >
+      {{ t('learning.tutorials.heading', locale) }}
+    </h2>
+
+    <ul
+      class="grid grid-cols-1 gap-x-6 gap-y-10 md:grid-cols-2 lg:grid-cols-3 lg:gap-x-8"
+    >
+      <li
+        v-for="tutorial in learningTutorials"
+        :key="tutorial.id"
+        class="bg-transparency-white-t4 flex flex-col gap-4 overflow-hidden rounded-3xl border-0 p-2"
+      >
+        <button
+          type="button"
+          class="group relative block aspect-video cursor-pointer overflow-hidden rounded-3xl"
+          :aria-label="`${t('learning.tutorials.titlePrefix', locale)} ${tutorial.title[locale]}`"
+          @click="activeTutorialId = tutorial.id"
+        >
+          <video
+            :src="getTutorialPosterSrc(tutorial)"
+            :poster="tutorial.poster"
+            class="size-full object-cover"
+            preload="metadata"
+            playsinline
+            muted
+          ></video>
+          <span
+            class="absolute inset-0 flex items-center justify-center"
+            aria-hidden="true"
+          >
+            <span
+              class="flex size-14 items-center justify-center rounded-full bg-white/25 backdrop-blur-sm transition-transform group-hover:scale-105 lg:size-16"
+            >
+              <svg
+                class="ml-1 size-5 text-white lg:size-6"
+                viewBox="0 0 24 24"
+                fill="currentColor"
+                aria-hidden="true"
+              >
+                <path d="M8 5v14l11-7z" />
+              </svg>
+            </span>
+          </span>
+        </button>
+
+        <div class="flex flex-col space-y-3 p-4">
+          <div class="flex items-center justify-between gap-4">
+            <h3
+              class="text-primary-comfy-canvas text-sm/snug lg:text-base/snug"
+            >
+              {{ t('learning.tutorials.titlePrefix', locale) }}<wbr />
+              {{ tutorial.title[locale] }}
+            </h3>
+            <MaskRevealButton
+              v-if="tutorial.href"
+              :href="tutorial.href"
+              icon-position="right"
+              class="shrink-0"
+              variant="ghost"
+              size="sm"
+            >
+              {{ t('cta.tryWorkflow', locale) }}
+              <template #icon>
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="3"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                  class="size-4"
+                >
+                  <polyline points="9 6 15 12 9 18" />
+                </svg>
+              </template>
+            </MaskRevealButton>
+          </div>
+
+          <ul class="flex flex-wrap gap-2">
+            <li v-for="tag in tutorial.tags" :key="tag">
+              <Badge>{{ t(tag, locale) }}</Badge>
+            </li>
+          </ul>
+        </div>
+      </li>
+    </ul>
+
+    <TutorialDetailDialog
+      v-if="activeTutorial()"
+      :tutorial="activeTutorial()!"
+      :locale="locale"
+      @close="activeTutorialId = null"
+    />
+  </section>
+</template>

apps/website/src/config/routes.ts

@@ -12,6 +12,7 @@ const baseRoutes = {
   careers: '/careers',
   customers: '/customers',
   demos: '/demos',
+  learning: '/learning',
   termsOfService: '/terms-of-service',
   privacyPolicy: '/privacy-policy',
   affiliates: '/affiliates',

apps/website/src/data/events.ts

@@ -0,0 +1,31 @@
+import type { EventItem } from '../components/common/EventsSection.vue'
+
+export const learningEvents: readonly EventItem[] = [
+  {
+    label: { en: 'Live Stream:', 'zh-CN': '直播：' },
+    title: {
+      en: 'Zero to Node: Building Your First Workflow',
+      'zh-CN': '从零到节点：构建你的第一个工作流'
+    },
+    cta: { en: 'Link', 'zh-CN': '链接' },
+    href: '#'
+  },
+  {
+    label: { en: 'Event 1', 'zh-CN': '活动 1' },
+    title: {
+      en: 'Lorem ipsum dollar sita met',
+      'zh-CN': '此处为活动描述的占位文本'
+    },
+    cta: { en: 'London, UK', 'zh-CN': '英国伦敦' },
+    href: '#'
+  },
+  {
+    label: { en: 'Event 2', 'zh-CN': '活动 2' },
+    title: {
+      en: 'Lorem ipsum dollar sita met',
+      'zh-CN': '此处为活动描述的占位文本'
+    },
+    cta: { en: 'San Francisco', 'zh-CN': '旧金山' },
+    href: '#'
+  }
+] as const

apps/website/src/data/learningTutorials.ts

@@ -0,0 +1,84 @@
+import type { LocalizedText, TranslationKey } from '../i18n/translations'
+
+export interface LearningTutorial {
+  id: string
+  tags: readonly TranslationKey[]
+  title: LocalizedText
+  videoSrc: string
+  href?: string
+  poster?: string
+  posterTime?: number
+}
+
+const DEFAULT_POSTER_TIME_SECONDS = 1
+
+const partnerNodesTag: TranslationKey = 'tags.partnerNodes'
+const imageToVideoTag: TranslationKey = 'tags.imageToVideo'
+
+export const getTutorialPosterSrc = (tutorial: LearningTutorial): string =>
+  tutorial.poster
+    ? tutorial.poster
+    : `${tutorial.videoSrc}#t=${tutorial.posterTime ?? DEFAULT_POSTER_TIME_SECONDS}`
+
+export const learningTutorials: readonly LearningTutorial[] = [
+  {
+    id: 'cleanplate_walkthrough_v03',
+    title: { en: 'Cleanplate Walkthrough', 'zh-CN': '净板演练' },
+    videoSrc:
+      'https://media.comfy.org/website/learning/cleanplate_walkthrough_v03.mp4',
+    poster:
+      'https://media.comfy.org/website/learning/cleanplate_walkthrough_v03_thumbnail.jpg',
+    // href: '#',
+    tags: [partnerNodesTag, imageToVideoTag]
+  },
+  {
+    id: 'deaging_workflow_v03',
+    title: { en: 'Deaging Workflow', 'zh-CN': '减龄工作流' },
+    videoSrc:
+      'https://media.comfy.org/website/learning/deaging_workflow_v03.mp4',
+    poster:
+      'https://media.comfy.org/website/learning/deaging_workflow_v03_thumbnail.jpg',
+    href: 'https://cloud.comfy.org/?share=93f286fbc2c8',
+    tags: [partnerNodesTag, imageToVideoTag]
+  },
+  {
+    id: 'frame_adjustments_demo_v03',
+    title: { en: 'Frame Adjustments Demo', 'zh-CN': '帧调整演示' },
+    videoSrc:
+      'https://media.comfy.org/website/learning/frame_adjustments_demo_v03.mp4',
+    poster:
+      'https://media.comfy.org/website/learning/frame_adjustments_demo_v03_thumbnail.jpg',
+    href: 'https://cloud.comfy.org/?share=7dca0438edf4',
+    tags: [partnerNodesTag, imageToVideoTag]
+  },
+  {
+    id: 'mattes_and_utilities_v03',
+    title: { en: 'Mattes and Utilities', 'zh-CN': '遮罩与实用工具' },
+    videoSrc:
+      'https://media.comfy.org/website/learning/mattes_and_utilities_v03.mp4',
+    poster:
+      'https://media.comfy.org/website/learning/mattes_and_utilities_v03_thumbnail.jpg',
+    href: 'https://cloud.comfy.org/?share=be0889296f65',
+    tags: [partnerNodesTag, imageToVideoTag]
+  },
+  {
+    id: 'seedance_demo_comfyui_v03',
+    title: { en: 'Seedance Demo ComfyUI', 'zh-CN': 'Seedance ComfyUI 演示' },
+    videoSrc:
+      'https://media.comfy.org/website/learning/seedance_demo_comfyui_v03.mp4',
+    poster:
+      'https://media.comfy.org/website/learning/seedance seedance_demo_comfyui_v03_thumbnail.jpg',
+    href: 'https://cloud.comfy.org/?share=ef543bd4a773',
+    tags: [partnerNodesTag, imageToVideoTag]
+  },
+  {
+    id: 'skyreplacement_smaller_v06',
+    title: { en: 'Sky Replacement', 'zh-CN': '天空替换' },
+    videoSrc:
+      'https://media.comfy.org/website/learning/skyreplacement_smaller_v06.mp4',
+    poster:
+      'https://media.comfy.org/website/learning/skyreplacement_smaller_v06_thumbnail.jpg',
+    href: 'https://comfy.org/workflows/537cf7f1f745-537cf7f1f745/',
+    tags: [partnerNodesTag, imageToVideoTag]
+  }
+] as const

apps/website/src/i18n/translations.ts

@@ -1,6 +1,22 @@
 type Locale = 'en' | 'zh-CN'
 
 const translations = {
+  // Tags (global, reusable across sections)
+  'tags.partnerNodes': {
+    en: 'Partner Nodes',
+    'zh-CN': '合作伙伴节点'
+  },
+  'tags.imageToVideo': {
+    en: 'Image To Video',
+    'zh-CN': '图像生成视频'
+  },
+
+  // CTAs (global, reusable across sections)
+  'cta.tryWorkflow': {
+    en: 'Try Workflow',
+    'zh-CN': '试用工作流'
+  },
+
   // HeroSection
   'hero.title': {
     en: 'Professional Control\nof Visual AI',
@@ -1435,6 +1451,62 @@ const translations = {
   'player.subtitlesOn': { en: 'Subtitles on', 'zh-CN': '开启字幕' },
   'player.subtitlesOff': { en: 'Subtitles off', 'zh-CN': '关闭字幕' },
 
+  // LearningHeroSection
+  'learning.heroTitle.before': { en: 'Learn', 'zh-CN': '学习' },
+  'learning.heroTitle.after': { en: '.', 'zh-CN': '。' },
+  'learning.heroTitle.line2': {
+    en: 'Build what doesn’t exist yet.',
+    'zh-CN': '构建尚未存在之物。'
+  },
+
+  // LearningFeaturedWorkflowSection
+  'learning.featured.title': {
+    en: 'Sky Replacement',
+    'zh-CN': '天空替换'
+  },
+  'learning.featured.author': {
+    en: 'by Doug Hogan',
+    'zh-CN': '作者：Doug Hogan'
+  },
+  'learning.featured.description': {
+    en: 'A sky replacement workflow built on Wan AI models. WanVideoSampler and WanVideoDecode synthesize new sky visuals into existing footage. CLIPVisionLoader and WanVideoClipVisionEncode ensure replacements feel native, not composited.',
+    'zh-CN':
+      '基于 Wan AI 模型构建的天空替换工作流。WanVideoSampler 与 WanVideoDecode 将全新的天空视觉合成到现有素材中。CLIPVisionLoader 与 WanVideoClipVisionEncode 确保替换效果自然融合，而非生硬叠加。'
+  },
+  'learning.featured.watchDemo': {
+    en: 'Watch Demo',
+    'zh-CN': '观看演示'
+  },
+
+  // LearningTutorialsSection
+  'learning.tutorials.heading': {
+    en: 'Featured Demos',
+    'zh-CN': '精选演示'
+  },
+  'learning.tutorials.titlePrefix': {
+    en: 'Learn how to:',
+    'zh-CN': '学习如何：'
+  },
+
+  // LearningCallToActionSection
+  'learning.cta.heading': {
+    en: 'Schedule a demo and see how ComfyUI fits your team’s creative needs.',
+    'zh-CN': '预约演示，了解 ComfyUI 如何契合你的团队创作需求。'
+  },
+  'learning.cta.contactSales': {
+    en: 'Contact Sales',
+    'zh-CN': '联系销售'
+  },
+
+  // LearningEventsSection
+  'learning.events.heading': { en: 'Events', 'zh-CN': '活动' },
+  'learning.events.description': {
+    en: 'Check out our upcoming live streams and community meetings. We’re always open to your questions, ideas, and conversations.',
+    'zh-CN':
+      '查看我们即将举办的直播和社区聚会。我们随时欢迎你的提问、想法和交流。'
+  },
+  'learning.events.getNotified': { en: 'Get Notified', 'zh-CN': '获取通知' },
+
   // GalleryHeroSection
   'gallery.label': { en: 'GALLERY', 'zh-CN': '画廊' },
   'gallery.heroTitle.before': {
@@ -1471,9 +1543,13 @@ const translations = {
   },
   'about.hero.body': {
     en: 'The team behind Comfy is small, intense, and building what we intend to be our life\u2019s work.',
-    'zh-CN': 'Comfy 背后的团队规模虽小，但充满热情，致力于打造我们毕生的事业。'
+    'zh-CN':
+      'Comfy \u80cc\u540e\u7684\u56e2\u961f\u89c4\u6a21\u867d\u5c0f\uff0c\u4f46\u5145\u6ee1\u70ed\u60c5\uff0c\u81f4\u529b\u4e8e\u6253\u9020\u6211\u4eec\u6bd5\u751f\u7684\u4e8b\u4e1a\u3002'
+  },
+  'about.hero.cta': {
+    en: 'SEE OPEN ROLES',
+    'zh-CN': '\u67e5\u770b\u5f00\u653e\u804c\u4f4d'
   },
-  'about.hero.cta': { en: 'SEE OPEN ROLES', 'zh-CN': '查看开放职位' },
 
   // AboutStorySection
   'about.story.label': { en: 'OUR STORY', 'zh-CN': '我们的故事' },
@@ -1743,6 +1819,7 @@ const translations = {
   },
   'nav.comfyHub': { en: 'Comfy Hub', 'zh-CN': 'Comfy Hub' },
   'nav.gallery': { en: 'Gallery', 'zh-CN': '画廊' },
+  'nav.learning': { en: 'Learning', 'zh-CN': '学习' },
   'nav.blogs': { en: 'Blog', 'zh-CN': '博客' },
   'nav.github': { en: 'GitHub', 'zh-CN': 'GitHub' },
   'nav.discord': { en: 'Discord', 'zh-CN': 'Discord' },
@@ -4736,6 +4813,8 @@ const translations = {
 
 type TranslationKey = keyof typeof translations
 
+type LocalizedText = Record<Locale, string>
+
 export function t(key: TranslationKey, locale: Locale = 'en'): string {
   return translations[key][locale] ?? translations[key].en
 }
@@ -4746,4 +4825,4 @@ export function hasKey(key: string): boolean {
   return key in translations
 }
 
-export type { Locale, TranslationKey }
+export type { Locale, LocalizedText, TranslationKey }

apps/website/src/pages/learning.astro

@@ -0,0 +1,27 @@
+---
+import BaseLayout from '../layouts/BaseLayout.astro'
+import HeroSection from '../components/learning/HeroSection.vue'
+import FeaturedWorkflowSection from '../components/learning/FeaturedWorkflowSection.vue'
+import TutorialsSection from '../components/learning/TutorialsSection.vue'
+import CallToActionSection from '../components/common/CallToActionSection.vue'
+// import EventsSection from '../components/common/EventsSection.vue'
+import { getRoutes } from '../config/routes'
+import { externalLinks } from '../config/routes'
+// import { learningEvents } from '../data/events'
+
+const routes = getRoutes('en')
+---
+
+<BaseLayout title="Learning — Comfy">
+  <HeroSection client:load />
+  <FeaturedWorkflowSection client:visible />
+  <TutorialsSection client:visible />
+  <CallToActionSection
+    headingKey="learning.cta.heading"
+    primaryLabelKey="learning.cta.contactSales"
+    primaryHref={routes.contact}
+    secondaryLabelKey="cta.tryWorkflow"
+    secondaryHref={externalLinks.workflows}
+    client:visible
+  />
+</BaseLayout>

apps/website/src/pages/zh-CN/learning.astro

@@ -0,0 +1,27 @@
+---
+import BaseLayout from '../../layouts/BaseLayout.astro'
+import HeroSection from '../../components/learning/HeroSection.vue'
+import FeaturedWorkflowSection from '../../components/learning/FeaturedWorkflowSection.vue'
+import TutorialsSection from '../../components/learning/TutorialsSection.vue'
+import CallToActionSection from '../../components/common/CallToActionSection.vue'
+import EventsSection from '../../components/common/EventsSection.vue'
+import { getRoutes, externalLinks } from '../../config/routes'
+import { learningEvents } from '../../data/events'
+
+const routes = getRoutes('zh-CN')
+---
+
+<BaseLayout title="学习 — Comfy">
+  <HeroSection locale="zh-CN" client:load />
+  <FeaturedWorkflowSection locale="zh-CN" client:visible />
+  <TutorialsSection locale="zh-CN" client:visible />
+  <CallToActionSection
+    locale="zh-CN"
+    headingKey="learning.cta.heading"
+    primaryLabelKey="learning.cta.contactSales"
+    primaryHref={routes.contact}
+    secondaryLabelKey="cta.tryWorkflow"
+    secondaryHref={externalLinks.workflows}
+    client:visible
+  />
+</BaseLayout>

browser_tests/fixtures/utils/boundsUtils.ts

@@ -1,4 +1,4 @@
-import type { Page } from '@playwright/test'
+import type { Locator, Page } from '@playwright/test'
 
 import { SELECTION_BOUNDS_PADDING } from '@/base/common/selectionBounds'
 import type { CanvasRect } from '@/base/common/selectionBounds'
@@ -91,3 +91,21 @@ export async function measureSelectionBounds(
     { ids: nodeIds, padding: SELECTION_BOUNDS_PADDING }
   ) as Promise<MeasureResult>
 }
+
+export async function intersection(a: Locator, b: Locator) {
+  const aBounds = await a.boundingBox()
+  const bBounds = await b.boundingBox()
+  if (!aBounds || !bBounds) return undefined
+
+  const y = Math.max(aBounds.y, bBounds.y)
+  const x = Math.max(aBounds.x, bBounds.x)
+  const bot = Math.min(aBounds.y + aBounds.height, bBounds.y + bBounds.height)
+  const right = Math.min(aBounds.x + aBounds.width, bBounds.x + bBounds.width)
+
+  if (y > bot || x > right) return undefined
+
+  const width = right - x
+  const height = bot - y
+
+  return { x, y, width, height }
+}

browser_tests/tests/load3d/load3dSerializeCache.spec.ts

@@ -1,63 +0,0 @@
-import { expect } from '@playwright/test'
-
-import { ExecutionHelper } from '@e2e/fixtures/helpers/ExecutionHelper'
-import { load3dTest as test } from '@e2e/fixtures/helpers/Load3DFixtures'
-
-type Load3dImageInput = {
-  image: string
-  mask: string
-  normal: string
-  recording: string
-}
-
-type PromptBody = {
-  prompt?: Record<
-    string,
-    { class_type?: string; inputs?: Record<string, unknown> }
-  >
-}
-
-function getLoad3dImageInput(body: unknown, nodeId: string): Load3dImageInput {
-  const prompt = (body as PromptBody).prompt ?? {}
-  const node = prompt[nodeId]
-  expect(node?.class_type, `node ${nodeId} should be Load3D`).toBe('Load3D')
-  const input = node!.inputs!.image as Load3dImageInput
-  expect(typeof input.image).toBe('string')
-  expect(typeof input.recording).toBe('string')
-  return input
-}
-
-test.describe('Load3D serialize cache', () => {
-  test('starting a recording forces the next queue to re-capture (FE-905)', async ({
-    comfyPage,
-    load3d
-  }) => {
-    const exec = new ExecutionHelper(comfyPage)
-
-    let firstBody: unknown
-    await exec.run({
-      onPromptRequest: (body) => {
-        firstBody = body
-      }
-    })
-    const firstInput = getLoad3dImageInput(firstBody, '1')
-    expect(firstInput.recording).toBe('')
-
-    await load3d.recordingButton.click()
-    await expect(load3d.stopRecordingButton).toBeVisible()
-
-    let secondBody: unknown
-    await exec.run({
-      onPromptRequest: (body) => {
-        secondBody = body
-      }
-    })
-    const secondInput = getLoad3dImageInput(secondBody, '1')
-
-    expect(
-      secondInput.image,
-      'after starting a recording, the next queue must re-capture ' +
-        '(image filename must change) so the recording is not dropped'
-    ).not.toBe(firstInput.image)
-  })
-})

browser_tests/tests/vueNodes/interactions/node/imagePreview.spec.ts

@@ -180,4 +180,44 @@ test.describe('Vue Nodes Batch Image Preview', { tag: '@vue-nodes' }, () => {
       await expect.poll(() => countColumns(node.imageGrid)).toBeLessThan(10)
     }
   )
+
+  wstest(
+    'requests lightweight thumbnail URLs for grid cells',
+    async ({ comfyPage, getWebSocket }) => {
+      const execution = new ExecutionHelper(comfyPage, await getWebSocket())
+
+      await test.step('Add node', async () => {
+        await comfyPage.menu.topbar.newWorkflowButton.click()
+        await comfyPage.nextFrame()
+
+        await comfyPage.searchBoxV2.addNode('Preview Image')
+        const previewImage = comfyPage.vueNodes.getNodeByTitle('Preview Image')
+        await expect(previewImage).toBeVisible()
+      })
+
+      const node = await comfyPage.vueNodes.getFixtureByTitle('Preview Image')
+      const gridImages = node.imageGrid.locator('img')
+
+      await test.step('Inject a multi-image grid', async () => {
+        const images = Array.from({ length: 4 }, (_, index) => ({
+          filename: `grid-${index}.png`,
+          subfolder: '',
+          type: 'output'
+        }))
+        execution.executed('', '1', { images })
+        await expect(gridImages).toHaveCount(4)
+      })
+
+      // FE-741: small on-node grid cells must request a server re-encoded
+      // thumbnail (`preview=webp;75`, `;` may be percent-encoded) instead of
+      // downloading the full-resolution image, while still pointing at the
+      // real `/api/view` URL for that output. Verifies the full path: WS
+      // output -> nodeOutputStore.buildImageUrls -> getGridThumbnailUrl ->
+      // rendered grid `<img>`.
+      for (const cell of await gridImages.all()) {
+        await expect(cell).toHaveAttribute('src', /[?&]preview=webp(%3B|;)75/)
+        await expect(cell).toHaveAttribute('src', /[?&]filename=grid-\d+\.png/)
+      }
+    }
+  )
 })

browser_tests/tests/vueNodes/widgets/combo/comboWidget.spec.ts

@@ -1,10 +1,12 @@
+import type { Locator } from '@playwright/test'
+
 import {
   comfyExpect as expect,
   comfyPageFixture as test
 } from '@e2e/fixtures/ComfyPage'
 import { TestIds } from '@e2e/fixtures/selectors'
 import type { ComfyPage } from '@e2e/fixtures/ComfyPage'
-import type { Locator } from '@playwright/test'
+import { intersection } from '@e2e/fixtures/utils/boundsUtils'
 
 test.describe('Vue Combo Widget', { tag: ['@vue-nodes', '@widget'] }, () => {
   async function openSamplerDropdown(comfyPage: ComfyPage) {
@@ -278,4 +280,31 @@ test.describe('Vue Combo Widget', { tag: ['@vue-nodes', '@widget'] }, () => {
       .getByRole('combobox', { name: 'scheduler', exact: true })
     await expect(schedulerComboAfterReload).toContainText('karras')
   })
+
+  test('Dropdown displays over Selection Toolbox', async ({ comfyPage }) => {
+    await comfyPage.settings.setSetting('Comfy.Canvas.SelectionToolbox', true)
+
+    const nodeName = 'Resize Image/Mask'
+    await comfyPage.searchBoxV2.addNode(nodeName, {
+      position: { x: 200, y: 630 }
+    })
+    const node = await comfyPage.vueNodes.getFixtureByTitle(nodeName)
+    await node.select()
+    await expect(comfyPage.selectionToolbox).toBeVisible()
+
+    const combo = comfyPage.vueNodes.getWidgetByName(nodeName, 'resize_type')
+    await combo.click()
+    const dropdown = comfyPage.page.getByTestId(
+      TestIds.widgets.selectDefaultViewport
+    )
+    await expect(dropdown).toBeVisible()
+
+    const bounds = (await intersection(dropdown, comfyPage.selectionToolbox))!
+    expect(bounds, 'toolbox and dropdown overlap').toBeDefined()
+    const cX = bounds.x + bounds.width / 2
+    const cY = bounds.y + bounds.height / 2
+    const dropdownBounds = (await dropdown.boundingBox())!
+    const position = { x: cX - dropdownBounds.x, y: cY - dropdownBounds.y }
+    await dropdown.click({ position, trial: true })
+  })
 })

src/components/builder/AppModeWidgetList.vue

@@ -8,7 +8,6 @@ import { useI18n } from 'vue-i18n'
 import Popover from '@/components/ui/Popover.vue'
 import Button from '@/components/ui/button/Button.vue'
 import { extractVueNodeData } from '@/composables/graph/useGraphNodeManager'
-import { OverlayAppendToKey } from '@/composables/useTransformCompatOverlayProps'
 import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
 import { LGraphEventMode } from '@/lib/litegraph/src/types/globalEnums'
 import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
@@ -50,7 +49,6 @@ const { onPointerDown } = useAppModeWidgetResizing((widget, config) =>
 )
 
 provide(HideLayoutFieldKey, true)
-provide(OverlayAppendToKey, 'body')
 
 const resolvedInputs = useResolvedSelectedInputs()
 

src/components/graph/SelectionToolbox.vue

@@ -20,6 +20,7 @@
         <InfoButton v-if="canOpenNodeInfo" />
 
         <ColorPickerButton v-if="showColorPicker" />
+        <ArrangeButton v-if="showArrange" />
         <FrameNodes v-if="showFrameNodes" />
         <ConvertToSubgraphButton v-if="showConvertToSubgraph" />
         <ConfigureSubgraph v-if="showSubgraphButtons" />
@@ -49,6 +50,7 @@
 import Panel from 'primevue/panel'
 import { computed, ref } from 'vue'
 
+import ArrangeButton from '@/components/graph/selectionToolbox/ArrangeButton.vue'
 import BypassButton from '@/components/graph/selectionToolbox/BypassButton.vue'
 import ColorPickerButton from '@/components/graph/selectionToolbox/ColorPickerButton.vue'
 import ConfigureSubgraph from '@/components/graph/selectionToolbox/ConfigureSubgraph.vue'
@@ -110,6 +112,7 @@ const {
 
 const showColorPicker = computed(() => hasAnySelection.value)
 const showConvertToSubgraph = computed(() => hasAnySelection.value)
+const showArrange = computed(() => hasMultipleSelection.value)
 const showFrameNodes = computed(() => hasMultipleSelection.value)
 const showSubgraphButtons = computed(() => isSingleSubgraph.value)
 
@@ -128,6 +131,7 @@ const showAnyPrimaryActions = computed(
   () =>
     showColorPicker.value ||
     showConvertToSubgraph.value ||
+    showArrange.value ||
     showFrameNodes.value ||
     showSubgraphButtons.value
 )

src/components/graph/selectionToolbox/ArrangeButton.vue

@@ -0,0 +1,115 @@
+<template>
+  <PopoverRoot v-model:open="isOpen">
+    <PopoverTrigger as-child>
+      <Button
+        v-tooltip.top="{ value: t('g.arrange'), showDelay: 1000 }"
+        variant="muted-textonly"
+        :aria-label="t('g.arrange')"
+      >
+        <div class="flex items-center gap-1 px-0">
+          <i class="icon-[lucide--layout-grid]" />
+          <i class="icon-[lucide--chevron-down]" />
+        </div>
+      </Button>
+    </PopoverTrigger>
+    <PopoverPortal>
+      <PopoverContent
+        side="bottom"
+        :side-offset="5"
+        :collision-padding="10"
+        class="data-[state=open]:data-[side=top]:animate-slideDownAndFade data-[state=open]:data-[side=right]:animate-slideLeftAndFade data-[state=open]:data-[side=bottom]:animate-slideUpAndFade data-[state=open]:data-[side=left]:animate-slideRightAndFade z-1700 rounded-lg border border-border-subtle bg-base-background p-2 shadow-sm will-change-[transform,opacity]"
+      >
+        <div
+          v-if="activeLayout"
+          class="flex w-32 flex-row items-center px-2 py-1"
+        >
+          <Slider
+            :model-value="[gap]"
+            :min="MIN_ARRANGE_GAP"
+            :max="MAX_ARRANGE_GAP"
+            :step="1"
+            :aria-label="t('g.arrangeSpacing')"
+            @update:model-value="onSliderUpdate"
+            @value-commit="onSliderCommit"
+          />
+        </div>
+        <div v-else class="flex flex-row gap-1">
+          <Button
+            v-tooltip.top="{
+              value: t('g.arrangeVertically'),
+              showDelay: 1000
+            }"
+            variant="muted-textonly"
+            :aria-label="t('g.arrangeVertically')"
+            @click="start('vertical')"
+          >
+            <i class="icon-[lucide--stretch-horizontal]" />
+          </Button>
+          <Button
+            v-tooltip.top="{
+              value: t('g.arrangeHorizontally'),
+              showDelay: 1000
+            }"
+            variant="muted-textonly"
+            :aria-label="t('g.arrangeHorizontally')"
+            @click="start('horizontal')"
+          >
+            <i class="icon-[lucide--stretch-vertical]" />
+          </Button>
+          <Button
+            v-tooltip.top="{ value: t('g.arrangeAsGrid'), showDelay: 1000 }"
+            variant="muted-textonly"
+            :aria-label="t('g.arrangeAsGrid')"
+            @click="start('grid')"
+          >
+            <i class="icon-[lucide--grid-3x3]" />
+          </Button>
+        </div>
+        <PopoverArrow class="fill-base-background stroke-border-subtle" />
+      </PopoverContent>
+    </PopoverPortal>
+  </PopoverRoot>
+</template>
+
+<script setup lang="ts">
+import {
+  PopoverArrow,
+  PopoverContent,
+  PopoverPortal,
+  PopoverRoot,
+  PopoverTrigger
+} from 'reka-ui'
+import { ref, watch } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import Button from '@/components/ui/button/Button.vue'
+import Slider from '@/components/ui/slider/Slider.vue'
+import {
+  MAX_ARRANGE_GAP,
+  MIN_ARRANGE_GAP
+} from '@/composables/graph/useArrangeNodes'
+import { useArrangeSession } from '@/composables/graph/useArrangeSession'
+
+const { t } = useI18n()
+const { activeLayout, gap, start, previewGap, commitGap, reset } =
+  useArrangeSession()
+
+const isOpen = ref(false)
+
+watch(isOpen, (open) => {
+  if (!open) reset()
+})
+
+const firstValue = (value: number[] | undefined): number | undefined =>
+  value?.[0]
+
+const onSliderUpdate = (value: number[] | undefined) => {
+  const next = firstValue(value)
+  if (next !== undefined) previewGap(next)
+}
+
+const onSliderCommit = (value: number[]) => {
+  const next = firstValue(value)
+  if (next !== undefined) commitGap(next)
+}
+</script>

src/composables/graph/useArrangeNodes.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest'
+
+import { computeArrangement } from '@/composables/graph/useArrangeNodes'
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import { TitleMode } from '@/lib/litegraph/src/types/globalEnums'
+
+interface MockNodeSpec {
+  id: number | string
+  pos: [number, number]
+  size: [number, number]
+  title_mode?: TitleMode
+}
+
+const makeNode = (spec: MockNodeSpec): LGraphNode =>
+  ({
+    id: spec.id,
+    pos: spec.pos,
+    size: spec.size,
+    title_mode: spec.title_mode
+  }) as unknown as LGraphNode
+
+const GAP = 12
+const TITLE = 30 // LiteGraph.NODE_TITLE_HEIGHT default
+
+describe('computeArrangement', () => {
+  it('returns no updates when fewer than 2 nodes are selected', () => {
+    expect(computeArrangement([], 'vertical')).toEqual([])
+    expect(
+      computeArrangement(
+        [makeNode({ id: 1, pos: [0, 0], size: [100, 50] })],
+        'grid'
+      )
+    ).toEqual([])
+  })
+
+  describe('vertical', () => {
+    it('left-aligns to anchor x and stacks downward sorted by current y', () => {
+      const nodes = [
+        makeNode({ id: 'a', pos: [10, 100], size: [100, 50] }),
+        makeNode({ id: 'b', pos: [200, 0], size: [80, 30] }),
+        makeNode({ id: 'c', pos: [50, 200], size: [120, 40] })
+      ]
+      // Anchor: 'a' has smallest x+y (110). Sort by Y: b(0), a(100), c(200).
+      // Visual top of layout = anchor.posY - TITLE = 100 - 30 = 70.
+      // Each node's pos.y = visualTop + its titleHeight (30).
+      // b: pos.y = 70+30 = 100; visualTop += (30+30)+12 = 142
+      // a: pos.y = 142+30 = 172; visualTop += (50+30)+12 = 234
+      // c: pos.y = 234+30 = 264
+      const result = computeArrangement(nodes, 'vertical')
+      expect(result).toEqual([
+        { nodeId: 'b', position: { x: 10, y: 100 } },
+        { nodeId: 'a', position: { x: 10, y: 172 } },
+        { nodeId: 'c', position: { x: 10, y: 264 } }
+      ])
+    })
+
+    it('omits the title-height contribution for NO_TITLE nodes', () => {
+      const nodes = [
+        makeNode({
+          id: 1,
+          pos: [0, 0],
+          size: [100, 100],
+          title_mode: TitleMode.NO_TITLE
+        }),
+        makeNode({
+          id: 2,
+          pos: [0, 200],
+          size: [100, 100],
+          title_mode: TitleMode.NO_TITLE
+        })
+      ]
+      // No titles: visualHeight = size[1] = 100. visualTop = 0. Gap = 12.
+      // 1: pos.y = 0; visualTop = 0 + 100 + 12 = 112.
+      // 2: pos.y = 112.
+      const result = computeArrangement(nodes, 'vertical')
+      expect(result).toEqual([
+        { nodeId: 1, position: { x: 0, y: 0 } },
+        { nodeId: 2, position: { x: 0, y: 100 + GAP } }
+      ])
+    })
+
+    it('preserves heterogeneous heights when computing gaps', () => {
+      const nodes = [
+        makeNode({ id: 1, pos: [0, 0], size: [100, 200] }),
+        makeNode({ id: 2, pos: [0, 50], size: [100, 50] })
+      ]
+      // visualTop=-30. 1: pos.y=0; visualTop += (200+30)+12 = 212.
+      // 2: pos.y = 212+30 = 242.
+      const result = computeArrangement(nodes, 'vertical')
+      expect(result).toEqual([
+        { nodeId: 1, position: { x: 0, y: 0 } },
+        { nodeId: 2, position: { x: 0, y: 200 + TITLE + GAP } }
+      ])
+    })
+  })
+
+  describe('horizontal', () => {
+    it('top-aligns to anchor y and lays out rightward sorted by current x', () => {
+      const nodes = [
+        makeNode({ id: 'a', pos: [100, 50], size: [80, 40] }),
+        makeNode({ id: 'b', pos: [0, 200], size: [60, 30] }),
+        makeNode({ id: 'c', pos: [300, 80], size: [50, 50] })
+      ]
+      // Anchor: smallest x+y → a(150), b(200), c(380) → anchor 'a' at (100, 50).
+      // Sort by X: b(0), a(100), c(300)
+      // Lay out from (100, 50):
+      //   b at (100, 50)
+      //   a at (100 + 60 + 12, 50) = (172, 50)
+      //   c at (172 + 80 + 12, 50) = (264, 50)
+      const result = computeArrangement(nodes, 'horizontal')
+      expect(result).toEqual([
+        { nodeId: 'b', position: { x: 100, y: 50 } },
+        { nodeId: 'a', position: { x: 172, y: 50 } },
+        { nodeId: 'c', position: { x: 264, y: 50 } }
+      ])
+    })
+  })
+
+  describe('grid', () => {
+    it('lays out 4 nodes as 2x2 with column/row sizes from max width/height', () => {
+      const nodes = [
+        makeNode({ id: 1, pos: [0, 0], size: [100, 50] }),
+        makeNode({ id: 2, pos: [200, 0], size: [80, 60] }),
+        makeNode({ id: 3, pos: [0, 100], size: [120, 40] }),
+        makeNode({ id: 4, pos: [200, 100], size: [90, 30] })
+      ]
+      // Anchor: 1 at (0,0). Sort by Y then X: 1, 2, 3, 4. cols=2, rows=2.
+      // Col widths: col0=max(100,120)=120; col1=max(80,90)=90.
+      // Row visual heights: row0=max(50+30,60+30)=90; row1=max(40+30,30+30)=70.
+      // colX=[0, 132]. rowVisualTop=[-30, -30+90+12=72].
+      // pos.y = rowVisualTop + 30 (titleHeight).
+      const result = computeArrangement(nodes, 'grid')
+      expect(result).toEqual([
+        { nodeId: 1, position: { x: 0, y: 0 } },
+        { nodeId: 2, position: { x: 132, y: 0 } },
+        { nodeId: 3, position: { x: 0, y: 102 } },
+        { nodeId: 4, position: { x: 132, y: 102 } }
+      ])
+    })
+
+    it('uses ceil(sqrt(n)) columns for non-square counts', () => {
+      // 5 nodes → ceil(sqrt(5))=3 cols, 2 rows. Last cell empty.
+      const nodes = Array.from({ length: 5 }, (_, i) =>
+        makeNode({
+          id: i + 1,
+          pos: [i * 50, i * 50],
+          size: [40, 40]
+        })
+      )
+      const result = computeArrangement(nodes, 'grid')
+      expect(result).toHaveLength(5)
+      // Sorted by Y then X = original order. Anchor = node 1 at (0,0).
+      // colWidths=[40,40,40]. rowVisualHeight = 40+30 = 70 each.
+      // colX=[0,52,104]. rowVisualTop=[-30, -30+70+12=52]. pos.y = visualTop+30.
+      expect(result[0].position).toEqual({ x: 0, y: 0 })
+      expect(result[1].position).toEqual({ x: 52, y: 0 })
+      expect(result[2].position).toEqual({ x: 104, y: 0 })
+      expect(result[3].position).toEqual({ x: 0, y: 82 })
+      expect(result[4].position).toEqual({ x: 52, y: 82 })
+    })
+  })
+
+  describe('anchor selection', () => {
+    it('picks the node with smallest x+y, not min-x or min-y alone', () => {
+      const nodes = [
+        // min y but large x: x+y = 1000
+        makeNode({ id: 'minY', pos: [1000, 0], size: [50, 50] }),
+        // min x but large y: x+y = 1000
+        makeNode({ id: 'minX', pos: [0, 1000], size: [50, 50] }),
+        // smallest x+y: 600
+        makeNode({ id: 'anchor', pos: [300, 300], size: [50, 50] })
+      ]
+      const result = computeArrangement(nodes, 'vertical')
+      // All updates left-align to anchor.x = 300. First in sort = minY (y=0).
+      expect(result[0]).toEqual({
+        nodeId: 'minY',
+        position: { x: 300, y: 300 }
+      })
+      expect(result.every((u) => u.position.x === 300)).toBe(true)
+    })
+  })
+})

src/composables/graph/useArrangeNodes.ts

@@ -0,0 +1,186 @@
+import { useSelectionState } from '@/composables/graph/useSelectionState'
+import { LiteGraph } from '@/lib/litegraph/src/litegraph'
+import type { LGraphNode, NodeId } from '@/lib/litegraph/src/litegraph'
+import { TitleMode } from '@/lib/litegraph/src/types/globalEnums'
+import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
+import { useLayoutMutations } from '@/renderer/core/layout/operations/layoutMutations'
+import { LayoutSource } from '@/renderer/core/layout/types'
+import type { Point } from '@/renderer/core/layout/types'
+import { app } from '@/scripts/app'
+
+export type ArrangeLayout = 'vertical' | 'horizontal' | 'grid'
+
+export const DEFAULT_ARRANGE_GAP = 12
+export const MIN_ARRANGE_GAP = 0
+export const MAX_ARRANGE_GAP = 48
+
+interface NodeBox {
+  id: NodeId
+  posX: number
+  posY: number
+  visualWidth: number
+  visualHeight: number
+  titleHeight: number
+}
+
+interface ArrangeUpdate {
+  nodeId: NodeId
+  position: Point
+}
+
+const titleHeightOf = (node: LGraphNode): number => {
+  const mode = node.title_mode
+  if (mode === TitleMode.TRANSPARENT_TITLE || mode === TitleMode.NO_TITLE) {
+    return 0
+  }
+  return LiteGraph.NODE_TITLE_HEIGHT
+}
+
+const toBox = (node: LGraphNode): NodeBox => {
+  const titleHeight = titleHeightOf(node)
+  return {
+    id: node.id,
+    posX: node.pos[0],
+    posY: node.pos[1],
+    visualWidth: node.size[0],
+    visualHeight: node.size[1] + titleHeight,
+    titleHeight
+  }
+}
+
+const byTopDown = (a: NodeBox, b: NodeBox) => a.posY - b.posY || a.posX - b.posX
+
+const byLeftRight = (a: NodeBox, b: NodeBox) =>
+  a.posX - b.posX || a.posY - b.posY
+
+const findAnchor = (boxes: NodeBox[]): NodeBox =>
+  boxes.reduce((best, box) =>
+    box.posX + box.posY < best.posX + best.posY ? box : best
+  )
+
+const cumulativeOffsets = (
+  sizes: number[],
+  origin: number,
+  gap: number
+): number[] => {
+  const offsets: number[] = [origin]
+  for (let i = 1; i < sizes.length; i++) {
+    offsets.push(offsets[i - 1] + sizes[i - 1] + gap)
+  }
+  return offsets
+}
+
+const arrangeVertical = (
+  boxes: NodeBox[],
+  anchor: NodeBox,
+  gap: number
+): ArrangeUpdate[] => {
+  const sorted = [...boxes].sort(byTopDown)
+  let visualTop = anchor.posY - anchor.titleHeight
+  return sorted.map((box) => {
+    const update: ArrangeUpdate = {
+      nodeId: box.id,
+      position: { x: anchor.posX, y: visualTop + box.titleHeight }
+    }
+    visualTop += box.visualHeight + gap
+    return update
+  })
+}
+
+const arrangeHorizontal = (
+  boxes: NodeBox[],
+  anchor: NodeBox,
+  gap: number
+): ArrangeUpdate[] => {
+  const sorted = [...boxes].sort(byLeftRight)
+  const visualTop = anchor.posY - anchor.titleHeight
+  let cursorX = anchor.posX
+  return sorted.map((box) => {
+    const update: ArrangeUpdate = {
+      nodeId: box.id,
+      position: { x: cursorX, y: visualTop + box.titleHeight }
+    }
+    cursorX += box.visualWidth + gap
+    return update
+  })
+}
+
+const arrangeGrid = (
+  boxes: NodeBox[],
+  anchor: NodeBox,
+  gap: number
+): ArrangeUpdate[] => {
+  const sorted = [...boxes].sort(byTopDown)
+  const cols = Math.ceil(Math.sqrt(sorted.length))
+  const rows = Math.ceil(sorted.length / cols)
+
+  const colWidths = new Array<number>(cols).fill(0)
+  const rowHeights = new Array<number>(rows).fill(0)
+  sorted.forEach((box, i) => {
+    const col = i % cols
+    const row = Math.floor(i / cols)
+    if (box.visualWidth > colWidths[col]) colWidths[col] = box.visualWidth
+    if (box.visualHeight > rowHeights[row]) rowHeights[row] = box.visualHeight
+  })
+
+  const colX = cumulativeOffsets(colWidths, anchor.posX, gap)
+  const rowVisualTop = cumulativeOffsets(
+    rowHeights,
+    anchor.posY - anchor.titleHeight,
+    gap
+  )
+
+  return sorted.map((box, i) => {
+    const col = i % cols
+    const row = Math.floor(i / cols)
+    return {
+      nodeId: box.id,
+      position: {
+        x: colX[col],
+        y: rowVisualTop[row] + box.titleHeight
+      }
+    }
+  })
+}
+
+export function computeArrangement(
+  nodes: LGraphNode[],
+  layout: ArrangeLayout,
+  gap: number = DEFAULT_ARRANGE_GAP
+): ArrangeUpdate[] {
+  if (nodes.length < 2) return []
+  const boxes = nodes.map(toBox)
+  const anchor = findAnchor(boxes)
+  if (layout === 'vertical') return arrangeVertical(boxes, anchor, gap)
+  if (layout === 'horizontal') return arrangeHorizontal(boxes, anchor, gap)
+  return arrangeGrid(boxes, anchor, gap)
+}
+
+interface ArrangeOptions {
+  gap?: number
+  captureUndo?: boolean
+}
+
+export function useArrangeNodes() {
+  const { selectedNodes, hasMultipleSelection } = useSelectionState()
+  const mutations = useLayoutMutations()
+  const workflowStore = useWorkflowStore()
+
+  const arrangeNodes = (
+    layout: ArrangeLayout,
+    { gap = DEFAULT_ARRANGE_GAP, captureUndo = true }: ArrangeOptions = {}
+  ) => {
+    if (!hasMultipleSelection.value) return
+    const updates = computeArrangement(selectedNodes.value, layout, gap)
+    if (updates.length === 0) return
+
+    mutations.setSource(LayoutSource.Canvas)
+    mutations.batchMoveNodes(updates)
+    app.canvas?.setDirty(true, true)
+    if (captureUndo) {
+      workflowStore.activeWorkflow?.changeTracker?.captureCanvasState()
+    }
+  }
+
+  return { arrangeNodes, canArrange: hasMultipleSelection }
+}

src/composables/graph/useArrangeSession.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type * as ArrangeNodesModule from '@/composables/graph/useArrangeNodes'
+import { useArrangeSession } from '@/composables/graph/useArrangeSession'
+
+const mockArrangeNodes = vi.fn()
+
+vi.mock('@/composables/graph/useArrangeNodes', async () => {
+  const actual = await vi.importActual<typeof ArrangeNodesModule>(
+    '@/composables/graph/useArrangeNodes'
+  )
+  return {
+    ...actual,
+    useArrangeNodes: () => ({ arrangeNodes: mockArrangeNodes })
+  }
+})
+
+describe('useArrangeSession', () => {
+  let frameCallbacks: Array<FrameRequestCallback>
+  let nextHandle: number
+
+  beforeEach(() => {
+    mockArrangeNodes.mockReset()
+    frameCallbacks = []
+    nextHandle = 1
+    vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation(
+      (cb: FrameRequestCallback) => {
+        frameCallbacks.push(cb)
+        return nextHandle++
+      }
+    )
+    vi.spyOn(globalThis, 'cancelAnimationFrame').mockImplementation((id) => {
+      frameCallbacks[id - 1] = () => {}
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  const flushFrames = () => {
+    const callbacks = frameCallbacks
+    frameCallbacks = []
+    callbacks.forEach((cb) => cb(performance.now()))
+  }
+
+  it('start() applies layout immediately and captures undo', () => {
+    const session = useArrangeSession()
+    session.start('vertical')
+
+    expect(mockArrangeNodes).toHaveBeenCalledTimes(1)
+    expect(mockArrangeNodes).toHaveBeenCalledWith('vertical', {
+      gap: 12,
+      captureUndo: true
+    })
+    expect(session.activeLayout.value).toBe('vertical')
+    expect(session.gap.value).toBe(12)
+  })
+
+  it('previewGap() throttles repeated calls into a single frame', () => {
+    const session = useArrangeSession()
+    session.start('grid')
+    mockArrangeNodes.mockClear()
+
+    session.previewGap(20)
+    session.previewGap(30)
+    session.previewGap(40)
+
+    expect(mockArrangeNodes).not.toHaveBeenCalled()
+    flushFrames()
+
+    expect(mockArrangeNodes).toHaveBeenCalledTimes(1)
+    expect(mockArrangeNodes).toHaveBeenCalledWith('grid', {
+      gap: 40,
+      captureUndo: false
+    })
+  })
+
+  it('previewGap() is a no-op outside an active session', () => {
+    const session = useArrangeSession()
+    session.previewGap(20)
+    flushFrames()
+    expect(mockArrangeNodes).not.toHaveBeenCalled()
+  })
+
+  it('commitGap() cancels any pending preview frame', () => {
+    const session = useArrangeSession()
+    session.start('horizontal')
+    mockArrangeNodes.mockClear()
+
+    session.previewGap(25)
+    session.commitGap(36)
+    flushFrames()
+
+    expect(mockArrangeNodes).toHaveBeenCalledTimes(1)
+    expect(mockArrangeNodes).toHaveBeenCalledWith('horizontal', {
+      gap: 36,
+      captureUndo: true
+    })
+  })
+
+  it('reset() ends the session and prevents pending frames from arranging', () => {
+    const session = useArrangeSession()
+    session.start('vertical')
+    mockArrangeNodes.mockClear()
+
+    session.previewGap(40)
+    session.reset()
+    flushFrames()
+
+    expect(mockArrangeNodes).not.toHaveBeenCalled()
+    expect(session.activeLayout.value).toBeNull()
+    expect(session.gap.value).toBe(12)
+  })
+})

src/composables/graph/useArrangeSession.ts

@@ -0,0 +1,60 @@
+import { readonly, ref } from 'vue'
+
+import {
+  DEFAULT_ARRANGE_GAP,
+  useArrangeNodes
+} from '@/composables/graph/useArrangeNodes'
+import type { ArrangeLayout } from '@/composables/graph/useArrangeNodes'
+
+export function useArrangeSession() {
+  const { arrangeNodes } = useArrangeNodes()
+
+  const activeLayout = ref<ArrangeLayout | null>(null)
+  const gap = ref(DEFAULT_ARRANGE_GAP)
+  let pendingFrame: number | null = null
+
+  const cancelPendingFrame = () => {
+    if (pendingFrame === null) return
+    cancelAnimationFrame(pendingFrame)
+    pendingFrame = null
+  }
+
+  const reset = () => {
+    cancelPendingFrame()
+    activeLayout.value = null
+    gap.value = DEFAULT_ARRANGE_GAP
+  }
+
+  const start = (layout: ArrangeLayout) => {
+    gap.value = DEFAULT_ARRANGE_GAP
+    activeLayout.value = layout
+    arrangeNodes(layout, { gap: gap.value, captureUndo: true })
+  }
+
+  const previewGap = (nextGap: number) => {
+    if (activeLayout.value === null) return
+    gap.value = nextGap
+    cancelPendingFrame()
+    pendingFrame = requestAnimationFrame(() => {
+      pendingFrame = null
+      if (activeLayout.value === null) return
+      arrangeNodes(activeLayout.value, { gap: nextGap, captureUndo: false })
+    })
+  }
+
+  const commitGap = (nextGap: number) => {
+    if (activeLayout.value === null) return
+    cancelPendingFrame()
+    gap.value = nextGap
+    arrangeNodes(activeLayout.value, { gap: nextGap, captureUndo: true })
+  }
+
+  return {
+    activeLayout: readonly(activeLayout),
+    gap: readonly(gap),
+    start,
+    previewGap,
+    commitGap,
+    reset
+  }
+}

src/composables/useLoad3d.test.ts

@@ -3,14 +3,7 @@ import { nextTick, reactive, ref, shallowRef } from 'vue'
 import type { Pinia } from 'pinia'
 import { getActivePinia } from 'pinia'
 
-import {
-  getLoad3dOutputCache,
-  isLoad3dSceneDirty,
-  markLoad3dSceneDirty,
-  nodeToLoad3dMap,
-  setLoad3dOutputCache,
-  useLoad3d
-} from '@/composables/useLoad3d'
+import { nodeToLoad3dMap, useLoad3d } from '@/composables/useLoad3d'
 import Load3d from '@/extensions/core/load3d/Load3d'
 import Load3dUtils from '@/extensions/core/load3d/Load3dUtils'
 import { createLoad3d } from '@/extensions/core/load3d/createLoad3d'
@@ -193,7 +186,6 @@ describe('useLoad3d', () => {
       resetGizmoTransform: vi.fn(),
       applyGizmoTransform: vi.fn(),
       fitToViewer: vi.fn(),
-      centerCameraOnModel: vi.fn(),
       getGizmoTransform: vi.fn().mockReturnValue({
         position: { x: 0, y: 0, z: 0 },
         rotation: { x: 0, y: 0, z: 0 },
@@ -1750,184 +1742,4 @@ describe('useLoad3d', () => {
       expect(originalOnRemoved).toHaveBeenCalledTimes(1)
     })
   })
-
-  describe('scene dirty tracking', () => {
-    const fakeCache = {
-      image: 'threed/scene-1.png [temp]',
-      mask: 'threed/scene_mask-1.png [temp]',
-      normal: 'threed/scene_normal-1.png [temp]',
-      camera_info: null,
-      recording: '',
-      model_3d_info: []
-    }
-
-    it('treats an unseen node as dirty by default', () => {
-      const fresh = createMockLGraphNode({ properties: {} })
-      expect(isLoad3dSceneDirty(fresh)).toBe(true)
-    })
-
-    it('markLoad3dSceneDirty sets the node dirty', () => {
-      const fresh = createMockLGraphNode({ properties: {} })
-      setLoad3dOutputCache(fresh, fakeCache)
-      expect(isLoad3dSceneDirty(fresh)).toBe(false)
-
-      markLoad3dSceneDirty(fresh)
-      expect(isLoad3dSceneDirty(fresh)).toBe(true)
-    })
-
-    it('setLoad3dOutputCache stores the output and clears dirty', () => {
-      const fresh = createMockLGraphNode({ properties: {} })
-      setLoad3dOutputCache(fresh, fakeCache)
-
-      expect(getLoad3dOutputCache(fresh)).toBe(fakeCache)
-      expect(isLoad3dSceneDirty(fresh)).toBe(false)
-    })
-
-    it('two nodes keep independent dirty state', () => {
-      const a = createMockLGraphNode({ properties: {} })
-      const b = createMockLGraphNode({ properties: {} })
-
-      setLoad3dOutputCache(a, fakeCache)
-      expect(isLoad3dSceneDirty(a)).toBe(false)
-      expect(isLoad3dSceneDirty(b)).toBe(true)
-
-      markLoad3dSceneDirty(a)
-      expect(isLoad3dSceneDirty(a)).toBe(true)
-      expect(isLoad3dSceneDirty(b)).toBe(true)
-    })
-
-    it('markLoad3dSceneDirty on null is a no-op', () => {
-      expect(() => markLoad3dSceneDirty(null)).not.toThrow()
-    })
-
-    it('sceneConfig changes flip the node dirty', async () => {
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      setLoad3dOutputCache(mockNode, fakeCache)
-      expect(isLoad3dSceneDirty(mockNode)).toBe(false)
-
-      composable.sceneConfig.value.backgroundColor = '#ffffff'
-      await nextTick()
-
-      expect(isLoad3dSceneDirty(mockNode)).toBe(true)
-    })
-
-    it('cameraChanged event marks the node dirty', async () => {
-      let cameraChangedHandler: ((state: unknown) => void) | undefined
-      vi.mocked(mockLoad3d.addEventListener!).mockImplementation(
-        (event: string, handler: unknown) => {
-          if (event === 'cameraChanged') {
-            cameraChangedHandler = handler as (state: unknown) => void
-          }
-        }
-      )
-
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      setLoad3dOutputCache(mockNode, fakeCache)
-      expect(isLoad3dSceneDirty(mockNode)).toBe(false)
-
-      cameraChangedHandler!({ position: { x: 1, y: 2, z: 3 } })
-
-      expect(isLoad3dSceneDirty(mockNode)).toBe(true)
-    })
-
-    it('handleStopRecording marks dirty when a recording was produced', async () => {
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      setLoad3dOutputCache(mockNode, fakeCache)
-
-      vi.mocked(mockLoad3d.getRecordingDuration!).mockReturnValue(5)
-      composable.handleStopRecording()
-
-      expect(isLoad3dSceneDirty(mockNode)).toBe(true)
-    })
-
-    it('handleStopRecording leaves dirty alone when no recording was produced', async () => {
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      setLoad3dOutputCache(mockNode, fakeCache)
-
-      vi.mocked(mockLoad3d.getRecordingDuration!).mockReturnValue(0)
-      composable.handleStopRecording()
-
-      expect(isLoad3dSceneDirty(mockNode)).toBe(false)
-    })
-
-    it('handleClearRecording marks dirty', async () => {
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      setLoad3dOutputCache(mockNode, fakeCache)
-      composable.handleClearRecording()
-
-      expect(isLoad3dSceneDirty(mockNode)).toBe(true)
-    })
-
-    it('handleStartRecording marks dirty so an in-progress recording forces a re-capture', async () => {
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      setLoad3dOutputCache(mockNode, fakeCache)
-      expect(isLoad3dSceneDirty(mockNode)).toBe(false)
-
-      await composable.handleStartRecording()
-
-      expect(mockLoad3d.startRecording).toHaveBeenCalledTimes(1)
-      expect(isLoad3dSceneDirty(mockNode)).toBe(true)
-    })
-
-    it('handleCenterCameraOnModel marks dirty', async () => {
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      setLoad3dOutputCache(mockNode, fakeCache)
-      expect(isLoad3dSceneDirty(mockNode)).toBe(false)
-
-      composable.handleCenterCameraOnModel()
-
-      expect(mockLoad3d.centerCameraOnModel).toHaveBeenCalledTimes(1)
-      expect(isLoad3dSceneDirty(mockNode)).toBe(true)
-    })
-
-    it('handleSeek marks dirty when the animation has a duration', async () => {
-      const composable = useLoad3d(mockNode)
-      const containerRef = document.createElement('div')
-      await composable.initializeLoad3d(containerRef)
-      await nextTick()
-
-      const calls = vi.mocked(mockLoad3d.addEventListener!).mock.calls
-      const match = calls.find(([event]) => event === 'animationProgressChange')
-      const animationProgressHandler = match![1] as (d: {
-        progress: number
-        currentTime: number
-        duration: number
-      }) => void
-
-      animationProgressHandler({ progress: 0, currentTime: 0, duration: 10 })
-      setLoad3dOutputCache(mockNode, fakeCache)
-
-      composable.handleSeek(50)
-
-      expect(isLoad3dSceneDirty(mockNode)).toBe(true)
-    })
-  })
 })

src/composables/useLoad3d.ts

@@ -22,7 +22,6 @@ import type {
   GizmoMode,
   LightConfig,
   MaterialMode,
-  Model3DInfo,
   ModelConfig,
   SceneConfig,
   UpDirection
@@ -39,38 +38,6 @@ import { useLoad3dService } from '@/services/load3dService'
 
 type Load3dReadyCallback = (load3d: Load3d) => void
 export const nodeToLoad3dMap = new Map<LGraphNode, Load3d>()
-
-export type Load3dCachedOutput = {
-  image: string
-  mask: string
-  normal: string
-  camera_info: CameraState | null
-  recording: string
-  model_3d_info: Model3DInfo
-}
-
-const load3dSceneDirty = new WeakMap<LGraphNode, boolean>()
-const load3dOutputCache = new WeakMap<LGraphNode, Load3dCachedOutput>()
-
-export const markLoad3dSceneDirty = (node: LGraphNode | null): void => {
-  if (!node) return
-  load3dSceneDirty.set(node, true)
-}
-
-export const isLoad3dSceneDirty = (node: LGraphNode): boolean =>
-  load3dSceneDirty.get(node) !== false
-
-export const getLoad3dOutputCache = (
-  node: LGraphNode
-): Load3dCachedOutput | undefined => load3dOutputCache.get(node)
-
-export const setLoad3dOutputCache = (
-  node: LGraphNode,
-  output: Load3dCachedOutput
-): void => {
-  load3dOutputCache.set(node, output)
-  load3dSceneDirty.set(node, false)
-}
 const pendingCallbacks = new Map<LGraphNode, Load3dReadyCallback[]>()
 const persistentReadyCallbacks = new Map<LGraphNode, Load3dReadyCallback[]>()
 
@@ -102,11 +69,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
   let load3d: Load3d | null = null
   let isFirstModelLoad = true
 
-  const markDirty = () => {
-    const rawNode = toRaw(nodeRef.value)
-    if (rawNode) markLoad3dSceneDirty(rawNode as LGraphNode)
-  }
-
   const debouncedHandleResize = useDebounceFn(() => {
     load3d?.handleResize()
   }, 150)
@@ -409,7 +371,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
     if (n) {
       n.properties['Light Config'] = lightConfig.value
     }
-    markDirty()
   }
 
   const waitForLoad3d = (callback: Load3dReadyCallback) => {
@@ -454,7 +415,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
       if (nodeRef.value) {
         nodeRef.value.properties['Scene Config'] = newValue
       }
-      markDirty()
     },
     { deep: true }
   )
@@ -495,7 +455,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
       if (nodeRef.value) {
         nodeRef.value.properties['Model Config'] = newValue
       }
-      markDirty()
     },
     { deep: true }
   )
@@ -529,7 +488,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
         load3d.toggleCamera(newValue.cameraType)
         load3d.setFOV(newValue.fov)
       }
-      markDirty()
     },
     { deep: true }
   )
@@ -589,21 +547,18 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
     if (load3d) {
       load3d.toggleAnimation(newValue)
     }
-    markDirty()
   })
 
   watch(selectedSpeed, (newValue) => {
     if (load3d && newValue) {
       load3d.setAnimationSpeed(newValue)
     }
-    markDirty()
   })
 
   watch(selectedAnimation, (newValue) => {
     if (load3d && newValue !== undefined) {
       load3d.updateSelectedAnimation(newValue)
     }
-    markDirty()
   })
 
   const handleMouseEnter = () => {
@@ -618,7 +573,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
     if (load3d) {
       await load3d.startRecording()
       isRecording.value = true
-      markDirty()
     }
   }
 
@@ -628,7 +582,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
       isRecording.value = false
       recordingDuration.value = load3d.getRecordingDuration()
       hasRecording.value = recordingDuration.value > 0
-      if (hasRecording.value) markDirty()
     }
   }
 
@@ -645,7 +598,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
       load3d.clearRecording()
       hasRecording.value = false
       recordingDuration.value = 0
-      markDirty()
     }
   }
 
@@ -653,7 +605,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
     if (load3d && animationDuration.value > 0) {
       const time = (progress / 100) * animationDuration.value
       load3d.setAnimationTime(time)
-      markDirty()
     }
   }
 
@@ -985,7 +936,6 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
             state: cameraState
           }
         }
-        markLoad3dSceneDirty(node)
       }
     },
     gizmoTransformChange: (data: GizmoConfig) => {
@@ -1026,9 +976,7 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
   }
 
   const handleCenterCameraOnModel = () => {
-    if (!load3d) return
-    load3d.centerCameraOnModel()
-    markDirty()
+    load3d?.centerCameraOnModel()
   }
 
   const handleResetGizmoTransform = () => {

src/composables/useTransformCompatOverlayProps.ts

@@ -1,55 +0,0 @@
-import type { HintedString } from '@primevue/core'
-import type { InjectionKey } from 'vue'
-import { computed, inject } from 'vue'
-
-/**
- * Options for configuring transform-compatible overlay props
- */
-interface TransformCompatOverlayOptions {
-  /**
-   * Where to append the overlay. 'self' keeps overlay within component
-   * for proper transform inheritance, 'body' teleports to document body
-   */
-  appendTo?: HintedString<'body' | 'self'> | undefined | HTMLElement
-  // Future: other props needed for transform compatibility
-  // scrollTarget?: string | HTMLElement
-  // autoZIndex?: boolean
-}
-
-export const OverlayAppendToKey: InjectionKey<
-  HintedString<'body' | 'self'> | undefined | HTMLElement
-> = Symbol('OverlayAppendTo')
-
-/**
- * Composable that provides props to make PrimeVue overlay components
- * compatible with CSS-transformed parent elements.
- *
- * Vue nodes use CSS transforms for positioning/scaling. PrimeVue overlay
- * components (Select, MultiSelect, TreeSelect, etc.) teleport to document
- * body by default, breaking transform inheritance. This composable provides
- * the necessary props to keep overlays within their component elements.
- *
- * @param overrides - Optional overrides for specific use cases
- * @returns Computed props object to spread on PrimeVue overlay components
- *
- * @example
- * ```vue
- * <template>
- *   <Select v-bind="overlayProps" />
- * </template>
- *
- * <script setup>
- * const overlayProps = useTransformCompatOverlayProps()
- * </script>
- * ```
- */
-export function useTransformCompatOverlayProps(
-  overrides: TransformCompatOverlayOptions = {}
-) {
-  const injectedAppendTo = inject(OverlayAppendToKey, undefined)
-
-  return computed(() => ({
-    appendTo: injectedAppendTo ?? ('self' as const),
-    ...overrides
-  }))
-}

src/extensions/core/load3d.test.ts

@@ -38,27 +38,13 @@ vi.mock('@/services/load3dService', () => ({
   })
 }))
 
-vi.mock('@/composables/useLoad3d', () => {
-  const sceneDirty = new WeakMap<LGraphNode, boolean>()
-  const outputCache = new WeakMap<LGraphNode, unknown>()
-  return {
-    useLoad3d: () => ({
-      waitForLoad3d: waitForLoad3dMock,
-      onLoad3dReady: onLoad3dReadyMock
-    }),
-    nodeToLoad3dMap,
-    markLoad3dSceneDirty: (node: LGraphNode | null) => {
-      if (!node) return
-      sceneDirty.set(node, true)
-    },
-    isLoad3dSceneDirty: (node: LGraphNode) => sceneDirty.get(node) !== false,
-    getLoad3dOutputCache: (node: LGraphNode) => outputCache.get(node),
-    setLoad3dOutputCache: (node: LGraphNode, value: unknown) => {
-      outputCache.set(node, value)
-      sceneDirty.set(node, false)
-    }
-  }
-})
+vi.mock('@/composables/useLoad3d', () => ({
+  useLoad3d: () => ({
+    waitForLoad3d: waitForLoad3dMock,
+    onLoad3dReady: onLoad3dReadyMock
+  }),
+  nodeToLoad3dMap
+}))
 
 vi.mock('@/extensions/core/load3d/Load3DConfiguration', () => ({
   default: class {
@@ -496,16 +482,13 @@ describe('Comfy.Load3D.nodeCreated', () => {
 
     await load3DExt.nodeCreated(node)
 
-    expect(configureMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        loadFolder: 'input',
-        modelWidget: widgets[0],
-        cameraState: undefined,
-        width: widgets[1],
-        height: widgets[2],
-        onSceneInvalidated: expect.any(Function)
-      })
-    )
+    expect(configureMock).toHaveBeenCalledWith({
+      loadFolder: 'input',
+      modelWidget: widgets[0],
+      cameraState: undefined,
+      width: widgets[1],
+      height: widgets[2]
+    })
   })
 
   it('attaches a serializeValue function to the scene widget', async () => {
@@ -742,7 +725,7 @@ describe('Comfy.Preview3DAdvanced.nodeCreated', () => {
     await preview3DAdvancedExt.nodeCreated(node)
 
     expect(configureForSaveMeshMock).toHaveBeenCalledWith(
-      'output',
+      'temp',
       'prev/model.glb',
       { silentOnNotFound: true }
     )
@@ -868,7 +851,7 @@ describe('Comfy.Preview3DAdvanced.nodeCreated', () => {
 
     expect(node.properties['Last Time Model File']).toBe('sub/nested/mesh.glb')
     expect(configureForSaveMeshMock).toHaveBeenCalledWith(
-      'output',
+      'temp',
       'sub/nested/mesh.glb',
       { silentOnNotFound: true }
     )
@@ -1031,95 +1014,3 @@ describe('Comfy.Preview3DAdvanced.getNodeMenuItems', () => {
     ])
   })
 })
-
-describe('Comfy.Load3D scene widget serializeValue caching', () => {
-  beforeEach(setupBaseMocks)
-
-  function makeFullFakeLoad3d() {
-    return {
-      getCurrentCameraType: vi.fn(() => 'perspective'),
-      cameraManager: { perspectiveCamera: { fov: 35 } },
-      getCameraState: vi.fn(() => ({ position: { x: 0, y: 0, z: 0 } })),
-      stopRecording: vi.fn(),
-      captureScene: vi.fn(async () => ({
-        scene: 'scene-data',
-        mask: 'mask-data',
-        normal: 'normal-data'
-      })),
-      handleResize: vi.fn(),
-      getModelInfo: vi.fn(() => null),
-      getRecordingData: vi.fn(() => null)
-    }
-  }
-
-  async function setup() {
-    const { load3DExt } = await loadExtensionsFresh()
-    const useLoad3dModule = await import('@/composables/useLoad3d')
-    const utilsModule = await import('@/extensions/core/load3d/Load3dUtils')
-    const uploadTempImage = utilsModule.default.uploadTempImage as ReturnType<
-      typeof vi.fn
-    >
-    let counter = 0
-    uploadTempImage.mockImplementation(
-      async (_data: unknown, kind: string) => ({
-        name: `${kind}-${++counter}.png`
-      })
-    )
-
-    const widgets: FakeWidget[] = [
-      { name: 'model_file', value: 'm.glb' },
-      { name: 'width', value: 256 },
-      { name: 'height', value: 256 },
-      { name: 'image', value: '' }
-    ]
-    const node = makeLoad3DNode({ widgets, properties: {} })
-    useLoad3dModule.nodeToLoad3dMap.set(node, makeFullFakeLoad3d() as never)
-
-    await load3DExt.nodeCreated(node)
-    const serialize = widgets[3].serializeValue! as () => Promise<{
-      image: string
-    } | null>
-
-    return { node, serialize, uploadTempImage, useLoad3dModule }
-  }
-
-  it('reuses the cached output when the scene has not been dirtied', async () => {
-    const { node, serialize, uploadTempImage, useLoad3dModule } = await setup()
-
-    const first = await serialize()
-    expect(uploadTempImage).toHaveBeenCalledTimes(3)
-    expect(first?.image).toBe('threed/scene-1.png [temp]')
-    expect(useLoad3dModule.isLoad3dSceneDirty(node)).toBe(false)
-    expect(useLoad3dModule.getLoad3dOutputCache(node)).toBe(first)
-
-    const second = await serialize()
-    expect(uploadTempImage).toHaveBeenCalledTimes(3)
-    expect(second).toBe(first)
-  })
-
-  it('re-captures after the scene is marked dirty', async () => {
-    const { node, serialize, uploadTempImage, useLoad3dModule } = await setup()
-
-    await serialize()
-    expect(uploadTempImage).toHaveBeenCalledTimes(3)
-
-    useLoad3dModule.markLoad3dSceneDirty(node)
-
-    const refreshed = await serialize()
-    expect(uploadTempImage).toHaveBeenCalledTimes(6)
-    expect(refreshed?.image).toBe('threed/scene-4.png [temp]')
-  })
-
-  it('returns null when no load3d instance is registered for the node', async () => {
-    const { load3DExt } = await loadExtensionsFresh()
-    const widgets: FakeWidget[] = [
-      { name: 'model_file', value: 'm.glb' },
-      { name: 'width', value: 256 },
-      { name: 'height', value: 256 },
-      { name: 'image', value: '' }
-    ]
-    const node = makeLoad3DNode({ widgets })
-    await load3DExt.nodeCreated(node)
-    expect(await widgets[3].serializeValue!()).toBeNull()
-  })
-})

src/extensions/core/load3d.ts

@@ -2,15 +2,7 @@ import { nextTick } from 'vue'
 
 import Load3D from '@/components/load3d/Load3D.vue'
 import Load3DViewerContent from '@/components/load3d/Load3dViewerContent.vue'
-import {
-  type Load3dCachedOutput,
-  getLoad3dOutputCache,
-  isLoad3dSceneDirty,
-  markLoad3dSceneDirty,
-  nodeToLoad3dMap,
-  setLoad3dOutputCache,
-  useLoad3d
-} from '@/composables/useLoad3d'
+import { nodeToLoad3dMap, useLoad3d } from '@/composables/useLoad3d'
 import { createExportMenuItems } from '@/extensions/core/load3d/exportMenuHelper'
 import type {
   CameraConfig,
@@ -104,8 +96,6 @@ async function handleModelUpload(files: FileList, node: LGraphNode) {
 
       modelWidget.value = uploadPath
     }
-
-    markLoad3dSceneDirty(node)
   } catch (error) {
     console.error('Model upload failed:', error)
     useToastStore().addAlert(t('toastMessages.fileUploadFailed'))
@@ -123,7 +113,6 @@ async function handleResourcesUpload(files: FileList, node: LGraphNode) {
       : '3d'
 
     await Load3dUtils.uploadMultipleFiles(files, subfolder)
-    markLoad3dSceneDirty(node)
   } catch (error) {
     console.error('Extra resources upload failed:', error)
     useToastStore().addAlert(t('toastMessages.extraResourcesUploadFailed'))
@@ -322,7 +311,6 @@ useExtensionService().registerExtension({
             if (modelWidget) {
               modelWidget.value = LOAD3D_NONE_MODEL
             }
-            markLoad3dSceneDirty(node)
           })
         }
 
@@ -381,8 +369,7 @@ useExtensionService().registerExtension({
         modelWidget,
         cameraState,
         width,
-        height,
-        onSceneInvalidated: () => markLoad3dSceneDirty(node)
+        height
       })
     })
 
@@ -400,11 +387,6 @@ useExtensionService().registerExtension({
             return null
           }
 
-          if (!isLoad3dSceneDirty(node)) {
-            const cached = getLoad3dOutputCache(node)
-            if (cached) return cached
-          }
-
           const cameraConfig: CameraConfig = (node.properties[
             'Camera Config'
           ] as CameraConfig | undefined) || {
@@ -436,7 +418,7 @@ useExtensionService().registerExtension({
           const modelInfo = currentLoad3d.getModelInfo()
           const model_3d_info: Model3DInfo = modelInfo ? [modelInfo] : []
 
-          const returnVal: Load3dCachedOutput = {
+          const returnVal = {
             image: `threed/${data.name} [temp]`,
             mask: `threed/${dataMask.name} [temp]`,
             normal: `threed/${dataNormal.name} [temp]`,
@@ -453,11 +435,9 @@ useExtensionService().registerExtension({
             const [recording] = await Promise.all([
               Load3dUtils.uploadTempImage(recordingData, 'recording', 'mp4')
             ])
-            returnVal.recording = `threed/${recording.name} [temp]`
+            returnVal['recording'] = `threed/${recording.name} [temp]`
           }
 
-          setLoad3dOutputCache(node, returnVal)
-
           return returnVal
         }
       }
@@ -708,7 +688,7 @@ useExtensionService().registerExtension({
       if (!lastTimeModelFile) return
 
       const config = new Load3DConfiguration(load3d, node.properties)
-      config.configureForSaveMesh('output', lastTimeModelFile as string, {
+      config.configureForSaveMesh('temp', lastTimeModelFile as string, {
         silentOnNotFound: true
       })
 
@@ -802,7 +782,7 @@ useExtensionService().registerExtension({
 
         const currentLoad3d = resolveLoad3d()
         const config = new Load3DConfiguration(currentLoad3d, node.properties)
-        config.configureForSaveMesh('output', normalizedPath, {
+        config.configureForSaveMesh('temp', normalizedPath, {
           silentOnNotFound: true
         })
 

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

@@ -682,138 +682,3 @@ describe('Load3DConfiguration "none" model handling', () => {
     })
   })
 })
-
-describe('Load3DConfiguration.onSceneInvalidated', () => {
-  function makeLoad3dMock(): Load3d {
-    return {
-      loadModel: vi.fn().mockResolvedValue(undefined),
-      clearModel: vi.fn(),
-      setUpDirection: vi.fn(),
-      setMaterialMode: vi.fn(),
-      setTargetSize: vi.fn(),
-      setCameraState: vi.fn(),
-      toggleGrid: vi.fn(),
-      setBackgroundColor: vi.fn(),
-      setBackgroundImage: vi.fn().mockResolvedValue(undefined),
-      setBackgroundRenderMode: vi.fn(),
-      toggleCamera: vi.fn(),
-      setFOV: vi.fn(),
-      setLightIntensity: vi.fn(),
-      setHDRIIntensity: vi.fn(),
-      setHDRIAsBackground: vi.fn(),
-      setHDRIEnabled: vi.fn(),
-      emitModelReady: vi.fn()
-    } as unknown as Load3d
-  }
-
-  async function flush() {
-    await new Promise<void>((resolve) => setTimeout(resolve, 0))
-  }
-
-  beforeEach(() => {
-    vi.mocked(Load3dUtils.splitFilePath).mockReturnValue(['', 'model.glb'])
-    vi.mocked(Load3dUtils.getResourceURL).mockReturnValue('/view')
-  })
-
-  it('width.callback invokes onSceneInvalidated', async () => {
-    const onSceneInvalidated = vi.fn()
-    const width = { value: 1024 } as unknown as IBaseWidget
-    const height = { value: 1024 } as unknown as IBaseWidget
-    const config = new Load3DConfiguration(makeLoad3dMock())
-
-    config.configure({
-      modelWidget: { value: 'none' } as unknown as IBaseWidget,
-      loadFolder: 'input',
-      width,
-      height,
-      onSceneInvalidated
-    })
-    await flush()
-
-    width.callback!(2048)
-
-    expect(onSceneInvalidated).toHaveBeenCalledTimes(1)
-  })
-
-  it('height.callback invokes onSceneInvalidated', async () => {
-    const onSceneInvalidated = vi.fn()
-    const width = { value: 1024 } as unknown as IBaseWidget
-    const height = { value: 1024 } as unknown as IBaseWidget
-    const config = new Load3DConfiguration(makeLoad3dMock())
-
-    config.configure({
-      modelWidget: { value: 'none' } as unknown as IBaseWidget,
-      loadFolder: 'input',
-      width,
-      height,
-      onSceneInvalidated
-    })
-    await flush()
-
-    height.callback!(2048)
-
-    expect(onSceneInvalidated).toHaveBeenCalledTimes(1)
-  })
-
-  it('model_file widget callback invokes onSceneInvalidated after the model loads', async () => {
-    const onSceneInvalidated = vi.fn()
-    const modelWidget = { value: 'none' } as unknown as IBaseWidget
-    const config = new Load3DConfiguration(makeLoad3dMock())
-
-    config.configure({
-      modelWidget,
-      loadFolder: 'input',
-      onSceneInvalidated
-    })
-    await flush()
-
-    modelWidget.value = 'model.glb'
-    await flush()
-
-    expect(onSceneInvalidated).toHaveBeenCalled()
-  })
-
-  it('preserves any pre-existing model widget callback alongside the invalidation hook', async () => {
-    const onSceneInvalidated = vi.fn()
-    const original = vi.fn()
-    const modelWidget = {
-      value: 'none',
-      callback: original
-    } as unknown as IBaseWidget
-    const config = new Load3DConfiguration(makeLoad3dMock())
-
-    config.configure({
-      modelWidget,
-      loadFolder: 'input',
-      onSceneInvalidated
-    })
-    await flush()
-
-    modelWidget.value = 'model.glb'
-    await flush()
-
-    expect(original).toHaveBeenCalledWith('model.glb')
-    expect(onSceneInvalidated).toHaveBeenCalled()
-  })
-
-  it('callbacks remain safe when onSceneInvalidated is omitted', async () => {
-    const width = { value: 1024 } as unknown as IBaseWidget
-    const height = { value: 1024 } as unknown as IBaseWidget
-    const modelWidget = { value: 'none' } as unknown as IBaseWidget
-    const config = new Load3DConfiguration(makeLoad3dMock())
-
-    config.configure({
-      modelWidget,
-      loadFolder: 'input',
-      width,
-      height
-    })
-    await flush()
-
-    expect(() => width.callback!(2048)).not.toThrow()
-    expect(() => height.callback!(2048)).not.toThrow()
-    expect(() => {
-      modelWidget.value = 'model.glb'
-    }).not.toThrow()
-  })
-})

src/extensions/core/load3d/Load3DConfiguration.ts

@@ -23,14 +23,6 @@ type Load3DConfigurationSettings = {
   height?: IBaseWidget
   bgImagePath?: string
   silentOnNotFound?: boolean
-  /**
-   * Called when a user-driven change to one of the wired widgets
-   * (model_file, width, height) makes the previously captured scene stale.
-   * Backend caching covers these inputs by themselves; this hook lets the
-   * caller invalidate any frontend-side capture cache so the next serialize
-   * re-renders at the new state.
-   */
-  onSceneInvalidated?: () => void
 }
 
 const ANNOTATED_FILENAME_PATTERN = / \[(input|output|temp)\]$/
@@ -54,7 +46,7 @@ class Load3DConfiguration {
   ) {}
 
   configureForSaveMesh(
-    loadFolder: 'input' | 'output',
+    loadFolder: 'input' | 'output' | 'temp',
     filePath: string,
     options?: { silentOnNotFound?: boolean }
   ) {
@@ -71,33 +63,22 @@ class Load3DConfiguration {
       setting.modelWidget,
       setting.loadFolder,
       setting.cameraState,
-      setting.silentOnNotFound ?? false,
-      setting.onSceneInvalidated
-    )
-    this.setupTargetSize(
-      setting.width,
-      setting.height,
-      setting.onSceneInvalidated
+      setting.silentOnNotFound ?? false
     )
+    this.setupTargetSize(setting.width, setting.height)
     this.setupDefaultProperties(setting.bgImagePath)
   }
 
-  private setupTargetSize(
-    width?: IBaseWidget,
-    height?: IBaseWidget,
-    onSceneInvalidated?: () => void
-  ) {
+  private setupTargetSize(width?: IBaseWidget, height?: IBaseWidget) {
     if (width && height) {
       this.load3d.setTargetSize(width.value as number, height.value as number)
 
       width.callback = (value: number) => {
         this.load3d.setTargetSize(value, height.value as number)
-        onSceneInvalidated?.()
       }
 
       height.callback = (value: number) => {
         this.load3d.setTargetSize(width.value as number, value)
-        onSceneInvalidated?.()
       }
     }
   }
@@ -122,8 +103,7 @@ class Load3DConfiguration {
     modelWidget: IBaseWidget,
     loadFolder: string,
     cameraState?: CameraState,
-    silentOnNotFound: boolean = false,
-    onSceneInvalidated?: () => void
+    silentOnNotFound: boolean = false
   ) {
     const onModelWidgetUpdate = this.createModelUpdateHandler(
       loadFolder,
@@ -157,8 +137,6 @@ class Load3DConfiguration {
       if (originalCallback) {
         originalCallback(value)
       }
-
-      onSceneInvalidated?.()
     }
   }
 

src/extensions/core/load3d/LoaderManager.ts

@@ -191,7 +191,11 @@ export class LoaderManager implements LoaderManagerInterface {
       return null
     }
 
-    const loadRootFolder = params.get('type') === 'output' ? 'output' : 'input'
+    const requestedType = params.get('type')
+    const loadRootFolder =
+      requestedType === 'output' || requestedType === 'temp'
+        ? requestedType
+        : 'input'
     const subfolder = params.get('subfolder') ?? ''
     const path =
       'api/view?type=' +

src/locales/en/main.json

@@ -350,6 +350,11 @@
     "nodeSlotsError": "Node Slots Error",
     "nodeWidgetsError": "Node Widgets Error",
     "frameNodes": "Frame Nodes",
+    "arrange": "Arrange",
+    "arrangeVertically": "Arrange vertically",
+    "arrangeHorizontally": "Arrange horizontally",
+    "arrangeAsGrid": "Arrange as grid",
+    "arrangeSpacing": "Arrangement spacing",
     "listening": "Listening...",
     "ready": "Ready",
     "play": "Play",

src/renderer/extensions/vueNodes/components/ImagePreview.test.ts

@@ -379,6 +379,16 @@ describe('ImagePreview', () => {
       expect(gridThumbnails).toHaveLength(2)
     })
 
+    it('requests lightweight thumbnails for grid cells instead of full-resolution images', () => {
+      renderImagePreview()
+
+      const gridImages = screen.getAllByRole('img')
+      expect(gridImages).toHaveLength(2)
+      for (const img of gridImages) {
+        expect(img.getAttribute('src')).toMatch(/[?&]preview=/)
+      }
+    })
+
     it('defaults to gallery mode for single image', () => {
       renderImagePreview({
         imageUrls: [defaultProps.imageUrls[0]]

src/renderer/extensions/vueNodes/components/ImagePreview.vue

@@ -13,7 +13,7 @@
       :style="{ gridTemplateColumns: `repeat(${gridCols}, 1fr)` }"
     >
       <Button
-        v-for="(url, index) in imageUrls"
+        v-for="(url, index) in gridImageUrls"
         :key="index"
         size="unset"
         class="ring-ring overflow-hidden rounded-none p-0 hover:ring-1 focus-visible:ring-2"
@@ -179,6 +179,7 @@ import Skeleton from '@/components/ui/skeleton/Skeleton.vue'
 import { useMaskEditor } from '@/composables/maskeditor/useMaskEditor'
 import { useToastStore } from '@/platform/updates/common/toastStore'
 import { useNodeOutputStore } from '@/stores/nodeOutputStore'
+import { getGridThumbnailUrl } from '@/utils/imageUtil'
 import { resolveNode } from '@/utils/litegraphUtil'
 import { cn } from '@comfyorg/tailwind-utils'
 
@@ -227,6 +228,7 @@ const { start: startDelayedLoader, stop: stopDelayedLoader } = useTimeoutFn(
 )
 
 const currentImageUrl = computed(() => imageUrls[currentIndex.value] ?? '')
+const gridImageUrls = computed(() => imageUrls.map(getGridThumbnailUrl))
 const hasMultipleImages = computed(() => imageUrls.length > 1)
 const imageAltText = computed(() =>
   t('g.viewImageOfTotal', {

src/renderer/extensions/vueNodes/widgets/components/WidgetSelectDefault.vue

@@ -60,7 +60,7 @@
         </ComboboxTrigger>
       </ComboboxAnchor>
 
-      <ComboboxPortal :to="portalTarget" :disabled="isPortalDisabled">
+      <ComboboxPortal>
         <ComboboxContent
           data-capture-wheel="true"
           data-testid="widget-select-default-overlay"
@@ -161,7 +161,6 @@ import {
 import { computed, ref } from 'vue'
 import type { CSSProperties } from 'vue'
 
-import { useTransformCompatOverlayProps } from '@/composables/useTransformCompatOverlayProps'
 import { useRestoreFocusOnViewportPointer } from '@/renderer/extensions/vueNodes/widgets/composables/useRestoreFocusOnViewportPointer'
 import type { SimplifiedWidget } from '@/types/simplifiedWidget'
 import { cn } from '@comfyorg/tailwind-utils'
@@ -242,19 +241,10 @@ const searchInputContainerRef = ref<HTMLElement>()
 const { handleFocusOutside, handleViewportPointerDown } =
   useRestoreFocusOnViewportPointer(focusSearchInput)
 
-const transformCompatProps = useTransformCompatOverlayProps()
-
 const widgetOptions = computed(
   () => widget.options as SelectWidgetOptions | undefined
 )
 
-const portalTarget = computed(() => {
-  const appendTo = transformCompatProps.value.appendTo
-  return appendTo === 'self' ? undefined : appendTo
-})
-
-const isPortalDisabled = computed(() => !portalTarget.value)
-
 const disabled = computed(() => Boolean(widgetOptions.value?.disabled))
 const placeholder = computed(() => widgetOptions.value?.placeholder ?? '')
 const filterPlaceholder = computed(

src/renderer/extensions/vueNodes/widgets/components/WidgetSelectDropdown.vue

@@ -2,7 +2,6 @@
 import { computed, provide, ref, toRef } from 'vue'
 import { useI18n } from 'vue-i18n'
 
-import { useTransformCompatOverlayProps } from '@/composables/useTransformCompatOverlayProps'
 import { SUPPORTED_EXTENSIONS_ACCEPT } from '@/extensions/core/load3d/constants'
 import { useAssetsApi } from '@/platform/assets/composables/media/useAssetsApi'
 import { useFlatOutputAssets } from '@/platform/assets/composables/media/useFlatOutputAssets'
@@ -53,12 +52,9 @@ const outputMediaAssets = isCloud
   ? useFlatOutputAssets()
   : useAssetsApi('output')
 
-const transformCompatProps = useTransformCompatOverlayProps()
-
-const combinedProps = computed(() => ({
-  ...filterWidgetProps(props.widget.options, PANEL_EXCLUDED_PROPS),
-  ...transformCompatProps.value
-}))
+const combinedProps = computed(() =>
+  filterWidgetProps(props.widget.options, PANEL_EXCLUDED_PROPS)
+)
 
 const getAssetData = () => {
   const nodeType: string | undefined =

src/utils/imageUtil.test.ts

@@ -1,6 +1,34 @@
 import { describe, expect, it } from 'vitest'
 
-import { parseImageWidgetValue } from './imageUtil'
+import { getGridThumbnailUrl, parseImageWidgetValue } from './imageUtil'
+
+describe('getGridThumbnailUrl', () => {
+  it('adds a compact preview format to a full-resolution view URL', () => {
+    const result = getGridThumbnailUrl(
+      '/api/view?filename=image.png&type=output&subfolder='
+    )
+    expect(result).toMatch(/[?&]preview=webp(%3B|;)75/)
+    expect(result).toContain('filename=image.png')
+  })
+
+  it('preserves an existing preview param (user-configured format)', () => {
+    const result = getGridThumbnailUrl(
+      '/api/view?filename=image.png&type=output&preview=jpeg;50'
+    )
+    expect(result).toContain('preview=jpeg')
+    expect(result).not.toMatch(/preview=webp/)
+  })
+
+  it('leaves SVGs untouched since the server cannot rasterize them', () => {
+    const url = '/api/view?filename=diagram.svg&type=output'
+    expect(getGridThumbnailUrl(url)).toBe(url)
+  })
+
+  it('leaves non-view URLs (e.g. blob previews) untouched', () => {
+    const blob = 'blob:http://localhost/abc-123'
+    expect(getGridThumbnailUrl(blob)).toBe(blob)
+  })
+})
 
 describe('parseImageWidgetValue', () => {
   it('parses a plain filename', () => {

src/utils/imageUtil.ts

@@ -1,3 +1,36 @@
+import { appendCloudResParam } from '@/platform/distribution/cloudPreviewUtil'
+
+const GRID_THUMBNAIL_PREVIEW_FORMAT = 'webp;75'
+
+/**
+ * Converts a full-resolution `/api/view` image URL into a lightweight
+ * thumbnail URL for small on-node grid cells: server-resized on cloud (`res`)
+ * and re-encoded to a compact format on every backend (`preview`). Non-view
+ * URLs, SVGs (the server cannot rasterize them into a preview), and URLs that
+ * already request a preview are returned unchanged.
+ */
+export function getGridThumbnailUrl(url: string): string {
+  if (!url) return url
+  let parsed: URL
+  try {
+    parsed = new URL(url, window.location.origin)
+  } catch {
+    return url
+  }
+  if (!parsed.pathname.endsWith('/view')) return url
+
+  const { searchParams } = parsed
+  const filename = searchParams.get('filename') ?? undefined
+  const isSvg = !!filename && filename.toLowerCase().endsWith('.svg')
+  appendCloudResParam(searchParams, filename)
+  if (!isSvg && !searchParams.has('preview'))
+    searchParams.set('preview', GRID_THUMBNAIL_PREVIEW_FORMAT)
+
+  return url.startsWith('http')
+    ? parsed.toString()
+    : `${parsed.pathname}${parsed.search}`
+}
+
 /**
  * Parses an image widget value like "subfolder/filename [type]" into its parts.
  */