fix: preserve annotations for bulk asset insertion (#14126)

## ELI5

When ComfyUI inserts or drops a generated asset, it must keep the marker
that says where the file lives. This change makes structured assets own
that decision, preventing valid output files from being reported as
missing.

## Summary

- Fix false missing-media errors after bulk-inserting temporary or
output assets from the Asset Panel.
- Fix dropped output `ResultItem`s on output-folder image loaders so
their serialized widget values retain `[output]`.
- Make the structured path API reject caller-supplied root/subfolder
options, while preserving the explicit string-path contract.
- Preserve the Job Queue insertion behavior merged in #14081.

## Changes

- **Path contract**: Separate string and `ResultItem` overloads.
`ResultItem` paths derive annotations from `item.type`, preserve
existing annotations, and reject caller options; string roots are
limited to `ResultItemType`.
- **Callers**: Share one Asset Panel asset-to-widget-path conversion
across single and bulk insertion. Keep string uploads driven by
`image_folder`, while dropped `ResultItem`s use their own type. Narrow
the Mask Editor string boundary safely.
- **Unit coverage**: Guard the forbidden `ResultItem` options call at
runtime and typecheck time; cover input/temp/output, pre-annotated
paths, missing types, single/bulk Asset Panel insertion, Job Queue media
types, and image-upload string/`ResultItem` controls.
- **E2E coverage**: From a blank workflow, bulk-insert exactly two
generated assets through the Asset Panel, confirm two nodes, and finish
at the user-visible no-error assertion without inspecting annotation
strings.
- **E2E synchronization**: The shared helper races the exact
verification response against surfaced error UI. Job Queue
synchronization now requires the output-tagged `/api/assets` request, so
a regression fails at `sawErrorUi` instead of an unrelated response or
network timeout.

## RED → GREEN proof

- **🔴 RED**: CodeRabbit reviewed the tests-only [bca10b0
commit](bca10b0)
with no remaining findings.
- [Unit test
job](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30234592564/job/89879872146):
the new test alone failed because `hash1.jpeg` and `hash2.jpeg` were
missing `[temp]` and `[output]`; the other 13,467 tests passed.
- [Chromium E2E shard
11/16](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30234592612/job/89880156060):
setup, two-asset selection, and two-node creation passed, then every
attempt failed only at the final no-error-UI observation with `observed:
true, sawErrorUi: true`. [Playwright Chromium
report](https://2e6947aa.comfyui-playwright-chromium.pages.dev).
- **🟢 GREEN**: The historical proof remains at the [production
implementation](06d27f9)
and [GREEN
HEAD](de4c593).
- [Unit test
job](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30236104670/job/89885801805):
all 1,020 test files and 13,476 tests passed, including
string/`ResultItem` controls, Asset Panel input/temp/output widget
values, and Job Queue image/video/audio annotations.
- [Chromium E2E shard
11/16](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30236104668/job/89884452924):
the regression passed through blank-workflow setup, two-asset selection,
two-node creation, and the final no-error-UI observation. [Playwright
Chromium
report](https://cc695aff.comfyui-playwright-chromium.pages.dev).
- **Current review HEAD**:
[eef7a9c](eef7a9c),
including the [review-response commit
b2d171c](b2d171c)
after integrating merged parent #14081 in
[b20d562](b20d562).
- Local verification: 99 focused Unit tests, app/browser typechecks,
full lint, format check, knip, and the focused Asset Panel Playwright
E2E pass.
  - Fresh CI is in progress for this HEAD.

## Follow-up

- #14356 tracks `[temp]` paths in missing-media detection. The
annotation is correct, but the detector lacks an authoritative
temp-asset source; simply widening its regex would not safely resolve
the end-to-end false positive.

## Review Focus

- Confirm the overloads make `ResultItem` ownership unambiguous while
preserving string-path behavior.
- Confirm single, bulk, drop, Job Queue, and input/temp/output controls
cover both the fixed paths and preserved behavior.
- Confirm both E2E paths protect the user-visible no-error outcome with
positive synchronization signals.

## Screenshot

Before


https://github.com/user-attachments/assets/1d309b94-6dda-4441-974f-5d69ff32beb8

After


https://github.com/user-attachments/assets/8cf5320f-6dc0-4552-86a3-98ef5d39aa1a

Author: jaeone94

apps/website/src/components/home/GetStartedSection.vue

@@ -37,17 +37,17 @@ const steps = [
 
 <template>
   <section
-    class="bg-primary-comfy-ink max-w-9xl mx-auto px-4 py-20 lg:px-20 lg:py-24"
+    class="max-w-9xl mx-auto bg-primary-comfy-ink px-4 py-20 lg:px-20 lg:py-24"
   >
     <div class="flex flex-col gap-12 lg:flex-row lg:gap-8">
       <!-- Left heading -->
       <div
-        class="bg-primary-comfy-ink sticky top-20 shrink-0 py-2 lg:top-28 lg:w-115 lg:self-start"
+        class="sticky top-20 shrink-0 bg-primary-comfy-ink py-2 lg:top-28 lg:w-115 lg:self-start"
       >
-        <h2 class="text-primary-comfy-canvas text-5xl font-light">
+        <h2 class="text-5xl font-light text-primary-comfy-canvas">
           {{ t('getStarted.heading', locale) }}
         </h2>
-        <p class="text-primary-comfy-canvas mt-8 text-base">
+        <p class="mt-8 text-base text-primary-comfy-canvas">
           {{ t('getStarted.subheading', locale) }}
         </p>
       </div>
@@ -57,27 +57,27 @@ const steps = [
         <div
           v-for="step in steps"
           :key="step.number"
-          class="border-primary-comfy-canvas flex flex-col gap-4 border-b py-12 first:pt-0 last:border-b lg:flex-row lg:items-start lg:gap-8"
+          class="flex flex-col gap-4 border-b border-primary-comfy-canvas py-12 first:pt-0 last:border-b lg:flex-row lg:items-start lg:gap-8"
         >
           <span
-            class="text-primary-comfy-canvas w-16 shrink-0 text-6xl font-light lg:text-7xl"
+            class="w-16 shrink-0 text-6xl font-light text-primary-comfy-canvas lg:text-7xl"
           >
             {{ step.number }}
           </span>
           <h3
-            class="text-primary-comfy-canvas shrink-0 text-2xl font-light lg:w-84"
+            class="shrink-0 text-2xl font-light text-primary-comfy-canvas lg:w-84"
           >
             {{ step.title }}
           </h3>
           <p
             v-if="step.description"
-            class="text-primary-comfy-canvas flex-1 text-sm"
+            class="flex-1 text-sm text-primary-comfy-canvas"
           >
             {{ step.description }}
           </p>
           <p
             v-else-if="step.number === '2'"
-            class="text-primary-comfy-canvas flex-1 text-sm"
+            class="flex-1 text-sm text-primary-comfy-canvas"
           >
             {{ t('getStarted.step2.descriptionPrefix', locale)
             }}<a

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

@@ -31,13 +31,13 @@ const { loaded: logoLoaded } = useHeroLogo(logoContainer)
 
     <div class="flex-1 px-6 py-12 lg:px-16">
       <h1
-        class="text-primary-comfy-canvas text-4xl font-light whitespace-pre-line lg:text-6xl"
+        class="text-4xl font-light whitespace-pre-line text-primary-comfy-canvas lg:text-6xl"
       >
         {{ t('hero.title', locale) }}
       </h1>
 
       <p
-        class="text-primary-comfy-canvas mt-8 max-w-lg text-sm/relaxed lg:text-base"
+        class="mt-8 max-w-lg text-sm/relaxed text-primary-comfy-canvas lg:text-base"
       >
         {{ t('hero.subtitle', locale) }}
       </p>

browser_tests/fixtures/helpers/ErrorsTabHelper.ts

@@ -50,10 +50,15 @@ export async function expectNoErrorUiAfterVerification(
   verificationResponse: Promise<Response>,
   observationMs = 2_000
 ): Promise<void> {
-  await verificationResponse
-
   const overlay = comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
-  let sawErrorUi = false
+  const readiness = await Promise.race([
+    verificationResponse.then(() => 'verification' as const),
+    overlay.waitFor({ state: 'visible' }).then(() => 'error-ui' as const),
+    panel.errorsTab
+      .waitFor({ state: 'visible' })
+      .then(() => 'error-ui' as const)
+  ])
+  let sawErrorUi = readiness === 'error-ui'
   const startedAt = Date.now()
 
   await expect

browser_tests/tests/queue/jobOutputInsertion.spec.ts

@@ -1,5 +1,6 @@
 import { expect } from '@playwright/test'
 
+import { assetRequestIncludesTag } from '@e2e/fixtures/assetApiFixture'
 import { jobOutputInsertionCases } from '@e2e/fixtures/data/jobOutputInsertion'
 import { expectNoErrorUiAfterVerification } from '@e2e/fixtures/helpers/ErrorsTabHelper'
 import { jobOutputInsertionTest as test } from '@e2e/fixtures/jobOutputInsertionFixture'
@@ -36,7 +37,8 @@ test.describe(
           (response) =>
             response.request().method().toUpperCase() === 'GET' &&
             response.status() === 200 &&
-            new URL(response.url()).pathname.endsWith('/api/assets')
+            new URL(response.url()).pathname.endsWith('/api/assets') &&
+            assetRequestIncludesTag(response.url(), 'output')
         )
 
         await comfyPage.queuePanel.addOutputToCurrentWorkflow(scenario.job.id)

browser_tests/tests/sidebar/assetsSidebarTab.spec.ts

@@ -1,12 +1,16 @@
 import { expect, mergeTests } from '@playwright/test'
-import type { Page } from '@playwright/test'
+import type { Page, Response } from '@playwright/test'
 
 import { comfyPageFixture } from '@e2e/fixtures/ComfyPage'
+import { expectNoErrorUiAfterVerification } from '@e2e/fixtures/helpers/ErrorsTabHelper'
 import {
   createRouteMockJob,
+  JobsRouteMocker,
   jobsRouteFixture,
   routeMockJobTimestamp
 } from '@e2e/fixtures/jobsRouteFixture'
+import { TestIds } from '@e2e/fixtures/selectors'
+import { PropertiesPanelHelper } from '@e2e/tests/propertiesPanel/PropertiesPanelHelper'
 import type {
   JobDetail,
   RawJobListItem
@@ -145,6 +149,27 @@ async function mockViewFiles(page: Page, filesByName: ViewFilesByName) {
   })
 }
 
+function isGeneratedAssetVerificationResponse(response: Response): boolean {
+  const url = new URL(response.url())
+  return (
+    response.request().method().toUpperCase() === 'GET' &&
+    response.status() === 200 &&
+    url.pathname.endsWith('/api/jobs') &&
+    url.searchParams.get('status')?.split(',').includes('completed') === true
+  )
+}
+
+const bulkInsertionTest = comfyPageFixture.extend({
+  page: async ({ page }, use) => {
+    const jobsRoutes = new JobsRouteMocker(page)
+    await jobsRoutes.mockJobsQueue([])
+    await jobsRoutes.mockJobsHistory(generatedJobs)
+    await mockInputFiles(page, [])
+    await mockViewFiles(page, viewFiles)
+    await use(page)
+  }
+})
+
 test.describe('FE-130 assets sidebar route mocks', () => {
   test.beforeEach(async ({ jobsRoutes, page }) => {
     await jobsRoutes.mockJobsQueue([])
@@ -284,6 +309,68 @@ test.describe('FE-130 assets sidebar route mocks', () => {
   })
 })
 
+bulkInsertionTest.describe(
+  'Assets sidebar - bulk insert as nodes',
+  { tag: ['@vue-nodes', '@ui', '@node', '@widget'] },
+  () => {
+    bulkInsertionTest.use({
+      initialSettings: {
+        'Comfy.RightSidePanel.ShowErrorsTab': true
+      }
+    })
+
+    bulkInsertionTest.beforeEach(async ({ comfyPage }) => {
+      await comfyPage.command.executeCommand('Comfy.NewBlankWorkflow')
+      await expect.poll(() => comfyPage.nodeOps.getGraphNodesCount()).toBe(0)
+      await comfyPage.toast.closeToasts()
+      const panel = new PropertiesPanelHelper(comfyPage.page)
+      await panel.open(comfyPage.actionbar.propertiesButton)
+      await expect(
+        comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
+      ).toBeHidden()
+      await expect(panel.errorsTab).toBeHidden()
+
+      const tab = comfyPage.menu.assetsTab
+      await tab.open()
+      await expect(tab.assetCards).toHaveCount(2)
+    })
+
+    bulkInsertionTest(
+      'does not surface errors for inserted output assets',
+      async ({ comfyPage }) => {
+        const tab = comfyPage.menu.assetsTab
+        const panel = new PropertiesPanelHelper(comfyPage.page)
+        await expect(panel.root).toBeVisible()
+
+        await tab.getAssetCardByName('alpha').click()
+        await comfyPage.page.keyboard.down('ControlOrMeta')
+        await tab.getAssetCardByName('beta').click()
+        await comfyPage.page.keyboard.up('ControlOrMeta')
+        await expect(tab.selectedCards).toHaveCount(2)
+
+        const generatedAssetVerificationResponse =
+          comfyPage.page.waitForResponse(isGeneratedAssetVerificationResponse)
+
+        await tab.getAssetCardByName('alpha').dispatchEvent('contextmenu', {
+          bubbles: true,
+          cancelable: true,
+          button: 2
+        })
+        await expect(comfyPage.contextMenu.primeVueMenu).toBeVisible()
+        await tab.contextMenuItem('Insert all assets as nodes').click()
+
+        await expect.poll(() => comfyPage.vueNodes.getNodeCount()).toBe(2)
+
+        await expectNoErrorUiAfterVerification(
+          comfyPage,
+          panel,
+          generatedAssetVerificationResponse
+        )
+      }
+    )
+  }
+)
+
 test.describe('FE-910 marquee selection and select all', () => {
   test.beforeEach(async ({ jobsRoutes, page, comfyPage }) => {
     await jobsRoutes.mockJobsQueue([])

src/composables/maskeditor/useMaskEditorSaver.ts

@@ -12,6 +12,7 @@ import { api } from '@/scripts/api'
 import { app } from '@/scripts/app'
 import { createAnnotatedPath } from '@/utils/createAnnotatedPath'
 import { encodeRgbaAsPng } from '@/utils/pngEncodeUtil'
+import { isResultItemType } from '@/utils/typeGuardUtil'
 import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
 
 // Private layer filename functions
@@ -302,7 +303,7 @@ export function useMaskEditorSaver() {
     node.imgs = undefined
     const annotatedPath = createAnnotatedPath(mainRef.filename, {
       subfolder: mainRef.subfolder,
-      rootFolder: mainRef.type
+      rootFolder: isResultItemType(mainRef.type) ? mainRef.type : undefined
     })
     nodeOutputStore.setNodeOutputs(node, annotatedPath, { folder: 'input' })
     node.graph?.setDirtyCanvas(true)

src/composables/queue/useJobMenu.test.ts

@@ -441,6 +441,7 @@ describe('useJobMenu', () => {
       filename: 'foo.png',
       widget: 'image',
       type: 'temp',
+      // TODO(#14356): Missing-media detection cannot yet verify [temp] paths.
       expectedWidgetValue: 'bar/foo.png [temp]'
     },
     {

src/composables/queue/useJobMenu.ts

@@ -10,7 +10,7 @@ import { useSettingStore } from '@/platform/settings/settingStore'
 import { withNodeAddSource } from '@/platform/telemetry/nodeAdded/nodeAddSource'
 import { useWorkflowService } from '@/platform/workflow/core/services/workflowService'
 import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
-import type { ResultItem, ResultItemType } from '@/schemas/apiSchema'
+import type { ResultItem } from '@/schemas/apiSchema'
 import { api } from '@/scripts/api'
 import { downloadBlob } from '@/scripts/utils'
 import { useDialogService } from '@/services/dialogService'
@@ -22,6 +22,7 @@ import { useQueueStore } from '@/stores/queueStore'
 import type { ResultItemImpl, TaskItemImpl } from '@/stores/queueStore'
 import { createAnnotatedPath } from '@/utils/createAnnotatedPath'
 import { appendJsonExt } from '@/utils/formatUtil'
+import { isResultItemType } from '@/utils/typeGuardUtil'
 
 export type MenuEntry =
   | {
@@ -153,18 +154,13 @@ export function useJobMenu(
 
     if (!node) return
 
-    const isResultItemType = (v: string | undefined): v is ResultItemType =>
-      v === 'input' || v === 'output' || v === 'temp'
-
     const apiItem: ResultItem = {
       filename: result.filename,
       subfolder: result.subfolder,
       type: isResultItemType(result.type) ? result.type : 'output'
     }
 
-    const annotated = createAnnotatedPath(apiItem, {
-      rootFolder: 'input'
-    })
+    const annotated = createAnnotatedPath(apiItem)
     const widget = node.widgets?.find((w) => w.name === widgetName)
     if (widget) {
       widget.value = annotated