docs: simplify CLAUDE.md for feature flags and settings

docs: update stores README.md
[docs] update CLAUDE.md and selected README.md files (#5293 )
2026-07-12 02:08:25 +00:00 · 2025-09-01 19:22:24 -07:00 · 2025-09-01 19:20:19 -07:00 · 2025-09-01 15:31:44 -07:00 · 2025-09-01 11:36:29 -07:00 · 2025-09-01 10:54:55 -07:00
25 changed files with 1848 additions and 394 deletions
--- a/.github/workflows/i18n.yaml
+++ b/.github/workflows/i18n.yaml
@@ -25,6 +25,13 @@ jobs:
        key: i18n-tools-cache-${{ runner.os }}-${{ hashFiles('ComfyUI_frontend/pnpm-lock.yaml') }}
        restore-keys: |
          i18n-tools-cache-${{ runner.os }}-
+    - name: Cache Playwright browsers
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-browsers-${{ runner.os }}-${{ hashFiles('ComfyUI_frontend/pnpm-lock.yaml') }}
+        restore-keys: |
+          playwright-browsers-${{ runner.os }}-
    - name: Install Playwright Browsers
      run: npx playwright install chromium --with-deps
      working-directory: ComfyUI_frontend
--- a/.github/workflows/pr-storybook-comment.yaml
+++ b/.github/workflows/pr-storybook-comment.yaml
@@ -8,7 +8,10 @@ on:
 jobs:
  comment-storybook:
    runs-on: ubuntu-latest
-    if: github.repository == 'Comfy-Org/ComfyUI_frontend' && github.event.workflow_run.event == 'pull_request'
+    if: >-
+      github.repository == 'Comfy-Org/ComfyUI_frontend'
+      && github.event.workflow_run.event == 'pull_request'
+      && startsWith(github.event.workflow_run.head_branch, 'version-bump-')
    permissions:
      pull-requests: write
      actions: read
@@ -97,7 +100,17 @@ jobs:
            <!-- STORYBOOK_BUILD_STATUS -->
            ## 🎨 Storybook Build Status

-            ${{ fromJSON(steps.workflow-run.outputs.result).conclusion == 'success' && '✅' || '❌' }} **${{ fromJSON(steps.workflow-run.outputs.result).conclusion == 'success' && 'Build completed successfully!' || 'Build failed!' }}**
+            ${{
+              fromJSON(steps.workflow-run.outputs.result).conclusion == 'success' && '✅'
+              || fromJSON(steps.workflow-run.outputs.result).conclusion == 'skipped' && '⏭️'
+              || fromJSON(steps.workflow-run.outputs.result).conclusion == 'cancelled' && '🚫'
+              || '❌'
+            }} **${{
+              fromJSON(steps.workflow-run.outputs.result).conclusion == 'success' && 'Build completed successfully!'
+              || fromJSON(steps.workflow-run.outputs.result).conclusion == 'skipped' && 'Build skipped.'
+              || fromJSON(steps.workflow-run.outputs.result).conclusion == 'cancelled' && 'Build cancelled.'
+              || 'Build failed!'
+            }}**

            ⏰ Completed at: ${{ steps.completion-time.outputs.time }} UTC

@@ -105,4 +118,9 @@ jobs:
            - [📊 View Workflow Run](${{ fromJSON(steps.workflow-run.outputs.result).html_url }})

            ---
-            ${{ fromJSON(steps.workflow-run.outputs.result).conclusion == 'success' && '🎉 Your Storybook is ready for review!' || '⚠️ Please check the workflow logs for error details.' }}
+            ${{
+              fromJSON(steps.workflow-run.outputs.result).conclusion == 'success' && '🎉 Your Storybook is ready for review!'
+              || fromJSON(steps.workflow-run.outputs.result).conclusion == 'skipped' && 'ℹ️ Chromatic was skipped for this PR.'
+              || fromJSON(steps.workflow-run.outputs.result).conclusion == 'cancelled' && 'ℹ️ The Chromatic run was cancelled.'
+              || '⚠️ Please check the workflow logs for error details.'
+            }}
--- a/.github/workflows/test-browser-exp.yaml
+++ b/.github/workflows/test-browser-exp.yaml
@@ -11,6 +11,13 @@ jobs:
    if: github.event.label.name == 'New Browser Test Expectations'
    steps:
    - uses: Comfy-Org/ComfyUI_frontend_setup_action@v3
+    - name: Cache Playwright browsers
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-browsers-${{ runner.os }}-${{ hashFiles('ComfyUI_frontend/pnpm-lock.yaml') }}
+        restore-keys: |
+          playwright-browsers-${{ runner.os }}-
    - name: Install Playwright Browsers
      run: npx playwright install chromium --with-deps
      working-directory: ComfyUI_frontend
--- a/.storybook/preview-head.html
+++ b/.storybook/preview-head.html
@@ -4,17 +4,26 @@
    transition: background-color 0.3s ease, color 0.3s ease;
  }

-  /* Light theme default */
-  body {
-    background-color: #ffffff;
-    color: #1a1a1a;
+  /* Light theme default - with explicit color to override media queries */
+  body:not(.dark-theme) {
+    background-color: #fff !important;
+    color: #000 !important;
+  }
+
+  /* Override browser dark mode preference for light theme */
+  @media (prefers-color-scheme: dark) {
+    body:not(.dark-theme) {
+      color: #000 !important;
+      --fg-color: #000 !important;
+      --bg-color: #fff !important;
+    }
  }

  /* Dark theme styles */
  body.dark-theme,
  .dark-theme body {
-    background-color: #0a0a0a;
-    color: #e5e5e5;
+    background-color: #202020;
+    color: #fff;
  }

  /* Ensure Storybook canvas follows theme */
@@ -24,11 +33,33 @@

  .dark-theme .sb-show-main,
  .dark-theme .docs-story {
-    background-color: #0a0a0a !important;
+    background-color: #202020 !important;
  }

-  /* Fix for Storybook controls panel in dark mode */
-  .dark-theme .docblock-argstable-body {
-    color: #e5e5e5;
+  /* CSS Variables for theme consistency */
+  body:not(.dark-theme) {
+    --fg-color: #000;
+    --bg-color: #fff;
+    --content-bg: #e0e0e0;
+    --content-fg: #000;
+    --content-hover-bg: #adadad;
+    --content-hover-fg: #000;
+  }
+
+  body.dark-theme {
+    --fg-color: #fff;
+    --bg-color: #202020;
+    --content-bg: #4e4e4e;
+    --content-fg: #fff;
+    --content-hover-bg: #222;
+    --content-hover-fg: #fff;
+  }
+
+  /* Override Storybook's problematic & selector styles */
+  /* Reset only the specific properties that Storybook injects */
+  #storybook-root li+li,
+  #storybook-docs li+li {
+    margin: inherit;
+    padding: inherit;
  }
 </style>
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,6 +82,14 @@ When referencing Comfy-Org repos:
 2. Use GitHub API for branches/PRs/metadata
 3. Curl GitHub website if needed

+## Settings and Feature Flags
+
+Extensive capabilities to adding settings and feature flags. Read documentation.
+
+**Documentation:**
+- Settings system: `docs/SETTINGS.md`
+- Feature flags system: `docs/FEATURE_FLAGS.md`
+
 ## Common Pitfalls

 - NEVER use `any` type - use proper TypeScript types
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,7 @@ Have another idea? Drop into Discord or open an issue, and let's chat!
 ### Prerequisites & Technology Stack

 - **Required Software**:
-  - Node.js (v16 or later; v24 strongly recommended) and pnpm
+  - Node.js (v18 or later to build; v24 for vite dev server) and pnpm
  - Git for version control
  - A running ComfyUI backend instance
  
--- a/docs/SETTINGS.md
+++ b/docs/SETTINGS.md
@@ -0,0 +1,293 @@
+# Settings System
+
+## Overview
+
+ComfyUI frontend uses a comprehensive settings system for user preferences with support for dynamic defaults, version-based rollouts, and environment-aware configuration.
+
+### Settings Architecture
+- Settings are defined as `SettingParams` in `src/constants/coreSettings.ts`
+- Registered at app startup, loaded/saved via `useSettingStore` (Pinia)
+- Persisted per user via backend `/settings` endpoint
+- If a value hasn't been set by the user, the store returns the computed default
+
+```typescript
+// From src/stores/settingStore.ts:105-122
+function getDefaultValue<K extends keyof Settings>(
+  key: K
+): Settings[K] | undefined {
+  const param = getSettingById(key)
+  if (param === undefined) return
+
+  const versionedDefault = getVersionedDefaultValue(key, param)
+  if (versionedDefault) {
+    return versionedDefault
+  }
+
+  return typeof param.defaultValue === 'function'
+    ? param.defaultValue()
+    : param.defaultValue
+}
+```
+
+### Settings Registration Process
+
+Settings are registered after server values are loaded:
+
+```typescript
+// From src/components/graph/GraphCanvas.vue:311-315
+CORE_SETTINGS.forEach((setting) => {
+  settingStore.addSetting(setting)
+})
+
+await newUserService().initializeIfNewUser(settingStore)
+```
+
+## Dynamic and Environment-Based Defaults
+
+### Computed Defaults
+You can compute defaults dynamically using function defaults that access runtime context:
+
+```typescript
+// From src/constants/coreSettings.ts:94-101
+{
+  id: 'Comfy.Sidebar.Size',
+  // Default to small if the window is less than 1536px(2xl) wide
+  defaultValue: () => (window.innerWidth < 1536 ? 'small' : 'normal')
+}
+```
+
+```typescript
+// From src/constants/coreSettings.ts:306
+{
+  id: 'Comfy.Locale',
+  defaultValue: () => navigator.language.split('-')[0] || 'en'
+}
+```
+
+### Version-Based Defaults
+You can vary defaults by installed frontend version using `defaultsByInstallVersion`:
+
+```typescript
+// From src/stores/settingStore.ts:129-150
+function getVersionedDefaultValue<K extends keyof Settings, TValue = Settings[K]>(
+  key: K, 
+  param: SettingParams<TValue> | undefined
+): TValue | null {
+  const defaultsByInstallVersion = param?.defaultsByInstallVersion
+  if (defaultsByInstallVersion && key !== 'Comfy.InstalledVersion') {
+    const installedVersion = get('Comfy.InstalledVersion')
+    if (installedVersion) {
+      const sortedVersions = Object.keys(defaultsByInstallVersion).sort(
+        (a, b) => compareVersions(b, a)
+      )
+      for (const version of sortedVersions) {
+        if (!isSemVer(version)) continue
+        if (compareVersions(installedVersion, version) >= 0) {
+          const versionedDefault = defaultsByInstallVersion[version]
+          return typeof versionedDefault === 'function'
+            ? versionedDefault()
+            : versionedDefault
+        }
+      }
+    }
+  }
+  return null
+}
+```
+
+Example versioned defaults from codebase:
+
+```typescript
+// From src/constants/coreSettings.ts:38-40
+{
+  id: 'Comfy.Graph.LinkReleaseAction',
+  defaultValue: LinkReleaseTriggerAction.CONTEXT_MENU,
+  defaultsByInstallVersion: {
+    '1.24.1': LinkReleaseTriggerAction.SEARCH_BOX
+  }
+}
+
+// Another versioned default example
+{
+  id: 'Comfy.Graph.LinkReleaseAction.Shift',
+  defaultValue: LinkReleaseTriggerAction.SEARCH_BOX,
+  defaultsByInstallVersion: {
+    '1.24.1': LinkReleaseTriggerAction.CONTEXT_MENU
+  }
+}
+```
+
+### Real Examples from Codebase
+
+Here are actual settings showing different patterns:
+
+```typescript
+// Number setting with validation
+{
+  id: 'LiteGraph.Node.TooltipDelay',
+  name: 'Tooltip Delay',
+  type: 'number',
+  attrs: {
+    min: 100,
+    max: 3000,
+    step: 50
+  },
+  defaultValue: 500,
+  versionAdded: '1.9.0'
+}
+
+// Hidden system setting for tracking
+{
+  id: 'Comfy.InstalledVersion',
+  name: 'The frontend version that was running when the user first installed ComfyUI',
+  type: 'hidden',
+  defaultValue: null,
+  versionAdded: '1.24.0'
+}
+
+// Slider with complex tooltip
+{
+  id: 'LiteGraph.Canvas.LowQualityRenderingZoomThreshold',
+  name: 'Low quality rendering zoom threshold',
+  tooltip: 'Zoom level threshold for performance mode. Lower values (0.1) = quality at all zoom levels. Higher values (1.0) = performance mode even when zoomed in.',
+  type: 'slider',
+  attrs: {
+    min: 0.1,
+    max: 1.0,
+    step: 0.05
+  },
+  defaultValue: 0.5
+}
+```
+
+### New User Version Capture
+
+The initial installed version is captured for new users to ensure versioned defaults remain stable:
+
+```typescript
+// From src/services/newUserService.ts:49-53
+await settingStore.set(
+  'Comfy.InstalledVersion',
+  __COMFYUI_FRONTEND_VERSION__
+)
+```
+
+## Practical Patterns for Environment-Based Defaults
+
+### Dynamic Default Patterns
+```typescript
+// Device-based default
+{
+  id: 'Comfy.Example.MobileDefault',
+  type: 'boolean',
+  defaultValue: () => /Mobile/i.test(navigator.userAgent)
+}
+
+// Environment-based default
+{
+  id: 'Comfy.Example.DevMode',
+  type: 'boolean',
+  defaultValue: () => import.meta.env.DEV
+}
+
+// Window size based
+{
+  id: 'Comfy.Example.CompactUI',
+  type: 'boolean',
+  defaultValue: () => window.innerWidth < 1024
+}
+```
+
+### Version-Based Rollout Pattern
+```typescript
+{
+  id: 'Comfy.Example.NewFeature',
+  type: 'combo',
+  options: ['legacy', 'enhanced'],
+  defaultValue: 'legacy',
+  defaultsByInstallVersion: {
+    '1.25.0': 'enhanced'
+  }
+}
+```
+
+## Settings Persistence and Access
+
+### API Interaction
+Values are stored per user via the backend. The store writes through API and falls back to defaults when not set:
+
+```typescript
+// From src/stores/settingStore.ts:73-75
+onChange(settingsById.value[key], newValue, oldValue)
+settingValues.value[key] = newValue
+await api.storeSetting(key, newValue)
+```
+
+### Usage in Components
+```typescript
+const settingStore = useSettingStore()
+
+// Get setting value (returns computed default if not set by user)
+const value = settingStore.get('Comfy.SomeSetting')
+
+// Update setting value
+await settingStore.set('Comfy.SomeSetting', newValue)
+```
+
+
+## Advanced Settings Features
+
+### Migration and Backward Compatibility
+
+Settings support migration from deprecated values:
+
+```typescript
+// From src/stores/settingStore.ts:68-69, 172-175
+const newValue = tryMigrateDeprecatedValue(
+  settingsById.value[key],
+  clonedValue
+)
+
+// Migration happens during addSetting for existing values:
+if (settingValues.value[setting.id] !== undefined) {
+  settingValues.value[setting.id] = tryMigrateDeprecatedValue(
+    setting,
+    settingValues.value[setting.id]
+  )
+}
+```
+
+### onChange Callbacks
+
+Settings can define onChange callbacks that receive the setting definition, new value, and old value:
+
+```typescript
+// From src/stores/settingStore.ts:73, 177
+onChange(settingsById.value[key], newValue, oldValue)  // During set()
+onChange(setting, get(setting.id), undefined)         // During addSetting()
+```
+
+### Settings UI and Categories
+
+Settings are automatically grouped for UI based on their `category` or derived from `id`:
+
+```typescript
+{
+  id: 'Comfy.Sidebar.Size',
+  category: ['Appearance', 'Sidebar', 'Size'],
+  // UI will group this under Appearance > Sidebar > Size
+}
+```
+
+## Related Documentation
+
+- Feature flag system: `docs/FEATURE_FLAGS.md`
+- Settings schema for backend: `src/schemas/apiSchema.ts` (zSettings)
+- Server configuration (separate from user settings): `src/constants/serverConfig.ts`
+
+## Summary
+
+- **Settings**: User preferences with dynamic/versioned defaults, persisted per user
+- **Environment Defaults**: Use function defaults to read runtime context (window, navigator, env)
+- **Version Rollouts**: Use `defaultsByInstallVersion` for gradual feature releases
+- **API Interaction**: Settings persist to `/settings` endpoint via `storeSetting()`
--- a/docs/SETTINGS_SEQUENCE_DIAGRAM.md
+++ b/docs/SETTINGS_SEQUENCE_DIAGRAM.md
@@ -0,0 +1,82 @@
+# Settings and Feature Flags Sequence Diagram
+
+This diagram shows the flow of settings initialization, default resolution, persistence, and feature flags exchange.
+
+This diagram accurately reflects the actual implementation in the ComfyUI frontend codebase.
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant Vue as Vue Component
+    participant Store as SettingStore (Pinia)
+    participant API as ComfyApi (WebSocket/REST)
+    participant Backend as Backend
+    participant NewUserSvc as NewUserService
+
+    Note over Vue,Store: App startup (GraphCanvas.vue)
+    Vue->>Store: loadSettingValues()
+    Store->>API: getSettings()
+    API->>Backend: GET /settings
+    Backend-->>API: settings map (per-user)
+    API-->>Store: settings map
+    Store-->>Vue: loaded
+
+    Vue->>Store: register CORE_SETTINGS (addSetting for each)
+    loop For each setting registration
+      Store->>Store: tryMigrateDeprecatedValue(existing value)
+      Store->>Store: onChange(setting, currentValue, undefined)
+    end
+
+    Note over Vue,NewUserSvc: New user detection
+    Vue->>NewUserSvc: initializeIfNewUser(settingStore)
+    NewUserSvc->>NewUserSvc: checkIsNewUser(settingStore)
+    alt New user detected
+      NewUserSvc->>Store: set("Comfy.InstalledVersion", __COMFYUI_FRONTEND_VERSION__)
+      Store->>Store: tryMigrateDeprecatedValue(newValue)
+      Store->>Store: onChange(setting, newValue, oldValue)
+      Store->>API: storeSetting(key, newValue)
+      API->>Backend: POST /settings/{id}
+    else Existing user
+      Note over NewUserSvc: Skip setting installed version
+    end
+
+    Note over Vue,Store: Component reads a setting
+    Vue->>Store: get(key)
+    Store->>Store: exists(key)?
+    alt User value exists
+      Store-->>Vue: return stored user value
+    else Not set by user
+      Store->>Store: getVersionedDefaultValue(key)
+      alt Versioned default matched (defaultsByInstallVersion)
+        Store-->>Vue: return versioned default
+      else No version match
+        Store->>Store: evaluate defaultValue (function or constant)
+        Note over Store: defaultValue can use window size,<br/>locale, env, etc.
+        Store-->>Vue: return computed default
+      end
+    end
+
+    Note over User,Store: User updates a setting
+    User->>Vue: changes setting in UI
+    Vue->>Store: set(key, newValue)
+    Store->>Store: tryMigrateDeprecatedValue(newValue)
+    Store->>Store: check if newValue === oldValue (early return if same)
+    Store->>Store: onChange(setting, newValue, oldValue)
+    Store->>Store: update settingValues[key]
+    Store->>API: storeSetting(key, newValue)
+    API->>Backend: POST /settings/{id}
+    Backend-->>API: 200 OK
+    API-->>Store: ack
+
+    Note over API,Backend: Feature Flags WebSocket Exchange
+    API->>Backend: WS connect
+    API->>Backend: send { type: "feature_flags", data: clientFeatureFlags.json }
+    Backend-->>API: WS send { type: "feature_flags", data: server flags }
+    API->>API: store serverFeatureFlags = data
+
+    Note over Vue,API: Feature flag consumption in UI/logic
+    Vue->>API: serverSupportsFeature(name)
+    API-->>Vue: boolean (true only if flag === true)
+    Vue->>API: getServerFeature(name, default)
+    API-->>Vue: value or default
+```
--- a/src/components/button/MoreButton.stories.ts
+++ b/src/components/button/MoreButton.stories.ts
@@ -24,22 +24,22 @@ export const Basic: Story = {
        <MoreButton>
          <template #default="{ close }">
            <IconTextButton
-              type="secondary"
+              type="transparent"
              label="Settings"
              @click="() => { close() }"
            >
              <template #icon>
-                <Download />
+                <Download :size="16" />
              </template>
            </IconTextButton>

            <IconTextButton
-              type="primary"
+              type="transparent"
              label="Profile"
              @click="() => { close() }"
            >
              <template #icon>
-                <ScrollText />
+                <ScrollText :size="16" />
              </template>
            </IconTextButton>
          </template>
--- a/src/components/input/MultiSelect.stories.ts
+++ b/src/components/input/MultiSelect.stories.ts
@@ -1,9 +1,23 @@
 import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import type { MultiSelectProps } from 'primevue/multiselect'
 import { ref } from 'vue'

 import MultiSelect from './MultiSelect.vue'

-const meta: Meta<typeof MultiSelect> = {
+// Combine our component props with PrimeVue MultiSelect props
+// Since we use v-bind="$attrs", all PrimeVue props are available
+interface ExtendedProps extends Partial<MultiSelectProps> {
+  // Our custom props
+  label?: string
+  showSearchBox?: boolean
+  showSelectedCount?: boolean
+  showClearButton?: boolean
+  searchPlaceholder?: string
+  // Override modelValue type to match our Option type
+  modelValue?: Array<{ name: string; value: string }>
+}
+
+const meta: Meta<ExtendedProps> = {
  title: 'Components/Input/MultiSelect',
  component: MultiSelect,
  tags: ['autodocs'],
@@ -13,7 +27,35 @@ const meta: Meta<typeof MultiSelect> = {
    },
    options: {
      control: 'object'
+    },
+    showSearchBox: {
+      control: 'boolean',
+      description: 'Toggle searchBar visibility'
+    },
+    showSelectedCount: {
+      control: 'boolean',
+      description: 'Toggle selected count visibility'
+    },
+    showClearButton: {
+      control: 'boolean',
+      description: 'Toggle clear button visibility'
+    },
+    searchPlaceholder: {
+      control: 'text'
    }
+  },
+  args: {
+    label: 'Select',
+    options: [
+      { name: 'Vue', value: 'vue' },
+      { name: 'React', value: 'react' },
+      { name: 'Angular', value: 'angular' },
+      { name: 'Svelte', value: 'svelte' }
+    ],
+    showSearchBox: false,
+    showSelectedCount: false,
+    showClearButton: false,
+    searchPlaceholder: 'Search...'
  }
 }

@@ -25,7 +67,7 @@ export const Default: Story = {
    components: { MultiSelect },
    setup() {
      const selected = ref([])
-      const options = [
+      const options = args.options || [
        { name: 'Vue', value: 'vue' },
        { name: 'React', value: 'react' },
        { name: 'Angular', value: 'angular' },
@@ -38,8 +80,11 @@ export const Default: Story = {
        <MultiSelect 
          v-model="selected" 
          :options="options"
-          label="Select Frameworks"
-          v-bind="args"
+          :label="args.label"
+          :showSearchBox="args.showSearchBox"
+          :showSelectedCount="args.showSelectedCount"
+          :showClearButton="args.showClearButton"
+          :searchPlaceholder="args.searchPlaceholder"
        />
        <div class="mt-4 p-3 bg-gray-50 dark-theme:bg-zinc-800 rounded">
          <p class="text-sm">Selected: {{ selected.length > 0 ? selected.map(s => s.name).join(', ') : 'None' }}</p>
@@ -50,10 +95,10 @@ export const Default: Story = {
 }

 export const WithPreselectedValues: Story = {
-  render: () => ({
+  render: (args) => ({
    components: { MultiSelect },
    setup() {
-      const options = [
+      const options = args.options || [
        { name: 'JavaScript', value: 'js' },
        { name: 'TypeScript', value: 'ts' },
        { name: 'Python', value: 'python' },
@@ -61,25 +106,43 @@ export const WithPreselectedValues: Story = {
        { name: 'Rust', value: 'rust' }
      ]
      const selected = ref([options[0], options[1]])
-      return { selected, options }
+      return { selected, options, args }
    },
    template: `
      <div>
        <MultiSelect 
          v-model="selected" 
          :options="options"
-          label="Select Languages"
+          :label="args.label"
+          :showSearchBox="args.showSearchBox"
+          :showSelectedCount="args.showSelectedCount"
+          :showClearButton="args.showClearButton"
+          :searchPlaceholder="args.searchPlaceholder"
        />
        <div class="mt-4 p-3 bg-gray-50 dark-theme:bg-zinc-800 rounded">
          <p class="text-sm">Selected: {{ selected.map(s => s.name).join(', ') }}</p>
        </div>
      </div>
    `
-  })
+  }),
+  args: {
+    label: 'Select Languages',
+    options: [
+      { name: 'JavaScript', value: 'js' },
+      { name: 'TypeScript', value: 'ts' },
+      { name: 'Python', value: 'python' },
+      { name: 'Go', value: 'go' },
+      { name: 'Rust', value: 'rust' }
+    ],
+    showSearchBox: false,
+    showSelectedCount: false,
+    showClearButton: false,
+    searchPlaceholder: 'Search...'
+  }
 }

 export const MultipleSelectors: Story = {
-  render: () => ({
+  render: (args) => ({
    components: { MultiSelect },
    setup() {
      const frameworkOptions = ref([
@@ -114,7 +177,8 @@ export const MultipleSelectors: Story = {
        tagOptions,
        selectedFrameworks,
        selectedProjects,
-        selectedTags
+        selectedTags,
+        args
      }
    },
    template: `
@@ -124,22 +188,34 @@ export const MultipleSelectors: Story = {
            v-model="selectedFrameworks" 
            :options="frameworkOptions"
            label="Select Frameworks"
+            :showSearchBox="args.showSearchBox"
+            :showSelectedCount="args.showSelectedCount"
+            :showClearButton="args.showClearButton"
+            :searchPlaceholder="args.searchPlaceholder"
          />
          <MultiSelect 
            v-model="selectedProjects" 
            :options="projectOptions"
            label="Select Projects"
+            :showSearchBox="args.showSearchBox"
+            :showSelectedCount="args.showSelectedCount"
+            :showClearButton="args.showClearButton"
+            :searchPlaceholder="args.searchPlaceholder"
          />
          <MultiSelect 
            v-model="selectedTags" 
            :options="tagOptions"
            label="Select Tags"
+            :showSearchBox="args.showSearchBox"
+            :showSelectedCount="args.showSelectedCount"
+            :showClearButton="args.showClearButton"
+            :searchPlaceholder="args.searchPlaceholder"
          />
        </div>
        
        <div class="p-4 bg-gray-50 dark-theme:bg-zinc-800 rounded">
-          <h4 class="font-medium mb-2">Current Selection:</h4>
-          <div class="space-y-1 text-sm">
+          <h4 class="font-medium mt-0">Current Selection:</h4>
+          <div class="flex flex-col text-sm">
            <p>Frameworks: {{ selectedFrameworks.length > 0 ? selectedFrameworks.map(s => s.name).join(', ') : 'None' }}</p>
            <p>Projects: {{ selectedProjects.length > 0 ? selectedProjects.map(s => s.name).join(', ') : 'None' }}</p>
            <p>Tags: {{ selectedTags.length > 0 ? selectedTags.map(s => s.name).join(', ') : 'None' }}</p>
@@ -147,5 +223,54 @@ export const MultipleSelectors: Story = {
        </div>
      </div>
    `
-  })
+  }),
+  args: {
+    showSearchBox: false,
+    showSelectedCount: false,
+    showClearButton: false,
+    searchPlaceholder: 'Search...'
+  }
+}
+
+export const WithSearchBox: Story = {
+  ...Default,
+  args: {
+    ...Default.args,
+    showSearchBox: true
+  }
+}
+
+export const WithSelectedCount: Story = {
+  ...Default,
+  args: {
+    ...Default.args,
+    showSelectedCount: true
+  }
+}
+
+export const WithClearButton: Story = {
+  ...Default,
+  args: {
+    ...Default.args,
+    showClearButton: true
+  }
+}
+
+export const AllHeaderFeatures: Story = {
+  ...Default,
+  args: {
+    ...Default.args,
+    showSearchBox: true,
+    showSelectedCount: true,
+    showClearButton: true
+  }
+}
+
+export const CustomSearchPlaceholder: Story = {
+  ...Default,
+  args: {
+    ...Default.args,
+    showSearchBox: true,
+    searchPlaceholder: 'Filter packages...'
+  }
 }
--- a/src/components/input/MultiSelect.vue
+++ b/src/components/input/MultiSelect.vue
@@ -1,93 +1,104 @@
 <template>
-  <div class="relative inline-block">
-    <MultiSelect
-      v-model="selectedItems"
-      :options="options"
-      option-label="name"
-      unstyled
-      :placeholder="label"
-      :max-selected-labels="0"
-      :pt="pt"
+  <!-- 
+    Note: Unlike SingleSelect, we don't need an explicit options prop because:
+    1. Our value template only shows a static label (not dynamic based on selection)
+    2. We display a count badge instead of actual selected labels
+    3. All PrimeVue props (including options) are passed via v-bind="$attrs"
+    
+    option-label="name" is required because our option template directly accesses option.name
+    max-selected-labels="0" is required to show count badge instead of selected item labels
+  -->
+  <MultiSelect
+    v-model="selectedItems"
+    v-bind="$attrs"
+    option-label="name"
+    unstyled
+    :max-selected-labels="0"
+    :pt="pt"
+  >
+    <template
+      v-if="showSearchBox || showSelectedCount || showClearButton"
+      #header
    >
-      <template
-        v-if="hasSearchBox || showSelectedCount || hasClearButton"
-        #header
-      >
-        <div class="p-2 flex flex-col gap-y-4 pb-0">
-          <SearchBox
-            v-if="hasSearchBox"
-            v-model="searchQuery"
-            :has-border="true"
-            :place-holder="searchPlaceholder"
-          />
-          <div class="flex items-center justify-between">
-            <span
-              v-if="showSelectedCount"
-              class="text-sm text-neutral-400 dark-theme:text-zinc-500 px-1"
-            >
-              {{
-                selectedCount > 0
-                  ? $t('g.itemsSelected', { selectedCount })
-                  : $t('g.itemSelected', { selectedCount })
-              }}
-            </span>
-            <TextButton
-              v-if="hasClearButton"
-              :label="$t('g.clearAll')"
-              type="transparent"
-              size="fit-content"
-              class="text-sm !text-blue-500 !dark-theme:text-blue-600"
-              @click.stop="selectedItems = []"
-            />
-          </div>
-          <div class="h-px bg-zinc-200 dark-theme:bg-zinc-700"></div>
-        </div>
-      </template>
-
-      <!-- Trigger value (keep text scale identical) -->
-      <template #value>
-        <span class="text-sm text-zinc-700 dark-theme:text-gray-200">
-          {{ label }}
-        </span>
-      </template>
-
-      <!-- Chevron size identical to current -->
-      <template #dropdownicon>
-        <i-lucide:chevron-down class="text-lg text-neutral-400" />
-      </template>
-
-      <!-- Custom option row: square checkbox + label (unchanged layout/colors) -->
-      <template #option="slotProps">
-        <div class="flex items-center gap-2">
-          <div
-            class="flex h-4 w-4 p-0.5 flex-shrink-0 items-center justify-center rounded border-[3px] transition-all duration-200"
-            :class="
-              slotProps.selected
-                ? 'border-blue-400 bg-blue-400 dark-theme:border-blue-500 dark-theme:bg-blue-500'
-                : 'border-neutral-300 dark-theme:border-zinc-600 bg-neutral-100 dark-theme:bg-zinc-700'
-            "
+      <div class="p-2 flex flex-col pb-0">
+        <SearchBox
+          v-if="showSearchBox"
+          v-model="searchQuery"
+          :class="showSelectedCount || showClearButton ? 'mb-2' : ''"
+          :show-order="true"
+          :place-holder="searchPlaceholder"
+        />
+        <div
+          v-if="showSelectedCount || showClearButton"
+          class="mt-2 flex items-center justify-between"
+        >
+          <span
+            v-if="showSelectedCount"
+            class="text-sm text-neutral-400 dark-theme:text-zinc-500 px-1"
          >
-            <i-lucide:check
-              v-if="slotProps.selected"
-              class="text-xs text-bold text-white"
-            />
-          </div>
-          <span>{{ slotProps.option.name }}</span>
+            {{
+              selectedCount > 0
+                ? $t('g.itemsSelected', { selectedCount })
+                : $t('g.itemSelected', { selectedCount })
+            }}
+          </span>
+          <TextButton
+            v-if="showClearButton"
+            :label="$t('g.clearAll')"
+            type="transparent"
+            size="fit-content"
+            class="text-sm !text-blue-500 !dark-theme:text-blue-600"
+            @click.stop="selectedItems = []"
+          />
        </div>
-      </template>
-    </MultiSelect>
+        <div class="mt-4 h-px bg-zinc-200 dark-theme:bg-zinc-700"></div>
+      </div>
+    </template>

-    <!-- Selected count badge -->
-    <div
-      v-if="selectedCount > 0"
-      class="pointer-events-none absolute -right-2 -top-2 z-10 flex h-5 w-5 items-center justify-center rounded-full bg-blue-400 dark-theme:bg-blue-500 text-xs font-semibold text-white"
-    >
-      {{ selectedCount }}
-    </div>
-  </div>
+    <!-- Trigger value (keep text scale identical) -->
+    <template #value>
+      <span class="text-sm text-zinc-700 dark-theme:text-gray-200">
+        {{ label }}
+      </span>
+      <span
+        v-if="selectedCount > 0"
+        class="pointer-events-none absolute -right-2 -top-2 z-10 flex h-5 w-5 items-center justify-center rounded-full bg-blue-400 dark-theme:bg-blue-500 text-xs font-semibold text-white"
+      >
+        {{ selectedCount }}
+      </span>
+    </template>
+
+    <!-- Chevron size identical to current -->
+    <template #dropdownicon>
+      <i-lucide:chevron-down class="text-lg text-neutral-400" />
+    </template>
+
+    <!-- Custom option row: square checkbox + label (unchanged layout/colors) -->
+    <template #option="slotProps">
+      <div class="flex items-center gap-2">
+        <div
+          class="flex h-4 w-4 p-0.5 flex-shrink-0 items-center justify-center rounded transition-all duration-200"
+          :class="
+            slotProps.selected
+              ? 'border-[3px] border-blue-400 bg-blue-400 dark-theme:border-blue-500 dark-theme:bg-blue-500'
+              : 'border-[1px] border-neutral-300 dark-theme:border-zinc-600 bg-neutral-100 dark-theme:bg-zinc-700'
+          "
+        >
+          <i-lucide:check
+            v-if="slotProps.selected"
+            class="text-xs text-bold text-white"
+          />
+        </div>
+        <Button class="border-none outline-none bg-transparent" unstyled>{{
+          slotProps.option.name
+        }}</Button>
+      </div>
+    </template>
+  </MultiSelect>
 </template>

 <script setup lang="ts">
+import Button from 'primevue/button'
 import MultiSelect, {
  MultiSelectPassThroughMethodOptions
 } from 'primevue/multiselect'
@@ -99,26 +110,29 @@ import TextButton from '../button/TextButton.vue'

 type Option = { name: string; value: string }

+defineOptions({
+  inheritAttrs: false
+})
+
 interface Props {
  /** Input label shown on the trigger button */
  label?: string
-  /** Static options for the multiselect (when not using async search) */
-  options: Option[]
  /** Show search box in the panel header */
-  hasSearchBox?: boolean
+  showSearchBox?: boolean
  /** Show selected count text in the panel header */
  showSelectedCount?: boolean
  /** Show "Clear all" action in the panel header */
-  hasClearButton?: boolean
+  showClearButton?: boolean
  /** Placeholder for the search input */
  searchPlaceholder?: string
+  // Note: options prop is intentionally omitted.
+  // It's passed via $attrs to maximize PrimeVue API compatibility
 }
 const {
  label,
-  options,
-  hasSearchBox = false,
+  showSearchBox = false,
  showSelectedCount = false,
-  hasClearButton = false,
+  showClearButton = false,
  searchPlaceholder = 'Search...'
 } = defineProps<Props>()

@@ -131,7 +145,7 @@ const selectedCount = computed(() => selectedItems.value.length)
 const pt = computed(() => ({
  root: ({ props }: MultiSelectPassThroughMethodOptions) => ({
    class: [
-      'relative inline-flex cursor-pointer select-none w-full',
+      'relative inline-flex cursor-pointer select-none',
      'rounded-lg bg-white dark-theme:bg-zinc-800 text-neutral dark-theme:text-white',
      'transition-all duration-200 ease-in-out',
      'border-[2.5px] border-solid',
@@ -153,7 +167,7 @@ const pt = computed(() => ({
  },
  header: () => ({
    class:
-      hasSearchBox || showSelectedCount || hasClearButton ? 'block' : 'hidden'
+      showSearchBox || showSelectedCount || showClearButton ? 'block' : 'hidden'
  }),
  // Overlay & list visuals unchanged
  overlay:
@@ -161,9 +175,17 @@ const pt = computed(() => ({
  list: {
    class: 'flex flex-col gap-1 p-0 list-none border-none text-xs'
  },
-  // Option row hover tone identical
-  option:
-    'flex gap-1 items-center p-2 hover:bg-neutral-100/50 dark-theme:hover:bg-zinc-700/50',
+  // Option row hover and focus tone
+  option: ({ context }: MultiSelectPassThroughMethodOptions) => ({
+    class: [
+      'flex gap-1 items-center p-2',
+      'hover:bg-neutral-100/50 dark-theme:hover:bg-zinc-700/50',
+      // Add focus/highlight state for keyboard navigation
+      {
+        'bg-neutral-100/50 dark-theme:bg-zinc-700/50': context?.focused
+      }
+    ]
+  }),
  // Hide built-in checkboxes entirely via PT (no :deep)
  pcHeaderCheckbox: {
    root: { class: 'hidden' },
--- a/src/components/input/SearchBox.stories.ts
+++ b/src/components/input/SearchBox.stories.ts
@@ -10,7 +10,15 @@ const meta: Meta<typeof SearchBox> = {
  argTypes: {
    placeHolder: {
      control: 'text'
+    },
+    showBorder: {
+      control: 'boolean',
+      description: 'Toggle border prop'
    }
+  },
+  args: {
+    placeHolder: 'Search...',
+    showBorder: false
  }
 }

@@ -25,9 +33,23 @@ export const Default: Story = {
      return { searchText, args }
    },
    template: `
-      <div>
-        <SearchBox v-model:="searchQuery" />
+      <div style="max-width: 320px;">
+        <SearchBox v-bind="args" v-model="searchText" />
      </div>
    `
  })
 }
+
+export const WithBorder: Story = {
+  ...Default,
+  args: {
+    showBorder: true
+  }
+}
+
+export const NoBorder: Story = {
+  ...Default,
+  args: {
+    showBorder: false
+  }
+}
--- a/src/components/input/SearchBox.vue
+++ b/src/components/input/SearchBox.vue
@@ -15,19 +15,20 @@
 import InputText from 'primevue/inputtext'
 import { computed } from 'vue'

-const { placeHolder, hasBorder = false } = defineProps<{
+const { placeHolder, showBorder = false } = defineProps<{
  placeHolder?: string
-  hasBorder?: boolean
+  showBorder?: boolean
 }>()
-const searchQuery = defineModel<string>('')
+// defineModel without arguments uses 'modelValue' as the prop name
+const searchQuery = defineModel<string>()

 const wrapperStyle = computed(() => {
-  return hasBorder
+  return showBorder
    ? 'flex w-full items-center rounded gap-2 bg-white dark-theme:bg-zinc-800 p-1 border border-solid border-zinc-200 dark-theme:border-zinc-700'
    : 'flex w-full items-center rounded px-2 py-1.5 gap-2 bg-white dark-theme:bg-zinc-800'
 })

 const iconColorStyle = computed(() => {
-  return !hasBorder ? 'text-neutral' : 'text-zinc-300 dark-theme:text-zinc-700'
+  return !showBorder ? 'text-neutral' : 'text-zinc-300 dark-theme:text-zinc-700'
 })
 </script>
--- a/src/components/input/SingleSelect.stories.ts
+++ b/src/components/input/SingleSelect.stories.ts
@@ -4,12 +4,24 @@ import { ref } from 'vue'

 import SingleSelect from './SingleSelect.vue'

+// SingleSelect already includes options prop, so no need to extend
 const meta: Meta<typeof SingleSelect> = {
  title: 'Components/Input/SingleSelect',
  component: SingleSelect,
  tags: ['autodocs'],
  argTypes: {
-    label: { control: 'text' }
+    label: { control: 'text' },
+    options: { control: 'object' }
+  },
+  args: {
+    label: 'Sorting Type',
+    options: [
+      { name: 'Popular', value: 'popular' },
+      { name: 'Newest', value: 'newest' },
+      { name: 'Oldest', value: 'oldest' },
+      { name: 'A → Z', value: 'az' },
+      { name: 'Z → A', value: 'za' }
+    ]
  }
 }

@@ -29,19 +41,18 @@ export const Default: Story = {
    components: { SingleSelect },
    setup() {
      const selected = ref<string | null>(null)
-      const options = sampleOptions
+      const options = args.options || sampleOptions
      return { selected, options, args }
    },
    template: `
      <div>
-        <SingleSelect v-model="selected" :options="options" :label="args.label || 'Sorting Type'" />
+        <SingleSelect v-model="selected" :options="options" :label="args.label" />
        <div class="mt-4 p-3 bg-gray-50 dark-theme:bg-zinc-800 rounded">
          <p class="text-sm">Selected: {{ selected ?? 'None' }}</p>
        </div>
      </div>
    `
-  }),
-  args: { label: 'Sorting Type' }
+  })
 }

 export const WithIcon: Story = {
--- a/src/components/input/SingleSelect.vue
+++ b/src/components/input/SingleSelect.vue
@@ -1,58 +1,73 @@
 <template>
-  <div class="relative inline-flex items-center">
-    <Select
-      v-model="selectedItem"
-      :options="options"
-      option-label="name"
-      option-value="value"
-      unstyled
-      :placeholder="label"
-      :pt="pt"
-    >
-      <!-- Trigger value -->
-      <template #value="slotProps">
-        <div class="flex items-center gap-2 text-sm">
-          <slot name="icon" />
-          <span
-            v-if="slotProps.value !== null && slotProps.value !== undefined"
-            class="text-zinc-700 dark-theme:text-gray-200"
-          >
-            {{ getLabel(slotProps.value) }}
-          </span>
-          <span v-else class="text-zinc-700 dark-theme:text-gray-200">
-            {{ label }}
-          </span>
-        </div>
-      </template>
+  <!-- 
+    Note: We explicitly pass options here (not just via $attrs) because:
+    1. Our custom value template needs options to look up labels from values
+    2. PrimeVue's value slot only provides 'value' and 'placeholder', not the selected item's label
+    3. We need to maintain the icon slot functionality in the value template
+    
+    option-label="name" is required because our option template directly accesses option.name
+  -->
+  <Select
+    v-model="selectedItem"
+    v-bind="$attrs"
+    :options="options"
+    option-label="name"
+    option-value="value"
+    unstyled
+    :pt="pt"
+  >
+    <!-- Trigger value -->
+    <template #value="slotProps">
+      <div class="flex items-center gap-2 text-sm">
+        <slot name="icon" />
+        <span
+          v-if="slotProps.value !== null && slotProps.value !== undefined"
+          class="text-zinc-700 dark-theme:text-gray-200"
+        >
+          {{ getLabel(slotProps.value) }}
+        </span>
+        <span v-else class="text-zinc-700 dark-theme:text-gray-200">
+          {{ label }}
+        </span>
+      </div>
+    </template>

-      <!-- Trigger caret -->
-      <template #dropdownicon>
-        <i-lucide:chevron-down
-          class="text-base text-neutral-400 dark-theme:text-gray-300"
+    <!-- Trigger caret -->
+    <template #dropdownicon>
+      <i-lucide:chevron-down
+        class="text-base text-neutral-400 dark-theme:text-gray-300"
+      />
+    </template>
+
+    <!-- Option row -->
+    <template #option="{ option, selected }">
+      <div class="flex items-center justify-between gap-3 w-full">
+        <span class="truncate">{{ option.name }}</span>
+        <i-lucide:check
+          v-if="selected"
+          class="text-neutral-900 dark-theme:text-white"
        />
-      </template>
-
-      <!-- Option row -->
-      <template #option="{ option, selected }">
-        <div class="flex items-center justify-between gap-3 w-full">
-          <span class="truncate">{{ option.name }}</span>
-          <i-lucide:check
-            v-if="selected"
-            class="text-neutral-900 dark-theme:text-white"
-          />
-        </div>
-      </template>
-    </Select>
-  </div>
+      </div>
+    </template>
+  </Select>
 </template>

 <script setup lang="ts">
 import Select, { SelectPassThroughMethodOptions } from 'primevue/select'
 import { computed } from 'vue'

+defineOptions({
+  inheritAttrs: false
+})
+
 const { label, options } = defineProps<{
  label?: string
-  options: {
+  /**
+   * Required for displaying the selected item's label.
+   * Cannot rely on $attrs alone because we need to access options
+   * in getLabel() to map values to their display names.
+   */
+  options?: {
    name: string
    value: string
  }[]
@@ -60,8 +75,14 @@ const { label, options } = defineProps<{

 const selectedItem = defineModel<string | null>({ required: true })

+/**
+ * Maps a value to its display label.
+ * Necessary because PrimeVue's value slot doesn't provide the selected item's label,
+ * only the raw value. We need this to show the correct text when an item is selected.
+ */
 const getLabel = (val: string | null | undefined) => {
  if (val == null) return label ?? ''
+  if (!options) return label ?? ''
  const found = options.find((o) => o.value === val)
  return found ? found.name : label ?? ''
 }
@@ -77,7 +98,7 @@ const pt = computed(() => ({
  }: SelectPassThroughMethodOptions<{ name: string; value: string }>) => ({
    class: [
      // container
-      'relative inline-flex w-full cursor-pointer select-none items-center',
+      'relative inline-flex cursor-pointer select-none items-center',
      // trigger surface
      'rounded-md',
      'bg-transparent text-neutral dark-theme:text-white',
@@ -115,7 +136,9 @@ const pt = computed(() => ({
      'flex items-center justify-between gap-3 px-3 py-2',
      'hover:bg-neutral-100/50 dark-theme:hover:bg-zinc-700/50',
      // Selected state + check icon
-      { 'bg-neutral-100/50 dark-theme:bg-zinc-700/50': context.selected }
+      { 'bg-neutral-100/50 dark-theme:bg-zinc-700/50': context.selected },
+      // Add focus state for keyboard navigation
+      { 'bg-neutral-100/50 dark-theme:bg-zinc-700/50': context.focused }
    ]
  }),
  optionLabel: {
--- a/src/components/widget/SampleModelSelector.vue
+++ b/src/components/widget/SampleModelSelector.vue
@@ -12,7 +12,7 @@
    </template>

    <template #header>
-      <SearchBox v-model:="searchQuery" class="max-w-[384px]" />
+      <SearchBox v-model="searchQuery" class="max-w-[384px]" />
    </template>

    <template #header-right-area>
@@ -59,12 +59,13 @@
      <div class="relative px-6 pt-2 pb-4 flex gap-2">
        <MultiSelect
          v-model="selectedFrameworks"
+          v-model:search-query="searchText"
          class="w-[250px]"
-          :has-search-box="true"
-          :show-selected-count="true"
-          :has-clear-button="true"
          label="Select Frameworks"
          :options="frameworkOptions"
+          :show-search-box="true"
+          :show-selected-count="true"
+          :show-clear-button="true"
        />
        <MultiSelect
          v-model="selectedProjects"
@@ -135,7 +136,7 @@
 </template>

 <script setup lang="ts">
-import { provide, ref } from 'vue'
+import { provide, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'

 import IconButton from '@/components/button/IconButton.vue'
@@ -201,9 +202,18 @@ const { onClose } = defineProps<{
 provide(OnCloseKey, onClose)

 const searchQuery = ref<string>('')
+const searchText = ref<string>('')
 const selectedFrameworks = ref([])
 const selectedProjects = ref([])
 const selectedSort = ref<string>('popular')

 const selectedNavItem = ref<string | null>('installed')
+
+watch(searchText, (newQuery) => {
+  console.log('searchText:', searchText.value, newQuery)
+})
+
+watch(searchQuery, (newQuery) => {
+  console.log('searchQuery:', searchQuery.value, newQuery)
+})
 </script>
--- a/src/components/widget/layout/BaseWidget.stories.ts
+++ b/src/components/widget/layout/BaseWidget.stories.ts
@@ -240,6 +240,9 @@ const createStoryTemplate = (args: StoryArgs) => ({
              v-model="selectedFrameworks"
              label="Select Frameworks"
              :options="frameworkOptions"
+              :has-search-box="true"
+              :show-selected-count="true"
+              :has-clear-button="true"
            />
            <MultiSelect
              v-model="selectedProjects"
--- a/src/composables/node/useNodePricing.ts
+++ b/src/composables/node/useNodePricing.ts
@@ -1,4 +1,4 @@
-import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { INodeInputSlot, LGraphNode } from '@/lib/litegraph/src/litegraph'
 import type { IComboWidget } from '@/lib/litegraph/src/types/widgets'

 /**
@@ -179,6 +179,12 @@ const apiNodeCosts: Record<string, { displayPrice: string | PricingFunction }> =
        const numImagesWidget = node.widgets?.find(
          (w) => w.name === 'num_images'
        ) as IComboWidget
+        const characterInput = node.inputs?.find(
+          (i) => i.name === 'character_image'
+        ) as INodeInputSlot
+        const hasCharacter =
+          typeof characterInput?.link !== 'undefined' &&
+          characterInput.link != null

        if (!renderingSpeedWidget)
          return '$0.03-0.08 x num_images/Run (varies with rendering speed & num_images)'
@@ -188,11 +194,23 @@ const apiNodeCosts: Record<string, { displayPrice: string | PricingFunction }> =

        const renderingSpeed = String(renderingSpeedWidget.value)
        if (renderingSpeed.toLowerCase().includes('quality')) {
-          basePrice = 0.09
-        } else if (renderingSpeed.toLowerCase().includes('balanced')) {
-          basePrice = 0.06
+          if (hasCharacter) {
+            basePrice = 0.2
+          } else {
+            basePrice = 0.09
+          }
+        } else if (renderingSpeed.toLowerCase().includes('default')) {
+          if (hasCharacter) {
+            basePrice = 0.15
+          } else {
+            basePrice = 0.06
+          }
        } else if (renderingSpeed.toLowerCase().includes('turbo')) {
-          basePrice = 0.03
+          if (hasCharacter) {
+            basePrice = 0.1
+          } else {
+            basePrice = 0.03
+          }
        }

        const totalCost = (basePrice * numImages).toFixed(2)
@@ -395,7 +413,12 @@ const apiNodeCosts: Record<string, { displayPrice: string | PricingFunction }> =
        const modeValue = String(modeWidget.value)

        // Same pricing matrix as KlingTextToVideoNode
-        if (modeValue.includes('v2-master')) {
+        if (modeValue.includes('v2-1')) {
+          if (modeValue.includes('10s')) {
+            return '$0.98/Run' // pro, 10s
+          }
+          return '$0.49/Run' // pro, 5s default
+        } else if (modeValue.includes('v2-master')) {
          if (modeValue.includes('10s')) {
            return '$2.80/Run'
          }
@@ -1462,7 +1485,7 @@ export const useNodePricing = () => {
      OpenAIGPTImage1: ['quality', 'n'],
      IdeogramV1: ['num_images', 'turbo'],
      IdeogramV2: ['num_images', 'turbo'],
-      IdeogramV3: ['rendering_speed', 'num_images'],
+      IdeogramV3: ['rendering_speed', 'num_images', 'character_image'],
      FluxProKontextProNode: [],
      FluxProKontextMaxNode: [],
      VeoVideoGenerationNode: ['duration_seconds'],
--- a/src/composables/node/useWatchWidget.ts
+++ b/src/composables/node/useWatchWidget.ts
@@ -75,6 +75,29 @@ export const useComputedWithWidgetWatch = (
        }
      })
    })
+    if (widgetNames && widgetNames.length > widgetsToObserve.length) {
+      //Inputs have been included
+      const indexesToObserve = widgetNames
+        .map((name) =>
+          widgetsToObserve.some((w) => w.name == name)
+            ? -1
+            : node.inputs.findIndex((i) => i.name == name)
+        )
+        .filter((i) => i >= 0)
+      node.onConnectionsChange = useChainCallback(
+        node.onConnectionsChange,
+        (_type: unknown, index: number, isConnected: boolean) => {
+          if (!indexesToObserve.includes(index)) return
+          widgetValues.value = {
+            ...widgetValues.value,
+            [indexesToObserve[index]]: isConnected
+          }
+          if (triggerCanvasRedraw) {
+            node.graph?.setDirtyCanvas(true, true)
+          }
+        }
+      )
+    }
  }

  // Returns a function that creates a computed that responds to widget changes.
--- a/src/composables/useModelSelectorDialog.ts
+++ b/src/composables/useModelSelectorDialog.ts
@@ -1,4 +1,4 @@
-import ModelSelector from '@/components/widget/ModelSelector.vue'
+import SampleModelSelector from '@/components/widget/SampleModelSelector.vue'
 import { useDialogService } from '@/services/dialogService'
 import { useDialogStore } from '@/stores/dialogStore'

@@ -15,7 +15,7 @@ export const useModelSelectorDialog = () => {
  function show() {
    dialogService.showLayoutDialog({
      key: DIALOG_KEY,
-      component: ModelSelector,
+      component: SampleModelSelector,
      props: {
        onClose: hide
      }
--- a/src/extensions/core/maskeditor.ts
+++ b/src/extensions/core/maskeditor.ts
@@ -1,3 +1,4 @@
+import QuickLRU from '@alloc/quick-lru'
 import { debounce } from 'es-toolkit/compat'
 import _ from 'es-toolkit/compat'

@@ -9,6 +10,7 @@ import { ComfyApp } from '../../scripts/app'
 import { $el, ComfyDialog } from '../../scripts/ui'
 import { getStorageValue, setStorageValue } from '../../scripts/utils'
 import { hexToRgb } from '../../utils/colorUtil'
+import { parseToRgb } from '../../utils/colorUtil'
 import { ClipspaceDialog } from './clipspace'
 import {
  imageLayerFilenamesByTimestamp,
@@ -811,7 +813,7 @@ interface Offset {
  y: number
 }

-export interface Brush {
+interface Brush {
  type: BrushShape
  size: number
  opacity: number
@@ -2049,9 +2051,16 @@ class BrushTool {
  rgbCtx: CanvasRenderingContext2D | null = null
  initialDraw: boolean = true

+  private static brushTextureCache = new QuickLRU<string, HTMLCanvasElement>({
+    maxSize: 8 // Reasonable limit for brush texture variations?
+  })
+
  brushStrokeCanvas: HTMLCanvasElement | null = null
  brushStrokeCtx: CanvasRenderingContext2D | null = null

+  private static readonly SMOOTHING_MAX_STEPS = 30
+  private static readonly SMOOTHING_MIN_STEPS = 2
+
  //brush adjustment
  isBrushAdjusting: boolean = false
  brushPreviewGradient: HTMLElement | null = null
@@ -2254,6 +2263,10 @@ class BrushTool {
    }
  }

+  private clampSmoothingPrecision(value: number): number {
+    return Math.min(Math.max(value, 1), 100)
+  }
+
  private drawWithBetterSmoothing(point: Point) {
    // Add current point to the smoothing array
    if (!this.smoothingCordsArray) {
@@ -2285,9 +2298,21 @@ class BrushTool {
      totalLength += Math.sqrt(dx * dx + dy * dy)
    }

-    const distanceBetweenPoints =
-      (this.brushSettings.size / this.brushSettings.smoothingPrecision) * 6
-    const stepNr = Math.ceil(totalLength / distanceBetweenPoints)
+    const maxSteps = BrushTool.SMOOTHING_MAX_STEPS
+    const minSteps = BrushTool.SMOOTHING_MIN_STEPS
+
+    const smoothing = this.clampSmoothingPrecision(
+      this.brushSettings.smoothingPrecision
+    )
+    const normalizedSmoothing = (smoothing - 1) / 99 // Convert to 0-1 range
+
+    // Optionality to use exponential curve
+    const stepNr = Math.round(
+      Math.round(minSteps + (maxSteps - minSteps) * normalizedSmoothing)
+    )
+
+    // Calculate step distance capped by brush size
+    const distanceBetweenPoints = totalLength / stepNr

    let interpolatedPoints = points

@@ -2435,101 +2460,205 @@ class BrushTool {
    const hardness = brushSettings.hardness
    const x = point.x
    const y = point.y
-    // Extend the gradient radius beyond the brush size
-    const extendedSize = size * (2 - hardness)

+    const brushRadius = size
    const isErasing = maskCtx.globalCompositeOperation === 'destination-out'
    const currentTool = await this.messageBroker.pull('currentTool')

-    // handle paint pen
+    // Helper function to get or create cached brush texture
+    const getCachedBrushTexture = (
+      radius: number,
+      hardness: number,
+      color: string,
+      opacity: number
+    ): HTMLCanvasElement => {
+      const cacheKey = `${radius}_${hardness}_${color}_${opacity}`
+
+      if (BrushTool.brushTextureCache.has(cacheKey)) {
+        return BrushTool.brushTextureCache.get(cacheKey)!
+      }
+
+      const tempCanvas = document.createElement('canvas')
+      const tempCtx = tempCanvas.getContext('2d')!
+      const size = radius * 2
+      tempCanvas.width = size
+      tempCanvas.height = size
+
+      const centerX = size / 2
+      const centerY = size / 2
+      const hardRadius = radius * hardness
+
+      const imageData = tempCtx.createImageData(size, size)
+      const data = imageData.data
+      const { r, g, b } = parseToRgb(color)
+
+      // Pre-calculate values to avoid repeated computations
+      const fadeRange = radius - hardRadius
+
+      for (let y = 0; y < size; y++) {
+        const dy = y - centerY
+        for (let x = 0; x < size; x++) {
+          const dx = x - centerX
+          const index = (y * size + x) * 4
+
+          // Calculate square distance (Chebyshev distance)
+          const distFromEdge = Math.max(Math.abs(dx), Math.abs(dy))
+
+          let pixelOpacity = 0
+          if (distFromEdge <= hardRadius) {
+            pixelOpacity = opacity
+          } else if (distFromEdge <= radius) {
+            const fadeProgress = (distFromEdge - hardRadius) / fadeRange
+            pixelOpacity = opacity * (1 - fadeProgress)
+          }
+
+          data[index] = r
+          data[index + 1] = g
+          data[index + 2] = b
+          data[index + 3] = pixelOpacity * 255
+        }
+      }
+
+      tempCtx.putImageData(imageData, 0, 0)
+
+      // Cache the texture
+      BrushTool.brushTextureCache.set(cacheKey, tempCanvas)
+
+      return tempCanvas
+    }
+
+    // RGB brush logic
    if (
      this.activeLayer === 'rgb' &&
      (currentTool === Tools.Eraser || currentTool === Tools.PaintPen)
    ) {
      const rgbaColor = this.formatRgba(this.rgbColor, opacity)
-      let gradient = rgbCtx.createRadialGradient(x, y, 0, x, y, extendedSize)
-      if (hardness === 1) {
-        gradient.addColorStop(0, rgbaColor)
-        gradient.addColorStop(
-          1,
-          this.formatRgba(this.rgbColor, brushSettingsSliderOpacity)
+
+      if (brushType === BrushShape.Rect && hardness < 1) {
+        const brushTexture = getCachedBrushTexture(
+          brushRadius,
+          hardness,
+          rgbaColor,
+          opacity
        )
-      } else {
-        gradient.addColorStop(0, rgbaColor)
-        gradient.addColorStop(hardness, rgbaColor)
-        gradient.addColorStop(1, this.formatRgba(this.rgbColor, 0))
+        rgbCtx.drawImage(brushTexture, x - brushRadius, y - brushRadius)
+        return
      }
+
+      // For max hardness, use solid fill to avoid anti-aliasing
+      if (hardness === 1) {
+        rgbCtx.fillStyle = rgbaColor
+        rgbCtx.beginPath()
+        if (brushType === BrushShape.Rect) {
+          rgbCtx.rect(
+            x - brushRadius,
+            y - brushRadius,
+            brushRadius * 2,
+            brushRadius * 2
+          )
+        } else {
+          rgbCtx.arc(x, y, brushRadius, 0, Math.PI * 2, false)
+        }
+        rgbCtx.fill()
+        return
+      }
+
+      // For soft brushes, use gradient
+      let gradient = rgbCtx.createRadialGradient(x, y, 0, x, y, brushRadius)
+      gradient.addColorStop(0, rgbaColor)
+      gradient.addColorStop(
+        hardness,
+        this.formatRgba(this.rgbColor, opacity * 0.5)
+      )
+      gradient.addColorStop(1, this.formatRgba(this.rgbColor, 0))
+
      rgbCtx.fillStyle = gradient
      rgbCtx.beginPath()
      if (brushType === BrushShape.Rect) {
        rgbCtx.rect(
-          x - extendedSize,
-          y - extendedSize,
-          extendedSize * 2,
-          extendedSize * 2
+          x - brushRadius,
+          y - brushRadius,
+          brushRadius * 2,
+          brushRadius * 2
        )
      } else {
-        rgbCtx.arc(x, y, extendedSize, 0, Math.PI * 2, false)
+        rgbCtx.arc(x, y, brushRadius, 0, Math.PI * 2, false)
      }
      rgbCtx.fill()
      return
    }

-    let gradient = maskCtx.createRadialGradient(x, y, 0, x, y, extendedSize)
+    // Mask brush logic
+    if (brushType === BrushShape.Rect && hardness < 1) {
+      const baseColor = isErasing
+        ? `rgba(255, 255, 255, ${opacity})`
+        : `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity})`
+
+      const brushTexture = getCachedBrushTexture(
+        brushRadius,
+        hardness,
+        baseColor,
+        opacity
+      )
+      maskCtx.drawImage(brushTexture, x - brushRadius, y - brushRadius)
+      return
+    }
+
+    // For max hardness, use solid fill to avoid anti-aliasing
    if (hardness === 1) {
+      const solidColor = isErasing
+        ? `rgba(255, 255, 255, ${opacity})`
+        : `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity})`
+
+      maskCtx.fillStyle = solidColor
+      maskCtx.beginPath()
+      if (brushType === BrushShape.Rect) {
+        maskCtx.rect(
+          x - brushRadius,
+          y - brushRadius,
+          brushRadius * 2,
+          brushRadius * 2
+        )
+      } else {
+        maskCtx.arc(x, y, brushRadius, 0, Math.PI * 2, false)
+      }
+      maskCtx.fill()
+      return
+    }
+
+    // For soft brushes, use gradient
+    let gradient = maskCtx.createRadialGradient(x, y, 0, x, y, brushRadius)
+
+    if (isErasing) {
+      gradient.addColorStop(0, `rgba(255, 255, 255, ${opacity})`)
+      gradient.addColorStop(hardness, `rgba(255, 255, 255, ${opacity * 0.5})`)
+      gradient.addColorStop(1, `rgba(255, 255, 255, 0)`)
+    } else {
      gradient.addColorStop(
        0,
-        isErasing
-          ? `rgba(255, 255, 255, ${opacity})`
-          : `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity})`
+        `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity})`
+      )
+      gradient.addColorStop(
+        hardness,
+        `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity * 0.5})`
      )
      gradient.addColorStop(
        1,
-        isErasing
-          ? `rgba(255, 255, 255, ${opacity})`
-          : `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity})`
+        `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, 0)`
      )
-    } else {
-      let softness = 1 - hardness
-      let innerStop = Math.max(0, hardness - softness)
-      let outerStop = size / extendedSize
-
-      if (isErasing) {
-        gradient.addColorStop(0, `rgba(255, 255, 255, ${opacity})`)
-        gradient.addColorStop(innerStop, `rgba(255, 255, 255, ${opacity})`)
-        gradient.addColorStop(outerStop, `rgba(255, 255, 255, ${opacity / 2})`)
-        gradient.addColorStop(1, `rgba(255, 255, 255, 0)`)
-      } else {
-        gradient.addColorStop(
-          0,
-          `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity})`
-        )
-        gradient.addColorStop(
-          innerStop,
-          `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity})`
-        )
-        gradient.addColorStop(
-          outerStop,
-          `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, ${opacity / 2})`
-        )
-        gradient.addColorStop(
-          1,
-          `rgba(${maskColor.r}, ${maskColor.g}, ${maskColor.b}, 0)`
-        )
-      }
    }

    maskCtx.fillStyle = gradient
    maskCtx.beginPath()
    if (brushType === BrushShape.Rect) {
      maskCtx.rect(
-        x - extendedSize,
-        y - extendedSize,
-        extendedSize * 2,
-        extendedSize * 2
+        x - brushRadius,
+        y - brushRadius,
+        brushRadius * 2,
+        brushRadius * 2
      )
    } else {
-      maskCtx.arc(x, y, extendedSize, 0, Math.PI * 2, false)
+      maskCtx.arc(x, y, brushRadius, 0, Math.PI * 2, false)
    }
    maskCtx.fill()
  }
@@ -4185,30 +4314,35 @@ class UIManager {
    const centerY = cursorPoint.y + pan_offset.y
    const brush = this.brush
    const hardness = brushSettings.hardness
-    const extendedSize = brushSettings.size * (2 - hardness) * 2 * zoom_ratio
+
+    // Now that brush size is constant, preview is simple
+    const brushRadius = brushSettings.size * zoom_ratio
+    const previewSize = brushRadius * 2

    this.brushSizeSlider.value = String(brushSettings.size)
    this.brushHardnessSlider.value = String(hardness)

-    brush.style.width = extendedSize + 'px'
-    brush.style.height = extendedSize + 'px'
-    brush.style.left = centerX - extendedSize / 2 + 'px'
-    brush.style.top = centerY - extendedSize / 2 + 'px'
+    brush.style.width = previewSize + 'px'
+    brush.style.height = previewSize + 'px'
+    brush.style.left = centerX - brushRadius + 'px'
+    brush.style.top = centerY - brushRadius + 'px'

    if (hardness === 1) {
      this.brushPreviewGradient.style.background = 'rgba(255, 0, 0, 0.5)'
      return
    }

-    const opacityStop = hardness / 4 + 0.25
+    // Simplified gradient - hardness controls where the fade starts
+    const midStop = hardness * 100
+    const outerStop = 100

    this.brushPreviewGradient.style.background = `
-        radial-gradient(
-            circle,
-            rgba(255, 0, 0, 0.5) 0%,
-            rgba(255, 0, 0, ${opacityStop}) ${hardness * 100}%,
-            rgba(255, 0, 0, 0) 100%
-        )
+      radial-gradient(
+        circle,
+        rgba(255, 0, 0, 0.5) 0%,
+        rgba(255, 0, 0, 0.25) ${midStop}%,
+        rgba(255, 0, 0, 0) ${outerStop}%
+      )
    `
  }

--- a/src/services/README.md
+++ b/src/services/README.md
@@ -12,7 +12,7 @@ This directory contains the service layer for the ComfyUI frontend application.

 ## Overview

-Services in ComfyUI provide organized modules that implement the application's functionality and logic. They handle operations such as API communication, workflow management, user settings, and other essential features. 
+Services in ComfyUI provide organized modules that implement the application's functionality and logic. They handle operations such as API communication, workflow management, user settings, and other essential features.

 The term "business logic" in this context refers to the code that implements the core functionality and behavior of the application - the rules, processes, and operations that make ComfyUI work as expected, separate from the UI display code.

@@ -57,21 +57,25 @@ While services can interact with both UI components and stores (centralized stat

 ## Core Services

-The following table lists ALL services in the system as of 2025-01-30:
+The following table lists ALL services in the system as of 2025-09-01:

 ### Main Services

 | Service | Description | Category |
 |---------|-------------|----------|
+| audioService.ts | Manages audio recording and WAV encoding functionality | Media |
 | autoQueueService.ts | Manages automatic queue execution | Execution |
 | colorPaletteService.ts | Handles color palette management and customization | UI |
 | comfyManagerService.ts | Manages ComfyUI application packages and updates | Manager |
 | comfyRegistryService.ts | Handles registration and discovery of ComfyUI extensions | Registry |
+| customerEventsService.ts | Handles customer event tracking and audit logs | Analytics |
 | dialogService.ts | Provides dialog and modal management | UI |
 | extensionService.ts | Manages extension registration and lifecycle | Extensions |
 | keybindingService.ts | Handles keyboard shortcuts and keybindings | Input |
 | litegraphService.ts | Provides utilities for working with the LiteGraph library | Graph |
 | load3dService.ts | Manages 3D model loading and visualization | 3D |
+| mediaCacheService.ts | Manages media file caching with blob storage and cleanup | Media |
+| newUserService.ts | Handles new user initialization and onboarding | System |
 | nodeHelpService.ts | Provides node documentation and help | Nodes |
 | nodeOrganizationService.ts | Handles node organization and categorization | Nodes |
 | nodeSearchService.ts | Implements node search functionality | Search |
@@ -105,47 +109,82 @@ For complex services with state management and multiple methods, class-based ser
 ```typescript
 export class NodeSearchService {
  // Service state
-  private readonly nodeFuseSearch: FuseSearch<ComfyNodeDefImpl>
-  private readonly filters: Record<string, FuseFilter<ComfyNodeDefImpl, string>>
+  public readonly nodeFuseSearch: FuseSearch<ComfyNodeDefImpl>
+  public readonly inputTypeFilter: FuseFilter<ComfyNodeDefImpl, string>
+  public readonly outputTypeFilter: FuseFilter<ComfyNodeDefImpl, string>
+  public readonly nodeCategoryFilter: FuseFilter<ComfyNodeDefImpl, string>
+  public readonly nodeSourceFilter: FuseFilter<ComfyNodeDefImpl, string>

  constructor(data: ComfyNodeDefImpl[]) {
-    // Initialize state
-    this.nodeFuseSearch = new FuseSearch(data, { /* options */ })
-    
-    // Setup filters
-    this.filters = {
-      inputType: new FuseFilter<ComfyNodeDefImpl, string>(/* options */),
-      category: new FuseFilter<ComfyNodeDefImpl, string>(/* options */)
-    }
+    // Initialize search index
+    this.nodeFuseSearch = new FuseSearch(data, {
+      fuseOptions: {
+        keys: ['name', 'display_name'],
+        includeScore: true,
+        threshold: 0.3,
+        shouldSort: false,
+        useExtendedSearch: true
+      },
+      createIndex: true,
+      advancedScoring: true
+    })
+
+    // Setup individual filters
+    const fuseOptions = { includeScore: true, threshold: 0.3, shouldSort: true }
+    this.inputTypeFilter = new FuseFilter<ComfyNodeDefImpl, string>(data, {
+      id: 'input',
+      name: 'Input Type',
+      invokeSequence: 'i',
+      getItemOptions: (node) => Object.values(node.inputs).map((input) => input.type),
+      fuseOptions
+    })
+    // Additional filters initialized similarly...
  }

-  public searchNode(query: string, filters: FuseFilterWithValue[] = []): ComfyNodeDefImpl[] {
-    // Implementation
-    return results
+  public searchNode(
+    query: string,
+    filters: FuseFilterWithValue<ComfyNodeDefImpl, string>[] = []
+  ): ComfyNodeDefImpl[] {
+    const matchedNodes = this.nodeFuseSearch.search(query)
+    return matchedNodes.filter((node) => {
+      return filters.every((filterAndValue) => {
+        const { filterDef, value } = filterAndValue
+        return filterDef.matches(node, value, { wildcard: '*' })
+      })
+    })
+  }
+
+  get nodeFilters(): FuseFilter<ComfyNodeDefImpl, string>[] {
+    return [
+      this.inputTypeFilter,
+      this.outputTypeFilter,
+      this.nodeCategoryFilter,
+      this.nodeSourceFilter
+    ]
  }
 }
 ```

 ### 2. Composable-style Services

-For simpler services or those that need to integrate with Vue's reactivity system, we prefer using composable-style services:
+For services that need to integrate with Vue's reactivity system or handle API interactions, we use composable-style services:

 ```typescript
 export function useNodeSearchService(initialData: ComfyNodeDefImpl[]) {
  // State (reactive if needed)
  const data = ref(initialData)
-  
+
  // Search functionality
  function searchNodes(query: string) {
    // Implementation
    return results
  }
-  
+
  // Additional methods
  function refreshData(newData: ComfyNodeDefImpl[]) {
    data.value = newData
  }
-  
+
  // Return public API
  return {
    searchNodes,
@@ -154,12 +193,35 @@ export function useNodeSearchService(initialData: ComfyNodeDefImpl[]) {
 }
 ```

-When deciding between these approaches, consider:
+### Service Pattern Comparison

-1. **Stateful vs. Stateless**: For stateful services, classes often provide clearer encapsulation
-2. **Reactivity needs**: If the service needs to be reactive, composable-style services integrate better with Vue's reactivity system
-3. **Complexity**: For complex services with many methods and internal state, classes can provide better organization
-4. **Testing**: Both approaches can be tested effectively, but composables may be simpler to test with Vue Test Utils
+| Aspect | Class-Based Services | Composable-Style Services | Bootstrap Services | Shared State Services |
+|--------|---------------------|---------------------------|-------------------|---------------------|
+| **Count** | 4 services | 18+ services | 1 service | 1 service |
+| **Export Pattern** | `export class ServiceName` | `export function useServiceName()` | `export function setupX()` | `export function serviceFactory()` |
+| **Instantiation** | `new ServiceName(data)` | `useServiceName()` | Direct function call | Direct function call |
+| **Best For** | Complex data structures, search algorithms, expensive initialization | Vue integration, API calls, reactive state | One-time app initialization | Singleton-like shared state |
+| **State Management** | Encapsulated private/public properties | External stores + reactive refs | Event listeners, side effects | Module-level state |
+| **Vue Integration** | Manual integration needed | Native reactivity support | N/A | Varies |
+| **Examples** | `NodeSearchService`, `Load3dService` | `workflowService`, `dialogService` | `autoQueueService` | `newUserService` |
+
+### Decision Criteria
+
+When choosing between these approaches, consider:
+
+1. **Data Structure Complexity**: Classes work well for services managing multiple related data structures (search indices, filters, complex state)
+2. **Initialization Cost**: Classes are ideal when expensive setup should happen once and be controlled by instantiation
+3. **Vue Integration**: Composables integrate seamlessly with Vue's reactivity system and stores
+4. **API Interactions**: Composables handle async operations and API calls more naturally
+5. **State Management**: Classes provide strong encapsulation; composables work better with external state management
+6. **Application Bootstrap**: Bootstrap services handle one-time app initialization, event listener setup, and side effects
+7. **Singleton Behavior**: Shared state services provide module-level state that persists across multiple function calls
+
+**Current Usage Patterns:**
+- **Class-based services (4)**: Complex data processing, search algorithms, expensive initialization
+- **Composable-style services (18+)**: UI interactions, API calls, store integration, reactive state management
+- **Bootstrap services (1)**: One-time application initialization and event handler setup
+- **Shared state services (1)**: Singleton-like behavior with module-level state management

 ### Service Template

@@ -172,7 +234,7 @@ Here's a template for creating a new composable-style service:
 export function useExampleService() {
  // Private state/functionality
  const cache = new Map()
-  
+
  /**
   * Description of what this method does
   * @param param1 Description of parameter
@@ -188,7 +250,7 @@ export function useExampleService() {
      throw error
    }
  }
-  
+
  // Return public API
  return {
    performOperation
@@ -206,16 +268,16 @@ Services in ComfyUI frequently use the following design patterns:
 export function useCachedService() {
  const cache = new Map()
  const pendingRequests = new Map()
-  
+
  async function fetchData(key: string) {
    // Check cache first
    if (cache.has(key)) return cache.get(key)
-    
+
    // Check if request is already in progress
    if (pendingRequests.has(key)) {
      return pendingRequests.get(key)
    }
-    
+
    // Perform new request
    const requestPromise = fetch(`/api/${key}`)
      .then(response => response.json())
@@ -224,11 +286,11 @@ export function useCachedService() {
        pendingRequests.delete(key)
        return data
      })
-    
+
    pendingRequests.set(key, requestPromise)
    return requestPromise
  }
-  
+
  return { fetchData }
 }
 ```
@@ -248,7 +310,7 @@ export function useNodeFactory() {
        throw new Error(`Unknown node type: ${type}`)
    }
  }
-  
+
  return { createNode }
 }
 ```
@@ -267,11 +329,243 @@ export function useWorkflowService(
    const storagePath = await storageService.getPath(name)
    return apiService.saveData(storagePath, graphData)
  }
-  
+
  return { saveWorkflow }
 }
 ```

+## Testing Services
+
+Services in ComfyUI can be tested effectively using different approaches depending on their implementation pattern.
+
+### Testing Class-Based Services
+
+**Setup Requirements:**
+```typescript
+// Manual instantiation required
+const mockData = [/* test data */]
+const service = new NodeSearchService(mockData)
+```
+
+**Characteristics:**
+- Requires constructor argument preparation
+- State is encapsulated within the class instance
+- Direct method calls on the instance
+- Good isolation - each test gets a fresh instance
+
+**Example:**
+```typescript
+describe('NodeSearchService', () => {
+  let service: NodeSearchService
+
+  beforeEach(() => {
+    const mockNodes = [/* mock node definitions */]
+    service = new NodeSearchService(mockNodes)
+  })
+
+  test('should search nodes by query', () => {
+    const results = service.searchNode('test query')
+    expect(results).toHaveLength(2)
+  })
+
+  test('should apply filters correctly', () => {
+    const filters = [{ filterDef: service.inputTypeFilter, value: 'IMAGE' }]
+    const results = service.searchNode('*', filters)
+    expect(results.every(node => /* has IMAGE input */)).toBe(true)
+  })
+})
+```
+
+### Testing Composable-Style Services
+
+**Setup Requirements:**
+```typescript
+// Direct function call, no instantiation
+const { saveWorkflow, loadWorkflow } = useWorkflowService()
+```
+
+**Characteristics:**
+- No instantiation needed
+- Integrates naturally with Vue Test Utils
+- Easy mocking of reactive dependencies
+- External store dependencies need mocking
+
+**Example:**
+```typescript
+describe('useWorkflowService', () => {
+  beforeEach(() => {
+    // Mock external dependencies
+    vi.mock('@/stores/settingStore', () => ({
+      useSettingStore: () => ({
+        get: vi.fn().mockReturnValue(true),
+        set: vi.fn()
+      })
+    }))
+
+    vi.mock('@/stores/toastStore', () => ({
+      useToastStore: () => ({
+        add: vi.fn()
+      })
+    }))
+  })
+
+  test('should save workflow with prompt', async () => {
+    const { saveWorkflow } = useWorkflowService()
+    await saveWorkflow('test-workflow')
+
+    // Verify interactions with mocked dependencies
+    expect(mockSettingStore.get).toHaveBeenCalledWith('Comfy.PromptFilename')
+  })
+})
+```
+
+### Testing Bootstrap Services
+
+**Focus on Setup Behavior:**
+```typescript
+describe('autoQueueService', () => {
+  beforeEach(() => {
+    // Mock global dependencies
+    vi.mock('@/scripts/api', () => ({
+      api: {
+        addEventListener: vi.fn()
+      }
+    }))
+
+    vi.mock('@/scripts/app', () => ({
+      app: {
+        queuePrompt: vi.fn()
+      }
+    }))
+  })
+
+  test('should setup event listeners', () => {
+    setupAutoQueueHandler()
+
+    expect(mockApi.addEventListener).toHaveBeenCalledWith('graphChanged', expect.any(Function))
+  })
+
+  test('should handle graph changes when auto-queue enabled', () => {
+    setupAutoQueueHandler()
+
+    // Simulate graph change event
+    const graphChangeHandler = mockApi.addEventListener.mock.calls[0][1]
+    graphChangeHandler()
+
+    expect(mockApp.queuePrompt).toHaveBeenCalled()
+  })
+})
+```
+
+### Testing Shared State Services
+
+**Focus on Shared State Behavior:**
+```typescript
+describe('newUserService', () => {
+  beforeEach(() => {
+    // Reset module state between tests
+    vi.resetModules()
+  })
+
+  test('should return consistent API across calls', () => {
+    const service1 = newUserService()
+    const service2 = newUserService()
+
+    // Same functions returned (shared behavior)
+    expect(service1.isNewUser).toBeDefined()
+    expect(service2.isNewUser).toBeDefined()
+  })
+
+  test('should share state between service instances', async () => {
+    const service1 = newUserService()
+    const service2 = newUserService()
+
+    // Initialize through one instance
+    const mockSettingStore = { set: vi.fn() }
+    await service1.initializeIfNewUser(mockSettingStore)
+
+    // State should be shared
+    expect(service2.isNewUser()).toBe(true) // or false, depending on mock
+  })
+})
+```
+
+### Common Testing Patterns
+
+**Mocking External Dependencies:**
+```typescript
+// Mock stores
+vi.mock('@/stores/settingStore', () => ({
+  useSettingStore: () => ({
+    get: vi.fn(),
+    set: vi.fn()
+  })
+}))
+
+// Mock API calls
+vi.mock('@/scripts/api', () => ({
+  api: {
+    get: vi.fn().mockResolvedValue({ data: 'mock' }),
+    post: vi.fn().mockResolvedValue({ success: true })
+  }
+}))
+
+// Mock Vue composables
+vi.mock('vue', () => ({
+  ref: vi.fn((val) => ({ value: val })),
+  reactive: vi.fn((obj) => obj)
+}))
+```
+
+**Async Testing:**
+```typescript
+test('should handle async operations', async () => {
+  const service = useMyService()
+  const result = await service.performAsyncOperation()
+  expect(result).toBeTruthy()
+})
+
+test('should handle concurrent requests', async () => {
+  const service = useMyService()
+  const promises = [
+    service.loadData('key1'),
+    service.loadData('key2')
+  ]
+
+  const results = await Promise.all(promises)
+  expect(results).toHaveLength(2)
+})
+```
+
+**Error Handling:**
+```typescript
+test('should handle service errors gracefully', async () => {
+  const service = useMyService()
+
+  // Mock API to throw error
+  mockApi.get.mockRejectedValue(new Error('Network error'))
+
+  await expect(service.fetchData()).rejects.toThrow('Network error')
+})
+
+test('should provide meaningful error messages', async () => {
+  const service = useMyService()
+  const consoleSpy = vi.spyOn(console, 'error').mockImplementation()
+
+  await service.handleError('test error')
+
+  expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('test error'))
+})
+```
+
+### Testing Best Practices
+
+1. **Isolate Dependencies**: Always mock external dependencies (stores, APIs, DOM)
+2. **Reset State**: Use `beforeEach` to ensure clean test state
+3. **Test Error Paths**: Don't just test happy paths - test error scenarios
+4. **Mock Timers**: Use `vi.useFakeTimers()` for time-dependent services
+5. **Test Async Properly**: Use `async/await` and proper promise handling
+
 For more detailed information about the service layer pattern and its applications, refer to:
 - [Service Layer Pattern](https://en.wikipedia.org/wiki/Service_layer_pattern)
 - [Service-Orientation](https://en.wikipedia.org/wiki/Service-orientation)
--- a/src/stores/README.md
+++ b/src/stores/README.md
@@ -100,57 +100,64 @@ The following diagram illustrates the store architecture and data flow:

 ## Core Stores

-The following table lists ALL stores in the system as of 2025-01-30:
+The following table lists ALL 46 store instances in the system as of 2025-09-01:

 ### Main Stores

-| Store | Description | Category |
-|-------|-------------|----------|
-| aboutPanelStore.ts | Manages the About panel state and badges | UI |
-| apiKeyAuthStore.ts | Handles API key authentication | Auth |
-| comfyManagerStore.ts | Manages ComfyUI application state | Core |
-| comfyRegistryStore.ts | Handles extensions registry | Registry |
-| commandStore.ts | Manages commands and command execution | Core |
-| dialogStore.ts | Controls dialog/modal display and state | UI |
-| domWidgetStore.ts | Manages DOM widget state | Widgets |
-| electronDownloadStore.ts | Handles Electron-specific download operations | Platform |
-| executionStore.ts | Tracks workflow execution state | Execution |
-| extensionStore.ts | Manages extension registration and state | Extensions |
-| firebaseAuthStore.ts | Handles Firebase authentication | Auth |
-| graphStore.ts | Manages the graph canvas state | Core |
-| imagePreviewStore.ts | Controls image preview functionality | Media |
-| keybindingStore.ts | Manages keyboard shortcuts | Input |
-| maintenanceTaskStore.ts | Handles system maintenance tasks | System |
-| menuItemStore.ts | Handles menu items and their state | UI |
-| modelStore.ts | Manages AI models information | Models |
-| modelToNodeStore.ts | Maps models to compatible nodes | Models |
-| nodeBookmarkStore.ts | Manages node bookmarks and favorites | Nodes |
-| nodeDefStore.ts | Manages node definitions | Nodes |
-| queueStore.ts | Handles the execution queue | Execution |
-| releaseStore.ts | Manages application release information | System |
-| serverConfigStore.ts | Handles server configuration | Config |
-| settingStore.ts | Manages application settings | Config |
-| subgraphNavigationStore.ts | Handles subgraph navigation state | Navigation |
-| systemStatsStore.ts | Tracks system performance statistics | System |
-| toastStore.ts | Manages toast notifications | UI |
-| userFileStore.ts | Manages user file operations | Files |
-| userStore.ts | Manages user data and preferences | User |
-| versionCompatibilityStore.ts | Manages frontend/backend version compatibility warnings | Core |
-| widgetStore.ts | Manages widget configurations | Widgets |
-| workflowStore.ts | Handles workflow data and operations | Workflows |
-| workflowTemplatesStore.ts | Manages workflow templates | Workflows |
-| workspaceStore.ts | Manages overall workspace state | Workspace |
+| File | Store | Description | Category |
+|------|-------|-------------|----------|
+| aboutPanelStore.ts | useAboutPanelStore | Manages the About panel state and badges | UI |
+| apiKeyAuthStore.ts | useApiKeyAuthStore | Handles API key authentication | Auth |
+| comfyManagerStore.ts | useComfyManagerStore | Manages ComfyUI application state | Core |
+| comfyManagerStore.ts | useManagerProgressDialogStore | Manages manager progress dialog state | UI |
+| comfyRegistryStore.ts | useComfyRegistryStore | Handles extensions registry | Registry |
+| commandStore.ts | useCommandStore | Manages commands and command execution | Core |
+| dialogStore.ts | useDialogStore | Controls dialog/modal display and state | UI |
+| domWidgetStore.ts | useDomWidgetStore | Manages DOM widget state | Widgets |
+| electronDownloadStore.ts | useElectronDownloadStore | Handles Electron-specific download operations | Platform |
+| executionStore.ts | useExecutionStore | Tracks workflow execution state | Execution |
+| extensionStore.ts | useExtensionStore | Manages extension registration and state | Extensions |
+| firebaseAuthStore.ts | useFirebaseAuthStore | Handles Firebase authentication | Auth |
+| graphStore.ts | useTitleEditorStore | Manages title editing for nodes and groups | UI |
+| graphStore.ts | useCanvasStore | Manages the graph canvas state and interactions | Core |
+| helpCenterStore.ts | useHelpCenterStore | Manages help center visibility and state | UI |
+| imagePreviewStore.ts | useNodeOutputStore | Manages node outputs and execution results | Media |
+| keybindingStore.ts | useKeybindingStore | Manages keyboard shortcuts | Input |
+| maintenanceTaskStore.ts | useMaintenanceTaskStore | Handles system maintenance tasks | System |
+| menuItemStore.ts | useMenuItemStore | Handles menu items and their state | UI |
+| modelStore.ts | useModelStore | Manages AI models information | Models |
+| modelToNodeStore.ts | useModelToNodeStore | Maps models to compatible nodes | Models |
+| nodeBookmarkStore.ts | useNodeBookmarkStore | Manages node bookmarks and favorites | Nodes |
+| nodeDefStore.ts | useNodeDefStore | Manages node definitions and schemas | Nodes |
+| nodeDefStore.ts | useNodeFrequencyStore | Tracks node usage frequency | Nodes |
+| queueStore.ts | useQueueStore | Manages execution queue and task history | Execution |
+| queueStore.ts | useQueuePendingTaskCountStore | Tracks pending task counts | Execution |
+| queueStore.ts | useQueueSettingsStore | Manages queue execution settings | Execution |
+| releaseStore.ts | useReleaseStore | Manages application release information | System |
+| serverConfigStore.ts | useServerConfigStore | Handles server configuration | Config |
+| settingStore.ts | useSettingStore | Manages application settings | Config |
+| subgraphNavigationStore.ts | useSubgraphNavigationStore | Handles subgraph navigation state | Navigation |
+| systemStatsStore.ts | useSystemStatsStore | Tracks system performance statistics | System |
+| toastStore.ts | useToastStore | Manages toast notifications | UI |
+| userFileStore.ts | useUserFileStore | Manages user file operations | Files |
+| userStore.ts | useUserStore | Manages user data and preferences | User |
+| versionCompatibilityStore.ts | useVersionCompatibilityStore | Manages frontend/backend version compatibility warnings | Core |
+| widgetStore.ts | useWidgetStore | Manages widget configurations | Widgets |
+| workflowStore.ts | useWorkflowStore | Handles workflow data and operations | Workflows |
+| workflowStore.ts | useWorkflowBookmarkStore | Manages workflow bookmarks and favorites | Workflows |
+| workflowTemplatesStore.ts | useWorkflowTemplatesStore | Manages workflow templates | Workflows |
+| workspaceStore.ts | useWorkspaceStore | Manages overall workspace state | Workspace |

 ### Workspace Stores
 Located in `stores/workspace/`:

-| Store | Description |
-|-------|-------------|
-| bottomPanelStore.ts | Controls bottom panel visibility and state |
-| colorPaletteStore.ts | Manages color palette configurations |
-| nodeHelpStore.ts | Handles node help and documentation display |
-| searchBoxStore.ts | Manages search box functionality |
-| sidebarTabStore.ts | Controls sidebar tab states and navigation |
+| File | Store | Description | Category |
+|------|-------|-------------|----------|
+| bottomPanelStore.ts | useBottomPanelStore | Controls bottom panel visibility and state | UI |
+| colorPaletteStore.ts | useColorPaletteStore | Manages color palette configurations | UI |
+| nodeHelpStore.ts | useNodeHelpStore | Handles node help and documentation display | UI |
+| searchBoxStore.ts | useSearchBoxStore | Manages search box functionality | UI |
+| sidebarTabStore.ts | useSidebarTabStore | Controls sidebar tab states and navigation | UI |

 ## Store Development Guidelines

@@ -189,7 +196,7 @@ export const useExampleStore = defineStore('example', () => {
  async function fetchItems() {
    isLoading.value = true
    error.value = null
-    
+
    try {
      const response = await fetch('/api/items')
      const data = await response.json()
@@ -207,11 +214,11 @@ export const useExampleStore = defineStore('example', () => {
    items,
    isLoading,
    error,
-    
+
    // Getters
    itemCount,
    hasError,
-    
+
    // Actions
    addItem,
    fetchItems
@@ -238,7 +245,7 @@ export const useDataStore = defineStore('data', () => {
  async function fetchData() {
    loading.value = true
    try {
-      const result = await api.getData()
+      const result = await api.getExtensions()
      data.value = result
    } catch (err) {
      error.value = err.message
@@ -266,21 +273,21 @@ import { useOtherStore } from './otherStore'
 export const useComposedStore = defineStore('composed', () => {
  const otherStore = useOtherStore()
  const { someData } = storeToRefs(otherStore)
-  
+
  // Local state
  const localState = ref(0)
-  
+
  // Computed value based on other store
  const derivedValue = computed(() => {
    return computeFromOtherData(someData.value, localState.value)
  })
-  
+
  // Action that uses another store
  async function complexAction() {
    await otherStore.someAction()
    localState.value += 1
  }
-  
+
  return {
    localState,
    derivedValue,
@@ -299,20 +306,20 @@ export const usePreferencesStore = defineStore('preferences', () => {
  // Load from localStorage if available
  const theme = ref(localStorage.getItem('theme') || 'light')
  const fontSize = ref(parseInt(localStorage.getItem('fontSize') || '14'))
-  
+
  // Save to localStorage when changed
  watch(theme, (newTheme) => {
    localStorage.setItem('theme', newTheme)
  })
-  
+
  watch(fontSize, (newSize) => {
    localStorage.setItem('fontSize', newSize.toString())
  })
-  
+
  function setTheme(newTheme) {
    theme.value = newTheme
  }
-  
+
  return {
    theme,
    fontSize,
@@ -347,7 +354,7 @@ describe('useExampleStore', () => {
    // Create a fresh pinia instance and make it active
    setActivePinia(createPinia())
    store = useExampleStore()
-    
+
    // Clear all mocks
    vi.clearAllMocks()
  })
@@ -363,14 +370,14 @@ describe('useExampleStore', () => {
    expect(store.items).toEqual(['test'])
    expect(store.itemCount).toBe(1)
  })
-  
+
  it('should fetch items', async () => {
    // Setup mock response
    vi.mocked(api.getData).mockResolvedValue(['item1', 'item2'])
-    
+
    // Call the action
    await store.fetchItems()
-    
+
    // Verify state changes
    expect(store.isLoading).toBe(false)
    expect(store.items).toEqual(['item1', 'item2'])
@@ -379,4 +386,209 @@ describe('useExampleStore', () => {
 })
 ```

+## ComfyUI-Specific Patterns
+
+ComfyUI stores follow additional patterns specific to the application's architecture:
+
+### WebSocket Message Handling
+
+Many stores handle real-time updates via WebSocket messages. The execution store is a prime example:
+
+```typescript
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { ExecutionStartWsMessage, ProgressWsMessage } from '@/schemas/apiSchema'
+import { api } from '@/scripts/api'
+
+export const useExecutionStore = defineStore('execution', () => {
+  const activePromptId = ref<string | null>(null)
+  const nodeProgressStates = ref<Record<string, NodeProgressState>>({})
+
+  // Register WebSocket event listeners
+  function registerEvents() {
+    api.addEventListener('execution_start', handleExecutionStart)
+    api.addEventListener('progress', handleProgress)
+    api.addEventListener('execution_error', handleExecutionError)
+  }
+
+  function handleExecutionStart(e: CustomEvent<ExecutionStartWsMessage>) {
+    activePromptId.value = e.detail.prompt_id
+    // Handle execution start
+  }
+
+  function handleProgress(e: CustomEvent<ProgressWsMessage>) {
+    // Update node progress states
+    const { value, max } = e.detail
+    // ... progress handling logic
+  }
+
+  // Clean up listeners when store is no longer needed
+  function unregisterEvents() {
+    api.removeEventListener('execution_start', handleExecutionStart)
+    api.removeEventListener('progress', handleProgress)
+    api.removeEventListener('execution_error', handleExecutionError)
+  }
+
+  return {
+    activePromptId,
+    nodeProgressStates,
+    registerEvents,
+    unregisterEvents
+  }
+})
+```
+
+### Store Communication Patterns
+
+ComfyUI stores frequently reference each other to maintain consistency across the application:
+
+```typescript
+import { defineStore } from 'pinia'
+import { computed } from 'vue'
+import { useCanvasStore } from './graphStore'
+import { useWorkflowStore } from './workflowStore'
+
+export const useExecutionStore = defineStore('execution', () => {
+  // Reference related stores
+  const workflowStore = useWorkflowStore()
+  const canvasStore = useCanvasStore()
+
+  // Computed values that depend on other stores
+  const activeWorkflow = computed(() => workflowStore.activeWorkflow)
+  
+  // Actions that coordinate between stores
+  async function executeWorkflow() {
+    const workflow = workflowStore.serialize()
+    const canvas = canvasStore.canvas
+    // Execute with coordination between stores
+  }
+
+  return {
+    activeWorkflow,
+    executeWorkflow
+  }
+})
+```
+
+### Extension Integration
+
+Extensions can register with stores to extend functionality:
+
+```typescript
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { ComfyExtension } from '@/types/comfy'
+
+export const useExtensionStore = defineStore('extension', () => {
+  const extensionByName = ref<Record<string, ComfyExtension>>({})
+
+  function registerExtension(extension: ComfyExtension) {
+    if (!extension.name) {
+      throw new Error("Extensions must have a 'name' property.")
+    }
+
+    if (extensionByName.value[extension.name]) {
+      console.warn(`Extension ${extension.name} already registered. Overwriting.`)
+    }
+
+    extensionByName.value[extension.name] = extension
+
+    // Call extension setup if provided
+    if (extension.setup) {
+      extension.setup()
+    }
+  }
+
+  function isExtensionEnabled(extensionName: string): boolean {
+    const extension = extensionByName.value[extensionName]
+    return extension && !extension.disabled
+  }
+
+  return {
+    extensionByName: readonly(extensionByName),
+    registerExtension,
+    isExtensionEnabled
+  }
+})
+```
+
+### Workspace Store Organization
+
+ComfyUI uses a two-tier store organization:
+
+1. **Main stores** (`src/stores/*.ts`) - Core application logic
+2. **Workspace stores** (`src/stores/workspace/*.ts`) - UI layout and workspace-specific state
+
+The `useWorkspaceStore` acts as a coordinator, providing computed access to other stores:
+
+```typescript
+import { defineStore } from 'pinia'
+import { computed } from 'vue'
+import { useWorkflowStore } from './workflowStore'
+import { useBottomPanelStore } from './workspace/bottomPanelStore'
+import { useSidebarTabStore } from './workspace/sidebarTabStore'
+
+export const useWorkspaceStore = defineStore('workspace', () => {
+  const focusMode = ref(false)
+
+  // Provide unified access to related stores
+  const workflow = computed(() => useWorkflowStore())
+  const sidebarTab = computed(() => useSidebarTabStore())
+  const bottomPanel = computed(() => useBottomPanelStore())
+
+  // Workspace-level actions that coordinate multiple stores
+  function toggleFocusMode() {
+    focusMode.value = !focusMode.value
+    // Hide/show panels based on focus mode
+    if (focusMode.value) {
+      bottomPanel.value.hide()
+      sidebarTab.value.closeTabs()
+    }
+  }
+
+  return {
+    focusMode,
+    workflow,
+    sidebarTab,
+    bottomPanel,
+    toggleFocusMode
+  }
+})
+```
+
+### Node and Workflow State Management
+
+ComfyUI stores often work with node and workflow concepts:
+
+```typescript
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import type { ComfyWorkflow, NodeId } from '@/schemas/comfyWorkflowSchema'
+
+export const useWorkflowStore = defineStore('workflow', () => {
+  const activeWorkflow = ref<ComfyWorkflow | null>(null)
+
+  // Convert node ID to a locator for cross-store communication
+  function nodeIdToNodeLocatorId(nodeId: NodeId): NodeLocatorId {
+    return createNodeLocatorId(activeWorkflow.value?.path, nodeId)
+  }
+
+  // Serialize current workflow for execution
+  function serialize(): ComfyApiWorkflow {
+    if (!activeWorkflow.value) {
+      throw new Error('No active workflow to serialize')
+    }
+    return convertToApiFormat(activeWorkflow.value)
+  }
+
+  return {
+    activeWorkflow,
+    nodeIdToNodeLocatorId,
+    serialize
+  }
+})
+```
+
+These patterns ensure that ComfyUI stores work together effectively to manage the complex state of a node-based workflow editor.
+
 For more information on Pinia, refer to the [Pinia documentation](https://pinia.vuejs.org/introduction.html).
--- a/src/utils/colorUtil.ts
+++ b/src/utils/colorUtil.ts
@@ -59,6 +59,59 @@ export function hexToRgb(hex: string): RGB {
  return { r, g, b }
 }

+export function parseToRgb(color: string): RGB {
+  const format = identifyColorFormat(color)
+  if (!format) return { r: 0, g: 0, b: 0 }
+
+  const hsla = parseToHSLA(color, format)
+  if (!isHSLA(hsla)) return { r: 0, g: 0, b: 0 }
+
+  // Convert HSL to RGB
+  const h = hsla.h / 360
+  const s = hsla.s / 100
+  const l = hsla.l / 100
+
+  const c = (1 - Math.abs(2 * l - 1)) * s
+  const x = c * (1 - Math.abs(((h * 6) % 2) - 1))
+  const m = l - c / 2
+
+  let r = 0,
+    g = 0,
+    b = 0
+
+  if (h < 1 / 6) {
+    r = c
+    g = x
+    b = 0
+  } else if (h < 2 / 6) {
+    r = x
+    g = c
+    b = 0
+  } else if (h < 3 / 6) {
+    r = 0
+    g = c
+    b = x
+  } else if (h < 4 / 6) {
+    r = 0
+    g = x
+    b = c
+  } else if (h < 5 / 6) {
+    r = x
+    g = 0
+    b = c
+  } else {
+    r = c
+    g = 0
+    b = x
+  }
+
+  return {
+    r: Math.round((r + m) * 255),
+    g: Math.round((g + m) * 255),
+    b: Math.round((b + m) * 255)
+  }
+}
+
 const identifyColorFormat = (color: string): ColorFormat | null => {
  if (!color) return null
  if (color.startsWith('#') && (color.length === 4 || color.length === 7))
--- a/tests-ui/tests/composables/node/useNodePricing.test.ts
+++ b/tests-ui/tests/composables/node/useNodePricing.test.ts
@@ -8,7 +8,12 @@ import type { IComboWidget } from '@/lib/litegraph/src/types/widgets'
 function createMockNode(
  nodeTypeName: string,
  widgets: Array<{ name: string; value: any }> = [],
-  isApiNode = true
+  isApiNode = true,
+  inputs: Array<{
+    name: string
+    connected?: boolean
+    useLinksArray?: boolean
+  }> = []
 ): LGraphNode {
  const mockWidgets = widgets.map(({ name, value }) => ({
    name,
@@ -16,7 +21,16 @@ function createMockNode(
    type: 'combo'
  })) as IComboWidget[]

-  return {
+  const mockInputs =
+    inputs.length > 0
+      ? inputs.map(({ name, connected, useLinksArray }) =>
+          useLinksArray
+            ? { name, links: connected ? [1] : [] }
+            : { name, link: connected ? 1 : null }
+        )
+      : undefined
+
+  const node: any = {
    id: Math.random().toString(),
    widgets: mockWidgets,
    constructor: {
@@ -25,7 +39,24 @@ function createMockNode(
        api_node: isApiNode
      }
    }
-  } as unknown as LGraphNode
+  }
+
+  if (mockInputs) {
+    node.inputs = mockInputs
+    // Provide the common helpers some frontend code may call
+    node.findInputSlot = function (portName: string) {
+      return this.inputs?.findIndex((i: any) => i.name === portName) ?? -1
+    }
+    node.isInputConnected = function (idx: number) {
+      const port = this.inputs?.[idx]
+      if (!port) return false
+      if (typeof port.link !== 'undefined') return port.link != null
+      if (Array.isArray(port.links)) return port.links.length > 0
+      return false
+    }
+  }
+
+  return node as LGraphNode
 }

 describe('useNodePricing', () => {
@@ -363,34 +394,51 @@ describe('useNodePricing', () => {
  })

  describe('dynamic pricing - IdeogramV3', () => {
-    it('should return $0.09 for Quality rendering speed', () => {
+    it('should return correct prices for IdeogramV3 node', () => {
      const { getNodeDisplayPrice } = useNodePricing()
-      const node = createMockNode('IdeogramV3', [
-        { name: 'rendering_speed', value: 'Quality' }
-      ])

-      const price = getNodeDisplayPrice(node)
-      expect(price).toBe('$0.09/Run')
-    })
+      const testCases = [
+        {
+          rendering_speed: 'Quality',
+          character_image: false,
+          expected: '$0.09/Run'
+        },
+        {
+          rendering_speed: 'Quality',
+          character_image: true,
+          expected: '$0.20/Run'
+        },
+        {
+          rendering_speed: 'Default',
+          character_image: false,
+          expected: '$0.06/Run'
+        },
+        {
+          rendering_speed: 'Default',
+          character_image: true,
+          expected: '$0.15/Run'
+        },
+        {
+          rendering_speed: 'Turbo',
+          character_image: false,
+          expected: '$0.03/Run'
+        },
+        {
+          rendering_speed: 'Turbo',
+          character_image: true,
+          expected: '$0.10/Run'
+        }
+      ]

-    it('should return $0.06 for Balanced rendering speed', () => {
-      const { getNodeDisplayPrice } = useNodePricing()
-      const node = createMockNode('IdeogramV3', [
-        { name: 'rendering_speed', value: 'Balanced' }
-      ])
-
-      const price = getNodeDisplayPrice(node)
-      expect(price).toBe('$0.06/Run')
-    })
-
-    it('should return $0.03 for Turbo rendering speed', () => {
-      const { getNodeDisplayPrice } = useNodePricing()
-      const node = createMockNode('IdeogramV3', [
-        { name: 'rendering_speed', value: 'Turbo' }
-      ])
-
-      const price = getNodeDisplayPrice(node)
-      expect(price).toBe('$0.03/Run')
+      testCases.forEach(({ rendering_speed, character_image, expected }) => {
+        const node = createMockNode(
+          'IdeogramV3',
+          [{ name: 'rendering_speed', value: rendering_speed }],
+          true,
+          [{ name: 'character_image', connected: character_image }]
+        )
+        expect(getNodeDisplayPrice(node)).toBe(expected)
+      })
    })

    it('should return range when rendering_speed widget is missing', () => {
@@ -935,7 +983,11 @@ describe('useNodePricing', () => {
          const { getRelevantWidgetNames } = useNodePricing()

          const widgetNames = getRelevantWidgetNames('IdeogramV3')
-          expect(widgetNames).toEqual(['rendering_speed', 'num_images'])
+          expect(widgetNames).toEqual([
+            'rendering_speed',
+            'num_images',
+            'character_image'
+          ])
        })
      })
Author	SHA1	Message	Date
Arjan Singh	712eead2d9	docs: simplify CLAUDE.md for feature flags and settings	2025-09-01 19:22:24 -07:00
Arjan Singh	4b3a56f744	docs: update stores README.md	2025-09-01 19:20:19 -07:00
Arjan Singh	481e3b593a	[docs] update CLAUDE.md and selected README.md files (#5293 ) * docs: add Claude documentation for settings and feature flags * docs: update services README.md * docs: update stores README.md	2025-09-01 15:31:44 -07:00
filtered	b592c9015e	Update & clarify Node.js version requirements (#5280 )	2025-09-01 11:36:29 -07:00
Alexander Piskun	f0afc261a4	add prices for Kling 2.1 model for KlingStartEndFrame node (#5264 )	2025-09-01 10:54:55 -07:00
Alexander Piskun	1e6ba5c689	api_nodes: added prices for Ideogram V3 node (character reference) (#5241 ) * api_nodes: added prices for Ideogram V3 node (character reference) * Support watching changes on connections. (#5250) * rename renderingSpeed default value from 'balanced' to 'default' * added missing type --------- Co-authored-by: AustinMroz <austin@comfy.org>	2025-09-01 10:54:36 -07:00
brucew4yn3rp	ddd7b4866f	Fixed Square Brush, Improve Brush Hardness and Smoothing Precision (#4519 ) * Fixed square brush with hardness <1; improved the effect of hardness, improved the effect of smoothing precision * Improved square hardness and code quality with performance optimizations * Fix brush rendering anti-aliasing and optimized square brushes using texture caching * Switched to QuickLRU for brush cache * Cleaned up exports from testing * Removed SOFT_BRUSH_STEPS unused variable	2025-08-31 15:29:24 -07:00
Benjamin Lu	e731f3b833	feat: Add Playwright browser caching to CI workflows (#5272 ) Improves CI performance by caching Playwright browsers between runs. This reduces the time spent downloading browsers on each workflow execution. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Claude <noreply@anthropic.com>	2025-08-31 13:42:22 -04:00
Benjamin Lu	b99e451f91	[fix] Improve Storybook comment workflow status handling (#5273 ) - Add condition to only run on version-bump branches - Handle additional build statuses (skipped, cancelled) with appropriate icons and messages - Improve readability by breaking long conditionals across multiple lines 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Claude <noreply@anthropic.com>	2025-08-31 13:42:09 -04:00
Jin Yi	f8b8b1c6ed	[feat] Enhance MultiSelect component and Storybook stories (#5154 )	2025-08-31 14:50:49 +09:00