[docs] Update API changelog for v1.31.1

- Usage examples via UI and CLI
- Detailed explanation of workflow steps
- Common use cases and troubleshooting
- Security and monitoring information

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

Co-Authored-By: Claude <noreply@anthropic.com>

.gitattributes

@@ -7,6 +7,7 @@
 *.json text eol=lf
 *.mjs text eol=lf
 *.mts text eol=lf
+*.snap text eol=lf
 *.ts text eol=lf
 *.vue text eol=lf
 *.yaml text eol=lf

.github/workflows/README-manual-api-changelog.md

@@ -0,0 +1,234 @@
+# Manual API Changelog Generation
+
+This workflow allows you to generate API changelogs by comparing any two versions of the ComfyUI Frontend package.
+
+## Usage
+
+### Via GitHub Actions UI
+
+1. Go to **Actions** tab in the repository
+2. Select **Manual API Changelog Generation** from the workflows list
+3. Click **Run workflow** button
+4. Fill in the inputs:
+   - **Previous version**: The earlier version (e.g., `1.29.0` or `v1.29.0`)
+   - **Current version**: The later version (e.g., `1.30.2` or `v1.30.2`)
+   - **Create PR**: Check this to automatically create a pull request with the changelog
+
+### Via GitHub CLI
+
+```bash
+# Basic usage - just generate changelog
+gh workflow run manual-api-changelog.yaml \
+  -f from_version=1.29.0 \
+  -f to_version=1.30.2 \
+  -f create_pr=false
+
+# Generate changelog and create PR
+gh workflow run manual-api-changelog.yaml \
+  -f from_version=1.29.0 \
+  -f to_version=1.30.2 \
+  -f create_pr=true
+```
+
+## What It Does
+
+1. **Validates Inputs**: Checks that version formats are valid (X.Y.Z) and tags exist
+2. **Builds Both Versions**: Checks out each version tag, installs dependencies, and builds TypeScript types
+3. **Generates Snapshots**: Creates structured JSON snapshots of the public API surface for each version
+4. **Compares APIs**: Analyzes differences and categorizes as:
+   - ⚠️ **Breaking changes** (removals, signature changes)
+   - ✨ **Additions** (new interfaces, methods, properties)
+   - 🔄 **Modifications** (non-breaking changes)
+5. **Uploads Artifact**: Saves the changelog and snapshots as a workflow artifact (90-day retention)
+6. **Creates PR** (optional): Generates a draft PR to update `docs/API-CHANGELOG.md`
+
+## Output
+
+### Workflow Artifacts
+
+Every run produces an artifact containing:
+- `CHANGELOG-{from}-to-{to}.md` - Human-readable changelog
+- `from.json` - API snapshot of the earlier version
+- `to.json` - API snapshot of the later version
+
+**Retention**: 90 days
+
+### Pull Request (Optional)
+
+If `create_pr` is enabled and changes are detected:
+- Creates a draft PR with title: `[docs] API Changelog: v{from} → v{to}`
+- Updates `docs/API-CHANGELOG.md` with the new changelog entry
+- Includes detailed metadata and review instructions
+- Labeled with `documentation`
+
+## Example Changelog Output
+
+```markdown
+## v1.30.2 (2025-11-04)
+
+Comparing v1.29.0 → v1.30.2. This changelog documents changes to the public API surface.
+
+### ✨ Additions
+
+**Type Aliases**
+- `WorkflowId`
+
+**Interfaces**
+- `ExtensionMetadata`
+  - Members: `id`, `name`, `version`, `description`
+
+### 🔄 Modifications
+
+> **Note**: Some modifications may be breaking changes.
+
+**Interfaces**
+- `ComfyApi`
+  - ✨ Added member: `queuePromptAsync`
+  - ✨ Added member: `cancelPrompt`
+  - ⚠️ **Breaking**: Removed member: `queuePrompt`
+
+**Enums**
+- `NodeStatus`
+  - ✨ Added enum value: `ERROR`
+  - ✨ Added enum value: `COMPLETED`
+```
+
+## Use Cases
+
+### 1. Generate Changelog for Missed Releases
+
+If the automatic workflow failed or was skipped for a release:
+
+```bash
+gh workflow run manual-api-changelog.yaml \
+  -f from_version=1.28.0 \
+  -f to_version=1.29.0 \
+  -f create_pr=true
+```
+
+### 2. Compare Non-Adjacent Versions
+
+To see cumulative changes across multiple releases:
+
+```bash
+gh workflow run manual-api-changelog.yaml \
+  -f from_version=1.25.0 \
+  -f to_version=1.30.2 \
+  -f create_pr=false
+```
+
+### 3. Test Upcoming Changes
+
+Compare current `main` branch against the latest release (requires creating a temporary tag):
+
+```bash
+# Create temporary tag for current main
+git tag v1.31.0-preview
+git push origin v1.31.0-preview
+
+# Run comparison
+gh workflow run manual-api-changelog.yaml \
+  -f from_version=1.30.2 \
+  -f to_version=1.31.0-preview \
+  -f create_pr=false
+
+# Clean up temporary tag
+git tag -d v1.31.0-preview
+git push origin :refs/tags/v1.31.0-preview
+```
+
+### 4. Audit Historical Changes
+
+Generate changelogs for documentation purposes:
+
+```bash
+# Compare multiple version pairs
+for from in 1.26.0 1.27.0 1.28.0 1.29.0; do
+  to=$(echo "$from" | awk -F. '{print $1"."$2+1".0"}')
+  gh workflow run manual-api-changelog.yaml \
+    -f from_version=$from \
+    -f to_version=$to \
+    -f create_pr=false
+done
+```
+
+## Validation
+
+The workflow validates:
+- ✅ Version format matches semantic versioning (X.Y.Z)
+- ✅ Both version tags exist in the repository
+- ✅ Tags reference valid commits with buildable code
+
+If validation fails, the workflow exits early with a clear error message.
+
+## Limitations
+
+- **Tag requirement**: Both versions must have corresponding `vX.Y.Z` git tags
+- **Build requirement**: Both versions must have functional build processes
+- **Type files**: Requires `dist/index.d.ts` to exist after building
+- **Scripts**: Requires `scripts/snapshot-api.js` and `scripts/compare-api-snapshots.js` to be present
+
+## Related Workflows
+
+- **[Release API Changelogs](.github/workflows/release-api-changelogs.yaml)**: Automatic changelog generation triggered by NPM releases
+- **[Release NPM Types](.github/workflows/release-npm-types.yaml)**: Publishes type definitions and triggers automatic changelog
+
+## Troubleshooting
+
+### "Tag does not exist" error
+
+Ensure the version exists as a git tag:
+
+```bash
+git tag -l 'v*' | grep 1.29.0
+```
+
+If missing, the version may not have been released yet.
+
+### "Build failed" error
+
+Check that the version can be built successfully:
+
+```bash
+git checkout v1.29.0
+pnpm install
+pnpm build:types
+```
+
+### No changes detected
+
+If the workflow reports no changes but you expect some:
+1. Check the artifact snapshots to verify they're different
+2. Ensure you're comparing the correct versions
+3. Review the comparison script logic in `scripts/compare-api-snapshots.js`
+
+### PR not created
+
+PR creation requires:
+- `create_pr` input set to `true`
+- Significant changes detected (more than just headers)
+- `PR_GH_TOKEN` secret configured with appropriate permissions
+
+## Security
+
+- **Permissions**: Workflow requires `contents: write` and `pull-requests: write`
+- **Token**: Uses `secrets.PR_GH_TOKEN` for PR creation
+- **Isolation**: Each workflow run uses a unique concurrency group
+- **Artifacts**: Retained for 90 days, accessible to repository collaborators
+
+## Monitoring
+
+View workflow runs:
+```bash
+gh run list --workflow=manual-api-changelog.yaml
+```
+
+View specific run details:
+```bash
+gh run view <run-id>
+```
+
+Download artifacts:
+```bash
+gh run download <run-id>
+```

.github/workflows/ci-size-data.yaml

@@ -1,4 +1,4 @@
-name: size data
+name: "CI: Size Data"
 
 on:
   push:

.github/workflows/manual-api-changelog.yaml

@@ -0,0 +1,249 @@
+name: Manual API Changelog Generation
+
+on:
+  workflow_dispatch:
+    inputs:
+      from_version:
+        description: 'Previous version (e.g., 1.29.0 or v1.29.0)'
+        required: true
+        type: string
+      to_version:
+        description: 'Current version (e.g., 1.30.2 or v1.30.2)'
+        required: true
+        type: string
+      create_pr:
+        description: 'Create a pull request with the changelog'
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: manual-api-changelog-${{ github.run_id }}
+  cancel-in-progress: false
+
+jobs:
+  generate_changelog:
+    name: Generate API Changelog
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Fetch all history for comparing versions
+
+      - name: Validate version inputs
+        id: validate_versions
+        run: |
+          # Normalize version strings (remove 'v' prefix if present)
+          FROM_VERSION="${{ github.event.inputs.from_version }}"
+          TO_VERSION="${{ github.event.inputs.to_version }}"
+
+          FROM_VERSION=${FROM_VERSION#v}
+          TO_VERSION=${TO_VERSION#v}
+
+          # Validate version format (semantic versioning)
+          if ! [[ "$FROM_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Error: Invalid from_version format: $FROM_VERSION"
+            echo "Expected format: X.Y.Z (e.g., 1.29.0)"
+            exit 1
+          fi
+
+          if ! [[ "$TO_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Error: Invalid to_version format: $TO_VERSION"
+            echo "Expected format: X.Y.Z (e.g., 1.30.2)"
+            exit 1
+          fi
+
+          # Check if tags exist
+          if ! git rev-parse "v$FROM_VERSION" >/dev/null 2>&1; then
+            echo "Error: Tag v$FROM_VERSION does not exist"
+            exit 1
+          fi
+
+          if ! git rev-parse "v$TO_VERSION" >/dev/null 2>&1; then
+            echo "Error: Tag v$TO_VERSION does not exist"
+            exit 1
+          fi
+
+          echo "from_version=$FROM_VERSION" >> $GITHUB_OUTPUT
+          echo "to_version=$TO_VERSION" >> $GITHUB_OUTPUT
+          echo "from_tag=v$FROM_VERSION" >> $GITHUB_OUTPUT
+          echo "to_tag=v$TO_VERSION" >> $GITHUB_OUTPUT
+
+          echo "✅ Validated versions: v$FROM_VERSION → v$TO_VERSION"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 'lts/*'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+        env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1'
+
+      - name: Create snapshots directory
+        run: mkdir -p .api-snapshots
+
+      - name: Preserve scripts
+        run: |
+          # Copy scripts to temporary location
+          mkdir -p /tmp/api-changelog-scripts
+          cp scripts/snapshot-api.js scripts/compare-api-snapshots.js /tmp/api-changelog-scripts/
+
+      - name: Build and snapshot TO version
+        run: |
+          echo "Building types for v${{ steps.validate_versions.outputs.to_version }}"
+          git checkout ${{ steps.validate_versions.outputs.to_tag }}
+
+          # Restore scripts
+          mkdir -p scripts
+          cp /tmp/api-changelog-scripts/*.js scripts/
+
+          pnpm install --frozen-lockfile
+          pnpm build:types
+
+          # Generate snapshot
+          node scripts/snapshot-api.js dist/index.d.ts > /tmp/api-snapshots-to.json
+
+          echo "✅ Created snapshot for v${{ steps.validate_versions.outputs.to_version }}"
+
+      - name: Build and snapshot FROM version
+        run: |
+          echo "Building types for v${{ steps.validate_versions.outputs.from_version }}"
+          git checkout ${{ steps.validate_versions.outputs.from_tag }}
+
+          # Restore scripts
+          mkdir -p scripts
+          cp /tmp/api-changelog-scripts/*.js scripts/
+
+          pnpm install --frozen-lockfile
+          pnpm build:types
+
+          # Generate snapshot
+          node scripts/snapshot-api.js dist/index.d.ts > /tmp/api-snapshots-from.json
+
+          echo "✅ Created snapshot for v${{ steps.validate_versions.outputs.from_version }}"
+
+      - name: Return to original branch
+        run: |
+          git checkout ${{ github.ref_name }}
+
+          # Restore scripts
+          mkdir -p scripts
+          cp /tmp/api-changelog-scripts/*.js scripts/
+
+          # Copy snapshots to working directory
+          cp /tmp/api-snapshots-from.json .api-snapshots/from.json
+          cp /tmp/api-snapshots-to.json .api-snapshots/to.json
+
+      - name: Compare API snapshots and generate changelog
+        id: generate_changelog
+        run: |
+          # Run the comparison script
+          CHANGELOG_OUTPUT=$(node scripts/compare-api-snapshots.js \
+            .api-snapshots/from.json \
+            .api-snapshots/to.json \
+            ${{ steps.validate_versions.outputs.from_version }} \
+            ${{ steps.validate_versions.outputs.to_version }})
+
+          # Save changelog to file for artifact
+          echo "$CHANGELOG_OUTPUT" > .api-snapshots/CHANGELOG-${{ steps.validate_versions.outputs.from_version }}-to-${{ steps.validate_versions.outputs.to_version }}.md
+
+          # Also output to step summary
+          echo "## 📊 Generated API Changelog" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "$CHANGELOG_OUTPUT" >> $GITHUB_STEP_SUMMARY
+
+          # Check if changelog is empty or just header
+          if [ $(echo "$CHANGELOG_OUTPUT" | wc -l) -lt 5 ]; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "⚠️ No significant API changes detected" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "✅ API changes detected and documented" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          echo "✅ Changelog generated successfully"
+
+      - name: Upload changelog artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-changelog-v${{ steps.validate_versions.outputs.from_version }}-to-v${{ steps.validate_versions.outputs.to_version }}
+          path: |
+            .api-snapshots/CHANGELOG-*.md
+            .api-snapshots/from.json
+            .api-snapshots/to.json
+          retention-days: 90
+
+      - name: Create Pull Request
+        if: github.event.inputs.create_pr == 'true' && steps.generate_changelog.outputs.has_changes == 'true'
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e
+        with:
+          token: ${{ secrets.PR_GH_TOKEN }}
+          commit-message: '[docs] Update API changelog for v${{ steps.validate_versions.outputs.from_version }} → v${{ steps.validate_versions.outputs.to_version }}'
+          title: '[docs] API Changelog: v${{ steps.validate_versions.outputs.from_version }} → v${{ steps.validate_versions.outputs.to_version }}'
+          body: |
+            ## API Changelog Update (Manual)
+
+            This PR documents public API changes between v${{ steps.validate_versions.outputs.from_version }} and v${{ steps.validate_versions.outputs.to_version }}.
+
+            The changelog has been manually generated by comparing TypeScript type definitions between versions.
+
+            ### Version Comparison
+            - **From:** v${{ steps.validate_versions.outputs.from_version }}
+            - **To:** v${{ steps.validate_versions.outputs.to_version }}
+            - **Requested by:** @${{ github.actor }}
+            - **Workflow run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+
+            ### Review Instructions
+            - Review the changes in `docs/API-CHANGELOG.md`
+            - Verify accuracy of breaking changes
+            - Add any additional context or migration notes if needed
+            - Merge when ready to publish changelog
+
+            ### Artifacts
+            The full changelog and snapshots are available as workflow artifacts for 90 days.
+
+            ---
+            🤖 Generated with [Claude Code](https://claude.com/claude-code)
+          branch: api-changelog-manual-${{ steps.validate_versions.outputs.from_version }}-to-${{ steps.validate_versions.outputs.to_version }}
+          base: ${{ github.ref_name }}
+          labels: documentation
+          delete-branch: true
+          draft: true
+          add-paths: |
+            docs/API-CHANGELOG.md
+
+      - name: Summary
+        run: |
+          echo "## 🎉 Workflow Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **From version:** v${{ steps.validate_versions.outputs.from_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **To version:** v${{ steps.validate_versions.outputs.to_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Changes detected:** ${{ steps.generate_changelog.outputs.has_changes }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Create PR:** ${{ github.event.inputs.create_pr }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Artifact" >> $GITHUB_STEP_SUMMARY
+          echo "The generated changelog and API snapshots have been uploaded as artifacts." >> $GITHUB_STEP_SUMMARY
+          echo "Retention: 90 days" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ github.event.inputs.create_pr }}" == "true" ] && [ "${{ steps.generate_changelog.outputs.has_changes }}" == "true" ]; then
+            echo "### 🔀 Pull Request" >> $GITHUB_STEP_SUMMARY
+            echo "A draft pull request has been created with the changelog updates." >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ github.event.inputs.create_pr }}" == "true" ]; then
+            echo "### ℹ️ No PR Created" >> $GITHUB_STEP_SUMMARY
+            echo "No significant changes were detected, so no PR was created." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "### ℹ️ PR Creation Skipped" >> $GITHUB_STEP_SUMMARY
+            echo "Pull request creation was not requested. Enable 'Create PR' option to automatically create a PR." >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/pr-backport.yaml

@@ -69,34 +69,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Check if backports already exist
-        id: check-existing
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ github.event_name == 'workflow_dispatch' && inputs.pr_number || github.event.pull_request.number }}
-        run: |
-          # Check for existing backport PRs for this PR number
-          EXISTING_BACKPORTS=$(gh pr list --state all --search "backport-${PR_NUMBER}-to" --json title,headRefName,baseRefName | jq -r '.[].headRefName')
-          
-          if [ -z "$EXISTING_BACKPORTS" ]; then
-            echo "skip=false" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-          
-          # For manual triggers with force_rerun, proceed anyway
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.force_rerun }}" = "true" ]; then
-            echo "skip=false" >> $GITHUB_OUTPUT
-            echo "::warning::Force rerun requested - existing backports will be updated"
-            exit 0
-          fi
-          
-          echo "Found existing backport PRs:"
-          echo "$EXISTING_BACKPORTS"
-          echo "skip=true" >> $GITHUB_OUTPUT
-          echo "::warning::Backport PRs already exist for PR #${PR_NUMBER}, skipping to avoid duplicates"
-
       - name: Collect backport targets
-        if: steps.check-existing.outputs.skip != 'true'
         id: targets
         run: |
           TARGETS=()
@@ -138,6 +111,14 @@ jobs:
               add_target "$label" "${BASH_REMATCH[1]}"
             elif [[ "$label" =~ ^backport:(.+)$ ]]; then
               add_target "$label" "${BASH_REMATCH[1]}"
+            elif [[ "$label" =~ ^core\/([0-9]+)\.([0-9]+)$ ]]; then
+              SAFE_MAJOR="${BASH_REMATCH[1]}"
+              SAFE_MINOR="${BASH_REMATCH[2]}"
+              add_target "$label" "core/${SAFE_MAJOR}.${SAFE_MINOR}"
+            elif [[ "$label" =~ ^cloud\/([0-9]+)\.([0-9]+)$ ]]; then
+              SAFE_MAJOR="${BASH_REMATCH[1]}"
+              SAFE_MINOR="${BASH_REMATCH[2]}"
+              add_target "$label" "cloud/${SAFE_MAJOR}.${SAFE_MINOR}"
             elif [[ "$label" =~ ^[0-9]+\.[0-9]+$ ]]; then
               add_target "$label" "core/${label}"
             fi
@@ -151,8 +132,76 @@ jobs:
           echo "targets=${TARGETS[*]}" >> $GITHUB_OUTPUT
           echo "Found backport targets: ${TARGETS[*]}"
 
+      - name: Filter already backported targets
+        id: filter-targets
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          FORCE_RERUN_INPUT: >-
+            ${{ github.event_name == 'workflow_dispatch' && inputs.force_rerun
+            || 'false' }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: >-
+            ${{ github.event_name == 'workflow_dispatch' && inputs.pr_number
+            || github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+
+          REQUESTED_TARGETS="${{ steps.targets.outputs.targets }}"
+          if [ -z "$REQUESTED_TARGETS" ]; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "pending-targets=" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          FORCE_RERUN=false
+          if [ "$EVENT_NAME" = "workflow_dispatch" ] && [ "$FORCE_RERUN_INPUT" = "true" ]; then
+            FORCE_RERUN=true
+          fi
+
+          mapfile -t EXISTING_BRANCHES < <(
+            git ls-remote --heads origin "backport-${PR_NUMBER}-to-*" || true
+          )
+
+          PENDING=()
+          SKIPPED=()
+
+          for target in $REQUESTED_TARGETS; do
+            SAFE_TARGET=$(echo "$target" | tr '/' '-')
+            BACKPORT_BRANCH="backport-${PR_NUMBER}-to-${SAFE_TARGET}"
+
+            if [ "$FORCE_RERUN" = true ]; then
+              PENDING+=("$target")
+              continue
+            fi
+
+            if printf '%s\n' "${EXISTING_BRANCHES[@]:-}" |
+              grep -Fq "refs/heads/${BACKPORT_BRANCH}"; then
+              SKIPPED+=("$target")
+            else
+              PENDING+=("$target")
+            fi
+          done
+
+          SKIPPED_JOINED="${SKIPPED[*]:-}"
+          PENDING_JOINED="${PENDING[*]:-}"
+
+          echo "already-exists=${SKIPPED_JOINED}" >> $GITHUB_OUTPUT
+          echo "pending-targets=${PENDING_JOINED}" >> $GITHUB_OUTPUT
+
+          if [ -z "$PENDING_JOINED" ]; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            if [ -n "$SKIPPED_JOINED" ]; then
+              echo "::warning::Backport branches already exist for: ${SKIPPED_JOINED}"
+            fi
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+            if [ -n "$SKIPPED_JOINED" ]; then
+              echo "::notice::Skipping already backported targets: ${SKIPPED_JOINED}"
+            fi
+          fi
+
       - name: Backport commits
-        if: steps.check-existing.outputs.skip != 'true'
+        if: steps.filter-targets.outputs.skip != 'true'
         id: backport
         env:
           PR_NUMBER: ${{ github.event_name == 'workflow_dispatch' && inputs.pr_number || github.event.pull_request.number }}
@@ -170,7 +219,7 @@ jobs:
             MERGE_COMMIT="${{ github.event.pull_request.merge_commit_sha }}"
           fi
 
-          for target in ${{ steps.targets.outputs.targets }}; do
+          for target in ${{ steps.filter-targets.outputs.pending-targets }}; do
             TARGET_BRANCH="${target}"
             SAFE_TARGET=$(echo "$TARGET_BRANCH" | tr '/' '-')
             BACKPORT_BRANCH="backport-${PR_NUMBER}-to-${SAFE_TARGET}"
@@ -185,6 +234,14 @@ jobs:
               continue
             fi
 
+            # Check if commit already exists on target branch
+            if git branch -r --contains "${MERGE_COMMIT}" | grep -q "origin/${TARGET_BRANCH}"; then
+              echo "::notice::Commit ${MERGE_COMMIT} already exists on ${TARGET_BRANCH}, skipping backport"
+              FAILED="${FAILED}${TARGET_BRANCH}:already-exists "
+              echo "::endgroup::"
+              continue
+            fi
+
             # Create backport branch
             git checkout -b "${BACKPORT_BRANCH}" "origin/${TARGET_BRANCH}"
 
@@ -219,7 +276,7 @@ jobs:
           fi
 
       - name: Create PR for each successful backport
-        if: steps.check-existing.outputs.skip != 'true' && steps.backport.outputs.success
+        if: steps.filter-targets.outputs.skip != 'true' && steps.backport.outputs.success
         env:
           GH_TOKEN: ${{ secrets.PR_GH_TOKEN }}
           PR_NUMBER: ${{ github.event_name == 'workflow_dispatch' && inputs.pr_number || github.event.pull_request.number }}
@@ -258,7 +315,7 @@ jobs:
           done
 
       - name: Comment on failures
-        if: steps.check-existing.outputs.skip != 'true' && failure() && steps.backport.outputs.failed
+        if: steps.filter-targets.outputs.skip != 'true' && failure() && steps.backport.outputs.failed
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -279,6 +336,9 @@ jobs:
             if [ "${reason}" = "branch-missing" ]; then
               gh pr comment "${PR_NUMBER}" --body "@${PR_AUTHOR} Backport failed: Branch \`${target}\` does not exist"
 
+            elif [ "${reason}" = "already-exists" ]; then
+              gh pr comment "${PR_NUMBER}" --body "@${PR_AUTHOR} Commit \`${MERGE_COMMIT}\` already exists on branch \`${target}\`. No backport needed."
+
             elif [ "${reason}" = "conflicts" ]; then
               # Convert comma-separated conflicts back to newlines for display
               CONFLICTS_LIST=$(echo "${conflicts}" | tr ',' '\n' | sed 's/^/- /')
@@ -287,3 +347,9 @@ jobs:
               gh pr comment "${PR_NUMBER}" --body "${COMMENT_BODY}"
             fi
           done
+
+      - name: Remove needs-backport label
+        if: steps.filter-targets.outputs.skip != 'true' && success()
+        run: gh pr edit ${{ github.event_name == 'workflow_dispatch' && inputs.pr_number || github.event.pull_request.number }} --remove-label "needs-backport"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pr-claude-review.yaml

@@ -28,6 +28,7 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           check-regexp: '^(lint-and-format|test|playwright-tests)'
+          allowed-conclusions: success,skipped,failure,cancelled,neutral,action_required,timed_out,stale
           wait-interval: 30
           repo-token: ${{ secrets.GITHUB_TOKEN }}
       

.github/workflows/pr-size-report.yaml

@@ -1,8 +1,8 @@
-name: size report
+name: "PR: Size Report"
 
 on:
   workflow_run:
-    workflows: ['size data']
+    workflows: ['CI: Size Data']
     types:
       - completed
   workflow_dispatch:
@@ -22,7 +22,7 @@ permissions:
   issues: write
 
 jobs:
-  size-report:
+  comment:
     runs-on: ubuntu-latest
     if: >
       github.repository == 'Comfy-Org/ComfyUI_frontend' &&
@@ -78,7 +78,7 @@ jobs:
         uses: dawidd6/action-download-artifact@v11
         with:
           branch: ${{ steps.pr-base.outputs.content }}
-          workflow: size-data.yml
+          workflow: ci-size-data.yaml
           event: push
           name: size-data
           path: temp/size-prev

.github/workflows/release-api-changelogs.yaml

@@ -0,0 +1,197 @@
+name: Release API Changelogs
+
+on:
+  workflow_run:
+    workflows: ['Release NPM Types']
+    types:
+      - completed
+  push:
+    branches:
+      - sno-api-changelog
+
+concurrency:
+  group: release-api-changelogs-${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  generate_changelog:
+    name: Generate API Changelog
+    runs-on: ubuntu-latest
+    # Only run on successful completion of the Release NPM Types workflow or on push to sno-api-changelog
+    if: ${{ github.event_name == 'push' || github.event.workflow_run.conclusion == 'success' }}
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Fetch all history for comparing versions
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 'lts/*'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+        env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1'
+
+      - name: Get current version
+        id: current_version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Current version: $VERSION"
+
+      - name: Get previous version
+        id: previous_version
+        run: |
+          # Get the two most recent version tags sorted
+          CURRENT_VERSION="${{ steps.current_version.outputs.version }}"
+          TAGS=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -2)
+
+          # Find the previous version tag (skip current if it exists)
+          PREVIOUS_TAG=""
+          for tag in $TAGS; do
+            TAG_VERSION=${tag#v}
+            if [ "$TAG_VERSION" != "$CURRENT_VERSION" ]; then
+              PREVIOUS_TAG=$tag
+              break
+            fi
+          done
+
+          if [ -z "$PREVIOUS_TAG" ]; then
+            echo "No previous version found, this may be the first release"
+            echo "version=" >> $GITHUB_OUTPUT
+            echo "tag=" >> $GITHUB_OUTPUT
+          else
+            echo "version=${PREVIOUS_TAG#v}" >> $GITHUB_OUTPUT
+            echo "tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT
+            echo "Previous version: ${PREVIOUS_TAG#v}"
+          fi
+
+      - name: Build current types
+        run: pnpm build:types
+
+      - name: Snapshot current API
+        id: current_snapshot
+        run: |
+          # Create snapshots directory
+          mkdir -p .api-snapshots
+
+          # Generate snapshot of current types
+          node scripts/snapshot-api.js dist/index.d.ts > .api-snapshots/current.json
+
+          echo "Current API snapshot created"
+
+      - name: Preserve scripts for previous version
+        if: steps.previous_version.outputs.tag != ''
+        run: |
+          # Copy scripts to temporary location to use with previous version
+          mkdir -p /tmp/api-changelog-scripts
+          cp scripts/snapshot-api.js scripts/compare-api-snapshots.js /tmp/api-changelog-scripts/
+
+      - name: Checkout previous version
+        if: steps.previous_version.outputs.tag != ''
+        run: |
+          # Stash current changes
+          git stash
+
+          # Checkout previous version
+          git checkout ${{ steps.previous_version.outputs.tag }}
+
+          # Restore scripts
+          mkdir -p scripts
+          cp /tmp/api-changelog-scripts/*.js scripts/
+
+      - name: Build previous types
+        if: steps.previous_version.outputs.tag != ''
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm build:types
+
+      - name: Snapshot previous API
+        if: steps.previous_version.outputs.tag != ''
+        run: |
+          # Generate snapshot of previous types
+          node scripts/snapshot-api.js dist/index.d.ts > .api-snapshots/previous.json
+
+          echo "Previous API snapshot created"
+
+      - name: Return to current version
+        if: steps.previous_version.outputs.tag != ''
+        run: |
+          # Remove copied scripts to avoid conflicts
+          rm -f scripts/snapshot-api.js scripts/compare-api-snapshots.js
+
+          git checkout -
+          git stash pop || true
+
+      - name: Compare API snapshots and generate changelog
+        id: generate_changelog
+        run: |
+          # Create docs directory if it doesn't exist
+          mkdir -p docs
+
+          # Run the comparison script
+          if [ -f .api-snapshots/previous.json ]; then
+            node scripts/compare-api-snapshots.js \
+              .api-snapshots/previous.json \
+              .api-snapshots/current.json \
+              ${{ steps.previous_version.outputs.version }} \
+              ${{ steps.current_version.outputs.version }} \
+              >> docs/API-CHANGELOG.md
+          else
+            # First release - just document the initial API surface
+            echo "## v${{ steps.current_version.outputs.version }} ($(date +%Y-%m-%d))" >> docs/API-CHANGELOG.md
+            echo "" >> docs/API-CHANGELOG.md
+            echo "Initial API release." >> docs/API-CHANGELOG.md
+            echo "" >> docs/API-CHANGELOG.md
+          fi
+
+          # Check if there are any changes
+          if git diff --quiet docs/API-CHANGELOG.md; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "No API changes detected"
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "API changes detected"
+          fi
+
+      - name: Create Pull Request
+        if: steps.generate_changelog.outputs.has_changes == 'true'
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e
+        with:
+          token: ${{ secrets.PR_GH_TOKEN }}
+          commit-message: '[docs] Update API changelog for v${{ steps.current_version.outputs.version }}'
+          title: '[docs] API Changelog for v${{ steps.current_version.outputs.version }}'
+          body: |
+            ## API Changelog Update
+
+            This PR documents public API changes between v${{ steps.previous_version.outputs.version }} and v${{ steps.current_version.outputs.version }}.
+
+            The changelog has been automatically generated by comparing TypeScript type definitions between versions.
+
+            ### Review Instructions
+            - Review the changes in `docs/API-CHANGELOG.md`
+            - Verify accuracy of breaking changes
+            - Add any additional context or migration notes if needed
+            - Merge when ready to publish changelog
+
+            ---
+            🤖 Generated with [Claude Code](https://claude.com/claude-code)
+          branch: api-changelog-v${{ steps.current_version.outputs.version }}
+          base: ${{ github.event_name == 'push' && github.ref_name || 'main' }}
+          labels: documentation
+          delete-branch: true
+          draft: true
+          add-paths: |
+            docs/API-CHANGELOG.md

.github/workflows/release-branch-create.yaml

@@ -69,6 +69,9 @@ jobs:
           echo "prev_version=$PREV_VERSION" >> $GITHUB_OUTPUT
           echo "prev_minor=$PREV_MINOR" >> $GITHUB_OUTPUT
 
+          BASE_COMMIT=$(git rev-parse HEAD)
+          echo "base_commit=$BASE_COMMIT" >> $GITHUB_OUTPUT
+
           # Get previous major version for comparison
           PREV_MAJOR=$(echo $PREV_VERSION | cut -d. -f1)
 
@@ -87,13 +90,13 @@ jobs:
           elif [[ "$MAJOR" -gt "$PREV_MAJOR" && "$MINOR" == "0" && "$PATCH" == "0" ]]; then
             # Major version bump (e.g., 1.99.x → 2.0.0)
             echo "is_minor_bump=true" >> $GITHUB_OUTPUT
-            BRANCH_NAME="core/${PREV_MAJOR}.${PREV_MINOR}"
-            echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
+            BRANCH_BASE="${PREV_MAJOR}.${PREV_MINOR}"
+            echo "branch_base=$BRANCH_BASE" >> $GITHUB_OUTPUT
           elif [[ "$MAJOR" == "$PREV_MAJOR" && "$MINOR" -gt "$PREV_MINOR" && "$PATCH" == "0" ]]; then
             # Minor version bump (e.g., 1.23.x → 1.24.0)
             echo "is_minor_bump=true" >> $GITHUB_OUTPUT
-            BRANCH_NAME="core/${MAJOR}.${PREV_MINOR}"
-            echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
+            BRANCH_BASE="${MAJOR}.${PREV_MINOR}"
+            echo "branch_base=$BRANCH_BASE" >> $GITHUB_OUTPUT
           else
             echo "is_minor_bump=false" >> $GITHUB_OUTPUT
           fi
@@ -101,64 +104,97 @@ jobs:
           # Return to main branch
           git checkout main
 
-      - name: Create release branch
+      - name: Create release branches
+        id: create_branches
         if: steps.check_version.outputs.is_minor_bump == 'true'
         run: |
-          BRANCH_NAME="${{ steps.check_version.outputs.branch_name }}"
+          BRANCH_BASE="${{ steps.check_version.outputs.branch_base }}"
+          PREV_VERSION="${{ steps.check_version.outputs.prev_version }}"
 
-          # Check if branch already exists
-          if git ls-remote --heads origin "$BRANCH_NAME" | grep -q "$BRANCH_NAME"; then
-            echo "⚠️  Branch $BRANCH_NAME already exists, skipping creation"
-            echo "branch_exists=true" >> $GITHUB_ENV
-            exit 0
-          else
-            echo "branch_exists=false" >> $GITHUB_ENV
+          if [[ -z "$BRANCH_BASE" ]]; then
+            echo "::error::Branch base not set; unable to determine release branches"
+            exit 1
           fi
 
-          # Create branch from the commit BEFORE the version bump
-          # This ensures the release branch has the previous minor version
-          git checkout -b "$BRANCH_NAME" HEAD^1
+          BASE_COMMIT="${{ steps.check_version.outputs.base_commit }}"
 
-          # Push the new branch
-          git push origin "$BRANCH_NAME"
+          if [[ -z "$BASE_COMMIT" ]]; then
+            echo "::error::Base commit not provided; cannot create release branches"
+            exit 1
+          fi
 
-          echo "✅ Created release branch: $BRANCH_NAME"
-          echo "This branch is now in feature freeze and will only receive:"
-          echo "- Bug fixes"
-          echo "- Critical security patches"
-          echo "- Documentation updates"
+          RESULTS_FILE=$(mktemp)
+          trap 'rm -f "$RESULTS_FILE"' EXIT
 
+          for PREFIX in core cloud; do
+            BRANCH_NAME="${PREFIX}/${BRANCH_BASE}"
+
+            if git ls-remote --exit-code --heads origin \
+              "$BRANCH_NAME" >/dev/null 2>&1; then
+              echo "⚠️  Branch $BRANCH_NAME already exists"
+              echo "ℹ️  Skipping creation for $BRANCH_NAME"
+              STATUS="exists"
+            else
+              # Create branch from the commit BEFORE the version bump
+              if ! git push origin "$BASE_COMMIT:refs/heads/$BRANCH_NAME"; then
+                echo "::error::Failed to push release branch $BRANCH_NAME"
+                exit 1
+              fi
+              echo "✅ Created release branch: $BRANCH_NAME"
+              STATUS="created"
+            fi
+
+            echo "$BRANCH_NAME|$STATUS|$PREV_VERSION" >> "$RESULTS_FILE"
+          done
+
+          {
+            echo "results<<'EOF'"
+            cat "$RESULTS_FILE"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
 
       - name: Post summary
         if: steps.check_version.outputs.is_minor_bump == 'true'
         run: |
-          BRANCH_NAME="${{ steps.check_version.outputs.branch_name }}"
-          PREV_VERSION="${{ steps.check_version.outputs.prev_version }}"
           CURRENT_VERSION="${{ steps.check_version.outputs.current_version }}"
+          RESULTS="${{ steps.create_branches.outputs.results }}"
 
-          if [[ "${{ env.branch_exists }}" == "true" ]]; then
+          if [[ -z "$RESULTS" ]]; then
             cat >> $GITHUB_STEP_SUMMARY << EOF
-          ## 🌿 Release Branch Already Exists
+          ## 🌿 Release Branch Summary
 
-          The release branch for the previous minor version already exists:
-          EOF
-          else
-            cat >> $GITHUB_STEP_SUMMARY << EOF
-          ## 🌿 Release Branch Created
-
-          A new release branch has been created for the previous minor version:
+          Release branch creation skipped; no eligible branches were found.
           EOF
+            exit 0
           fi
 
           cat >> $GITHUB_STEP_SUMMARY << EOF
+          ## 🌿 Release Branch Summary
 
-          - **Branch**: \`$BRANCH_NAME\`
-          - **Version**: \`$PREV_VERSION\` (feature frozen)
           - **Main branch**: \`$CURRENT_VERSION\` (active development)
 
+          ### Branch Status
+          EOF
+
+          while IFS='|' read -r BRANCH STATUS PREV_VERSION; do
+            if [[ "$STATUS" == "created" ]]; then
+              cat >> $GITHUB_STEP_SUMMARY << EOF
+
+          - \`$BRANCH\` created from version \`$PREV_VERSION\`
+          EOF
+            else
+              cat >> $GITHUB_STEP_SUMMARY << EOF
+
+          - \`$BRANCH\` already existed (based on version \`$PREV_VERSION\`)
+          EOF
+            fi
+          done <<< "$RESULTS"
+
+          cat >> $GITHUB_STEP_SUMMARY << EOF
+
           ### Branch Policy
 
-          The \`$BRANCH_NAME\` branch is now in **feature freeze** and will only accept:
+          Release branches are feature-frozen and only accept:
           - 🐛 Bug fixes
           - 🔒 Security patches
           - 📚 Documentation updates
@@ -167,9 +203,9 @@ jobs:
 
           ### Backporting Changes
 
-          To backport a fix to this release branch:
+          To backport a fix:
           1. Create your fix on \`main\` first
-          2. Cherry-pick to \`$BRANCH_NAME\`
-          3. Create a PR targeting \`$BRANCH_NAME\`
-          4. Use the \`Release\` label on the PR
+          2. Cherry-pick to the target release branch
+          3. Create a PR targeting that branch
+          4. Apply the matching \`core/x.y\` or \`cloud/x.y\` label
           EOF

.github/workflows/weekly-docs-check.yaml

@@ -0,0 +1,145 @@
+name: "Weekly Documentation Check"
+description: "Automated weekly documentation accuracy check and update via Claude"
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+on:
+  schedule:
+    # Run every Monday at 9 AM UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  docs-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: main
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies for analysis tools
+        run: |
+          # Check if packages are already available locally
+          if ! pnpm list typescript @vue/compiler-sfc >/dev/null 2>&1; then
+            echo "Installing TypeScript and Vue compiler globally..."
+            pnpm install -g typescript @vue/compiler-sfc
+          else
+            echo "TypeScript and Vue compiler already available locally"
+          fi
+
+      - name: Run Claude Documentation Review
+        uses: anthropics/claude-code-action@v1.0.6
+        with:
+          prompt: |
+            Is all documentation still 100% accurate?
+
+            INSTRUCTIONS:
+            1. Fact-check all documentation against the current codebase
+            2. Look for:
+               - Outdated API references
+               - Deprecated functions or components still documented
+               - Missing documentation for new features
+               - Incorrect code examples
+               - Broken internal references
+               - Configuration examples that no longer work
+               - Documentation that contradicts actual implementation
+            3. Update any inaccurate or outdated documentation
+            4. Add documentation for significant undocumented features
+            5. Ensure all code examples are valid and tested against current code
+
+            Focus on these key areas:
+            - docs/**/*.md (all documentation files)
+            - CLAUDE.md (project guidelines)
+            - README.md files throughout the repository
+            - .claude/commands/*.md (Claude command documentation)
+
+            Make changes directly to the documentation files as needed.
+            DO NOT modify any source code files unless absolutely necessary for documentation accuracy.
+
+            After making all changes, create a comprehensive PR message summary:
+            1. Write a detailed PR body to /tmp/pr-body-${{ github.run_id }}.md in markdown format
+            2. Include:
+               - ## Summary section with bullet points of what was changed
+               - ## Changes Made section with details organized by category
+               - ## Review Notes section with any important context
+            3. Be specific about which files were updated and why
+            4. If no changes were needed, write a brief message stating documentation is up to date
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_args: "--max-turns 256 --allowedTools 'Bash(git status),Bash(git diff),Bash(git log),Bash(pnpm:*),Bash(npm:*),Bash(node:*),Bash(tsc:*),Bash(echo:*),Read,Write,Edit,Glob,Grep'"
+        continue-on-error: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check for changes
+        id: check_changes
+        run: |
+          if git diff --quiet && git diff --cached --quiet; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "No documentation changes needed"
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "Documentation changes detected"
+          fi
+
+      - name: Create default PR body if not generated
+        if: steps.check_changes.outputs.has_changes == 'true'
+        run: |
+          if [ ! -f /tmp/pr-body-${{ github.run_id }}.md ]; then
+            cat > /tmp/pr-body-${{ github.run_id }}.md <<'EOF'
+          ## Automated Documentation Review
+
+          This PR contains documentation updates identified by the weekly automated review.
+
+          ### Review Process
+          - Automated fact-checking against current codebase
+          - Verification of code examples and API references
+          - Detection of outdated or missing documentation
+
+          ### What was checked
+          - All markdown documentation in `docs/`
+          - Project guidelines in `CLAUDE.md`
+          - README files throughout the repository
+          - Claude command documentation in `.claude/commands/`
+
+          **Note**: This is an automated PR. Please review all changes carefully before merging.
+
+          🤖 Generated by weekly documentation check workflow
+          EOF
+          fi
+
+      - name: Create or Update Pull Request
+        if: steps.check_changes.outputs.has_changes == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.PR_GH_TOKEN }}
+          commit-message: 'docs: weekly documentation accuracy update'
+          branch: docs/weekly-update
+          delete-branch: true
+          title: 'docs: Weekly Documentation Update'
+          body-path: /tmp/pr-body-${{ github.run_id }}.md
+          labels: |
+            documentation
+            automated
+          draft: true
+          assignees: ${{ github.repository_owner }}

CLAUDE.md

@@ -62,6 +62,11 @@ Key Nx features:
 
 ## Project Philosophy
 
+- Follow good software engineering principles
+  - YAGNI
+  - AHA
+  - DRY
+  - SOLID
 - Clean, stable public APIs
 - Domain-driven design
 - Thousands of users and extensions

browser_tests/fixtures/ComfyPage.ts

@@ -1657,7 +1657,8 @@ export const comfyPageFixture = base.extend<{
         'Comfy.userId': userId,
         // Set tutorial completed to true to avoid loading the tutorial workflow.
         'Comfy.TutorialCompleted': true,
-        'Comfy.SnapToGrid.GridSize': testComfySnapToGridGridSize
+        'Comfy.SnapToGrid.GridSize': testComfySnapToGridGridSize,
+        'Comfy.VueNodes.AutoScaleLayout': false
       })
     } catch (e) {
       console.error(e)

browser_tests/fixtures/utils/litegraphUtils.ts

@@ -503,7 +503,7 @@ export class NodeReference {
       for (const position of clickPositions) {
         // Clear any selection first
         await this.comfyPage.canvas.click({
-          position: { x: 50, y: 50 },
+          position: { x: 250, y: 250 },
           force: true
         })
         await this.comfyPage.nextFrame()

demo-snapshots/CHANGELOG-DEMO.md

@@ -0,0 +1,49 @@
+## v1.30.2 (2025-11-01)
+
+Comparing v1.29.0 → v1.30.2. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on.
+
+### ✨ Additions
+
+**Type Aliases**
+
+- `WorkflowId`
+
+**Interfaces**
+
+- `ExtensionMetadata`
+  - Members: `id`, `name`, `version`, `description`
+
+### 🔄 Modifications
+
+> **Note**: Some modifications may be breaking changes.
+
+**Interfaces**
+
+- `ComfyApi`
+  - ✨ Added member: `queuePromptAsync`
+  - ✨ Added member: `cancelPrompt`
+  - ✨ Added member: `getQueueStatus`
+  - ⚠️ **Breaking**: Removed member: `queuePrompt`
+- `NodeDef`
+  - ✨ Added member: `input`
+  - ✨ Added member: `output`
+  - ✨ Added member: `output_name`
+- `WorkflowMetadata`
+  - ✨ Added member: `tags`
+  - ✨ Added member: `thumbnail`
+
+**Enums**
+
+- `NodeStatus`
+  - ✨ Added enum value: `ERROR`
+  - ✨ Added enum value: `COMPLETED`
+
+**Classes**
+
+- `WorkflowManager`
+  - ✨ Added member: `cache`
+  - ✨ Added method: `deleteWorkflow()`
+  - ✨ Added method: `searchWorkflows()`
+
+---
+

demo-snapshots/README.md

@@ -0,0 +1,188 @@
+# API Changelog Generation Demo
+
+This demo showcases the automated API changelog generation system comparing two versions of the ComfyUI Frontend public API.
+
+## Overview
+
+The demo compares **v1.29.0** → **v1.30.2** to demonstrate:
+- Breaking change detection
+- API additions tracking
+- Non-breaking modifications
+- Human-readable changelog generation
+
+## Demo Files
+
+### Input Files
+- **`v1.29.0.d.ts`** - TypeScript definitions representing the v1.29.0 API surface
+- **`v1.30.2.d.ts`** - TypeScript definitions representing the v1.30.2 API surface
+
+### Generated Files
+- **`v1.29.0.json`** - Structured API snapshot from v1.29.0
+- **`v1.30.2.json`** - Structured API snapshot from v1.30.2
+- **`CHANGELOG-DEMO.md`** - Generated changelog comparing the two versions
+
+## Running the Demo
+
+```bash
+# Generate API snapshots
+node scripts/snapshot-api.js demo-snapshots/v1.29.0.d.ts > demo-snapshots/v1.29.0.json
+node scripts/snapshot-api.js demo-snapshots/v1.30.2.d.ts > demo-snapshots/v1.30.2.json
+
+# Compare snapshots and generate changelog
+node scripts/compare-api-snapshots.js \
+  demo-snapshots/v1.29.0.json \
+  demo-snapshots/v1.30.2.json \
+  1.29.0 \
+  1.30.2 \
+  > demo-snapshots/CHANGELOG-DEMO.md
+```
+
+## Key Changes Detected
+
+### ⚠️ Breaking Changes
+
+1. **`ComfyApi.queuePrompt()` removed**
+   - Replaced with `queuePromptAsync()` which includes additional options
+   - Extension developers need to update their code to use the new async method
+
+### ✨ New Additions
+
+1. **New Interface: `ExtensionMetadata`**
+   - Provides metadata for extensions
+   - Fields: `id`, `name`, `version`, `description`
+
+2. **New Type: `WorkflowId`**
+   - Type alias for workflow identifiers
+
+3. **Enhanced `ComfyApi` Interface**
+   - `queuePromptAsync()` - Async queue with priority support
+   - `cancelPrompt()` - Cancel queued prompts
+   - `getQueueStatus()` - Query queue state
+
+4. **Extended `NodeDef` Interface**
+   - `input` - Input specification
+   - `output` - Output types
+   - `output_name` - Output names
+
+5. **Enhanced `NodeStatus` Enum**
+   - Added `ERROR` state
+   - Added `COMPLETED` state
+
+6. **Extended `WorkflowManager` Class**
+   - `cache` property for workflow caching
+   - `deleteWorkflow()` method
+   - `searchWorkflows()` method
+
+### 🔄 Non-Breaking Modifications
+
+1. **`WorkflowMetadata` enhancements**
+   - Added optional `tags` field
+   - Added optional `thumbnail` field
+
+## Real-World Usage
+
+In production, this system will:
+
+1. **Automatic Triggering**: Run after each NPM types release
+2. **Version Detection**: Automatically detect current and previous versions from git tags
+3. **Build Integration**: Build actual TypeScript types from the repository
+4. **PR Creation**: Generate draft pull requests with the changelog
+5. **Human Review**: Allow maintainers to review and enhance before merging
+
+## Benefits for Extension Developers
+
+### Clear Breaking Change Visibility
+Extension developers can immediately see:
+- What APIs were removed
+- What signatures changed
+- How to migrate their code
+
+### Migration Planning
+With clear documentation of additions and changes, developers can:
+- Plan updates around breaking changes
+- Adopt new features when ready
+- Understand version compatibility
+
+### Historical Reference
+The cumulative `docs/API-CHANGELOG.md` provides:
+- Complete API evolution history
+- Context for design decisions
+- Migration guides for major versions
+
+## Example Extension Migration
+
+### Before (v1.29.0)
+```typescript
+// Old code using queuePrompt
+const result = await api.queuePrompt(workflow);
+console.log('Queued:', result.prompt_id);
+```
+
+### After (v1.30.2)
+```typescript
+// New code using queuePromptAsync with priority
+const result = await api.queuePromptAsync(workflow, { priority: 1 });
+console.log('Queued:', result.prompt_id, 'Position:', result.number);
+```
+
+## Snapshot Structure
+
+The JSON snapshots contain structured representations of:
+
+```json
+{
+  "types": { /* Type aliases */ },
+  "interfaces": { /* Interface definitions with members */ },
+  "enums": { /* Enum values */ },
+  "functions": { /* Exported functions */ },
+  "classes": { /* Class definitions with methods */ },
+  "constants": { /* Exported constants */ }
+}
+```
+
+Each entry includes:
+- **Name**: Identifier
+- **Kind**: Type of declaration
+- **Members/Methods**: Properties and functions
+- **Types**: Parameter and return types
+- **Visibility**: Public/private/protected modifiers
+- **Optional**: Whether parameters/properties are optional
+
+## Comparison Algorithm
+
+The comparison script:
+
+1. **Categorizes changes** into breaking, additions, and modifications
+2. **Detects breaking changes**:
+   - Removed interfaces, classes, functions
+   - Removed methods or properties
+   - Changed method signatures
+   - Changed return types
+   - Removed enum values
+3. **Tracks additions**:
+   - New interfaces, classes, types
+   - New methods and properties
+   - New enum values
+4. **Identifies modifications**:
+   - Type changes
+   - Optionality changes
+   - Signature changes
+
+## Future Enhancements
+
+Planned improvements include:
+
+- **LLM Enhancement**: Use AI to generate better descriptions and migration guides
+- **Email Notifications**: Alert developers on mailing list for major changes
+- **Release Notes Integration**: Auto-include in GitHub releases
+- **Deprecation Tracking**: Mark APIs as deprecated before removal
+- **Example Code**: Generate migration code snippets automatically
+
+## Conclusion
+
+This automated system ensures:
+- ✅ Zero manual effort for changelog generation
+- ✅ Consistent documentation format
+- ✅ Clear breaking change visibility
+- ✅ Historical API evolution tracking
+- ✅ Better extension developer experience

demo-snapshots/v1.29.0.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Mock TypeScript definitions representing v1.29.0 API surface
+ * This represents the public API as it existed in version 1.29.0
+ */
+
+export interface ComfyApi {
+  /**
+   * Get API URL for backend calls
+   */
+  apiURL(path: string): string
+
+  /**
+   * Get file URL for static resources
+   */
+  fileURL(path: string): string
+
+  /**
+   * Queue a prompt for execution
+   */
+  queuePrompt(prompt: object): Promise<{ prompt_id: string }>
+
+  /**
+   * Interrupt current execution
+   */
+  interrupt(): Promise<void>
+}
+
+export interface NodeDef {
+  name: string
+  category: string
+  display_name?: string
+  description?: string
+  python_module: string
+}
+
+export enum NodeStatus {
+  IDLE = 'idle',
+  QUEUED = 'queued',
+  RUNNING = 'running'
+}
+
+export interface WorkflowMetadata {
+  title?: string
+  description?: string
+  author?: string
+  version?: string
+}
+
+export class WorkflowManager {
+  workflows: Map<string, object>
+
+  constructor()
+
+  loadWorkflow(id: string): Promise<object>
+  saveWorkflow(id: string, data: object): Promise<void>
+}
+
+export type NodeId = string

demo-snapshots/v1.29.0.json

@@ -0,0 +1,192 @@
+{
+  "types": {
+    "NodeId": {
+      "kind": "type",
+      "name": "NodeId",
+      "text": "export type NodeId = string;",
+      "exported": true
+    }
+  },
+  "interfaces": {
+    "ComfyApi": {
+      "kind": "interface",
+      "name": "ComfyApi",
+      "members": [
+        {
+          "name": "apiURL",
+          "kind": "method",
+          "parameters": [
+            {
+              "name": "path",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "string"
+        },
+        {
+          "name": "fileURL",
+          "kind": "method",
+          "parameters": [
+            {
+              "name": "path",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "string"
+        },
+        {
+          "name": "queuePrompt",
+          "kind": "method",
+          "parameters": [
+            {
+              "name": "prompt",
+              "type": "object",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<{ prompt_id: string }>"
+        },
+        {
+          "name": "interrupt",
+          "kind": "method",
+          "parameters": [],
+          "returnType": "Promise<void>"
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    },
+    "NodeDef": {
+      "kind": "interface",
+      "name": "NodeDef",
+      "members": [
+        {
+          "name": "name",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "category",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "display_name",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "python_module",
+          "type": "string",
+          "optional": false
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    },
+    "WorkflowMetadata": {
+      "kind": "interface",
+      "name": "WorkflowMetadata",
+      "members": [
+        {
+          "name": "title",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "author",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "version",
+          "type": "string",
+          "optional": true
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    }
+  },
+  "enums": {
+    "NodeStatus": {
+      "kind": "enum",
+      "name": "NodeStatus",
+      "members": [
+        {
+          "name": "IDLE",
+          "value": "\"idle\""
+        },
+        {
+          "name": "QUEUED",
+          "value": "\"queued\""
+        },
+        {
+          "name": "RUNNING",
+          "value": "\"running\""
+        }
+      ],
+      "exported": true
+    }
+  },
+  "functions": {},
+  "classes": {
+    "WorkflowManager": {
+      "kind": "class",
+      "name": "WorkflowManager",
+      "members": [
+        {
+          "name": "workflows",
+          "type": "Map<string, object>",
+          "visibility": "public"
+        }
+      ],
+      "methods": [
+        {
+          "name": "loadWorkflow",
+          "parameters": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<object>",
+          "visibility": "public"
+        },
+        {
+          "name": "saveWorkflow",
+          "parameters": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false
+            },
+            {
+              "name": "data",
+              "type": "object",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<void>",
+          "visibility": "public"
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    }
+  },
+  "constants": {}
+}

demo-snapshots/v1.30.2.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Mock TypeScript definitions representing v1.30.2 API surface
+ * This represents the public API with several breaking changes and additions
+ */
+
+export interface ComfyApi {
+  /**
+   * Get API URL for backend calls
+   */
+  apiURL(path: string): string
+
+  /**
+   * Get file URL for static resources
+   */
+  fileURL(path: string): string
+
+  /**
+   * Queue a prompt for execution (async version)
+   */
+  queuePromptAsync(
+    prompt: object,
+    options?: { priority?: number }
+  ): Promise<{ prompt_id: string; number: number }>
+
+  /**
+   * Cancel a queued prompt
+   */
+  cancelPrompt(prompt_id: string): Promise<void>
+
+  /**
+   * Interrupt current execution
+   */
+  interrupt(): Promise<void>
+
+  /**
+   * Get queue status
+   */
+  getQueueStatus(): Promise<{ queue_running: any[]; queue_pending: any[] }>
+}
+
+export interface NodeDef {
+  name: string
+  category: string
+  display_name?: string
+  description?: string
+  python_module: string
+  input: {
+    required?: Record<string, any>
+    optional?: Record<string, any>
+  }
+  output: string[]
+  output_name: string[]
+}
+
+export enum NodeStatus {
+  IDLE = 'idle',
+  QUEUED = 'queued',
+  RUNNING = 'running',
+  ERROR = 'error',
+  COMPLETED = 'completed'
+}
+
+export interface WorkflowMetadata {
+  title?: string
+  description?: string
+  author?: string
+  version?: string
+  tags?: string[]
+  thumbnail?: string
+}
+
+export interface ExtensionMetadata {
+  id: string
+  name: string
+  version: string
+  description?: string
+}
+
+export class WorkflowManager {
+  workflows: Map<string, object>
+  cache: Map<string, object>
+
+  constructor()
+
+  loadWorkflow(id: string): Promise<object>
+  saveWorkflow(id: string, data: object): Promise<void>
+  deleteWorkflow(id: string): Promise<void>
+  searchWorkflows(query: string): Promise<object[]>
+}
+
+export type NodeId = string
+export type WorkflowId = string

demo-snapshots/v1.30.2.json

@@ -0,0 +1,311 @@
+{
+  "types": {
+    "NodeId": {
+      "kind": "type",
+      "name": "NodeId",
+      "text": "export type NodeId = string;",
+      "exported": true
+    },
+    "WorkflowId": {
+      "kind": "type",
+      "name": "WorkflowId",
+      "text": "export type WorkflowId = string;",
+      "exported": true
+    }
+  },
+  "interfaces": {
+    "ComfyApi": {
+      "kind": "interface",
+      "name": "ComfyApi",
+      "members": [
+        {
+          "name": "apiURL",
+          "kind": "method",
+          "parameters": [
+            {
+              "name": "path",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "string"
+        },
+        {
+          "name": "fileURL",
+          "kind": "method",
+          "parameters": [
+            {
+              "name": "path",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "string"
+        },
+        {
+          "name": "queuePromptAsync",
+          "kind": "method",
+          "parameters": [
+            {
+              "name": "prompt",
+              "type": "object",
+              "optional": false
+            },
+            {
+              "name": "options",
+              "type": "{ priority?: number }",
+              "optional": true
+            }
+          ],
+          "returnType": "Promise<{ prompt_id: string; number: number }>"
+        },
+        {
+          "name": "cancelPrompt",
+          "kind": "method",
+          "parameters": [
+            {
+              "name": "prompt_id",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<void>"
+        },
+        {
+          "name": "interrupt",
+          "kind": "method",
+          "parameters": [],
+          "returnType": "Promise<void>"
+        },
+        {
+          "name": "getQueueStatus",
+          "kind": "method",
+          "parameters": [],
+          "returnType": "Promise<{ queue_running: any[]; queue_pending: any[] }>"
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    },
+    "NodeDef": {
+      "kind": "interface",
+      "name": "NodeDef",
+      "members": [
+        {
+          "name": "name",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "category",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "display_name",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "python_module",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "input",
+          "type": "{\n    required?: Record<string, any>;\n    optional?: Record<string, any>;\n  }",
+          "optional": false
+        },
+        {
+          "name": "output",
+          "type": "string[]",
+          "optional": false
+        },
+        {
+          "name": "output_name",
+          "type": "string[]",
+          "optional": false
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    },
+    "WorkflowMetadata": {
+      "kind": "interface",
+      "name": "WorkflowMetadata",
+      "members": [
+        {
+          "name": "title",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "author",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "version",
+          "type": "string",
+          "optional": true
+        },
+        {
+          "name": "tags",
+          "type": "string[]",
+          "optional": true
+        },
+        {
+          "name": "thumbnail",
+          "type": "string",
+          "optional": true
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    },
+    "ExtensionMetadata": {
+      "kind": "interface",
+      "name": "ExtensionMetadata",
+      "members": [
+        {
+          "name": "id",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "version",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "optional": true
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    }
+  },
+  "enums": {
+    "NodeStatus": {
+      "kind": "enum",
+      "name": "NodeStatus",
+      "members": [
+        {
+          "name": "IDLE",
+          "value": "\"idle\""
+        },
+        {
+          "name": "QUEUED",
+          "value": "\"queued\""
+        },
+        {
+          "name": "RUNNING",
+          "value": "\"running\""
+        },
+        {
+          "name": "ERROR",
+          "value": "\"error\""
+        },
+        {
+          "name": "COMPLETED",
+          "value": "\"completed\""
+        }
+      ],
+      "exported": true
+    }
+  },
+  "functions": {},
+  "classes": {
+    "WorkflowManager": {
+      "kind": "class",
+      "name": "WorkflowManager",
+      "members": [
+        {
+          "name": "workflows",
+          "type": "Map<string, object>",
+          "visibility": "public"
+        },
+        {
+          "name": "cache",
+          "type": "Map<string, object>",
+          "visibility": "public"
+        }
+      ],
+      "methods": [
+        {
+          "name": "loadWorkflow",
+          "parameters": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<object>",
+          "visibility": "public"
+        },
+        {
+          "name": "saveWorkflow",
+          "parameters": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false
+            },
+            {
+              "name": "data",
+              "type": "object",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<void>",
+          "visibility": "public"
+        },
+        {
+          "name": "deleteWorkflow",
+          "parameters": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<void>",
+          "visibility": "public"
+        },
+        {
+          "name": "searchWorkflows",
+          "parameters": [
+            {
+              "name": "query",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<object[]>",
+          "visibility": "public"
+        }
+      ],
+      "exported": true,
+      "heritage": []
+    }
+  },
+  "constants": {}
+}

docs/API-CHANGELOG.md

@@ -0,0 +1,53 @@
+# Public API Changelog
+
+This changelog documents changes to the ComfyUI Frontend public API surface across versions. The public API surface includes types, interfaces, and objects used by third-party extensions and custom nodes.
+
+**Important**: This is an automatically generated changelog based on TypeScript type definitions. Breaking changes are marked with ⚠️.
+
+## What is tracked
+
+This changelog tracks changes to the following public API components exported from `@comfyorg/comfyui-frontend-types`:
+
+- **Type Aliases**: Type definitions used by extensions
+- **Interfaces**: Object shapes and contracts
+- **Enums**: Enumerated values
+- **Functions**: Public utility functions
+- **Classes**: Exported classes and their public members
+- **Constants**: Public constant values
+
+## Migration Guide
+
+When breaking changes occur, refer to the specific version section below for:
+- What changed
+- Why it changed (if applicable)
+- How to migrate your code
+
+---
+
+<!-- Automated changelog entries will be added below -->
+## v1.31.1 (2025-11-04)
+
+Comparing v1.32.1 → v1.31.1. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on.
+
+### ⚠️ Breaking Changes
+
+**Type Aliases**
+
+- **Removed**: `WorkflowOpenSource`
+
+**Interfaces**
+
+- **Removed**: `WorkflowImportMetadata`
+
+### 🔄 Modifications
+
+> **Note**: Some modifications may be breaking changes.
+
+**Classes**
+
+- `ComfyApp`
+  - ⚠️ **Breaking**: Method `loadGraphData()` signature changed
+  - ⚠️ **Breaking**: Method `handleFile()` signature changed
+
+---
+

eslint.config.ts

@@ -5,7 +5,6 @@ import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescrip
 import { importX } from 'eslint-plugin-import-x'
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
 import storybook from 'eslint-plugin-storybook'
-import tailwind from 'eslint-plugin-tailwindcss'
 import unusedImports from 'eslint-plugin-unused-imports'
 import pluginVue from 'eslint-plugin-vue'
 import { defineConfig } from 'eslint/config'
@@ -34,11 +33,7 @@ const settings = {
       ],
       noWarnOnMultipleProjects: true
     })
-  ],
-  tailwindcss: {
-    config: `${import.meta.dirname}/packages/design-system/src/css/style.css`,
-    functions: ['cn', 'clsx', 'tw']
-  }
+  ]
 } as const
 
 const commonParserOptions = {
@@ -63,7 +58,8 @@ export default defineConfig([
       'src/extensions/core/*',
       'src/scripts/*',
       'src/types/generatedManagerTypes.ts',
-      'src/types/vue-shim.d.ts'
+      'src/types/vue-shim.d.ts',
+      'demo-snapshots/*'
     ]
   },
   {
@@ -97,7 +93,6 @@ export default defineConfig([
   // Difference in typecheck on CI vs Local
   // eslint-disable-next-line @typescript-eslint/ban-ts-comment
   // @ts-ignore Bad types in the plugin
-  tailwind.configs['flat/recommended'],
   pluginVue.configs['flat/recommended'],
   eslintPluginPrettierRecommended,
   storybook.configs['flat/recommended'],
@@ -129,7 +124,6 @@ export default defineConfig([
       'import-x/no-relative-packages': 'error',
       'unused-imports/no-unused-imports': 'error',
       'no-console': ['error', { allow: ['warn', 'error'] }],
-      'tailwindcss/no-custom-classname': 'off', // TODO: fix
       'vue/no-v-html': 'off',
       // Enforce dark-theme: instead of dark: prefix
       'vue/no-restricted-class': ['error', '/^dark:/'],

knip.config.ts

@@ -14,7 +14,7 @@ const config: KnipConfig = {
     },
     'apps/desktop-ui': {
       entry: ['src/main.ts', 'src/i18n.ts'],
-      project: ['src/**/*.{js,ts,vue}', '*.{js,ts,mts}']
+      project: ['src/**/*.{js,ts,vue}']
     },
     'packages/tailwind-utils': {
       project: ['src/**/*.{js,ts}']
@@ -41,7 +41,9 @@ const config: KnipConfig = {
     'src/workbench/extensions/manager/types/generatedManagerTypes.ts',
     'packages/registry-types/src/comfyRegistryTypes.ts',
     // Used by a custom node (that should move off of this)
-    'src/scripts/ui/components/splitButton.ts'
+    'src/scripts/ui/components/splitButton.ts',
+    // Demo snapshots for API changelog system
+    'demo-snapshots/**'
   ],
   compilers: {
     // https://github.com/webpro-nl/knip/issues/1008#issuecomment-3207756199

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comfyorg/comfyui-frontend",
   "private": true,
-  "version": "1.30.3",
+  "version": "1.31.1",
   "type": "module",
   "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
   "homepage": "https://comfy.org",
@@ -43,7 +43,8 @@
     "test:browser": "pnpm exec nx e2e",
     "test:unit": "nx run test",
     "typecheck": "vue-tsc --noEmit",
-    "zipdist": "node scripts/zipdist.js"
+    "zipdist": "node scripts/zipdist.js",
+    "clean": "nx reset"
   },
   "devDependencies": {
     "@eslint/js": "catalog:",
@@ -61,7 +62,6 @@
     "@storybook/vue3-vite": "catalog:",
     "@tailwindcss/vite": "catalog:",
     "@trivago/prettier-plugin-sort-imports": "catalog:",
-    "@types/eslint-plugin-tailwindcss": "catalog:",
     "@types/fs-extra": "catalog:",
     "@types/jsdom": "catalog:",
     "@types/node": "catalog:",
@@ -78,7 +78,6 @@
     "eslint-plugin-import-x": "catalog:",
     "eslint-plugin-prettier": "catalog:",
     "eslint-plugin-storybook": "catalog:",
-    "eslint-plugin-tailwindcss": "catalog:",
     "eslint-plugin-unused-imports": "catalog:",
     "eslint-plugin-vue": "catalog:",
     "fs-extra": "^11.2.0",

packages/design-system/src/css/style.css

@@ -9,29 +9,18 @@
 
 @config '../../tailwind.config.ts';
 
-@media (prefers-color-scheme: dark) {
-  :root {
-    --fg-color: #fff;
-    --bg-color: #202020;
-    --content-bg: #4e4e4e;
-    --content-fg: #fff;
-    --content-hover-bg: #222;
-    --content-hover-fg: #fff;
-  }
-}
-
 @theme {
   --text-xxs: 0.625rem;
   --text-xxs--line-height: calc(1 / 0.625);
 
-  /* Spacing */
-  --spacing-xs: 8px;
+  --text-xxxs: 0.5625rem;
+  --text-xxxs--line-height: calc(1 / 0.5625);
 
   /* Font Families */
   --font-inter: 'Inter', sans-serif;
 
   /* Palette Colors */
-  --color-charcoal-100: #171718;
+  --color-charcoal-100: #55565e;
   --color-charcoal-200: #494a50;
   --color-charcoal-300: #3c3d42;
   --color-charcoal-400: #313235;
@@ -42,43 +31,60 @@
 
   --color-neutral-550: #636363;
 
-  --color-stone-100: #828282;
-  --color-stone-200: #444444;
-  --color-stone-300: #bbbbbb;
+  --color-ash-300: #bbbbbb;
+  --color-ash-500: #828282;
+  --color-ash-800: #444444;
 
   --color-ivory-100: #fdfbfa;
   --color-ivory-200: #faf9f5;
   --color-ivory-300: #f0eee6;
 
-  --color-gray-100: #f3f3f3;
-  --color-gray-200: #e9e9e9;
-  --color-gray-300: #e1e1e1;
-  --color-gray-400: #d9d9d9;
-  --color-gray-500: #c5c5c5;
-  --color-gray-600: #b4b4b4;
-  --color-gray-700: #a0a0a0;
-  --color-gray-800: #8a8a8a;
+  --color-smoke-100: #f3f3f3;
+  --color-smoke-200: #e9e9e9;
+  --color-smoke-300: #e1e1e1;
+  --color-smoke-400: #d9d9d9;
+  --color-smoke-500: #c5c5c5;
+  --color-smoke-600: #b4b4b4;
+  --color-smoke-700: #a0a0a0;
+  --color-smoke-800: #8a8a8a;
 
   --color-sand-100: #e1ded5;
-  --color-sand-200: #d6cfc2;
+  --color-sand-200: #fff7d5;
   --color-sand-300: #888682;
-
-  --color-pure-black: #000000;
-  --color-pure-white: #ffffff;
+  --color-sand-400: #eed7ac;
 
   --color-slate-100: #9c9eab;
   --color-slate-200: #9fa2bd;
   --color-slate-300: #5b5e7d;
 
-  --color-brand-yellow: #f0ff41;
-  --color-brand-blue: #172dd7;
+  --color-white: #ffffff;
+  --color-black: #000000;
+
+  --color-electric-400: #f0ff41;
+  --color-sapphire-700: #172dd7;
+  --color-brand-yellow: var(--color-electric-400);
+  --color-brand-blue: var(--color-sapphire-700);
+
+  --color-azure-300: #78bae9;
+  --color-azure-400: #31b9f4;
+  --color-azure-600: #0b8ce9;
+
+  --color-cobalt-800: #185a8b;
+
+  --color-jade-400: #47e469;
+  --color-jade-600: #00cd72;
+
+  --color-gold-400: #fcbf64;
+  --color-gold-500: #fdab34;
+  --color-gold-600: #fd9903;
+
+  --color-coral-500: #f75951;
+  --color-coral-600: #e04e48;
+  --color-coral-700: #b33a3a;
+
+  --color-magenta-300: #ceaac9;
+  --color-magenta-700: #6a246a;
 
-  --color-blue-100: #0b8ce9;
-  --color-blue-200: #31b9f4;
-  --color-success-100: #00cd72;
-  --color-success-200: #47e469;
-  --color-warning-100: #fd9903;
-  --color-warning-200: #fcbf64;
   --color-danger-100: #c02323;
   --color-danger-200: #d62952;
 
@@ -90,28 +96,31 @@
   --color-error: #962a2a;
 
   --color-comfy-menu-secondary: var(--comfy-menu-secondary-bg);
-  --text-xxxs: 0.5625rem;
-  --text-xxxs--line-height: calc(1 / 0.5625);
 
-  --color-blue-selection: rgb(from var(--color-blue-100) r g b / 0.3);
-  --color-node-hover-100: rgb(from var(--color-charcoal-100) r g b/ 0.15);
-  --color-node-hover-200: rgb(from var(--color-charcoal-100) r g b/ 0.1);
-  --color-modal-tag: rgb(from var(--color-gray-400) r g b/ 0.4);
+  --color-blue-selection: rgb(from var(--color-azure-600) r g b / 0.3);
+  --color-node-hover-100: rgb(from var(--color-charcoal-800) r g b/ 0.15);
+  --color-node-hover-200: rgb(from var(--color-charcoal-800) r g b/ 0.1);
+  --color-modal-tag: rgb(from var(--color-smoke-400) r g b/ 0.4);
   --color-alpha-charcoal-600-30: color-mix(
     in srgb,
     var(--color-charcoal-600) 30%,
     transparent
   );
-  --color-alpha-stone-100-20: color-mix(
+  --color-alpha-ash-500-20: color-mix(
     in srgb,
-    var(--color-stone-100) 20%,
+    var(--color-ash-500) 20%,
     transparent
   );
-  --color-alpha-gray-500-50: color-mix(
+  --color-alpha-smoke-500-50: color-mix(
     in srgb,
-    var(--color-gray-500) 50%,
+    var(--color-smoke-500) 50%,
     transparent
   );
+  --color-alpha-smoke-500-20: #c5c5c533;
+  --color-alpha-smoke-400-40: #d9d9d966;
+  --color-alpha-azure-600-30: #0b8ce94d;
+  --color-alpha-magenta-700-60: #6a246a99;
+  --color-alpha-magenta-300-60: #ceaac999;
 
   /* PrimeVue pulled colors */
   --color-muted: var(--p-text-muted-color);
@@ -145,8 +154,10 @@
   --content-hover-bg: #adadad;
   --content-hover-fg: #000;
 
-  --button-surface: var(--color-pure-white);
-  --button-surface-contrast: var(--color-pure-black);
+  --button-surface: var(--color-white);
+  --button-surface-contrast: var(--color-black);
+
+  --modal-card-button-surface: var(--color-smoke-300);
 
   /* Code styling colors for help menu*/
   --code-text-color: rgb(0 122 255 / 1);
@@ -157,31 +168,36 @@
 
   --accent-primary: var(--color-charcoal-700);
   --backdrop: var(--color-white);
-  --button-hover-surface: var(--color-gray-200);
-  --button-active-surface: var(--color-gray-400);
-  --button-icon: var(--color-gray-600);
+
+  --button-hover-surface: var(--color-smoke-200);
+  --button-active-surface: var(--color-smoke-400);
+  --button-icon: var(--color-smoke-600);
+
   --dialog-surface: var(--color-neutral-200);
-  --interface-menu-component-surface-hovered: var(--color-gray-200);
-  --interface-menu-component-surface-selected: var(--color-gray-400);
-  --interface-menu-keybind-surface-default: var(--color-gray-500);
-  --interface-panel-surface: var(--color-pure-white);
-  --interface-stroke: var(--color-gray-300);
-  --nav-background: var(--color-pure-white);
-  --node-border: var(--color-gray-300);
-  --node-component-border: var(--color-gray-400);
-  --node-component-disabled: var(--color-alpha-stone-100-20);
+
+  --interface-menu-component-surface-hovered: var(--color-smoke-200);
+  --interface-menu-component-surface-selected: var(--color-smoke-400);
+  --interface-menu-keybind-surface-default: var(--color-smoke-500);
+  --interface-panel-surface: var(--color-white);
+  --interface-stroke: var(--color-smoke-300);
+
+  --nav-background: var(--color-white);
+
+  --node-border: var(--color-smoke-300);
+  --node-component-border: var(--color-smoke-400);
+  --node-component-disabled: var(--color-alpha-ash-500-20);
   --node-component-executing: var(--color-blue-500);
   --node-component-header: var(--fg-color);
-  --node-component-header-icon: var(--color-stone-200);
+  --node-component-header-icon: var(--color-ash-800);
   --node-component-header-surface: var(--color-white);
   --node-component-outline: var(--color-black);
-  --node-component-ring: rgb(from var(--color-gray-500) r g b / 50%);
+  --node-component-ring: rgb(from var(--color-smoke-500) r g b / 50%);
   --node-component-slot-dot-outline-opacity-mult: 1;
   --node-component-slot-dot-outline-opacity: 5%;
   --node-component-slot-dot-outline: var(--color-black);
-  --node-component-slot-text: var(--color-stone-200);
-  --node-component-surface-highlight: var(--color-stone-100);
-  --node-component-surface-hovered: var(--color-gray-200);
+  --node-component-slot-text: var(--color-ash-800);
+  --node-component-surface-highlight: var(--color-ash-500);
+  --node-component-surface-hovered: var(--color-smoke-200);
   --node-component-surface-selected: var(--color-charcoal-200);
   --node-component-surface: var(--color-white);
   --node-component-tooltip: var(--color-charcoal-700);
@@ -193,40 +209,76 @@
   );
   --node-component-widget-skeleton-surface: var(--color-zinc-300);
   --node-divider: var(--color-sand-100);
-  --node-icon-disabled: var(--color-alpha-gray-500-50);
-  --node-stroke: var(--color-gray-400);
+  --node-icon-disabled: var(--color-alpha-smoke-500-50);
+  --node-stroke: var(--color-smoke-400);
   --node-stroke-selected: var(--color-accent-primary);
   --node-stroke-error: var(--color-error);
-  --node-stroke-executing: var(--color-blue-100);
-  --text-secondary: var(--color-stone-100);
+  --node-stroke-executing: var(--color-azure-600);
+
+  --text-secondary: var(--color-ash-500);
   --text-primary: var(--color-charcoal-700);
   --input-surface: rgb(0 0 0 / 0.15);
+
+  /* Semantic tokens - light mode */
+  --muted-foreground: var(--color-charcoal-200);
+  --base-foreground: var(--color-charcoal-800);
+  --brand-yellow: var(--color-electric-400);
+  --brand-blue: var(--color-sapphire-700);
+  --secondary-background: var(--color-smoke-200);
+  --secondary-background-hover: var(--color-smoke-400);
+  --secondary-background-selected: var(--color-smoke-600);
+  --base-background: var(--color-white);
+  --primary-background: var(--color-azure-400);
+  --primary-background-hover: var(--color-cobalt-800);
+  --destructive-background: var(--color-coral-500);
+  --destructive-background-hover: var(--color-coral-600);
+  --inverted-background-hover: var(--color-charcoal-600);
+  --warning-background: var(--color-gold-400);
+  --warning-background-hover: var(--color-gold-500);
+  --border-default: var(--color-smoke-600);
+  --border-subtle: var(--color-smoke-400);
+  --muted-background: var(--color-smoke-700);
+  --accent-background: var(--color-smoke-800);
 }
 
 .dark-theme {
-  --accent-primary: var(--color-pure-white);
+  --fg-color: #fff;
+  --bg-color: #202020;
+  --content-bg: #4e4e4e;
+  --content-fg: #fff;
+  --content-hover-bg: #222;
+  --content-hover-fg: #fff;
+
+  --accent-primary: var(--color-white);
   --backdrop: var(--color-neutral-900);
+
   --button-surface: var(--color-charcoal-600);
-  --button-surface-contrast: var(--color-pure-white);
+  --button-surface-contrast: var(--color-white);
   --button-hover-surface: var(--color-charcoal-600);
   --button-active-surface: var(--color-charcoal-600);
-  --button-icon: var(--color-gray-800);
+  --button-icon: var(--color-smoke-800);
+
+  --modal-card-button-surface: var(--color-charcoal-300);
+
   --dialog-surface: var(--color-neutral-700);
+
   --interface-menu-component-surface-hovered: var(--color-charcoal-400);
   --interface-menu-component-surface-selected: var(--color-charcoal-300);
   --interface-menu-keybind-surface-default: var(--color-charcoal-200);
-  --interface-panel-surface: var(--color-charcoal-100);
+  --interface-panel-surface: var(--color-charcoal-800);
   --interface-stroke: var(--color-charcoal-400);
-  --nav-background: var(--color-charcoal-100);
+
+  --nav-background: var(--color-charcoal-800);
+
   --node-border: var(--color-charcoal-500);
-  --node-component-border: var(--color-stone-200);
+  --node-component-border: var(--color-ash-800);
   --node-component-border-error: var(--color-danger-100);
   --node-component-border-executing: var(--color-blue-500);
   --node-component-border-selected: var(--color-charcoal-200);
   --node-component-header-icon: var(--color-slate-300);
   --node-component-header-surface: var(--color-charcoal-800);
   --node-component-outline: var(--color-white);
-  --node-component-ring: rgb(var(--color-gray-500) / 20%);
+  --node-component-ring: rgb(var(--color-smoke-500) / 20%);
   --node-component-slot-dot-outline-opacity: 10%;
   --node-component-slot-dot-outline: var(--color-white);
   --node-component-slot-text: var(--color-slate-200);
@@ -240,14 +292,37 @@
   --node-component-widget-skeleton-surface: var(--color-zinc-800);
   --node-component-disabled: var(--color-alpha-charcoal-600-30);
   --node-divider: var(--color-charcoal-500);
-  --node-icon-disabled: var(--color-alpha-stone-100-20);
-  --node-stroke: var(--color-stone-200);
-  --node-stroke-selected: var(--color-pure-white);
+  --node-icon-disabled: var(--color-alpha-ash-500-20);
+  --node-stroke: var(--color-ash-800);
+  --node-stroke-selected: var(--color-white);
   --node-stroke-error: var(--color-error);
-  --node-stroke-executing: var(--color-blue-100);
+  --node-stroke-executing: var(--color-azure-600);
+
   --text-secondary: var(--color-slate-100);
-  --text-primary: var(--color-pure-white);
+  --text-primary: var(--color-white);
+
   --input-surface: rgb(130 130 130 / 0.1);
+
+  /* Semantic tokens - dark mode */
+  --muted-foreground: var(--color-smoke-800);
+  --base-foreground: var(--color-white);
+  --brand-yellow: var(--color-electric-400);
+  --brand-blue: var(--color-sapphire-700);
+  --secondary-background: var(--color-charcoal-600);
+  --secondary-background-hover: var(--color-charcoal-400);
+  --secondary-background-selected: var(--color-charcoal-200);
+  --base-background: var(--color-charcoal-800);
+  --primary-background: var(--color-azure-600);
+  --primary-background-hover: var(--color-azure-400);
+  --destructive-background: var(--color-coral-700);
+  --destructive-background-hover: var(--color-coral-600);
+  --inverted-background-hover: var(--color-smoke-200);
+  --warning-background: var(--color-gold-600);
+  --warning-background-hover: var(--color-gold-500);
+  --border-default: var(--color-charcoal-200);
+  --border-subtle: var(--color-charcoal-300);
+  --muted-background: var(--color-charcoal-100);
+  --accent-background: var(--color-charcoal-100);
 }
 
 @theme inline {
@@ -257,6 +332,7 @@
   --color-button-icon: var(--button-icon);
   --color-button-surface: var(--button-surface);
   --color-button-surface-contrast: var(--button-surface-contrast);
+  --color-modal-card-button-surface: var(--modal-card-button-surface);
   --color-dialog-surface: var(--dialog-surface);
   --color-interface-menu-component-surface-hovered: var(
     --interface-menu-component-surface-hovered
@@ -312,6 +388,27 @@
   --color-text-secondary: var(--text-secondary);
   --color-text-primary: var(--text-primary);
   --color-input-surface: var(--input-surface);
+
+  /* Semantic tokens */
+  --color-base-foreground: var(--base-foreground);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-base-background: var(--base-background);
+  --color-secondary-background: var(--secondary-background);
+  --color-secondary-background-hover: var(--secondary-background-hover);
+  --color-secondary-background-selected: var(--secondary-background-selected);
+  --color-primary-background: var(--primary-background);
+  --color-primary-background-hover: var(--primary-background-hover);
+  --color-destructive-background: var(--destructive-background);
+  --color-destructive-background-hover: var(--destructive-background-hover);
+  --color-inverted-background-hover: var(--inverted-background-hover);
+  --color-warning-background: var(--warning-background);
+  --color-warning-background-hover: var(--warning-background-hover);
+  --color-border-default: var(--border-default);
+  --color-border-subtle: var(--border-subtle);
+  --color-muted-background: var(--muted-background);
+  --color-accent-background: var(--accent-background);
+  --color-brand-yellow: var(--brand-yellow);
+  --color-brand-blue: var(--brand-blue);
 }
 
 @custom-variant dark-theme {
@@ -330,7 +427,6 @@
   }
 }
 
-
 /* ===================== Scrollbar Utilities (Tailwind) =====================
    Usage: Add `scrollbar-custom` class to scrollable containers.
    The scrollbar styling adapts to light/dark theme automatically.

packages/design-system/src/icons/image-ai-edit.svg

@@ -0,0 +1,5 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M14 9.99996L11.9427 7.94263C11.6926 7.69267 11.3536 7.55225 11 7.55225C10.6464 7.55225 10.3074 7.69267 10.0573 7.94263L9 9M8 14H12.6667C13.403 14 14 13.403 14 12.6667V3.33333C14 2.59695 13.403 2 12.6667 2H3.33333C2.59695 2 2 2.59695 2 3.33333V8" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M5.51377 12.671L4.77612 14.3921C4.67222 14.6346 4.32853 14.6346 4.22463 14.3921L3.48699 12.671C3.45664 12.6002 3.40022 12.5437 3.32942 12.5134L1.60825 11.7757C1.36581 11.6718 1.36581 11.3282 1.60825 11.2243L3.32942 10.4866C3.40022 10.4563 3.45664 10.3998 3.48699 10.329L4.22463 8.60787C4.32853 8.36544 4.67222 8.36544 4.77612 8.60787L5.51377 10.329C5.54411 10.3998 5.60053 10.4563 5.67134 10.4866L7.39251 11.2243C7.63494 11.3282 7.63494 11.6718 7.39251 11.7757L5.67134 12.5134C5.60053 12.5437 5.54411 12.6002 5.51377 12.671Z" stroke="currentColor" stroke-width="1.3" stroke-linecap="round"/>
+<path d="M5 5H5.0001" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+</svg>

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

@@ -474,3 +474,68 @@ export function formatDuration(milliseconds: number): string {
 
   return parts.join(' ')
 }
+
+const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp'] as const
+const VIDEO_EXTENSIONS = ['mp4', 'webm', 'mov', 'avi'] as const
+const AUDIO_EXTENSIONS = ['mp3', 'wav', 'ogg', 'flac'] as const
+const THREE_D_EXTENSIONS = ['obj', 'fbx', 'gltf', 'glb'] as const
+
+const MEDIA_TYPES = ['image', 'video', 'audio', '3D'] as const
+type MediaType = (typeof MEDIA_TYPES)[number]
+
+// Type guard helper for checking array membership
+type ImageExtension = (typeof IMAGE_EXTENSIONS)[number]
+type VideoExtension = (typeof VIDEO_EXTENSIONS)[number]
+type AudioExtension = (typeof AUDIO_EXTENSIONS)[number]
+type ThreeDExtension = (typeof THREE_D_EXTENSIONS)[number]
+
+/**
+ * Truncates a filename while preserving the extension
+ * @param filename The filename to truncate
+ * @param maxLength Maximum length for the filename without extension
+ * @returns Truncated filename with extension preserved
+ */
+export function truncateFilename(
+  filename: string,
+  maxLength: number = 20
+): string {
+  if (!filename || filename.length <= maxLength) {
+    return filename
+  }
+
+  const lastDotIndex = filename.lastIndexOf('.')
+  const nameWithoutExt =
+    lastDotIndex > -1 ? filename.substring(0, lastDotIndex) : filename
+  const extension = lastDotIndex > -1 ? filename.substring(lastDotIndex) : ''
+
+  // If the name without extension is short enough, return as is
+  if (nameWithoutExt.length <= maxLength) {
+    return filename
+  }
+
+  // Calculate how to split the truncation
+  const halfLength = Math.floor((maxLength - 3) / 2) // -3 for '...'
+  const start = nameWithoutExt.substring(0, halfLength)
+  const end = nameWithoutExt.substring(nameWithoutExt.length - halfLength)
+
+  return `${start}...${end}${extension}`
+}
+
+/**
+ * Determines the media type from a filename's extension (singular form)
+ * @param filename The filename to analyze
+ * @returns The media type: 'image', 'video', 'audio', or '3D'
+ */
+export function getMediaTypeFromFilename(filename: string): MediaType {
+  if (!filename) return 'image'
+  const ext = filename.split('.').pop()?.toLowerCase()
+  if (!ext) return 'image'
+
+  // Type-safe array includes check using type assertion
+  if (IMAGE_EXTENSIONS.includes(ext as ImageExtension)) return 'image'
+  if (VIDEO_EXTENSIONS.includes(ext as VideoExtension)) return 'video'
+  if (AUDIO_EXTENSIONS.includes(ext as AudioExtension)) return 'audio'
+  if (THREE_D_EXTENSIONS.includes(ext as ThreeDExtension)) return '3D'
+
+  return 'image'
+}

packages/tailwind-utils/README.md

@@ -14,7 +14,7 @@ import { cn } from '@comfyorg/tailwind-utils'
 
 // Use with conditional classes (ternary)
 <button
-  :class="cn('px-4 py-2', isActive ? 'bg-blue-500' : 'bg-gray-500')"
+  :class="cn('px-4 py-2', isActive ? 'bg-blue-500' : 'bg-smoke-500')"
 />
 ```
 

pnpm-lock.yaml

@@ -87,9 +87,6 @@ catalogs:
     '@trivago/prettier-plugin-sort-imports':
       specifier: ^5.2.0
       version: 5.2.2
-    '@types/eslint-plugin-tailwindcss':
-      specifier: ^3.17.0
-      version: 3.17.0
     '@types/fs-extra':
       specifier: ^11.0.4
       version: 11.0.4
@@ -153,9 +150,6 @@ catalogs:
     eslint-plugin-storybook:
       specifier: ^9.1.6
       version: 9.1.6
-    eslint-plugin-tailwindcss:
-      specifier: 4.0.0-beta.0
-      version: 4.0.0-beta.0
     eslint-plugin-unused-imports:
       specifier: ^4.2.0
       version: 4.2.0
@@ -519,9 +513,6 @@ importers:
       '@trivago/prettier-plugin-sort-imports':
         specifier: 'catalog:'
         version: 5.2.2(@vue/compiler-sfc@3.5.13)(prettier@3.6.2)
-      '@types/eslint-plugin-tailwindcss':
-        specifier: 'catalog:'
-        version: 3.17.0
       '@types/fs-extra':
         specifier: 'catalog:'
         version: 11.0.4
@@ -570,9 +561,6 @@ importers:
       eslint-plugin-storybook:
         specifier: 'catalog:'
         version: 9.1.6(eslint@9.35.0(jiti@2.4.2))(storybook@9.1.6(@testing-library/dom@10.4.1)(prettier@3.6.2)(vite@5.4.19(@types/node@20.14.10)(lightningcss@1.30.1)(terser@5.39.2)))(typescript@5.9.2)
-      eslint-plugin-tailwindcss:
-        specifier: 'catalog:'
-        version: 4.0.0-beta.0(tailwindcss@4.1.12)
       eslint-plugin-unused-imports:
         specifier: 'catalog:'
         version: 4.2.0(@typescript-eslint/eslint-plugin@8.44.0(@typescript-eslint/parser@8.44.0(eslint@9.35.0(jiti@2.4.2))(typescript@5.9.2))(eslint@9.35.0(jiti@2.4.2))(typescript@5.9.2))(eslint@9.35.0(jiti@2.4.2))
@@ -3155,9 +3143,6 @@ packages:
   '@types/diff-match-patch@1.0.36':
     resolution: {integrity: sha512-xFdR6tkm0MWvBfO8xXCSsinYxHcqkQUlcHeSpMC2ukzOb6lwQAfDmW+Qt0AvlGd8HpsS28qKsB+oPeJn9I39jg==}
 
-  '@types/eslint-plugin-tailwindcss@3.17.0':
-    resolution: {integrity: sha512-ucQGf2YIdTcndYcxRU3UdZgmhUHsOlbIF4BaRtl0op+7k2JmqM2i3aXZ6XIcfZgVq1ZKov7VM5c/BR81ukmkyg==}
-
   '@types/estree@1.0.5':
     resolution: {integrity: sha512-/kYRxGDLWzHOB7q+wtSUQlFrtcdUccpfy+X+9iMBpHK8QLLhx2wIPYuS5DYtR9Wa/YlZAbIovy7qVdB1Aq6Lyw==}
 
@@ -4700,12 +4685,6 @@ packages:
       eslint: '>=8'
       storybook: ^9.1.6
 
-  eslint-plugin-tailwindcss@4.0.0-beta.0:
-    resolution: {integrity: sha512-WWCajZgQu38Sd67ZCl2W6i3MRzqB0d+H8s4qV9iB6lBJbsDOIpIlj6R1Fj2FXkoWErbo05pZnZYbCGIU9o/DsA==}
-    engines: {node: '>=18.12.0'}
-    peerDependencies:
-      tailwindcss: ^3.4.0 || ^4.0.0
-
   eslint-plugin-unused-imports@4.2.0:
     resolution: {integrity: sha512-hLbJ2/wnjKq4kGA9AUaExVFIbNzyxYdVo49QZmKCnhk5pc9wcYRbfgLHvWJ8tnsdcseGhoUAddm9gn/lt+d74w==}
     peerDependencies:
@@ -7163,11 +7142,6 @@ packages:
     resolution: {integrity: sha512-9kY+CygyYM6j02t5YFHbNz2FN5QmYGv9zAjVp4lCDjlCw7amdckXlEt/bjMhUIfj4ThGRE4gCUH5+yGnNuPo5A==}
     engines: {node: '>=10.0.0'}
 
-  tailwind-api-utils@1.0.3:
-    resolution: {integrity: sha512-KpzUHkH1ug1sq4394SLJX38ZtpeTiqQ1RVyFTTSY2XuHsNSTWUkRo108KmyyrMWdDbQrLYkSHaNKj/a3bmA4sQ==}
-    peerDependencies:
-      tailwindcss: ^3.3.0 || ^4.0.0 || ^4.0.0-beta
-
   tailwind-merge@2.6.0:
     resolution: {integrity: sha512-P+Vu1qXfzediirmHOC3xKGAYeZtPcV9g76X+xg2FD4tYgR71ewMA35Y3sCz3zhiN/dwefRpJX0yBcgwi1fXNQA==}
 
@@ -7626,6 +7600,9 @@ packages:
   vue-component-type-helpers@3.1.1:
     resolution: {integrity: sha512-B0kHv7qX6E7+kdc5nsaqjdGZ1KwNKSUQDWGy7XkTYT7wFsOpkEyaJ1Vq79TjwrrtuLRgizrTV7PPuC4rRQo+vw==}
 
+  vue-component-type-helpers@3.1.2:
+    resolution: {integrity: sha512-ch3/SKBtxdZq18vsEntiGCdSszCRNfhX5QaTxjSacCAXLlNQRXfXo+ANjoQEYJMsJOJy1/vHF6Tkc4s85MS+zw==}
+
   vue-demi@0.14.10:
     resolution: {integrity: sha512-nMZBOwuzabUO0nLgIcc6rycZEebF6eeUfaiQx9+WSk8e29IbLvPU9feI6tqW4kTo3hvoYAJkMh8n8D0fuISphg==}
     engines: {node: '>=12'}
@@ -10308,7 +10285,7 @@ snapshots:
       storybook: 9.1.6(@testing-library/dom@10.4.1)(prettier@3.6.2)(vite@5.4.19(@types/node@20.14.10)(lightningcss@1.30.1)(terser@5.39.2))
       type-fest: 2.19.0
       vue: 3.5.13(typescript@5.9.2)
-      vue-component-type-helpers: 3.1.1
+      vue-component-type-helpers: 3.1.2
 
   '@swc/helpers@0.5.17':
     dependencies:
@@ -10613,8 +10590,6 @@ snapshots:
 
   '@types/diff-match-patch@1.0.36': {}
 
-  '@types/eslint-plugin-tailwindcss@3.17.0': {}
-
   '@types/estree@1.0.5': {}
 
   '@types/estree@1.0.8': {}
@@ -12380,14 +12355,6 @@ snapshots:
       - supports-color
       - typescript
 
-  eslint-plugin-tailwindcss@4.0.0-beta.0(tailwindcss@4.1.12):
-    dependencies:
-      fast-glob: 3.3.3
-      postcss: 8.5.6
-      synckit: 0.11.11
-      tailwind-api-utils: 1.0.3(tailwindcss@4.1.12)
-      tailwindcss: 4.1.12
-
   eslint-plugin-unused-imports@4.2.0(@typescript-eslint/eslint-plugin@8.44.0(@typescript-eslint/parser@8.44.0(eslint@9.35.0(jiti@2.4.2))(typescript@5.9.2))(eslint@9.35.0(jiti@2.4.2))(typescript@5.9.2))(eslint@9.35.0(jiti@2.4.2)):
     dependencies:
       eslint: 9.35.0(jiti@2.4.2)
@@ -15431,13 +15398,6 @@ snapshots:
       string-width: 4.2.3
       strip-ansi: 6.0.1
 
-  tailwind-api-utils@1.0.3(tailwindcss@4.1.12):
-    dependencies:
-      enhanced-resolve: 5.18.3
-      jiti: 2.5.1
-      local-pkg: 1.1.2
-      tailwindcss: 4.1.12
-
   tailwind-merge@2.6.0: {}
 
   tailwindcss-primeui@0.6.1(tailwindcss@4.1.12):
@@ -15983,6 +15943,8 @@ snapshots:
 
   vue-component-type-helpers@3.1.1: {}
 
+  vue-component-type-helpers@3.1.2: {}
+
   vue-demi@0.14.10(vue@3.5.13(typescript@5.9.2)):
     dependencies:
       vue: 3.5.13(typescript@5.9.2)

pnpm-workspace.yaml

@@ -30,7 +30,6 @@ catalog:
   '@storybook/vue3-vite': ^9.1.1
   '@tailwindcss/vite': ^4.1.12
   '@trivago/prettier-plugin-sort-imports': ^5.2.0
-  '@types/eslint-plugin-tailwindcss': ^3.17.0
   '@types/fs-extra': ^11.0.4
   '@types/jsdom': ^21.1.7
   '@types/node': ^20.14.8
@@ -52,7 +51,6 @@ catalog:
   eslint-plugin-import-x: ^4.16.1
   eslint-plugin-prettier: ^5.5.4
   eslint-plugin-storybook: ^9.1.6
-  eslint-plugin-tailwindcss: 4.0.0-beta.0
   eslint-plugin-unused-imports: ^4.2.0
   eslint-plugin-vue: ^10.4.0
   firebase: ^11.6.0
@@ -64,6 +62,7 @@ catalog:
   knip: ^5.62.0
   lint-staged: ^15.2.7
   markdown-table: ^3.0.4
+  mixpanel-browser: ^2.71.0
   nx: 21.4.1
   picocolors: ^1.1.1
   pinia: ^2.1.7
@@ -99,7 +98,6 @@ catalog:
   zod: ^3.23.8
   zod-to-json-schema: ^3.24.1
   zod-validation-error: ^3.3.0
-  mixpanel-browser: ^2.71.0
 
 cleanupUnusedCatalogs: true
 

scripts/compare-api-snapshots.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+
+/**
+ * Compares two API snapshots and generates a human-readable changelog
+ * documenting additions, removals, and modifications to the public API.
+ */
+
+import * as fs from 'fs'
+
+const args = process.argv.slice(2)
+if (args.length < 4) {
+  console.error(
+    'Usage: compare-api-snapshots.js <previous.json> <current.json> <previous-version> <current-version>'
+  )
+  process.exit(1)
+}
+
+const [previousPath, currentPath, previousVersion, currentVersion] = args
+
+if (!fs.existsSync(previousPath)) {
+  console.error(`Previous snapshot not found: ${previousPath}`)
+  process.exit(1)
+}
+
+if (!fs.existsSync(currentPath)) {
+  console.error(`Current snapshot not found: ${currentPath}`)
+  process.exit(1)
+}
+
+const previousApi = JSON.parse(fs.readFileSync(previousPath, 'utf-8'))
+const currentApi = JSON.parse(fs.readFileSync(currentPath, 'utf-8'))
+
+/**
+ * Compare two API snapshots and generate changelog
+ */
+function compareApis(previous, current) {
+  const changes = {
+    breaking: [],
+    additions: [],
+    modifications: [],
+    deprecations: []
+  }
+
+  const categories = [
+    'types',
+    'interfaces',
+    'enums',
+    'functions',
+    'classes',
+    'constants'
+  ]
+
+  for (const category of categories) {
+    const prevItems = previous[category] || {}
+    const currItems = current[category] || {}
+
+    // Find additions
+    for (const name in currItems) {
+      if (!prevItems[name]) {
+        changes.additions.push({
+          category,
+          name,
+          item: currItems[name]
+        })
+      }
+    }
+
+    // Find removals and modifications
+    for (const name in prevItems) {
+      if (!currItems[name]) {
+        changes.breaking.push({
+          category,
+          name,
+          type: 'removed',
+          item: prevItems[name]
+        })
+      } else {
+        // Check for modifications
+        const diff = compareItems(prevItems[name], currItems[name], category)
+        if (diff.length > 0) {
+          changes.modifications.push({
+            category,
+            name,
+            changes: diff
+          })
+        }
+      }
+    }
+  }
+
+  return changes
+}
+
+/**
+ * Compare two items and return differences
+ */
+function compareItems(prev, curr, category) {
+  const differences = []
+
+  if (category === 'interfaces' || category === 'classes') {
+    // Compare members
+    const prevMembers = new Map(prev.members?.map((m) => [m.name, m]) || [])
+    const currMembers = new Map(curr.members?.map((m) => [m.name, m]) || [])
+
+    // Find added members
+    for (const [name, member] of currMembers) {
+      if (!prevMembers.has(name)) {
+        differences.push({
+          type: 'member_added',
+          name,
+          member
+        })
+      }
+    }
+
+    // Find removed members
+    for (const [name, member] of prevMembers) {
+      if (!currMembers.has(name)) {
+        differences.push({
+          type: 'member_removed',
+          name,
+          member
+        })
+      } else {
+        // Check if member type changed
+        const prevMember = prevMembers.get(name)
+        const currMember = currMembers.get(name)
+
+        if (prevMember.type !== currMember.type) {
+          differences.push({
+            type: 'member_type_changed',
+            name,
+            from: prevMember.type,
+            to: currMember.type
+          })
+        }
+
+        if (prevMember.optional !== currMember.optional) {
+          differences.push({
+            type: 'member_optionality_changed',
+            name,
+            from: prevMember.optional ? 'optional' : 'required',
+            to: currMember.optional ? 'optional' : 'required'
+          })
+        }
+      }
+    }
+
+    // Compare methods (for classes and interfaces)
+    if (category === 'classes') {
+      const prevMethods = new Map(prev.methods?.map((m) => [m.name, m]) || [])
+      const currMethods = new Map(curr.methods?.map((m) => [m.name, m]) || [])
+
+      for (const [name, method] of currMethods) {
+        if (!prevMethods.has(name)) {
+          differences.push({
+            type: 'method_added',
+            name,
+            method
+          })
+        }
+      }
+
+      for (const [name, method] of prevMethods) {
+        if (!currMethods.has(name)) {
+          differences.push({
+            type: 'method_removed',
+            name,
+            method
+          })
+        } else {
+          const prevMethod = prevMethods.get(name)
+          const currMethod = currMethods.get(name)
+
+          if (prevMethod.returnType !== currMethod.returnType) {
+            differences.push({
+              type: 'method_return_type_changed',
+              name,
+              from: prevMethod.returnType,
+              to: currMethod.returnType
+            })
+          }
+
+          // Compare parameters
+          if (
+            JSON.stringify(prevMethod.parameters) !==
+            JSON.stringify(currMethod.parameters)
+          ) {
+            differences.push({
+              type: 'method_signature_changed',
+              name,
+              from: prevMethod.parameters,
+              to: currMethod.parameters
+            })
+          }
+        }
+      }
+    }
+  } else if (category === 'functions') {
+    // Compare function signatures
+    if (prev.returnType !== curr.returnType) {
+      differences.push({
+        type: 'return_type_changed',
+        from: prev.returnType,
+        to: curr.returnType
+      })
+    }
+
+    if (JSON.stringify(prev.parameters) !== JSON.stringify(curr.parameters)) {
+      differences.push({
+        type: 'parameters_changed',
+        from: prev.parameters,
+        to: curr.parameters
+      })
+    }
+  } else if (category === 'enums') {
+    // Compare enum members
+    const prevMembers = new Set(prev.members?.map((m) => m.name) || [])
+    const currMembers = new Set(curr.members?.map((m) => m.name) || [])
+
+    for (const member of currMembers) {
+      if (!prevMembers.has(member)) {
+        differences.push({
+          type: 'enum_member_added',
+          name: member
+        })
+      }
+    }
+
+    for (const member of prevMembers) {
+      if (!currMembers.has(member)) {
+        differences.push({
+          type: 'enum_member_removed',
+          name: member
+        })
+      }
+    }
+  }
+
+  return differences
+}
+
+/**
+ * Format changelog as markdown
+ */
+function formatChangelog(changes, prevVersion, currVersion) {
+  const lines = []
+
+  lines.push(`## v${currVersion} (${new Date().toISOString().split('T')[0]})`)
+  lines.push('')
+  lines.push(
+    `Comparing v${prevVersion} → v${currVersion}. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on.`
+  )
+  lines.push('')
+
+  // Breaking changes
+  if (changes.breaking.length > 0) {
+    lines.push('### ⚠️ Breaking Changes')
+    lines.push('')
+
+    const grouped = groupByCategory(changes.breaking)
+    for (const [category, items] of Object.entries(grouped)) {
+      lines.push(`**${categoryToTitle(category)}**`)
+      lines.push('')
+      for (const item of items) {
+        lines.push(`- **Removed**: \`${item.name}\``)
+      }
+      lines.push('')
+    }
+  }
+
+  // Additions
+  if (changes.additions.length > 0) {
+    lines.push('### ✨ Additions')
+    lines.push('')
+
+    const grouped = groupByCategory(changes.additions)
+    for (const [category, items] of Object.entries(grouped)) {
+      lines.push(`**${categoryToTitle(category)}**`)
+      lines.push('')
+      for (const item of items) {
+        lines.push(`- \`${item.name}\``)
+        if (item.item.members && item.item.members.length > 0) {
+          const publicMembers = item.item.members.filter(
+            (m) => !m.visibility || m.visibility === 'public'
+          )
+          if (publicMembers.length > 0 && publicMembers.length <= 5) {
+            lines.push(
+              `  - Members: ${publicMembers.map((m) => `\`${m.name}\``).join(', ')}`
+            )
+          }
+        }
+      }
+      lines.push('')
+    }
+  }
+
+  // Modifications
+  if (changes.modifications.length > 0) {
+    lines.push('### 🔄 Modifications')
+    lines.push('')
+
+    const hasBreakingMods = changes.modifications.some((mod) =>
+      mod.changes.some((c) => isBreakingChange(c))
+    )
+
+    if (hasBreakingMods) {
+      lines.push('> **Note**: Some modifications may be breaking changes.')
+      lines.push('')
+    }
+
+    const grouped = groupByCategory(changes.modifications)
+    for (const [category, items] of Object.entries(grouped)) {
+      lines.push(`**${categoryToTitle(category)}**`)
+      lines.push('')
+      for (const item of items) {
+        lines.push(`- \`${item.name}\``)
+        for (const change of item.changes) {
+          const formatted = formatChange(change)
+          if (formatted) {
+            lines.push(`  ${formatted}`)
+          }
+        }
+      }
+      lines.push('')
+    }
+  }
+
+  if (
+    changes.breaking.length === 0 &&
+    changes.additions.length === 0 &&
+    changes.modifications.length === 0
+  ) {
+    lines.push('_No API changes detected._')
+    lines.push('')
+  }
+
+  lines.push('---')
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+function groupByCategory(items) {
+  const grouped = {}
+  for (const item of items) {
+    if (!grouped[item.category]) {
+      grouped[item.category] = []
+    }
+    grouped[item.category].push(item)
+  }
+  return grouped
+}
+
+function categoryToTitle(category) {
+  const titles = {
+    types: 'Type Aliases',
+    interfaces: 'Interfaces',
+    enums: 'Enums',
+    functions: 'Functions',
+    classes: 'Classes',
+    constants: 'Constants'
+  }
+  return titles[category] || category
+}
+
+function isBreakingChange(change) {
+  const breakingTypes = [
+    'member_removed',
+    'method_removed',
+    'member_type_changed',
+    'method_return_type_changed',
+    'method_signature_changed',
+    'return_type_changed',
+    'parameters_changed',
+    'enum_member_removed'
+  ]
+  return breakingTypes.includes(change.type)
+}
+
+function formatChange(change) {
+  switch (change.type) {
+    case 'member_added':
+      return `- ✨ Added member: \`${change.name}\``
+    case 'member_removed':
+      return `- ⚠️ **Breaking**: Removed member: \`${change.name}\``
+    case 'member_type_changed':
+      return `- ⚠️ **Breaking**: Member \`${change.name}\` type changed: \`${change.from}\` → \`${change.to}\``
+    case 'member_optionality_changed':
+      return `- ${change.to === 'required' ? '⚠️ **Breaking**' : '✨'}: Member \`${change.name}\` is now ${change.to}`
+    case 'method_added':
+      return `- ✨ Added method: \`${change.name}()\``
+    case 'method_removed':
+      return `- ⚠️ **Breaking**: Removed method: \`${change.name}()\``
+    case 'method_return_type_changed':
+      return `- ⚠️ **Breaking**: Method \`${change.name}()\` return type changed: \`${change.from}\` → \`${change.to}\``
+    case 'method_signature_changed':
+      return `- ⚠️ **Breaking**: Method \`${change.name}()\` signature changed`
+    case 'return_type_changed':
+      return `- ⚠️ **Breaking**: Return type changed: \`${change.from}\` → \`${change.to}\``
+    case 'parameters_changed':
+      return `- ⚠️ **Breaking**: Function parameters changed`
+    case 'enum_member_added':
+      return `- ✨ Added enum value: \`${change.name}\``
+    case 'enum_member_removed':
+      return `- ⚠️ **Breaking**: Removed enum value: \`${change.name}\``
+    default:
+      return null
+  }
+}
+
+// Main execution
+const changes = compareApis(previousApi, currentApi)
+const changelog = formatChangelog(changes, previousVersion, currentVersion)
+
+console.log(changelog)

scripts/size-report.js

@@ -314,6 +314,11 @@ function renderCategoryDetails(report) {
 
   for (const category of report.categories) {
     lines.push(renderCategoryBlock(category, report.hasBaseline))
+    lines.push('')
+  }
+
+  if (report.categories.length > 0) {
+    lines.pop()
   }
 
   lines.push('</details>')
@@ -339,9 +344,11 @@ function renderCategoryBlock(category, hasBaseline) {
 
   summaryParts.push('</summary>')
   lines.push(summaryParts.join(''))
+  lines.push('')
 
   if (category.description) {
     lines.push(`_${category.description}_`)
+    lines.push('')
   }
 
   if (category.bundles.length === 0) {
@@ -382,6 +389,7 @@ function renderCategoryBlock(category, hasBaseline) {
     })
 
   lines.push(markdownTable([headers, ...rows]))
+  lines.push('')
 
   const statusParts = []
   if (category.counts.added) statusParts.push(`${category.counts.added} added`)
@@ -393,10 +401,11 @@ function renderCategoryBlock(category, hasBaseline) {
     statusParts.push(`${category.counts.decreased} shrank`)
 
   if (statusParts.length > 0) {
-    lines.push(`\n_Status:_ ${statusParts.join(' / ')}`)
+    lines.push(`_Status:_ ${statusParts.join(' / ')}`)
+    lines.push('')
   }
 
-  lines.push('</details>\n')
+  lines.push('</details>')
   return lines.join('\n')
 }
 

scripts/snapshot-api.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * Generates a JSON snapshot of the public API surface from TypeScript definitions.
+ * This snapshot is used to track API changes between versions.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import * as ts from 'typescript'
+
+const args = process.argv.slice(2)
+if (args.length === 0) {
+  console.error('Usage: snapshot-api.js <path-to-index.d.ts>')
+  process.exit(1)
+}
+
+const filePath = args[0]
+if (!fs.existsSync(filePath)) {
+  console.error(`File not found: ${filePath}`)
+  process.exit(1)
+}
+
+/**
+ * Extract API surface from TypeScript definitions
+ */
+function extractApiSurface(sourceFile) {
+  const api = {
+    types: {},
+    interfaces: {},
+    enums: {},
+    functions: {},
+    classes: {},
+    constants: {}
+  }
+
+  function visit(node) {
+    // Extract type aliases
+    if (ts.isTypeAliasDeclaration(node) && node.name) {
+      const name = node.name.text
+      api.types[name] = {
+        kind: 'type',
+        name,
+        text: node.getText(sourceFile),
+        exported: hasExportModifier(node)
+      }
+    }
+
+    // Extract interfaces
+    if (ts.isInterfaceDeclaration(node) && node.name) {
+      const name = node.name.text
+      const members = []
+
+      node.members.forEach((member) => {
+        if (ts.isPropertySignature(member) && member.name) {
+          members.push({
+            name: member.name.getText(sourceFile),
+            type: member.type ? member.type.getText(sourceFile) : 'any',
+            optional: !!member.questionToken
+          })
+        } else if (ts.isMethodSignature(member) && member.name) {
+          members.push({
+            name: member.name.getText(sourceFile),
+            kind: 'method',
+            parameters: member.parameters.map((p) => ({
+              name: p.name.getText(sourceFile),
+              type: p.type ? p.type.getText(sourceFile) : 'any',
+              optional: !!p.questionToken
+            })),
+            returnType: member.type ? member.type.getText(sourceFile) : 'void'
+          })
+        }
+      })
+
+      api.interfaces[name] = {
+        kind: 'interface',
+        name,
+        members,
+        exported: hasExportModifier(node),
+        heritage: node.heritageClauses
+          ? node.heritageClauses
+              .map((clause) =>
+                clause.types.map((type) => type.getText(sourceFile))
+              )
+              .flat()
+          : []
+      }
+    }
+
+    // Extract enums
+    if (ts.isEnumDeclaration(node) && node.name) {
+      const name = node.name.text
+      const members = node.members.map((member) => ({
+        name: member.name.getText(sourceFile),
+        value: member.initializer
+          ? member.initializer.getText(sourceFile)
+          : undefined
+      }))
+
+      api.enums[name] = {
+        kind: 'enum',
+        name,
+        members,
+        exported: hasExportModifier(node)
+      }
+    }
+
+    // Extract functions
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      const name = node.name.text
+      api.functions[name] = {
+        kind: 'function',
+        name,
+        parameters: node.parameters.map((p) => ({
+          name: p.name.getText(sourceFile),
+          type: p.type ? p.type.getText(sourceFile) : 'any',
+          optional: !!p.questionToken
+        })),
+        returnType: node.type ? node.type.getText(sourceFile) : 'any',
+        exported: hasExportModifier(node)
+      }
+    }
+
+    // Extract classes
+    if (ts.isClassDeclaration(node) && node.name) {
+      const name = node.name.text
+      const members = []
+      const methods = []
+
+      node.members.forEach((member) => {
+        if (ts.isPropertyDeclaration(member) && member.name) {
+          members.push({
+            name: member.name.getText(sourceFile),
+            type: member.type ? member.type.getText(sourceFile) : 'any',
+            static: hasStaticModifier(member),
+            visibility: getVisibility(member)
+          })
+        } else if (ts.isMethodDeclaration(member) && member.name) {
+          methods.push({
+            name: member.name.getText(sourceFile),
+            parameters: member.parameters.map((p) => ({
+              name: p.name.getText(sourceFile),
+              type: p.type ? p.type.getText(sourceFile) : 'any',
+              optional: !!p.questionToken
+            })),
+            returnType: member.type ? member.type.getText(sourceFile) : 'any',
+            static: hasStaticModifier(member),
+            visibility: getVisibility(member)
+          })
+        }
+      })
+
+      api.classes[name] = {
+        kind: 'class',
+        name,
+        members,
+        methods,
+        exported: hasExportModifier(node),
+        heritage: node.heritageClauses
+          ? node.heritageClauses
+              .map((clause) =>
+                clause.types.map((type) => type.getText(sourceFile))
+              )
+              .flat()
+          : []
+      }
+    }
+
+    // Extract variable declarations (constants)
+    if (ts.isVariableStatement(node)) {
+      node.declarationList.declarations.forEach((decl) => {
+        if (decl.name && ts.isIdentifier(decl.name)) {
+          const name = decl.name.text
+          api.constants[name] = {
+            kind: 'constant',
+            name,
+            type: decl.type ? decl.type.getText(sourceFile) : 'unknown',
+            exported: hasExportModifier(node)
+          }
+        }
+      })
+    }
+
+    ts.forEachChild(node, visit)
+  }
+
+  function hasExportModifier(node) {
+    return (
+      node.modifiers &&
+      node.modifiers.some((mod) => mod.kind === ts.SyntaxKind.ExportKeyword)
+    )
+  }
+
+  function hasStaticModifier(node) {
+    return (
+      node.modifiers &&
+      node.modifiers.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)
+    )
+  }
+
+  function getVisibility(node) {
+    if (!node.modifiers) return 'public'
+    if (node.modifiers.some((mod) => mod.kind === ts.SyntaxKind.PrivateKeyword))
+      return 'private'
+    if (
+      node.modifiers.some((mod) => mod.kind === ts.SyntaxKind.ProtectedKeyword)
+    )
+      return 'protected'
+    return 'public'
+  }
+
+  visit(sourceFile)
+  return api
+}
+
+// Read and parse the file
+const sourceCode = fs.readFileSync(filePath, 'utf-8')
+const sourceFile = ts.createSourceFile(
+  path.basename(filePath),
+  sourceCode,
+  ts.ScriptTarget.Latest,
+  true
+)
+
+const apiSurface = extractApiSurface(sourceFile)
+
+// Output as JSON
+console.log(JSON.stringify(apiSurface, null, 2))

src/components/card/CardTop.vue

@@ -54,7 +54,7 @@ const {
 }>()
 
 const topStyle = computed(() => {
-  const baseClasses = 'relative p-0'
+  const baseClasses = 'relative p-0 overflow-hidden'
 
   const ratioClasses = {
     square: 'aspect-square',

src/components/common/EditableText.vue

@@ -21,6 +21,8 @@
       @keyup.enter="blurInputElement"
       @keyup.escape="cancelEditing"
       @click.stop
+      @pointerdown.stop.capture
+      @pointermove.stop.capture
     />
   </div>
 </template>

src/components/common/FormImageUpload.vue

@@ -3,14 +3,14 @@
     <div class="flex items-center gap-2">
       <div
         class="preview-box flex h-16 w-16 items-center justify-center rounded border p-2"
-        :class="{ 'bg-gray-100 dark-theme:bg-gray-800': !modelValue }"
+        :class="{ 'bg-smoke-100 dark-theme:bg-smoke-800': !modelValue }"
       >
         <img
           v-if="modelValue"
           :src="modelValue"
           class="max-h-full max-w-full object-contain"
         />
-        <i v-else class="pi pi-image text-xl text-gray-400" />
+        <i v-else class="pi pi-image text-xl text-smoke-400" />
       </div>
 
       <div class="flex flex-col gap-2">

src/components/custom/widget/WorkflowTemplateSelectorDialog.vue

@@ -36,53 +36,55 @@
     </template>
 
     <template #contentFilter>
-      <div class="relative flex flex-wrap gap-2 px-6 pt-2 pb-4">
-        <!-- Model Filter -->
-        <MultiSelect
-          v-model="selectedModelObjects"
-          v-model:search-query="modelSearchText"
-          class="w-[250px]"
-          :label="modelFilterLabel"
-          :options="modelOptions"
-          :show-search-box="true"
-          :show-selected-count="true"
-          :show-clear-button="true"
-        >
-          <template #icon>
-            <i class="icon-[lucide--cpu]" />
-          </template>
-        </MultiSelect>
+      <div class="relative flex flex-wrap justify-between gap-2 px-6 pb-4">
+        <div class="flex flex-wrap gap-2">
+          <!-- Model Filter -->
+          <MultiSelect
+            v-model="selectedModelObjects"
+            v-model:search-query="modelSearchText"
+            class="w-[250px]"
+            :label="modelFilterLabel"
+            :options="modelOptions"
+            :show-search-box="true"
+            :show-selected-count="true"
+            :show-clear-button="true"
+          >
+            <template #icon>
+              <i class="icon-[lucide--cpu]" />
+            </template>
+          </MultiSelect>
 
-        <!-- Use Case Filter -->
-        <MultiSelect
-          v-model="selectedUseCaseObjects"
-          :label="useCaseFilterLabel"
-          :options="useCaseOptions"
-          :show-search-box="true"
-          :show-selected-count="true"
-          :show-clear-button="true"
-        >
-          <template #icon>
-            <i class="icon-[lucide--target]" />
-          </template>
-        </MultiSelect>
+          <!-- Use Case Filter -->
+          <MultiSelect
+            v-model="selectedUseCaseObjects"
+            :label="useCaseFilterLabel"
+            :options="useCaseOptions"
+            :show-search-box="true"
+            :show-selected-count="true"
+            :show-clear-button="true"
+          >
+            <template #icon>
+              <i class="icon-[lucide--target]" />
+            </template>
+          </MultiSelect>
 
-        <!-- License Filter -->
-        <MultiSelect
-          v-model="selectedLicenseObjects"
-          :label="licenseFilterLabel"
-          :options="licenseOptions"
-          :show-search-box="true"
-          :show-selected-count="true"
-          :show-clear-button="true"
-        >
-          <template #icon>
-            <i class="icon-[lucide--file-text]" />
-          </template>
-        </MultiSelect>
+          <!-- License Filter -->
+          <MultiSelect
+            v-model="selectedLicenseObjects"
+            :label="licenseFilterLabel"
+            :options="licenseOptions"
+            :show-search-box="true"
+            :show-selected-count="true"
+            :show-clear-button="true"
+          >
+            <template #icon>
+              <i class="icon-[lucide--file-text]" />
+            </template>
+          </MultiSelect>
+        </div>
 
         <!-- Sort Options -->
-        <div class="absolute right-5">
+        <div>
           <SingleSelect
             v-model="sortBy"
             :label="$t('templateWorkflows.sorting', 'Sort by')"
@@ -144,7 +146,7 @@
             size="compact"
             variant="ghost"
             rounded="lg"
-            class="hover:bg-white dark-theme:hover:bg-zinc-800"
+            class="hover:bg-base-background"
           >
             <template #top>
               <CardTop ratio="landscape">
@@ -178,7 +180,7 @@
             variant="ghost"
             rounded="lg"
             :data-testid="`template-workflow-${template.name}`"
-            class="hover:bg-white dark-theme:hover:bg-zinc-800"
+            class="hover:bg-base-background"
             @mouseenter="hoveredTemplate = template.name"
             @mouseleave="hoveredTemplate = null"
             @click="onLoadWorkflow(template)"
@@ -323,7 +325,7 @@
             size="compact"
             variant="ghost"
             rounded="lg"
-            class="hover:bg-white dark-theme:hover:bg-zinc-800"
+            class="hover:bg-base-background"
           >
             <template #top>
               <CardTop ratio="square">

src/components/dialog/content/setting/UsageLogsTable.vue

@@ -50,7 +50,7 @@
                 <div class="font-semibold">
                   {{ data.params?.api_name || 'API' }}
                 </div>
-                <div class="text-sm text-gray-400">
+                <div class="text-sm text-smoke-400">
                   {{ $t('credits.model') }}: {{ data.params?.model || '-' }}
                 </div>
               </div>

src/components/dialog/content/setting/UserPanel.vue

@@ -78,7 +78,7 @@
 
       <!-- Login Section -->
       <div v-else class="flex flex-col gap-4">
-        <p class="text-gray-600">
+        <p class="text-smoke-600">
           {{ $t('auth.login.title') }}
         </p>
 

src/components/graph/GraphCanvas.vue

@@ -3,8 +3,10 @@
   <!-- If load immediately, the top-level splitter stateKey won't be correctly
   synced with the stateStorage (localStorage). -->
   <LiteGraphCanvasSplitterOverlay v-if="comfyAppReady">
-    <template v-if="showUI && workflowTabsPosition === 'Topbar'" #workflow-tabs>
+    <template v-if="showUI" #workflow-tabs>
+      <TryVueNodeBanner />
       <div
+        v-if="workflowTabsPosition === 'Topbar'"
         class="workflow-tabs-container pointer-events-auto relative h-9.5 w-full"
       >
         <!-- Native drag area for Electron -->
@@ -152,6 +154,8 @@ import { useSearchBoxStore } from '@/stores/workspace/searchBoxStore'
 import { useWorkspaceStore } from '@/stores/workspaceStore'
 import { isNativeWindow } from '@/utils/envUtil'
 
+import TryVueNodeBanner from '../topbar/TryVueNodeBanner.vue'
+
 const emit = defineEmits<{
   ready: []
 }>()

src/components/graph/modals/ZoomControlsModal.vue

@@ -148,6 +148,6 @@ watch(
 </script>
 <style>
 .zoomInputContainer:focus-within {
-  border: 1px solid var(--color-pure-white);
+  border: 1px solid var(--color-white);
 }
 </style>

src/components/graph/selectionToolbox/BypassButton.test.ts

@@ -92,7 +92,7 @@ describe('BypassButton', () => {
     const button = wrapper.find('button')
 
     expect(button.classes()).not.toContain(
-      'dark-theme:[&:not(:active)]:!bg-[#262729]'
+      'dark-theme:[&:not(:active)]:!bg-charcoal-600'
     )
   })
 

src/components/graph/selectionToolbox/BypassButton.vue

@@ -7,7 +7,7 @@
     severity="secondary"
     text
     data-testid="bypass-button"
-    class="hover:bg-[#E7E6E6] hover:dark-theme:bg-charcoal-600"
+    class="hover:bg-secondary-background"
     @click="toggleBypass"
   >
     <template #icon>

src/components/graph/selectionToolbox/ExecuteButton.vue

@@ -4,7 +4,7 @@
       value: t('selectionToolbox.executeButton.tooltip'),
       showDelay: 1000
     }"
-    class="size-8 bg-[#31B9F4] !p-0 dark-theme:bg-[#0B8CE9]"
+    class="size-8 bg-azure-400 !p-0 dark-theme:bg-azure-600"
     text
     @mouseenter="() => handleMouseEnter()"
     @mouseleave="() => handleMouseLeave()"

src/components/graph/selectionToolbox/MenuOptionItem.vue

@@ -1,7 +1,7 @@
 <template>
   <div
     v-if="option.type === 'divider'"
-    class="my-1 h-px bg-gray-200 dark-theme:bg-zinc-700"
+    class="my-1 h-px bg-smoke-200 dark-theme:bg-zinc-700"
   />
   <div
     v-else
@@ -27,9 +27,9 @@
       :severity="option.badge === 'new' ? 'info' : 'secondary'"
       :value="t(option.badge)"
       :class="{
-        'rounded-4xl bg-[#31B9F4] dark-theme:bg-[#0B8CE9]':
+        'rounded-4xl bg-azure-400 dark-theme:bg-azure-600':
           option.badge === 'new',
-        'rounded-4xl bg-[#9C9EAB] dark-theme:bg-[#000]':
+        'rounded-4xl bg-slate-100 dark-theme:bg-black':
           option.badge === 'deprecated',
         'h-4 gap-2.5 px-1 text-[9px] text-white uppercase': true
       }"

src/components/graph/selectionToolbox/SubmenuPopover.vue

@@ -20,15 +20,15 @@
         :key="subOption.label"
         :class="
           isColorSubmenu
-            ? 'w-7 h-7 flex items-center justify-center hover:bg-gray-100 dark-theme:hover:bg-zinc-700 rounded cursor-pointer'
-            : 'flex items-center gap-2 px-3 py-1.5 text-sm hover:bg-gray-100 dark-theme:hover:bg-zinc-700 rounded cursor-pointer'
+            ? 'w-7 h-7 flex items-center justify-center hover:bg-smoke-100 dark-theme:hover:bg-zinc-700 rounded cursor-pointer'
+            : 'flex items-center gap-2 px-3 py-1.5 text-sm hover:bg-smoke-100 dark-theme:hover:bg-zinc-700 rounded cursor-pointer'
         "
         :title="subOption.label"
         @click="handleSubmenuClick(subOption)"
       >
         <div
           v-if="subOption.color"
-          class="h-5 w-5 rounded-full border border-gray-300 dark-theme:border-zinc-600"
+          class="h-5 w-5 rounded-full border border-smoke-300 dark-theme:border-zinc-600"
           :style="{ backgroundColor: subOption.color }"
         />
         <template v-else-if="!subOption.color">

src/components/graph/selectionToolbox/VerticalDivider.vue

@@ -1,3 +1,5 @@
 <template>
-  <div class="h-6 w-px self-center bg-gray-300/10 dark-theme:bg-gray-600/10" />
+  <div
+    class="h-6 w-px self-center bg-smoke-300/10 dark-theme:bg-smoke-600/10"
+  />
 </template>

src/components/graph/widgets/ChatHistoryWidget.vue

@@ -13,7 +13,7 @@
       >
         <div class="mb-1 flex justify-end">
           <div
-            class="max-w-[80%] rounded-xl bg-gray-300 px-4 py-1 text-right dark-theme:bg-gray-800"
+            class="max-w-[80%] rounded-xl bg-smoke-300 px-4 py-1 text-right dark-theme:bg-smoke-800"
           >
             <div class="text-[12px] break-words">{{ item.prompt }}</div>
           </div>
@@ -26,7 +26,7 @@
             "
             text
             rounded
-            class="h-4! w-4! p-1! text-gray-400 transition hover:text-gray-600 hover:dark-theme:text-gray-200"
+            class="h-4! w-4! p-1! text-smoke-400 transition hover:text-smoke-600 hover:dark-theme:text-smoke-200"
             pt:icon:class="text-xs!"
             :icon="editIndex === i ? 'pi pi-times' : 'pi pi-pencil'"
             :aria-label="

src/components/graph/widgets/chatHistory/CopyButton.vue

@@ -5,7 +5,7 @@
     "
     text
     rounded
-    class="h-4! w-6! p-1! text-gray-400 transition hover:text-gray-600 hover:dark-theme:text-gray-200"
+    class="h-4! w-6! p-1! text-smoke-400 transition hover:text-smoke-600 hover:dark-theme:text-smoke-200"
     pt:icon:class="text-xs!"
     :icon="copied ? 'pi pi-check' : 'pi pi-copy'"
     :aria-label="

src/components/helpcenter/HelpCenterMenuContent.vue

@@ -1,5 +1,9 @@
 <template>
-  <div class="help-center-menu" role="menu" aria-label="Help Center Menu">
+  <div
+    class="help-center-menu"
+    role="menu"
+    :aria-label="$t('helpCenter.helpFeedback')"
+  >
     <!-- Main Menu Items -->
     <nav class="help-menu-section" role="menubar">
       <button
@@ -68,7 +72,11 @@
       <h3 class="section-description">{{ $t('helpCenter.whatsNew') }}</h3>
 
       <!-- Release Items -->
-      <div v-if="hasReleases" role="group" aria-label="Recent releases">
+      <div
+        v-if="hasReleases"
+        role="group"
+        :aria-label="$t('helpCenter.recentReleases')"
+      >
         <article
           v-for="release in releaseStore.recentReleases"
           :key="release.id || release.version"

src/components/input/MultiSelect.accessibility.stories.ts

@@ -119,12 +119,12 @@ export const KeyboardNavigationDemo: Story = {
     },
     template: `
       <div class="space-y-4 p-4">
-        <div class="bg-blue-50 dark-theme:bg-blue-900/20 border border-blue-200 dark-theme:border-blue-700 rounded-lg p-4">
+        <div class="bg-blue-50 dark-theme:bg-blue-900/20 border border-azure-400 dark-theme:border-blue-700 rounded-lg p-4">
           <h3 class="text-lg font-semibold mb-2">🎯 Keyboard Navigation Test</h3>
-          <p class="text-sm text-gray-600 dark-theme:text-gray-300 mb-4">
+          <p class="text-sm text-smoke-600 dark-theme:text-smoke-300 mb-4">
             Use your keyboard to navigate this MultiSelect:
           </p>
-          <ol class="text-sm text-gray-600 list-decimal list-inside space-y-1">
+          <ol class="text-sm text-smoke-600 list-decimal list-inside space-y-1">
             <li><strong>Tab</strong> to focus the dropdown</li>
             <li><strong>Enter/Space</strong> to open dropdown</li>
             <li><strong>Arrow Up/Down</strong> to navigate options</li>
@@ -134,11 +134,11 @@ export const KeyboardNavigationDemo: Story = {
         </div>
 
         <div class="space-y-2">
-          <label class="block text-sm font-medium text-gray-700">
+          <label class="block text-sm font-medium text-smoke-700">
             Select Frameworks (Keyboard Navigation Test)
           </label>
           <MultiSelect v-bind="args" class="w-80" />
-          <p class="text-xs text-gray-500">
+          <p class="text-xs text-smoke-500">
             Selected: {{ selectedFrameworks.map(f => f.name).join(', ') || 'None' }}
           </p>
         </div>
@@ -186,10 +186,10 @@ export const ScreenReaderFriendly: Story = {
       <div class="space-y-6 p-4">
         <div class="bg-green-50 dark-theme:bg-green-900/20 border border-green-200 dark-theme:border-green-700 rounded-lg p-4">
           <h3 class="text-lg font-semibold mb-2">♿ Screen Reader Test</h3>
-          <p class="text-sm text-gray-600 mb-2">
+          <p class="text-sm text-smoke-600 mb-2">
             These dropdowns have proper ARIA attributes and labels for screen readers:
           </p>
-          <ul class="text-sm text-gray-600 list-disc list-inside space-y-1">
+          <ul class="text-sm text-smoke-600 list-disc list-inside space-y-1">
             <li><code>role="combobox"</code> identifies as dropdown</li>
             <li><code>aria-haspopup="listbox"</code> indicates popup type</li>
             <li><code>aria-expanded</code> shows open/closed state</li>
@@ -200,7 +200,7 @@ export const ScreenReaderFriendly: Story = {
 
         <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
           <div class="space-y-2">
-            <label class="block text-sm font-medium text-gray-700">
+            <label class="block text-sm font-medium text-smoke-700">
               Color Preferences
             </label>
             <MultiSelect
@@ -211,13 +211,13 @@ export const ScreenReaderFriendly: Story = {
               :show-clear-button="true"
               class="w-full"
             />
-            <p class="text-xs text-gray-500" aria-live="polite">
+            <p class="text-xs text-smoke-500" aria-live="polite">
               {{ selectedColors.length }} color(s) selected
             </p>
           </div>
 
           <div class="space-y-2">
-            <label class="block text-sm font-medium text-gray-700">
+            <label class="block text-sm font-medium text-smoke-700">
               Size Preferences
             </label>
             <MultiSelect
@@ -228,7 +228,7 @@ export const ScreenReaderFriendly: Story = {
               :show-search-box="true"
               class="w-full"
             />
-            <p class="text-xs text-gray-500" aria-live="polite">
+            <p class="text-xs text-smoke-500" aria-live="polite">
               {{ selectedSizes.length }} size(s) selected
             </p>
           </div>
@@ -259,25 +259,25 @@ export const FocusManagement: Story = {
       <div class="space-y-4 p-4">
         <div class="bg-purple-50 dark-theme:bg-purple-900/20 border border-purple-200 dark-theme:border-purple-700 rounded-lg p-4">
           <h3 class="text-lg font-semibold mb-2">🎯 Focus Management Test</h3>
-          <p class="text-sm text-gray-600 dark-theme:text-gray-300 mb-4">
+          <p class="text-sm text-smoke-600 dark-theme:text-smoke-300 mb-4">
             Test focus behavior with multiple form elements:
           </p>
         </div>
 
         <div class="space-y-4">
           <div>
-            <label class="block text-sm font-medium text-gray-700 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 mb-1">
               Before MultiSelect
             </label>
             <input
               type="text"
               placeholder="Previous field"
-              class="block w-64 px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+              class="block w-64 px-3 py-2 border border-smoke-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
             />
           </div>
 
           <div>
-            <label class="block text-sm font-medium text-gray-700 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 mb-1">
               MultiSelect (Test Focus Ring)
             </label>
             <MultiSelect
@@ -290,13 +290,13 @@ export const FocusManagement: Story = {
           </div>
 
           <div>
-            <label class="block text-sm font-medium text-gray-700 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 mb-1">
               After MultiSelect
             </label>
             <input
               type="text"
               placeholder="Next field"
-              class="block w-64 px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+              class="block w-64 px-3 py-2 border border-smoke-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
             />
           </div>
 
@@ -307,7 +307,7 @@ export const FocusManagement: Story = {
           </button>
         </div>
 
-        <div class="text-sm text-gray-600 mt-4">
+        <div class="text-sm text-smoke-600 mt-4">
           <strong>Test:</strong> Tab through all elements and verify focus rings are visible and logical.
         </div>
       </div>
@@ -319,7 +319,7 @@ export const AccessibilityChecklist: Story = {
   render: () => ({
     template: `
       <div class="max-w-4xl mx-auto p-6 space-y-6">
-        <div class="bg-gray-50 dark-theme:bg-zinc-800 border border-gray-200 dark-theme:border-zinc-700 rounded-lg p-6">
+        <div class="bg-gray-50 dark-theme:bg-zinc-800 border border-smoke-200 dark-theme:border-zinc-700 rounded-lg p-6">
           <h2 class="text-2xl font-bold mb-4">♿ MultiSelect Accessibility Checklist</h2>
 
           <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
@@ -366,9 +366,9 @@ export const AccessibilityChecklist: Story = {
             </div>
           </div>
 
-          <div class="mt-6 p-4 bg-blue-50 dark-theme:bg-blue-900/20 border border-blue-200 dark-theme:border-blue-700 rounded-lg">
+          <div class="mt-6 p-4 bg-blue-50 dark-theme:bg-blue-900/20 border border-azure-400 dark-theme:border-blue-700 rounded-lg">
             <h4 class="font-semibold mb-2">🎯 Quick Test</h4>
-            <p class="text-sm text-gray-700 dark-theme:text-gray-300">
+            <p class="text-sm text-smoke-700 dark-theme:text-smoke-300">
               Close your eyes, use only the keyboard, and try to select multiple options from any dropdown above.
               If you can successfully navigate and make selections, the accessibility implementation is working!
             </p>

src/components/input/MultiSelect.vue

@@ -62,7 +62,7 @@
 
     <!-- Trigger value (keep text scale identical) -->
     <template #value>
-      <span class="text-sm text-zinc-700 dark-theme:text-gray-200">
+      <span class="text-sm text-zinc-700 dark-theme:text-smoke-200">
         {{ label }}
       </span>
       <span
@@ -242,7 +242,7 @@ const pt = computed(() => ({
     )
   },
   listContainer: () => ({
-    style: { maxHeight: listMaxHeight },
+    style: { maxHeight: `min(${listMaxHeight}, 50vh)` },
     class: 'scrollbar-custom'
   }),
   list: {

src/components/input/SingleSelect.accessibility.stories.ts

@@ -101,12 +101,12 @@ export const KeyboardNavigationDemo: Story = {
     },
     template: `
       <div class="space-y-6 p-4">
-        <div class="bg-blue-50 dark-theme:bg-blue-900/20 border border-blue-200 dark-theme:border-blue-700 rounded-lg p-4">
+        <div class="bg-blue-50 dark-theme:bg-blue-900/20 border border-azure-400 dark-theme:border-blue-700 rounded-lg p-4">
           <h3 class="text-lg font-semibold mb-2">🎯 Keyboard Navigation Test</h3>
-          <p class="text-sm text-gray-600 dark-theme:text-gray-300 mb-4">
+          <p class="text-sm text-smoke-600 dark-theme:text-smoke-300 mb-4">
             Use your keyboard to navigate these SingleSelect dropdowns:
           </p>
-          <ol class="text-sm text-gray-600 dark-theme:text-gray-300 list-decimal list-inside space-y-1">
+          <ol class="text-sm text-smoke-600 dark-theme:text-smoke-300 list-decimal list-inside space-y-1">
             <li><strong>Tab</strong> to focus the dropdown</li>
             <li><strong>Enter/Space</strong> to open dropdown</li>
             <li><strong>Arrow Up/Down</strong> to navigate options</li>
@@ -117,7 +117,7 @@ export const KeyboardNavigationDemo: Story = {
 
         <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
           <div class="space-y-2">
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200">
               Sort Order
             </label>
             <SingleSelect
@@ -126,13 +126,13 @@ export const KeyboardNavigationDemo: Story = {
               label="Choose sort order"
               class="w-full"
             />
-            <p class="text-xs text-gray-500">
+            <p class="text-xs text-smoke-500">
               Selected: {{ selectedSort ? sortOptions.find(o => o.value === selectedSort)?.name : 'None' }}
             </p>
           </div>
 
           <div class="space-y-2">
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200">
               Task Priority (With Icon)
             </label>
             <SingleSelect
@@ -147,7 +147,7 @@ export const KeyboardNavigationDemo: Story = {
                 </svg>
               </template>
             </SingleSelect>
-            <p class="text-xs text-gray-500">
+            <p class="text-xs text-smoke-500">
               Selected: {{ selectedPriority ? priorityOptions.find(o => o.value === selectedPriority)?.name : 'None' }}
             </p>
           </div>
@@ -191,10 +191,10 @@ export const ScreenReaderFriendly: Story = {
       <div class="space-y-6 p-4">
         <div class="bg-green-50 dark-theme:bg-green-900/20 border border-green-200 dark-theme:border-green-700 rounded-lg p-4">
           <h3 class="text-lg font-semibold mb-2">♿ Screen Reader Test</h3>
-          <p class="text-sm text-gray-600 dark-theme:text-gray-300 mb-2">
+          <p class="text-sm text-smoke-600 dark-theme:text-smoke-300 mb-2">
             These dropdowns have proper ARIA attributes and labels for screen readers:
           </p>
-          <ul class="text-sm text-gray-600 dark-theme:text-gray-300 list-disc list-inside space-y-1">
+          <ul class="text-sm text-smoke-600 dark-theme:text-smoke-300 list-disc list-inside space-y-1">
             <li><code>role="combobox"</code> identifies as dropdown</li>
             <li><code>aria-haspopup="listbox"</code> indicates popup type</li>
             <li><code>aria-expanded</code> shows open/closed state</li>
@@ -205,7 +205,7 @@ export const ScreenReaderFriendly: Story = {
 
         <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
           <div class="space-y-2">
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200" id="language-label">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200" id="language-label">
               Preferred Language
             </label>
             <SingleSelect
@@ -215,13 +215,13 @@ export const ScreenReaderFriendly: Story = {
               class="w-full"
               aria-labelledby="language-label"
             />
-            <p class="text-xs text-gray-500" aria-live="polite">
+            <p class="text-xs text-smoke-500" aria-live="polite">
               Current: {{ selectedLanguage ? languageOptions.find(o => o.value === selectedLanguage)?.name : 'None selected' }}
             </p>
           </div>
 
           <div class="space-y-2">
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200" id="theme-label">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200" id="theme-label">
               Interface Theme
             </label>
             <SingleSelect
@@ -231,7 +231,7 @@ export const ScreenReaderFriendly: Story = {
               class="w-full"
               aria-labelledby="theme-label"
             />
-            <p class="text-xs text-gray-500" aria-live="polite">
+            <p class="text-xs text-smoke-500" aria-live="polite">
               Current: {{ selectedTheme ? themeOptions.find(o => o.value === selectedTheme)?.name : 'No theme selected' }}
             </p>
           </div>
@@ -239,7 +239,7 @@ export const ScreenReaderFriendly: Story = {
 
         <div class="bg-yellow-50 border border-yellow-200 rounded-lg p-4">
           <h4 class="font-semibold mb-2">🎧 Screen Reader Testing Tips</h4>
-          <ul class="text-sm text-gray-600 dark-theme:text-gray-300 space-y-1">
+          <ul class="text-sm text-smoke-600 dark-theme:text-smoke-300 space-y-1">
             <li>• Listen for role announcements when focusing</li>
             <li>• Verify dropdown state changes are announced</li>
             <li>• Check that selected values are spoken clearly</li>
@@ -299,7 +299,7 @@ export const FormIntegration: Story = {
       <div class="max-w-2xl mx-auto p-6">
         <div class="bg-purple-50 dark-theme:bg-purple-900/20 border border-purple-200 dark-theme:border-purple-700 rounded-lg p-4 mb-6">
           <h3 class="text-lg font-semibold mb-2">📝 Form Integration Test</h3>
-          <p class="text-sm text-gray-600 dark-theme:text-gray-300">
+          <p class="text-sm text-smoke-600 dark-theme:text-smoke-300">
             Test keyboard navigation through a complete form with SingleSelect components.
             Tab order should be logical and all elements should be accessible.
           </p>
@@ -307,19 +307,19 @@ export const FormIntegration: Story = {
 
         <form @submit.prevent="handleSubmit" class="space-y-6">
           <div>
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200 mb-1">
               Title *
             </label>
             <input
               type="text"
               required
               placeholder="Enter a title"
-              class="block w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+              class="block w-full px-3 py-2 border border-smoke-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
             />
           </div>
 
           <div>
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200 mb-1">
               Category *
             </label>
             <SingleSelect
@@ -332,7 +332,7 @@ export const FormIntegration: Story = {
           </div>
 
           <div>
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200 mb-1">
               Status
             </label>
             <SingleSelect
@@ -344,7 +344,7 @@ export const FormIntegration: Story = {
           </div>
 
           <div>
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200 mb-1">
               Assignee
             </label>
             <SingleSelect
@@ -356,13 +356,13 @@ export const FormIntegration: Story = {
           </div>
 
           <div>
-            <label class="block text-sm font-medium text-gray-700 dark-theme:text-gray-200 mb-1">
+            <label class="block text-sm font-medium text-smoke-700 dark-theme:text-smoke-200 mb-1">
               Description
             </label>
             <textarea
               rows="4"
               placeholder="Enter description"
-              class="block w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+              class="block w-full px-3 py-2 border border-smoke-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
             />
           </div>
 
@@ -375,16 +375,16 @@ export const FormIntegration: Story = {
             </button>
             <button
               type="button"
-              class="px-4 py-2 bg-gray-300 dark-theme:bg-gray-600 text-gray-700 dark-theme:text-gray-200 rounded-md hover:bg-gray-400 dark-theme:hover:bg-gray-500 focus:ring-2 focus:ring-gray-500 focus:ring-offset-2"
+              class="px-4 py-2 bg-smoke-300 dark-theme:bg-smoke-600 text-smoke-700 dark-theme:text-smoke-200 rounded-md hover:bg-smoke-400 dark-theme:hover:bg-smoke-500 focus:ring-2 focus:ring-smoke-500 focus:ring-offset-2"
             >
               Cancel
             </button>
           </div>
         </form>
 
-        <div class="mt-6 p-4 bg-gray-50 dark-theme:bg-zinc-800 border border-gray-200 dark-theme:border-zinc-700 rounded-lg">
+        <div class="mt-6 p-4 bg-gray-50 dark-theme:bg-zinc-800 border border-smoke-200 dark-theme:border-zinc-700 rounded-lg">
           <h4 class="font-semibold mb-2">Current Form Data:</h4>
-          <pre class="text-xs text-gray-600 dark-theme:text-gray-300">{{ JSON.stringify(formData, null, 2) }}</pre>
+          <pre class="text-xs text-smoke-600 dark-theme:text-smoke-300">{{ JSON.stringify(formData, null, 2) }}</pre>
         </div>
       </div>
     `
@@ -395,7 +395,7 @@ export const AccessibilityChecklist: Story = {
   render: () => ({
     template: `
       <div class="max-w-4xl mx-auto p-6 space-y-6">
-        <div class="bg-gray-50 dark-theme:bg-zinc-800 border border-gray-200 dark-theme:border-zinc-700 rounded-lg p-6">
+        <div class="bg-gray-50 dark-theme:bg-zinc-800 border border-smoke-200 dark-theme:border-zinc-700 rounded-lg p-6">
           <h2 class="text-2xl font-bold mb-4">♿ SingleSelect Accessibility Checklist</h2>
 
           <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
@@ -442,9 +442,9 @@ export const AccessibilityChecklist: Story = {
             </div>
           </div>
 
-          <div class="mt-6 p-4 bg-blue-50 dark-theme:bg-blue-900/20 border border-blue-200 dark-theme:border-blue-700 rounded-lg">
+          <div class="mt-6 p-4 bg-blue-50 dark-theme:bg-blue-900/20 border border-azure-400 dark-theme:border-blue-700 rounded-lg">
             <h4 class="font-semibold mb-2">🎯 Quick Test</h4>
-            <p class="text-sm text-gray-700 dark-theme:text-gray-200">
+            <p class="text-sm text-smoke-700 dark-theme:text-smoke-200">
               Close your eyes, use only the keyboard, and try to select different options from any dropdown above.
               If you can successfully navigate and make selections, the accessibility implementation is working!
             </p>
@@ -452,7 +452,7 @@ export const AccessibilityChecklist: Story = {
 
           <div class="mt-4 p-4 bg-orange-50 border border-orange-200 rounded-lg">
             <h4 class="font-semibold mb-2">⚡ Performance Note</h4>
-            <p class="text-sm text-gray-700 dark-theme:text-gray-200">
+            <p class="text-sm text-smoke-700 dark-theme:text-smoke-200">
               These accessibility features are built into the component with minimal performance impact.
               The ARIA attributes and keyboard handlers add less than 1KB to the bundle size.
             </p>

src/components/input/SingleSelect.vue

@@ -26,11 +26,11 @@
         <slot name="icon" />
         <span
           v-if="slotProps.value !== null && slotProps.value !== undefined"
-          class="text-zinc-700 dark-theme:text-gray-200"
+          class="text-zinc-700 dark-theme:text-smoke-200"
         >
           {{ getLabel(slotProps.value) }}
         </span>
-        <span v-else class="text-zinc-700 dark-theme:text-gray-200">
+        <span v-else class="text-zinc-700 dark-theme:text-smoke-200">
           {{ label }}
         </span>
       </div>
@@ -158,7 +158,7 @@ const pt = computed(() => ({
     )
   },
   listContainer: () => ({
-    style: `max-height: ${listMaxHeight}`,
+    style: `max-height: min(${listMaxHeight}, 50vh)`,
     class: 'scrollbar-custom'
   }),
   list: {

src/components/load3d/Load3DControls.vue

@@ -1,6 +1,6 @@
 <template>
   <div
-    class="pointer-events-auto absolute top-12 left-2 z-20 flex flex-col rounded-lg bg-gray-700/30"
+    class="pointer-events-auto absolute top-12 left-2 z-20 flex flex-col rounded-lg bg-smoke-700/30"
   >
     <div class="show-menu relative">
       <Button class="p-button-rounded p-button-text" @click="toggleMenu">
@@ -16,7 +16,7 @@
             v-for="category in availableCategories"
             :key="category"
             class="p-button-text flex w-full items-center justify-start"
-            :class="{ 'bg-gray-600': activeCategory === category }"
+            :class="{ 'bg-smoke-600': activeCategory === category }"
             @click="selectCategory(category)"
           >
             <i :class="getCategoryIcon(category)" />
@@ -26,7 +26,7 @@
       </div>
     </div>
 
-    <div v-show="activeCategory" class="rounded-lg bg-gray-700/30">
+    <div v-show="activeCategory" class="rounded-lg bg-smoke-700/30">
       <SceneControls
         v-if="activeCategory === 'scene'"
         ref="sceneControlsRef"

src/components/load3d/controls/RecordingControls.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="relative rounded-lg bg-gray-700/30">
+  <div class="relative rounded-lg bg-smoke-700/30">
     <div class="flex flex-col gap-2">
       <Button
         class="p-button-rounded p-button-text"

src/components/load3d/controls/ViewerControls.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="relative rounded-lg bg-gray-700/30">
+  <div class="relative rounded-lg bg-smoke-700/30">
     <div class="flex flex-col gap-2">
       <Button class="p-button-rounded p-button-text" @click="openIn3DViewer">
         <i