Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions browser_tests/fixtures/agentPanelFixture.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,9 @@ const APP_URL = process.env.PLAYWRIGHT_TEST_URL || 'http://localhost:8188'

function agentFeatures(agentFlag: boolean): RemoteConfig {
return {
'agent-in-app-experience': agentFlag,
posthog_project_token: 'phc_e2e_agent_panel',
posthog_config: {
advanced_disable_flags: true,
bootstrap: {
featureFlags: { 'agent-in-app-experience': agentFlag }
}
}
posthog_config: { advanced_disable_flags: true }
}
}

Expand Down
8 changes: 2 additions & 6 deletions browser_tests/tests/agent/agentPanelMocks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -143,13 +143,9 @@ export const MESSAGE_DONE_EVENT: AgentWsEvent = {

function agentFeatures(agentFlag: boolean): RemoteConfig {
return {
'agent-in-app-experience': agentFlag,
posthog_project_token: 'phc_e2e_agent_panel',
posthog_config: {
advanced_disable_flags: true,
bootstrap: {
featureFlags: { 'agent-in-app-experience': agentFlag }
}
}
posthog_config: { advanced_disable_flags: true }
}
}

Expand Down
6 changes: 2 additions & 4 deletions browser_tests/tests/agent/agentPaywallSubscribe.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,9 @@ async function reconfigureBilling(
{ subscriptionRequired }: { subscriptionRequired: boolean }
): Promise<void> {
const features: RemoteConfig = {
'agent-in-app-experience': true,
posthog_project_token: 'phc_e2e_agent_panel',
posthog_config: {
advanced_disable_flags: true,
bootstrap: { featureFlags: { 'agent-in-app-experience': true } }
},
posthog_config: { advanced_disable_flags: true },
subscription_required: subscriptionRequired
}
await page.route('**/api/features', (route) =>
Expand Down
148 changes: 118 additions & 30 deletions docs/FEATURE_FLAGS.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,10 +129,8 @@ classDiagram
}

class useFeatureFlags {
+serverSupports(name) boolean
+getServerFeature(name, default) T
+createServerFeatureFlag(name) ComputedRef
+extension: ExtensionFlags
+flags: Readonly~ReactiveFlags~
+featureFlag(path, default) ComputedRef
}

class VueComponent {
Expand Down Expand Up @@ -209,8 +207,8 @@ SERVER_FEATURE_FLAGS = {
**Frontend Usage:**

```typescript
const { getServerFeature } = useFeatureFlags()
const maxUploadSize = getServerFeature('max_upload_size', 100 * 1024 * 1024) // Default 100MB
const { flags } = useFeatureFlags()
const maxUploadSize = flags.maxUploadSize
```

## Using Feature Flags
Expand All @@ -231,25 +229,42 @@ const maxSize = api.getServerFeature('max_upload_size', 100 * 1024 * 1024)

2. **Using the composable (recommended for reactive components):**

`useFeatureFlags()` returns `{ flags, featureFlag }`.

`flags` is a readonly reactive object of named, camelCase properties. Most
correspond to an entry in the `ServerFeatureFlag` enum; a few resolve a bare
string path instead (`assetsEnabled` reads `'assets'`). Each is a getter, so
reading it always reflects the current value and tracks reactively:

```typescript
const { serverSupports, getServerFeature, extension } = useFeatureFlags()
const { flags } = useFeatureFlags()

// Check feature support
if (serverSupports('supports_preview_metadata')) {
if (flags.supportsPreviewMetadata) {
// Use enhanced previews
}

// Use reactive convenience properties (automatically update if flags change)
if (extension.manager.supportsV4.value) {
// Nested extension flags are exposed as named properties too
if (flags.supportsManagerV4) {
// Use V4 manager API
}
```

`featureFlag(path, defaultValue)` returns a `ComputedRef` for a flag that has no
named property yet. It accepts dot-separated paths for nested flags:

```typescript
const { featureFlag } = useFeatureFlags()

const customFlag = featureFlag('extension.custom.nested.feature', false)
console.log(customFlag.value)
```

3. **Reactive usage in templates:**

```vue
<template>
<div v-if="featureFlags.extension.manager.supportsV4">
<div v-if="flags.supportsManagerV4">
<!-- V4-specific UI -->
</div>
<div v-else>
Expand All @@ -259,10 +274,69 @@ if (extension.manager.supportsV4.value) {

<script setup>
import { useFeatureFlags } from '@/composables/useFeatureFlags'
const featureFlags = useFeatureFlags()

const { flags } = useFeatureFlags()
</script>
```

### Flag Resolution Order

Getters built on the `resolveFlag()` helper in
`src/composables/useFeatureFlags.ts` do not read the server value directly.
They resolve in this order, first match wins:

1. **Session override** — `getSessionOverride()`
(`src/utils/sessionFeatureFlagOverride.ts`)
2. **Dev override** — `getDevOverride()`
(`src/utils/devFeatureFlagOverride.ts`)
3. **Remote config** — the matching `remoteConfig.value.*` field, when the
getter passes one
4. **Server feature flag** — `api.getServerFeature(flagKey, defaultValue)`

Getters that call `api.getServerFeature()` directly — `supportsPreviewMetadata`,
`maxUploadSize`, `supportsManagerV4`, `nodeReplacementsEnabled`,
`showSignInButton` — skip the override layers entirely.

Three variants exist alongside `resolveFlag()`:

- `resolveAuthGatedFlag()` — for per-user Cloud-only flags that select backend
behaviour. Always `false` off the Cloud build, and while authenticated config
is still loading it falls back to the cached session value so anonymous
bootstrap config cannot route the user to the wrong backend.
- `resolveStrictBooleanFlag()` — returns `true` only for a literal `true`,
and `false` if the read throws.
- `resolveWhitelistFlag()` — for per-user allowlists that gate a visible
surface. Always `false` off the Cloud build and before the first
authenticated answer. After one, a failed refresh falls back to that
answer — held in memory for the session only, never in storage, because a
persisted grant makes two browsers disagree for one account (PM-1707).

#### Dev overrides (local, `import.meta.env.DEV` only)

Stripped from production builds. Set a JSON value under an `ff:` prefix in
`localStorage`:

```js
localStorage.setItem('ff:linear_toggle_enabled', 'true')
localStorage.removeItem('ff:linear_toggle_enabled')
```

#### Session overrides (`?ff=` query parameter)

Captured into `sessionStorage` under `Comfy.FeatureFlagOverride` and scoped to
the tab. These apply **only to a signed-in Comfy employee** with a verified
`@comfy.org` address, so a link handed to a customer stays inert.

| URL | Effect |
| ----------------------- | ------------------------------------- |
| `?ff=some_flag` | Sets the flag to `true` |
| `?ff=some_flag:false` | Sets the boolean `false` |
| `?ff=some_flag:12` | Sets the number `12` |
| `?ff=some_flag:"12"` | Sets the string `"12"` |
| `?ff=some_flag:enforce` | Unparseable JSON is taken as a string |
| `?ff=a&ff=b:2` | Multiple overrides merge into the tab |
| `?ff=` | Clears every override in the session |

### Backend Access Patterns

```python
Expand Down Expand Up @@ -310,34 +384,47 @@ if feature_flags.supports_feature(sockets_metadata, sid, "your_new_feature"):

```json
{
"supports_preview_metadata": false,
"supports_preview_metadata": true,
"supports_manager_v4_ui": true,
"supports_progress_text_metadata": true,
"your_new_feature": true
}
```

2. **For extension features**, update the composable to add convenience accessors:
2. **For server or extension features**, add the flag path to the
`ServerFeatureFlag` enum and expose a named getter on the `flags` object in
`src/composables/useFeatureFlags.ts`. Nested extension flags use a
dot-separated path:

```typescript
// In useFeatureFlags.ts
const extension = {
manager: {
supportsV4: computed(() =>
getServerFeature('extension.manager.supports_v4', false)
)
},
yourExtension: {
supportsNewFeature: computed(() =>
getServerFeature('extension.yourExtension.supports_new_feature', false)
)
}
export enum ServerFeatureFlag {
// ... existing entries
YOUR_EXTENSION_NEW_FEATURE = 'extension.yourExtension.supports_new_feature'
}

return {
// ... existing returns
extension
export function useFeatureFlags() {
const flags = reactive({
// ... existing getters
get yourExtensionNewFeature() {
return api.getServerFeature(
ServerFeatureFlag.YOUR_EXTENSION_NEW_FEATURE,
false
)
}
})
// ...
}
```

The telemetry sweep in `startFeatureFlagTelemetry()` is an explicit list, not a
loop over the enum — adding an enum entry does not enrol the flag. Add a
matching line to the `evaluations` object there so its evaluated value is
reported.

For a one-off flag that does not warrant a named property, call
`featureFlag(path, defaultValue)` at the call site instead.

## Testing Feature Flags

```mermaid
Expand All @@ -364,14 +451,15 @@ Test your feature flags with different combinations:

```typescript
// Example from a colocated unit test
// `serverFeatureFlags` is a ref, so assign through `.value`
it('should handle preview metadata based on feature flag', () => {
// Mock server supports feature
api.serverFeatureFlags = { supports_preview_metadata: true }
api.serverFeatureFlags.value = { supports_preview_metadata: true }

expect(api.serverSupportsFeature('supports_preview_metadata')).toBe(true)

// Mock server doesn't support feature
api.serverFeatureFlags = {}
api.serverFeatureFlags.value = {}

expect(api.serverSupportsFeature('supports_preview_metadata')).toBe(false)
})
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ within an enabled lifetime retain their existing state-vector recovery behavior.
### Current gate map

```text
PostHog agent-in-app-experience ─┐
/features agent-in-app-experience ─┐
existing development override ──┴─> agentPanelStore.enabled
├─> docked panel mount
├─> follower lifetime / transport
Expand All @@ -250,13 +250,12 @@ host document updates ─> follower ─> frontend stores / canvas
human semantic operations ─> host applier (never raw shared-doc writes)
```

`src/extensions/core/agentPanel.ts` currently obtains the product flag from
`utils/postHogFlagSource.ts`. It retains the existing development-mode override
and settles the panel gate separately from flag enablement. The general
`useFeatureFlags` pipeline exists, but is not yet the agent flag's source on
main. [The pending feature-pipeline migration](https://github.com/Comfy-Org/ComfyUI_frontend/pull/16208)
changes that producer; the follower continues to consume the same store rather
than adding a second PostHog or server-feature reader.
`src/extensions/core/agentPanel.ts` now obtains the product flag from the
general `useFeatureFlags` pipeline, backed by the server-evaluated `/features`
payload; `utils/postHogFlagSource.ts` has been removed. It retains the existing
development-mode override and settles the panel gate separately from flag
enablement. The follower continues to consume the same store rather than adding
a second server-feature reader.

| Surface | Product transport control | Diagnostics |
| ------------- | ------------------------------------------------------- | -------------------------------------------------------- |
Expand Down
Loading
Loading