fix(playground): address review blockers on the secret changes

The docs pages also mount ItemVariableResolverProvider, so hardcoding
withExternalSecrets there resolved external secrets in the docs too.
It now follows the writable flag, and the unit test asserts through that
provider rather than one the docs never use.

A literal {{$secrets.foo}} provider reference lost its read-only note
when the scope was dropped from getReadOnlyNote. The note now keys off
whether the variable is editable, which separates a provider reference
from a declared external secret without a second scope label.

Rebuilding external secret rows in the environments editor dropped the
session value written by the hover card. The merge moved to a tested
helper in utils/environments.

Replaced a vacuous playground assertion: the card portals to
document.body so it is never inside playground-view, and no snippet is
rendered there at all.

Author: sundram-bruno

packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts

@@ -133,10 +133,14 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.value).toHaveText('*'.repeat('vault-value'.length));
   });
 
-  test('a typed secret never reaches the generated code snippet', async ({ playground }) => {
+  test('a typed secret stays masked in the card until revealed', async ({ playground }) => {
     await playground.variable.hoverInputToken('unsetSecret');
     await playground.variable.editTo('typed-secret');
 
-    await expect(playground.view).not.toContainText('typed-secret');
+    await expect(playground.variable.card).not.toContainText('typed-secret');
+
+    await playground.variable.revealToggle.click();
+
+    await expect(playground.variable.card).toContainText('typed-secret');
   });
 });

packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts

@@ -75,6 +75,16 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.copyButton).toHaveCount(0);
   });
 
+  // External secrets are fillable in the playground only; the docs must not resolve them.
+  test('leaves an external secret undefined', async ({ requestPage }) => {
+    const { variableCard } = requestPage;
+    await variableCard.hoverToken('vaultKey');
+
+    await expect(variableCard.card).toBeVisible();
+    await expect(variableCard.scopeBadge).toHaveText('Undefined');
+    await expect(variableCard.note).toHaveText('Variable is not defined');
+  });
+
   test('shows an (empty) placeholder with no copy for a defined variable that has no value', async ({ requestPage }) => {
     const { variableCard } = requestPage;
     await variableCard.hoverToken('emptyValue');

packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx

@@ -13,7 +13,7 @@ import { variableTypeColumn } from '../Common/VariableTypeControl/variableTypeCo
 import { GlobeIcon } from '../../../../../assets/icons';
 import { useAppDispatch } from '../../../../../store/hooks';
 import { cx } from '../../../../../utils/cx';
-import { envVariableToRow, envRowToVariable } from '../../../../../utils/environments';
+import { envVariableToRow, envRowToVariable, mergeExternalSecretRows } from '../../../../../utils/environments';
 import { isSecretVariable } from '../../../../../utils/variableResolution';
 import { updateCollectionEnvironments } from '@slices/playground';
 
@@ -100,11 +100,7 @@ const EnvironmentsView: React.FC<EnvironmentsViewProps> = ({ collection, compact
     applyToSelectedEnv({
       externalSecrets: {
         ...(selectedEnvironment?.externalSecrets ?? {}),
-        variables: rows.map((row) => ({
-          name: row.name,
-          [secretPointerField]: row.value,
-          disabled: !row.enabled
-        }))
+        variables: mergeExternalSecretRows(selectedEnvironment?.externalSecrets?.variables, rows, secretPointerField)
       }
     });
 

packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx

@@ -89,9 +89,21 @@ describe('VariableInfoCard', () => {
     expect(root.querySelector(selector('copy'))).toBeNull();
   });
 
-  // External secrets are a playground affordance; the docs leave them unresolved.
-  it('does not resolve an external secret', () => {
+  // PageRouter wraps the docs pages in ItemVariableResolverProvider without
+  // `writable`, so that mount must leave external secrets unresolved too.
+  it('does not resolve an external secret on either docs provider', () => {
     expect(part(useRenderToDom(cardTree('vaultKey')), 'scope').text).toBe('Undefined');
+
+    const store = createOpenCollectionStore();
+    store.dispatch(setActiveEnv('Dev'));
+    const docsItemTree = (
+      <Provider store={store}>
+        <ItemVariableResolverProvider collection={collection} ancestry={[]} item={null}>
+          <VariableInfoCard name="vaultKey" />
+        </ItemVariableResolverProvider>
+      </Provider>
+    );
+    expect(part(useRenderToDom(docsItemTree), 'scope').text).toBe('Undefined');
   });
 
   it('pretty-prints an object-typed value', () => {

packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx

@@ -17,8 +17,14 @@ interface VariableInfoCardProps {
   testId?: string;
 }
 
-const getReadOnlyNote = (scope: VariableScope, activeEnvName: string | null): string | null => {
+/**
+ * `$secrets` covers two things: a literal `{{$secrets.x}}` provider reference,
+ * which nothing here can resolve, and an environment's declared external secret,
+ * which the playground can fill in. Only the latter is editable.
+ */
+const getReadOnlyNote = (scope: VariableScope, activeEnvName: string | null, canEdit: boolean): string | null => {
   if (scope === 'process.env' || scope === 'oauth2') return 'read-only';
+  if (scope === '$secrets' && !canEdit) return 'read-only';
   if (scope === 'undefined') return activeEnvName ? 'Variable is not defined' : 'No active environment';
   return null;
 };
@@ -130,7 +136,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     );
   }
 
-  const readOnlyNote = getReadOnlyNote(info.scope, activeEnvName);
+  const readOnlyNote = getReadOnlyNote(info.scope, activeEnvName, canEdit);
   const emptyLabel = !secretFillable && info.value === '' ? '(empty)' : null;
   const placeholder = info.secret && !editable ? '(Secret)' : canEdit ? null : emptyLabel;
 

packages/bruno-api-docs/src/hooks/useVariableResolver.tsx

@@ -120,7 +120,7 @@ const externalSecretVariables = (environment: Environment | undefined): SecretVa
     .filter((entry) => entry.name && entry.disabled !== true)
     .map((entry) => ({ name: entry.name, secret: true, value: entry.value ?? '' }) as unknown as SecretVariable);
 
-/** `withExternalSecrets` is playground-only; the docs leave them unresolved. */
+/** `withExternalSecrets` tracks the writable (playground) mount; docs leave them unresolved. */
 const collectionAndEnvSources = (
   collection: OpenCollection | null,
   activeEnvName: string | null,
@@ -211,14 +211,16 @@ export const ItemVariableResolverProvider: React.FC<{
   const activeEnvName = useAppSelector(selectActiveEnvName);
   const showVars = useAppSelector(selectShowVars);
 
+  // This provider also backs the rendered docs pages, which pass no `writable`.
+  // Only the writable (playground) mount folds in external secrets.
   const model = useMemo(() => {
-    const sources: VariableSource[] = collectionAndEnvSources(collection, activeEnvName, true);
+    const sources: VariableSource[] = collectionAndEnvSources(collection, activeEnvName, writable);
     for (const folder of ancestry) {
       sources.push({ scope: 'folder', variables: folderVariables(folder) });
     }
     if (item) sources.push(itemSource(item));
     return buildScopedVariableModel(sources);
-  }, [collection, activeEnvName, ancestry, item]);
+  }, [collection, activeEnvName, ancestry, item, writable]);
 
   const resolver = useMemo(() => makeResolver(model, showVars, activeEnvName), [model, showVars, activeEnvName]);
 

packages/bruno-api-docs/src/utils/environments.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { getEnvironmentVariables, envVariableToRow, envRowToVariable } from './environments';
+import { getEnvironmentVariables, envVariableToRow, envRowToVariable, mergeExternalSecretRows } from './environments';
 
 describe('getEnvironmentVariables', () => {
   it('splits regular and secret variables', () => {
@@ -274,3 +274,40 @@ describe('envVariableToRow / envRowToVariable round-trip', () => {
     expect(out.value).toBe('new-token');
   });
 });
+
+describe('mergeExternalSecretRows', () => {
+  const existing = [
+    { name: 'vaultKey', secretName: 'prod/api-key', value: 'typed-this-session' },
+    { name: 'dbPassword', secretName: 'prod/db' }
+  ];
+
+  it('keeps a session value when another field on the row is edited', () => {
+    const rows = [
+      { name: 'vaultKey', value: 'prod/api-key-renamed', enabled: true },
+      { name: 'dbPassword', value: 'prod/db', enabled: true }
+    ];
+
+    const out = mergeExternalSecretRows(existing, rows, 'secretName') as Record<string, string | boolean>[];
+
+    expect(out[0].value).toBe('typed-this-session');
+    expect(out[0].secretName).toBe('prod/api-key-renamed');
+    expect(out[1].value).toBeUndefined();
+  });
+
+  it('carries the session value through a disable toggle', () => {
+    const rows = [{ name: 'vaultKey', value: 'prod/api-key', enabled: false }];
+
+    const out = mergeExternalSecretRows(existing, rows, 'secretName') as Record<string, string | boolean>[];
+
+    expect(out[0].value).toBe('typed-this-session');
+    expect(out[0].disabled).toBe(true);
+  });
+
+  it('adds a brand new row with no carried fields', () => {
+    const rows = [{ name: 'fresh', value: 'prod/fresh', enabled: true }];
+
+    const out = mergeExternalSecretRows(existing, rows, 'secretName') as Record<string, string | boolean>[];
+
+    expect(out).toEqual([{ name: 'fresh', secretName: 'prod/fresh', disabled: false }]);
+  });
+});

packages/bruno-api-docs/src/utils/environments.ts

@@ -76,6 +76,25 @@ interface ExternalSecretsConfig {
   variables?: { name?: string; secretName?: string; enabled?: boolean; type?: VariableValueType }[];
 }
 
+/**
+ * Rebuild an environment's external secrets from edited rows, carrying over any
+ * field the row model does not round-trip. The hover card writes a session
+ * `value` onto these entries, and rebuilding a row from scratch would drop it.
+ */
+export const mergeExternalSecretRows = (
+  existing: { name?: string }[] | undefined,
+  rows: { name: string; value: string; enabled: boolean }[],
+  pointerField: string
+): Record<string, unknown>[] => {
+  const byName = new Map((existing ?? []).map((variable) => [variable.name, variable]));
+  return rows.map((row) => ({
+    ...(byName.get(row.name) ?? {}),
+    name: row.name,
+    [pointerField]: row.value,
+    disabled: !row.enabled
+  }));
+};
+
 export interface EnvironmentVariableRow {
   name: string;
   value: string;