From 22c89d479ef108da8630d44ce0cb28beee324c18 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Thu, 30 Jul 2026 22:40:14 +0530
Subject: [PATCH 01/25] fix(playground): place caret at end when editing a
 variable value

---
 .../tests/playground/playground-variables.spec.ts   | 13 +++++++++++++
 .../VariableInfoCard/VariableInfoCard.tsx           |  7 +++++++
 2 files changed, 20 insertions(+)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index f8cc71ed..14edebd9 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -84,4 +84,17 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await playground.variable.value.click();
     await expect(playground.variable.editField).toHaveCount(0);
   });
+
+  test('clicking the value puts the caret at the end, not the start', async ({ playground }) => {
+    await playground.variable.hoverInputToken('host');
+    await playground.variable.value.click();
+
+    const caret = await playground.variable.editField.evaluate(
+      (el: HTMLTextAreaElement) => ({ start: el.selectionStart, end: el.selectionEnd, length: el.value.length })
+    );
+
+    expect(caret.length).toBeGreaterThan(0);
+    expect(caret.start).toBe(caret.length);
+    expect(caret.end).toBe(caret.length);
+  });
 });
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 2b9066a1..0aa45c79 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -37,6 +37,13 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     el.style.height = `${el.scrollHeight}px`;
   }, [editing, draft]);
 
+  useLayoutEffect(() => {
+    const el = editRef.current;
+    if (!editing || !el) return;
+    const end = el.value.length;
+    el.setSelectionRange(end, end);
+  }, [editing]);
+
   const canEdit
     = editable
       && canWrite

From e27164c886010fac62f244297d80b67a46fd8f44 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Thu, 30 Jul 2026 23:00:22 +0530
Subject: [PATCH 02/25] fix(playground): show the copy control in every
 variable card state

The copy button lived inside the editable and read-only display branches,
so it vanished while the value was being edited and never rendered on the
(Secret) or (empty) placeholders. Render it as a sibling of the value node
instead, matching the desktop app where the icons row is built once.
---
 .../playground/playground-variables.spec.ts   | 10 ++++
 .../variableInfoPopup.spec.ts                 | 10 ++--
 .../VariableInfoCard/StyledWrapper.ts         |  2 +-
 .../VariableInfoCard.spec.tsx                 | 18 +++++--
 .../VariableInfoCard/VariableInfoCard.tsx     | 53 +++++++++----------
 5 files changed, 55 insertions(+), 38 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 14edebd9..89e38b9f 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -97,4 +97,14 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     expect(caret.start).toBe(caret.length);
     expect(caret.end).toBe(caret.length);
   });
+
+  test('the copy control stays available while the value is being edited', async ({ playground }) => {
+    await playground.variable.hoverInputToken('host');
+    await expect(playground.variable.copyButton).toHaveCount(1);
+
+    await playground.variable.startEditing('https://edited.example.com');
+
+    await expect(playground.variable.editField).toBeVisible();
+    await expect(playground.variable.copyButton).toHaveCount(1);
+  });
 });
diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index 6f660e5a..a552fa18 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -72,17 +72,17 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
     await expect(variableCard.value).toHaveText('(Secret)');
-    await expect(variableCard.copyButton).toHaveCount(0);
+    await expect(variableCard.copyButton).toHaveCount(1);
   });
 
-  test('shows an (empty) placeholder with no copy for a defined variable that has no value', async ({ requestPage }) => {
+  test('shows an (empty) placeholder for a defined variable that has no value', async ({ requestPage }) => {
     const { variableCard } = requestPage;
     await variableCard.hoverToken('emptyValue');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
     await expect(variableCard.value).toHaveText('(empty)');
-    await expect(variableCard.copyButton).toHaveCount(0);
+    await expect(variableCard.copyButton).toHaveCount(1);
   });
 
   test('pretty-prints an object-typed value', async ({ requestPage }) => {
@@ -110,7 +110,7 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.note).toContainText('random value');
   });
 
-  test('shows a (Secret) placeholder with no reveal or copy, never exposing the value', async ({ requestPage }) => {
+  test('shows a (Secret) placeholder with no reveal, never exposing the value', async ({ requestPage }) => {
     const { variableCard } = requestPage;
     await variableCard.pinToken('bearer_token');
 
@@ -119,7 +119,7 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.value).toHaveText('(Secret)');
     await expect(variableCard.card).not.toContainText('super-secret-token');
     await expect(variableCard.revealToggle).toHaveCount(0);
-    await expect(variableCard.copyButton).toHaveCount(0);
+    await expect(variableCard.copyButton).toHaveCount(1);
   });
 
   test('copies the resolved value from the copy button', async ({ page, requestPage }) => {
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
index dcdb111c..a0d38f71 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
@@ -95,7 +95,7 @@ export const StyledWrapper = styled.div`
     display: block;
     width: 100%;
     margin: 0;
-    padding: 0;
+    padding: 0 1.5rem 0 0;
     font-family: var(--font-sans);
     font-size: 0.8125rem;
     font-weight: 400;
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index d505603b..cae0ee06 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -69,19 +69,29 @@ describe('VariableInfoCard', () => {
     expect(part(useRenderToDom(cardTree('endpoint')), 'value').text).toBe('https://dev.test/v1');
   });
 
-  it('shows a (Secret) placeholder with no reveal/copy and never prints the plaintext', () => {
+  it('shows a (Secret) placeholder with no reveal and never prints the plaintext', () => {
     const root = useRenderToDom(cardTree('bearer_token'));
     expect(part(root, 'value').text).toBe('(Secret)');
     expect(root.toString()).not.toContain('super-secret');
     expect(root.querySelector(selector('reveal'))).toBeNull();
-    expect(root.querySelector(selector('copy'))).toBeNull();
   });
 
-  it('shows an (empty) placeholder with no copy control when the value is blank', () => {
+  it('shows an (empty) placeholder when the value is blank', () => {
     const root = useRenderToDom(cardTree('emptyValue'));
     expect(part(root, 'scope').text).toBe('Environment');
     expect(part(root, 'value').text).toBe('(empty)');
-    expect(root.querySelector(selector('copy'))).toBeNull();
+  });
+
+  it('offers the copy control alongside a resolved value', () => {
+    expect(useRenderToDom(cardTree('host')).querySelector(selector('copy'))).not.toBeNull();
+  });
+
+  it('offers the copy control on the secret placeholder', () => {
+    expect(useRenderToDom(cardTree('bearer_token')).querySelector(selector('copy'))).not.toBeNull();
+  });
+
+  it('offers the copy control on the empty placeholder', () => {
+    expect(useRenderToDom(cardTree('emptyValue')).querySelector(selector('copy'))).not.toBeNull();
   });
 
   it('pretty-prints an object-typed value', () => {
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 0aa45c79..d76d2989 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -157,36 +157,30 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   );
 
   const editableDisplayNode = (
-    <>
-      <div
-        className="var-value-display var-value-editable"
-        data-testid={`${testId}-value`}
-        role="button"
-        tabIndex={0}
-        title="Click to edit"
-        onMouseDown={(event) => {
-          event.preventDefault();
-          startEditing();
-        }}
-        onKeyDown={(event) => {
-          if (event.key !== 'Enter' && event.key !== ' ') return;
-          event.preventDefault();
-          startEditing();
-        }}
-      >
-        {emptyLabel ?? info.value}
-      </div>
-      {copyButton}
-    </>
+    <div
+      className="var-value-display var-value-editable"
+      data-testid={`${testId}-value`}
+      role="button"
+      tabIndex={0}
+      title="Click to edit"
+      onMouseDown={(event) => {
+        event.preventDefault();
+        startEditing();
+      }}
+      onKeyDown={(event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        event.preventDefault();
+        startEditing();
+      }}
+    >
+      {emptyLabel ?? info.value}
+    </div>
   );
 
   const readOnlyDisplayNode = (
-    <>
-      <div className="var-value-display" data-testid={`${testId}-value`}>
-        {info.value}
-      </div>
-      {copyButton}
-    </>
+    <div className="var-value-display" data-testid={`${testId}-value`}>
+      {info.value}
+    </div>
   );
 
   const editableNode = editing ? editFieldNode : editableDisplayNode;
@@ -195,7 +189,10 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   return (
     <StyledWrapper className="variable-info-card" data-testid={testId}>
       {header}
-      <div className="var-value-container">{valueNode}</div>
+      <div className="var-value-container">
+        {valueNode}
+        {copyButton}
+      </div>
       {readOnlyNote && (
         <div className="var-readonly-note" data-testid={`${testId}-note`}>
           {readOnlyNote}

From cdba47f3959b29e28370adbff5542b62a7d347aa Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Thu, 30 Jul 2026 23:20:13 +0530
Subject: [PATCH 03/25] fix(playground): drop the copy control when there is no
 value to copy

CopyButton no-ops on an empty string, so rendering it for process.env,
undefined variables and blank values left a visible control that does
nothing.
---
 .../variableInfoPopup/variableInfoPopup.spec.ts     |  4 ++--
 .../VariableInfoCard/VariableInfoCard.spec.tsx      | 13 +++----------
 .../VariableInfoCard/VariableInfoCard.tsx           |  2 +-
 3 files changed, 6 insertions(+), 13 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index a552fa18..00f9ca9c 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -75,14 +75,14 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.copyButton).toHaveCount(1);
   });
 
-  test('shows an (empty) placeholder for a defined variable that has no value', async ({ requestPage }) => {
+  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');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
     await expect(variableCard.value).toHaveText('(empty)');
-    await expect(variableCard.copyButton).toHaveCount(1);
+    await expect(variableCard.copyButton).toHaveCount(0);
   });
 
   test('pretty-prints an object-typed value', async ({ requestPage }) => {
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index cae0ee06..8c642ad1 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -76,24 +76,17 @@ describe('VariableInfoCard', () => {
     expect(root.querySelector(selector('reveal'))).toBeNull();
   });
 
-  it('shows an (empty) placeholder when the value is blank', () => {
+  it('shows an (empty) placeholder with no copy control when the value is blank', () => {
     const root = useRenderToDom(cardTree('emptyValue'));
     expect(part(root, 'scope').text).toBe('Environment');
     expect(part(root, 'value').text).toBe('(empty)');
+    expect(root.querySelector(selector('copy'))).toBeNull();
   });
 
-  it('offers the copy control alongside a resolved value', () => {
-    expect(useRenderToDom(cardTree('host')).querySelector(selector('copy'))).not.toBeNull();
-  });
-
-  it('offers the copy control on the secret placeholder', () => {
+  it('offers the copy control on the secret placeholder, which has a value to copy', () => {
     expect(useRenderToDom(cardTree('bearer_token')).querySelector(selector('copy'))).not.toBeNull();
   });
 
-  it('offers the copy control on the empty placeholder', () => {
-    expect(useRenderToDom(cardTree('emptyValue')).querySelector(selector('copy'))).not.toBeNull();
-  });
-
   it('pretty-prints an object-typed value', () => {
     const value = part(useRenderToDom(cardTree('profile')), 'value').text;
     expect(JSON.parse(value)).toEqual({ city: 'NYC', zip: 10001 });
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index d76d2989..9586f726 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -122,7 +122,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   const emptyLabel = info.value === '' ? '(empty)' : null;
   const placeholder = info.secret ? '(Secret)' : canEdit ? null : emptyLabel;
 
-  const copyButton = (
+  const copyButton = info.value !== '' && (
     <div className="var-icons">
       <CopyButton
         text={info.value}

From e3b3c81493347963955e1c74d12cecabf01f4713 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Thu, 30 Jul 2026 23:35:38 +0530
Subject: [PATCH 04/25] feat(ui): show a green tick on copy and block repeat
 clicks

Matches the desktop copy button: the glyph swaps to a checkmark tinted
with the success token, the button is inert for the second the tick is
shown, and both glyphs use rounded stroke ends.

The tick is stroke="currentColor", so the tint is applied as the button's
colour, the same way brunoVarInfo.js does it.
---
 .../variableInfoPopup.spec.ts                 | 21 +++++++++++++
 .../VariableInfoCard/StyledWrapper.ts         |  6 ++++
 .../src/ui/CopyButton/CopyButton.spec.tsx     | 27 ++++++++++++-----
 .../src/ui/CopyButton/CopyButton.tsx          | 30 ++++++++++++++++---
 .../src/ui/CopyButton/StyledWrapper.ts        |  4 +++
 5 files changed, 77 insertions(+), 11 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index 00f9ca9c..585615f5 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -133,6 +133,27 @@ test.describe('Variable hover card', () => {
     await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe('2024-01');
   });
 
+  test('turns the copy glyph into a green tick while copied, then reverts', async ({ page, requestPage }) => {
+    const { variableCard } = requestPage;
+    await page.context().grantPermissions(['clipboard-read', 'clipboard-write']);
+
+    await variableCard.pinToken('apiVersion');
+    await expect(variableCard.card).toBeVisible();
+
+    const tick = variableCard.copyButton.locator('polyline');
+    await expect(tick).toHaveCount(0);
+
+    await variableCard.copyButton.click();
+
+    await expect(variableCard.copyButton).toHaveAttribute('data-copied', 'true');
+    await expect(tick).toHaveCount(1);
+    // The tick is stroke="currentColor", so the button's colour is the tick's colour.
+    await expect(variableCard.copyButton).toHaveAttribute('style', /--oc-status-success-text/);
+
+    await expect(variableCard.copyButton).not.toHaveAttribute('data-copied', 'true', { timeout: 3000 });
+    await expect(tick).toHaveCount(0);
+  });
+
   test('is read-only — no editor inside the card', async ({ requestPage }) => {
     const { variableCard } = requestPage;
     await variableCard.pinToken('host');
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
index a0d38f71..9b16587c 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
@@ -149,6 +149,12 @@ export const StyledWrapper = styled.div`
     background: transparent;
   }
 
+  .var-icons .copy-button[data-copied],
+  .var-icons .copy-button[data-copied]:hover {
+    opacity: 1;
+    cursor: default;
+  }
+
   .var-icons .copy-button:focus-visible {
     outline: 0.125rem solid var(--primary-color);
     outline-offset: 0.0625rem;
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx
index 2151fd71..406e43fa 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx
@@ -1,18 +1,31 @@
 import React from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
 import { describe, it, expect } from 'vitest';
+import { useRenderToDom } from '../../hooks/useRenderToDom';
+import { getByTestId } from '../../test-utils/dom';
 import { CopyButton } from './CopyButton';
 
 describe('CopyButton', () => {
   it('renders an accessible button with the default copy label', () => {
-    const html = renderToStaticMarkup(<CopyButton text="hello" />);
-    expect(html).toContain('<button');
-    expect(html).toContain('type="button"');
-    expect(html).toContain('aria-label="Copy"');
+    const button = getByTestId(useRenderToDom(<CopyButton text="hello" />), 'copy-button');
+    expect(button.tagName.toLowerCase()).toBe('button');
+    expect(button.getAttribute('type')).toBe('button');
+    expect(button.getAttribute('aria-label')).toBe('Copy');
   });
 
   it('uses the provided label', () => {
-    const html = renderToStaticMarkup(<CopyButton text="hello" label="Copy code" />);
-    expect(html).toContain('aria-label="Copy code"');
+    const button = getByTestId(useRenderToDom(<CopyButton text="hello" label="Copy code" />), 'copy-button');
+    expect(button.getAttribute('aria-label')).toBe('Copy code');
+  });
+
+  it('is not marked copied on first render', () => {
+    const root = useRenderToDom(<CopyButton text="hello" />);
+    expect(getByTestId(root, 'copy-button').getAttribute('data-copied')).toBeFalsy();
+  });
+
+  it('renders rounded stroke ends so the glyph matches the desktop app', () => {
+    const root = useRenderToDom(<CopyButton text="hello" />);
+    const svg = getByTestId(root, 'copy-button').querySelector('svg');
+    expect(svg?.getAttribute('stroke-linecap')).toBe('round');
+    expect(svg?.getAttribute('stroke-linejoin')).toBe('round');
   });
 });
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
index a15b4e63..d6979177 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
@@ -13,14 +13,34 @@ interface CopyButtonProps {
 }
 
 const CopyGlyph: React.FC = () => (
-  <svg width="1em" height="1em" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
+  <svg
+    width="1em"
+    height="1em"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
     <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
     <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
   </svg>
 );
 
 const CheckGlyph: React.FC = () => (
-  <svg width="1em" height="1em" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
+  <svg
+    width="1em"
+    height="1em"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
     <polyline points="20 6 9 17 4 12" />
   </svg>
 );
@@ -46,6 +66,7 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
   );
 
   const handleCopy = useCallback(async () => {
+    if (copied) return;
     if (!navigator.clipboard) return;
     const value = getText ? getText() : text;
     if (!value) return;
@@ -57,7 +78,7 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
     } catch {
       // Clipboard unavailable (e.g. insecure context) — fail silently.
     }
-  }, [text, getText, resetAfterMs]);
+  }, [copied, text, getText, resetAfterMs]);
 
   return (
     <StyledWrapper
@@ -65,8 +86,9 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
       className={['copy-button', className].filter(Boolean).join(' ')}
       onClick={handleCopy}
       aria-label={copied ? copiedLabel : label}
+      data-copied={copied ? 'true' : undefined}
       data-testid={testId}
-      style={style}
+      style={copied ? { color: 'var(--oc-status-success-text)', ...style } : style}
     >
       {copied ? <CheckGlyph /> : <CopyGlyph />}
     </StyledWrapper>
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts b/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts
index eab43ce3..236d8a25 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts
@@ -18,6 +18,10 @@ export const StyledWrapper = styled.button`
     background-color: var(--badge-bg);
   }
 
+  &[data-copied] {
+    cursor: default;
+  }
+
   &:focus-visible {
     outline: 2px solid var(--primary-color);
     outline-offset: 1px;

From f813ec500a808aa05600b1cbe4d5094beff17870 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Thu, 30 Jul 2026 23:41:40 +0530
Subject: [PATCH 05/25] refactor(ui): reuse baseIconProps for the copy glyphs

Both glyphs hand-repeated the nine attributes baseIconProps already
exports, including the rounded stroke ends. Also drops a redundant
:hover selector and renames the card's icons row after what it holds.
---
 .../VariableInfoCard/StyledWrapper.ts         |  3 +--
 .../VariableInfoCard/VariableInfoCard.tsx     |  4 +--
 .../src/ui/CopyButton/CopyButton.tsx          | 27 ++++---------------
 3 files changed, 8 insertions(+), 26 deletions(-)

diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
index 9b16587c..9b4a9cc8 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
@@ -149,8 +149,7 @@ export const StyledWrapper = styled.div`
     background: transparent;
   }
 
-  .var-icons .copy-button[data-copied],
-  .var-icons .copy-button[data-copied]:hover {
+  .var-icons .copy-button[data-copied] {
     opacity: 1;
     cursor: default;
   }
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 9586f726..ab8086b1 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -122,7 +122,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   const emptyLabel = info.value === '' ? '(empty)' : null;
   const placeholder = info.secret ? '(Secret)' : canEdit ? null : emptyLabel;
 
-  const copyButton = info.value !== '' && (
+  const icons = info.value !== '' && (
     <div className="var-icons">
       <CopyButton
         text={info.value}
@@ -191,7 +191,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
       {header}
       <div className="var-value-container">
         {valueNode}
-        {copyButton}
+        {icons}
       </div>
       {readOnlyNote && (
         <div className="var-readonly-note" data-testid={`${testId}-note`}>
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
index d6979177..ef7b9688 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
@@ -1,4 +1,5 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { baseIconProps } from '../../assets/icons/baseIconProps';
 import { StyledWrapper } from './StyledWrapper';
 
 interface CopyButtonProps {
@@ -12,35 +13,17 @@ interface CopyButtonProps {
   className?: string;
 }
 
+const glyphProps = { ...baseIconProps, width: '1em', height: '1em' };
+
 const CopyGlyph: React.FC = () => (
-  <svg
-    width="1em"
-    height="1em"
-    viewBox="0 0 24 24"
-    fill="none"
-    stroke="currentColor"
-    strokeWidth="2"
-    strokeLinecap="round"
-    strokeLinejoin="round"
-    aria-hidden="true"
-  >
+  <svg {...glyphProps}>
     <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
     <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
   </svg>
 );
 
 const CheckGlyph: React.FC = () => (
-  <svg
-    width="1em"
-    height="1em"
-    viewBox="0 0 24 24"
-    fill="none"
-    stroke="currentColor"
-    strokeWidth="2"
-    strokeLinecap="round"
-    strokeLinejoin="round"
-    aria-hidden="true"
-  >
+  <svg {...glyphProps}>
     <polyline points="20 6 9 17 4 12" />
   </svg>
 );

From cd7e13a44180aebcf84d80b377b33df67964aff0 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 00:09:04 +0530
Subject: [PATCH 06/25] feat(playground): make secrets fillable so a request
 can be sent with them

Secrets rendered a (Secret) placeholder and refused edits, so a request
needing one could not be sent from the playground. They now mask by
length, reveal behind an eye toggle, and accept a typed value.

External secrets ($secrets.name) are pointers with no value of their
own and were previously transmitted as literal text; they take a session
value too and resolve through the interpolator's existing dot-path
lookup, the same way process.env does.

Values live only on the in-memory playground collection, which is
rebuilt on reload and never serialized. Secrets stay out of the display
model, so the generated code snippet still shows {{name}}.
---
 .../playground/playground-variables.spec.ts   | 32 +++++++
 .../variableInfoPopup.spec.ts                 | 17 ++--
 .../VariableInfoCard/StyledWrapper.ts         | 55 ++++++++++++
 .../VariableInfoCard.spec.tsx                 | 30 +++++--
 .../VariableInfoCard/VariableInfoCard.tsx     | 88 +++++++++++++------
 .../src/e2eFixtures/variablesCollection.ts    |  9 +-
 .../src/hooks/useVariableResolver.tsx         | 29 ++++--
 packages/bruno-api-docs/src/runner/index.ts   | 20 ++++-
 .../src/runner/utils/variable-interpolator.ts |  8 +-
 .../src/store/slices/playground.spec.ts       | 29 +++++-
 .../src/store/slices/playground.ts            | 13 +--
 11 files changed, 266 insertions(+), 64 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 89e38b9f..b09c4906 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -107,4 +107,36 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.editField).toBeVisible();
     await expect(playground.variable.copyButton).toHaveCount(1);
   });
+
+  test('an unset secret starts blank with a reveal control and takes a typed value', async ({ playground }) => {
+    await playground.variable.hoverInputToken('unsetSecret');
+
+    await expect(playground.variable.value).toHaveText('');
+    await expect(playground.variable.revealToggle).toHaveCount(1);
+
+    await playground.variable.editTo('typed-secret');
+
+    await expect(playground.variable.value).toHaveText('*'.repeat('typed-secret'.length));
+
+    await playground.variable.revealToggle.click();
+    await expect(playground.variable.value).toHaveText('typed-secret');
+  });
+
+  test('an external secret is editable and keeps its Secret scope', async ({ playground }) => {
+    await playground.variable.hoverInputToken('$secrets.vaultKey');
+
+    await expect(playground.variable.scopeBadge).toHaveText('Secret');
+    await expect(playground.variable.value).toHaveText('');
+
+    await playground.variable.editTo('vault-value');
+
+    await expect(playground.variable.value).toHaveText('*'.repeat('vault-value'.length));
+  });
+
+  test('a typed secret never reaches the generated code snippet', async ({ playground }) => {
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.editTo('typed-secret');
+
+    await expect(playground.view).not.toContainText('typed-secret');
+  });
 });
diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index 585615f5..d1c0a57e 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -65,13 +65,13 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.value).toHaveText('https://api.dev.example.com');
   });
 
-  test('shows a (Secret) placeholder for a secret referenced in the request body', async ({ requestPage }) => {
+  test('masks a secret referenced in the request body', async ({ requestPage }) => {
     const { bodyVariableCard: variableCard } = requestPage;
     await variableCard.hoverToken('bearer_token');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
-    await expect(variableCard.value).toHaveText('(Secret)');
+    await expect(variableCard.value).toHaveText('*'.repeat('super-secret-token'.length));
     await expect(variableCard.copyButton).toHaveCount(1);
   });
 
@@ -110,16 +110,19 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.note).toContainText('random value');
   });
 
-  test('shows a (Secret) placeholder with no reveal, never exposing the value', async ({ requestPage }) => {
+  test('masks a secret until the reveal control is used', async ({ requestPage }) => {
     const { variableCard } = requestPage;
     await variableCard.pinToken('bearer_token');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
-    await expect(variableCard.value).toHaveText('(Secret)');
+    await expect(variableCard.value).toHaveText('*'.repeat('super-secret-token'.length));
     await expect(variableCard.card).not.toContainText('super-secret-token');
-    await expect(variableCard.revealToggle).toHaveCount(0);
     await expect(variableCard.copyButton).toHaveCount(1);
+
+    await variableCard.revealToggle.click();
+
+    await expect(variableCard.value).toHaveText('super-secret-token');
   });
 
   test('copies the resolved value from the copy button', async ({ page, requestPage }) => {
@@ -240,13 +243,13 @@ test.describe('Variable hover card — Overview page', () => {
     await expect(variableCard.value).toHaveText('2024-01');
   });
 
-  test('shows a (Secret) placeholder for a secret referenced in a collection header', async ({ overviewPage }) => {
+  test('masks a secret referenced in a collection header', async ({ overviewPage }) => {
     const { variableCard } = overviewPage;
     await variableCard.hoverToken('bearer_token');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
-    await expect(variableCard.value).toHaveText('(Secret)');
+    await expect(variableCard.value).toHaveText('*'.repeat('super-secret-token'.length));
   });
 });
 
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
index 9b4a9cc8..5beecd5b 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
@@ -66,6 +66,7 @@ export const StyledWrapper = styled.div`
   }
 
   .var-value-display {
+    min-height: 1.25rem;
     padding-right: 1.5rem;
     font-family: var(--font-sans);
     font-size: 0.8125rem;
@@ -113,6 +114,35 @@ export const StyledWrapper = styled.div`
     outline: none;
   }
 
+  .var-value-editor {
+    position: relative;
+  }
+
+  .var-value-mirror {
+    position: absolute;
+    top: 0;
+    right: 1.5rem;
+    left: 0;
+    visibility: hidden;
+    pointer-events: none;
+    font-family: var(--font-sans);
+    font-size: 0.8125rem;
+    font-weight: 400;
+    line-height: 1.25rem;
+    color: var(--text-primary);
+    white-space: pre-wrap;
+    word-break: break-all;
+  }
+
+  .var-value-editor--masked .var-value-mirror {
+    visibility: visible;
+  }
+
+  .var-value-editor--masked .var-value-edit {
+    color: transparent;
+    caret-color: var(--text-primary);
+  }
+
   .var-icons {
     position: absolute;
     top: 50%;
@@ -154,6 +184,31 @@ export const StyledWrapper = styled.div`
     cursor: default;
   }
 
+  .var-icons .reveal-button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0.125rem;
+    font-size: 0.875rem;
+    color: var(--text-secondary);
+    background: transparent;
+    border: none;
+    border-radius: var(--oc-radius);
+    opacity: 0.7;
+    cursor: pointer;
+    transition: opacity 0.15s ease, color 0.15s ease;
+  }
+
+  .var-icons .reveal-button:hover {
+    opacity: 1;
+    color: var(--text-primary);
+  }
+
+  .var-icons .reveal-button:focus-visible {
+    outline: 0.125rem solid var(--primary-color);
+    outline-offset: 0.0625rem;
+  }
+
   .var-icons .copy-button:focus-visible {
     outline: 0.125rem solid var(--primary-color);
     outline-offset: 0.0625rem;
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index 8c642ad1..0345df7c 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -24,6 +24,7 @@ const collection: any = {
           { name: 'host', value: 'https://dev.test' },
           { name: 'endpoint', value: '{{host}}/v1' },
           { name: 'bearer_token', value: 'super-secret', secret: true },
+          { name: 'unsetSecret', secret: true },
           { name: 'emptyValue', value: '' },
           {
             name: 'variantValue',
@@ -32,7 +33,11 @@ const collection: any = {
               { title: 'second', value: 'two' }
             ]
           }
-        ]
+        ],
+        externalSecrets: {
+          type: 'aws-secrets-manager',
+          variables: [{ name: 'vaultKey', secretName: 'prod/api-key' }]
+        }
       }
     ]
   }
@@ -69,11 +74,11 @@ describe('VariableInfoCard', () => {
     expect(part(useRenderToDom(cardTree('endpoint')), 'value').text).toBe('https://dev.test/v1');
   });
 
-  it('shows a (Secret) placeholder with no reveal and never prints the plaintext', () => {
+  it('masks a secret by length and offers reveal, without printing the plaintext', () => {
     const root = useRenderToDom(cardTree('bearer_token'));
-    expect(part(root, 'value').text).toBe('(Secret)');
+    expect(part(root, 'value').text).toBe('*'.repeat('super-secret'.length));
     expect(root.toString()).not.toContain('super-secret');
-    expect(root.querySelector(selector('reveal'))).toBeNull();
+    expect(root.querySelector(selector('reveal'))).not.toBeNull();
   });
 
   it('shows an (empty) placeholder with no copy control when the value is blank', () => {
@@ -83,10 +88,19 @@ describe('VariableInfoCard', () => {
     expect(root.querySelector(selector('copy'))).toBeNull();
   });
 
-  it('offers the copy control on the secret placeholder, which has a value to copy', () => {
+  it('offers the copy control on a secret, which has a value to copy', () => {
     expect(useRenderToDom(cardTree('bearer_token')).querySelector(selector('copy'))).not.toBeNull();
   });
 
+  it('shows a declared external secret as blank with a reveal and no copy', () => {
+    const root = useRenderToDom(cardTree('$secrets.vaultKey'));
+    expect(part(root, 'scope').text).toBe('Secret');
+    expect(part(root, 'value').text).toBe('');
+    expect(root.querySelector(selector('reveal'))).not.toBeNull();
+    expect(root.querySelector(selector('copy'))).toBeNull();
+    expect(root.querySelector(selector('note'))).toBeNull();
+  });
+
   it('pretty-prints an object-typed value', () => {
     const value = part(useRenderToDom(cardTree('profile')), 'value').text;
     expect(JSON.parse(value)).toEqual({ city: 'NYC', zip: 10001 });
@@ -185,10 +199,10 @@ describe('VariableInfoCard (editable)', () => {
     expect(value.classList.contains('var-value-placeholder')).toBe(false);
   });
 
-  it('never makes a secret variable editable', () => {
+  it('makes a secret editable so a value can be supplied for the request', () => {
     const value = part(useRenderToDom(editableCardTree('bearer_token')), 'value');
-    expect(value.text).toBe('(Secret)');
-    expect(value.classList.contains('var-value-editable')).toBe(false);
+    expect(value.text).toBe('*'.repeat('super-secret'.length));
+    expect(value.classList.contains('var-value-editable')).toBe(true);
   });
 
   it('never makes a read-only scope (process.env) editable', () => {
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index ab8086b1..a0719074 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -1,11 +1,15 @@
 import React, { useLayoutEffect, useRef, useState } from 'react';
 import { useResolvedVariables } from '../../hooks';
 import { CopyButton } from '../../ui/CopyButton/CopyButton';
+import { EyeIcon, EyeOffIcon } from '../../assets/icons';
 import { SCOPE_LABELS, INVALID_NAME_WARNING } from '../../constants';
 import type { VariableScope } from '../../utils/variableResolution';
 import { StyledWrapper } from './StyledWrapper';
 
-const EDITABLE_SCOPES = new Set<VariableScope>(['environment', 'collection', 'folder', 'request']);
+const EDITABLE_SCOPES = new Set<VariableScope>(['environment', 'collection', 'folder', 'request', '$secrets']);
+
+/** Scopes whose value the active environment supplies, so editing needs one selected. */
+const ENV_BOUND_SCOPES = new Set<VariableScope>(['environment', '$secrets']);
 
 interface VariableInfoCardProps {
   name: string;
@@ -14,11 +18,14 @@ interface VariableInfoCardProps {
 }
 
 const getReadOnlyNote = (scope: VariableScope, activeEnvName: string | null): string | null => {
-  if (scope === 'process.env' || scope === 'oauth2' || scope === '$secrets') return 'read-only';
+  if (scope === 'process.env' || scope === 'oauth2') return 'read-only';
   if (scope === 'undefined') return activeEnvName ? 'Variable is not defined' : 'No active environment';
   return null;
 };
 
+/** Masks per character so newlines survive and the mask lines up with the value. */
+const maskValue = (value: string): string => value.replace(/[^\n]/g, '*');
+
 export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   name,
   editable = false,
@@ -27,6 +34,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   const { lookup, activeEnvName, updateVariable, canWrite } = useResolvedVariables();
   const info = lookup(name);
   const [editing, setEditing] = useState(false);
+  const [revealed, setRevealed] = useState(false);
   const [draft, setDraft] = useState('');
   const editRef = useRef<HTMLTextAreaElement>(null);
 
@@ -48,10 +56,12 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     = editable
       && canWrite
       && info.valid
-      && !info.secret
       && info.simpleString
       && EDITABLE_SCOPES.has(info.scope)
-      && (info.scope !== 'environment' || !!activeEnvName);
+      && (!ENV_BOUND_SCOPES.has(info.scope) || !!activeEnvName);
+
+  const masked = info.secret && !revealed;
+  const displayValue = masked ? maskValue(info.value) : info.value;
 
   const startEditing = () => {
     setDraft(info.rawValue);
@@ -119,18 +129,33 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   }
 
   const readOnlyNote = getReadOnlyNote(info.scope, activeEnvName);
-  const emptyLabel = info.value === '' ? '(empty)' : null;
-  const placeholder = info.secret ? '(Secret)' : canEdit ? null : emptyLabel;
+  const emptyLabel = !info.secret && info.value === '' ? '(empty)' : null;
+  const placeholder = canEdit ? null : emptyLabel;
 
-  const icons = info.value !== '' && (
+  const icons = (info.value !== '' || info.secret) && (
     <div className="var-icons">
-      <CopyButton
-        text={info.value}
-        label="Copy value"
-        resetAfterMs={1000}
-        className="copy-button"
-        testId={`${testId}-copy`}
-      />
+      {info.secret && (
+        <button
+          type="button"
+          className="reveal-button"
+          aria-label={revealed ? 'Hide value' : 'Show value'}
+          aria-pressed={revealed}
+          data-testid={`${testId}-reveal`}
+          onMouseDown={(event) => event.preventDefault()}
+          onClick={() => setRevealed((previous) => !previous)}
+        >
+          {revealed ? <EyeOffIcon /> : <EyeIcon />}
+        </button>
+      )}
+      {info.value !== '' && (
+        <CopyButton
+          text={info.value}
+          label="Copy value"
+          resetAfterMs={1000}
+          className="copy-button"
+          testId={`${testId}-copy`}
+        />
+      )}
     </div>
   );
 
@@ -141,19 +166,24 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   );
 
   const editFieldNode = (
-    <textarea
-      ref={editRef}
-      className="var-value-edit"
-      data-testid={`${testId}-edit`}
-      aria-label={`Edit ${info.name}`}
-      value={draft}
-      autoFocus
-      rows={1}
-      spellCheck={false}
-      onChange={(event) => setDraft(event.target.value)}
-      onKeyDown={handleEditKeyDown}
-      onBlur={commit}
-    />
+    <div className={`var-value-editor${masked ? ' var-value-editor--masked' : ''}`}>
+      <div className="var-value-mirror" aria-hidden="true">
+        {maskValue(draft)}
+      </div>
+      <textarea
+        ref={editRef}
+        className="var-value-edit"
+        data-testid={`${testId}-edit`}
+        aria-label={`Edit ${info.name}`}
+        value={draft}
+        autoFocus
+        rows={1}
+        spellCheck={false}
+        onChange={(event) => setDraft(event.target.value)}
+        onKeyDown={handleEditKeyDown}
+        onBlur={commit}
+      />
+    </div>
   );
 
   const editableDisplayNode = (
@@ -173,13 +203,13 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
         startEditing();
       }}
     >
-      {emptyLabel ?? info.value}
+      {emptyLabel ?? displayValue}
     </div>
   );
 
   const readOnlyDisplayNode = (
     <div className="var-value-display" data-testid={`${testId}-value`}>
-      {info.value}
+      {displayValue}
     </div>
   );
 
diff --git a/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts b/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts
index e0a678ef..fa5d20ef 100644
--- a/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts
+++ b/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts
@@ -11,8 +11,13 @@ export const variablesFixtureCollection = {
           { name: 'host', value: 'https://api.dev.example.com' },
           { name: 'endpoint', value: '{{host}}/v1' },
           { name: 'bearer_token', value: 'super-secret-token', secret: true },
+          { name: 'unsetSecret', secret: true },
           { name: 'emptyValue', value: '' }
-        ]
+        ],
+        externalSecrets: {
+          type: 'aws-secrets-manager',
+          variables: [{ name: 'vaultKey', secretName: 'prod/payment/api-key' }]
+        }
       }
     ]
   },
@@ -48,7 +53,7 @@ export const variablesFixtureCollection = {
           type: 'http',
           seq: 1,
           method: 'GET',
-          url: '{{host}}/customers/{{userId}}?v={{apiVersion}}',
+          url: '{{host}}/customers/{{userId}}?v={{apiVersion}}&k={{$secrets.vaultKey}}&s={{unsetSecret}}',
           auth: { type: 'bearer', token: '{{bearer_token}}' },
           headers: [
             { name: 'Authorization', value: 'Bearer {{bearer_token}}' },
diff --git a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
index 4b7b6dd8..ba885984 100644
--- a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
+++ b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
@@ -18,7 +18,6 @@ import {
   isValidVariableName,
   formatEntryValue,
   referencesSecret,
-  isSecretVariable,
   type ScopedVariableModel,
   type VariableScope,
   type VariableSource
@@ -74,11 +73,12 @@ const lookupVariable = (rawName: string, model: ScopedVariableModel): VariableLo
 
   const special = detectSpecialScope(name);
   if (special === 'dynamic') return { ...base, scope: 'dynamic', valid: true, dynamicKind: classifyDynamic(name) };
-  if (special) return { ...base, scope: special, valid: true };
-  if (!isValidVariableName(name)) return { ...base, scope: 'undefined', valid: false };
+  // `$secrets` falls through so a declared external secret can carry a session value.
+  if (special && special !== '$secrets') return { ...base, scope: special, valid: true };
+  if (!special && !isValidVariableName(name)) return { ...base, scope: 'undefined', valid: false };
 
   const entry = model.entries[name];
-  if (!entry) return { ...base, scope: 'undefined', valid: true };
+  if (!entry) return { ...base, scope: special ?? 'undefined', valid: true };
 
   const safeValue = formatEntryValue(entry, model.values);
   const secret = entry.secret || model.secretNames.has(name) || referencesSecret(safeValue, model.secretNames);
@@ -110,13 +110,24 @@ const makeResolver = (
   };
 };
 
+/**
+ * External secrets are declared as `{ name, secretName }` pointers with no value
+ * of their own. They surface as `$secrets.<name>` entries so the hover card can
+ * show and edit the session value typed into the in-memory collection.
+ */
+const externalSecretVariables = (environment: Environment | undefined): SecretVariable[] =>
+  ((environment?.externalSecrets?.variables ?? []) as { name?: string; disabled?: boolean; value?: string }[])
+    .filter((entry) => entry.name && entry.disabled !== true)
+    .map((entry) => ({ name: `$secrets.${entry.name}`, secret: true, value: entry.value ?? '' }) as unknown as SecretVariable);
+
 const collectionAndEnvSources = (collection: OpenCollection | null, activeEnvName: string | null): VariableSource[] => {
   const collectionVariables = (collection?.request?.variables ?? []) as (Variable | SecretVariable)[];
   const environments = (collection?.config?.environments ?? []) as Environment[];
   const activeEnvironment = environments.find((environment) => environment.name === activeEnvName);
   return [
     { scope: 'collection', variables: collectionVariables },
-    { scope: 'environment', variables: activeEnvironment?.variables }
+    { scope: 'environment', variables: activeEnvironment?.variables },
+    { scope: '$secrets', variables: externalSecretVariables(activeEnvironment) }
   ];
 };
 
@@ -208,7 +219,11 @@ export const ItemVariableResolverProvider: React.FC<{
   const updateVariable = useCallback(
     (name: string, value: string) => {
       const { name: varName, scope } = resolver.lookup(name);
-      if (scope === 'environment') {
+      if (scope === '$secrets') {
+        // The store keys external secrets by their bare name, not the `$secrets.` reference.
+        const secretName = varName.slice('$secrets.'.length);
+        if (activeEnvName) dispatch(setPlaygroundVariable({ scope, name: secretName, value, envName: activeEnvName }));
+      } else if (scope === 'environment') {
         if (activeEnvName) dispatch(setPlaygroundVariable({ scope, name: varName, value, envName: activeEnvName }));
       } else if (scope === 'collection') {
         dispatch(setPlaygroundVariable({ scope, name: varName, value }));
@@ -217,7 +232,7 @@ export const ItemVariableResolverProvider: React.FC<{
         if (itemUuid) dispatch(setPlaygroundVariable({ scope, name: varName, value, itemUuid }));
       } else if (scope === 'folder') {
         const owner = [...ancestry].reverse().find((folder) =>
-          folderVariables(folder).some((v) => v.name === varName && !v.disabled && !isSecretVariable(v))
+          folderVariables(folder).some((v) => v.name === varName && !v.disabled)
         );
         const itemUuid = getItemUuid(owner);
         if (itemUuid) dispatch(setPlaygroundVariable({ scope, name: varName, value, itemUuid }));
diff --git a/packages/bruno-api-docs/src/runner/index.ts b/packages/bruno-api-docs/src/runner/index.ts
index bc5e26df..fa2f3d2e 100644
--- a/packages/bruno-api-docs/src/runner/index.ts
+++ b/packages/bruno-api-docs/src/runner/index.ts
@@ -101,7 +101,8 @@ export class RequestRunner {
         processEnvVars,
         collectionVariables,
         folderVariables,
-        requestVariables
+        requestVariables,
+        externalSecrets: this.getExternalSecrets(environment)
       };
       
       // Get scripts in object format for easier access
@@ -228,6 +229,23 @@ export class RequestRunner {
   }
 
 
+  /**
+   * External secrets are pointers to a provider the browser cannot reach, so only a
+   * value typed into the playground this session can resolve `{{$secrets.name}}`.
+   */
+  private getExternalSecrets(environment?: Environment): Record<string, string> {
+    const variables = (environment?.externalSecrets?.variables ?? []) as {
+      name?: string;
+      disabled?: boolean;
+      value?: string;
+    }[];
+
+    return variables.reduce((secrets, variable) => {
+      if (variable.name && !variable.disabled && variable.value) secrets[variable.name] = variable.value;
+      return secrets;
+    }, {} as Record<string, string>);
+  }
+
   private async preprocessRequest(
     item: HttpRequest, 
     collection: OpenCollectionCollection
diff --git a/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts b/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts
index 41b044e4..c975a851 100644
--- a/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts
+++ b/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts
@@ -126,6 +126,7 @@ export const interpolateVars = (
     runtimeVariables?: Record<string, any>;
     processEnvVars?: Record<string, any>;
     promptVariables?: Record<string, any>;
+    externalSecrets?: Record<string, string>;
   } = {}
 ): HttpRequest => {
   // Clone the request to avoid mutation
@@ -141,7 +142,8 @@ export const interpolateVars = (
     environmentVariables = {},
     runtimeVariables = {},
     processEnvVars = {},
-    promptVariables = {}
+    promptVariables = {},
+    externalSecrets = {}
   } = variableSources;
 
   const combinedVariables = {
@@ -157,6 +159,10 @@ export const interpolateVars = (
       env: {
         ...processEnvVars
       }
+    },
+    // `{{$secrets.name}}` resolves through the same dot-path lookup as process.env.
+    $secrets: {
+      ...externalSecrets
     }
   };
 
diff --git a/packages/bruno-api-docs/src/store/slices/playground.spec.ts b/packages/bruno-api-docs/src/store/slices/playground.spec.ts
index 78f76d9e..073d3842 100644
--- a/packages/bruno-api-docs/src/store/slices/playground.spec.ts
+++ b/packages/bruno-api-docs/src/store/slices/playground.spec.ts
@@ -155,16 +155,37 @@ describe('setPlaygroundVariable', () => {
     expect(item.variables.find((v) => v.name === 'rv').value).toBe('2');
   });
 
-  it('never writes to a secret variable', () => {
+  // The value lives only on this in-memory copy, so a request can be sent with a
+  // secret the published collection never carries.
+  it('writes a session value to a secret variable, keeping it marked secret', () => {
     const collection = makeCollection();
     collection.config.environments[0].variables.push({ name: 'sec', secret: true });
     const store = createOpenCollectionStore();
     store.dispatch(setPlaygroundCollection(collection));
 
-    store.dispatch(setPlaygroundVariable({ scope: 'environment', name: 'sec', value: 'leak', envName: 'Dev' }));
+    store.dispatch(setPlaygroundVariable({ scope: 'environment', name: 'sec', value: 'typed', envName: 'Dev' }));
 
-    const sec = envVariables(store).find((v: any) => v.name === 'sec');
-    expect((sec as any).value).toBeUndefined();
+    const sec = envVariables(store).find((v) => v.name === 'sec') as { value: string; secret: boolean };
+    expect(sec.value).toBe('typed');
+    expect(sec.secret).toBe(true);
+  });
+
+  it('writes a session value to an external secret pointer', () => {
+    const collection = makeCollection();
+    collection.config.environments[0].externalSecrets = {
+      type: 'aws-secrets-manager',
+      variables: [{ name: 'vaultKey', secretName: 'prod/api-key' }]
+    };
+    const store = createOpenCollectionStore();
+    store.dispatch(setPlaygroundCollection(collection));
+
+    store.dispatch(setPlaygroundVariable({ scope: '$secrets', name: 'vaultKey', value: 'typed', envName: 'Dev' }));
+
+    const env = selectHydratedCollection(store.getState())!.config!.environments![0] as unknown as {
+      externalSecrets: { variables: { value: string; secretName: string }[] };
+    };
+    expect(env.externalSecrets.variables[0].value).toBe('typed');
+    expect(env.externalSecrets.variables[0].secretName).toBe('prod/api-key');
   });
 });
 
diff --git a/packages/bruno-api-docs/src/store/slices/playground.ts b/packages/bruno-api-docs/src/store/slices/playground.ts
index d1c9dd81..0143ea87 100644
--- a/packages/bruno-api-docs/src/store/slices/playground.ts
+++ b/packages/bruno-api-docs/src/store/slices/playground.ts
@@ -8,7 +8,6 @@ import type { Variable, SecretVariable } from '@opencollection/types/common/vari
 import type { RootState } from '../store';
 import { hydrateWithUUIDs, findAndUpdateItem } from '../../utils/fileUtils';
 import { isFolder, getRequestVariables } from '../../utils/schemaHelpers';
-import { isSecretVariable } from '../../utils/variableResolution';
 
 export type ViewMode = 'playground' | 'environments' | 'folder-settings' | 'collection-settings' | 'example';
 
@@ -231,7 +230,7 @@ const playgroundSlice = createSlice({
     setPlaygroundVariable: (
       state: PlaygroundState,
       action: PayloadAction<{
-        scope: 'environment' | 'collection' | 'folder' | 'request';
+        scope: 'environment' | 'collection' | 'folder' | 'request' | '$secrets';
         name: string;
         value: string;
         envName?: string;
@@ -239,14 +238,18 @@ const playgroundSlice = createSlice({
       }>
     ) => {
       const { scope, name, value, envName, itemUuid } = action.payload;
+      // Secrets are writable here: the value lives only on this in-memory copy,
+      // which is rebuilt from the source collection on reload and never serialized.
       const setInList = (list: (Variable | SecretVariable)[] | undefined): void => {
         const enabled = (list ?? []).filter((v) => v.name === name && !v.disabled);
-        const variable = enabled[enabled.length - 1];
-        if (variable && !isSecretVariable(variable)) variable.value = value;
+        const variable = enabled[enabled.length - 1] as (Variable & { value?: string }) | undefined;
+        if (variable) variable.value = value;
       };
       const apply = (collection: OpenCollectionCollection | null) => {
         if (!collection) return;
-        if (scope === 'environment') {
+        if (scope === '$secrets') {
+          setInList(readEnvironments(collection)?.find((env) => env.name === envName)?.externalSecrets?.variables);
+        } else if (scope === 'environment') {
           setInList(readEnvironments(collection)?.find((env) => env.name === envName)?.variables);
         } else if (scope === 'collection') {
           setInList(collection.request?.variables as (Variable | SecretVariable)[] | undefined);

From dba0eaaa642bab8bbc60f888c784db2c17d24016 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 00:29:17 +0530
Subject: [PATCH 07/25] fix(playground): reference external secrets by bare
 name, not a $secrets prefix

Bruno has no $secrets namespace: an external secret's `name` is the
variable the collection references as {{name}}, and `secretName` only
says where a provider would fetch it. Keying entries by the bare name
makes {{vaultKey}} resolve and drops the interpolator bucket entirely,
since the runner now folds external secrets into the environment bag.

$secrets survives only as an internal scope, so the card can badge these
as Secret and mark them env-bound.

Fixture also gains folder- and collection-scoped secrets, referenced from
request headers, so every scope is verifiable.
---
 .../playground/playground-variables.spec.ts   |  2 +-
 .../VariableInfoCard.spec.tsx                 |  3 +-
 .../src/e2eFixtures/variablesCollection.ts    | 16 ++++++--
 .../src/hooks/useVariableResolver.tsx         | 26 ++++++------
 packages/bruno-api-docs/src/runner/index.ts   | 41 ++++++++-----------
 .../src/runner/utils/variable-interpolator.ts |  8 +---
 6 files changed, 46 insertions(+), 50 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index b09c4906..796e08ad 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -123,7 +123,7 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
   });
 
   test('an external secret is editable and keeps its Secret scope', async ({ playground }) => {
-    await playground.variable.hoverInputToken('$secrets.vaultKey');
+    await playground.variable.hoverInputToken('vaultKey');
 
     await expect(playground.variable.scopeBadge).toHaveText('Secret');
     await expect(playground.variable.value).toHaveText('');
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index 0345df7c..216e6bbe 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -92,8 +92,9 @@ describe('VariableInfoCard', () => {
     expect(useRenderToDom(cardTree('bearer_token')).querySelector(selector('copy'))).not.toBeNull();
   });
 
+  // An external secret is referenced by its bare name, like any other variable.
   it('shows a declared external secret as blank with a reveal and no copy', () => {
-    const root = useRenderToDom(cardTree('$secrets.vaultKey'));
+    const root = useRenderToDom(cardTree('vaultKey'));
     expect(part(root, 'scope').text).toBe('Secret');
     expect(part(root, 'value').text).toBe('');
     expect(root.querySelector(selector('reveal'))).not.toBeNull();
diff --git a/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts b/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts
index fa5d20ef..158d38eb 100644
--- a/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts
+++ b/packages/bruno-api-docs/src/e2eFixtures/variablesCollection.ts
@@ -35,7 +35,8 @@ export const variablesFixtureCollection = {
     variables: [
       { name: 'apiVersion', value: '2024-01' },
       { name: 'profile', value: { type: 'object', data: { city: 'NYC', zip: 10001 } } },
-      { name: 'exampleOnly', value: 'example-value' }
+      { name: 'exampleOnly', value: 'example-value' },
+      { name: 'collectionSecret', value: 'collection-secret-value', secret: true }
     ]
   },
   items: [
@@ -45,7 +46,10 @@ export const variablesFixtureCollection = {
       seq: 1,
       request: {
         headers: [{ name: 'X-Folder-Scope', value: '{{folderScope}}' }],
-        variables: [{ name: 'folderScope', value: 'from-folder' }]
+        variables: [
+          { name: 'folderScope', value: 'from-folder' },
+          { name: 'folderSecret', value: 'folder-secret-value', secret: true }
+        ]
       },
       items: [
         {
@@ -53,7 +57,7 @@ export const variablesFixtureCollection = {
           type: 'http',
           seq: 1,
           method: 'GET',
-          url: '{{host}}/customers/{{userId}}?v={{apiVersion}}&k={{$secrets.vaultKey}}&s={{unsetSecret}}',
+          url: '{{host}}/customers/{{userId}}?v={{apiVersion}}&k={{vaultKey}}&s={{unsetSecret}}',
           auth: { type: 'bearer', token: '{{bearer_token}}' },
           headers: [
             { name: 'Authorization', value: 'Bearer {{bearer_token}}' },
@@ -62,7 +66,11 @@ export const variablesFixtureCollection = {
             { name: 'X-Profile', value: '{{profile}}' },
             { name: 'X-Home', value: '{{process.env.HOME}}' },
             { name: 'X-Random', value: '{{$randomInt}}' },
-            { name: 'X-Empty', value: '{{emptyValue}}' }
+            { name: 'X-Empty', value: '{{emptyValue}}' },
+            { name: 'X-Collection-Secret', value: '{{collectionSecret}}' },
+            { name: 'X-Folder-Secret', value: '{{folderSecret}}' },
+            { name: 'X-Vault-Key', value: '{{vaultKey}}' },
+            { name: 'X-Unset-Secret', value: '{{unsetSecret}}' }
           ],
           body: {
             type: 'json',
diff --git a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
index ba885984..71b2a582 100644
--- a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
+++ b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
@@ -73,12 +73,11 @@ const lookupVariable = (rawName: string, model: ScopedVariableModel): VariableLo
 
   const special = detectSpecialScope(name);
   if (special === 'dynamic') return { ...base, scope: 'dynamic', valid: true, dynamicKind: classifyDynamic(name) };
-  // `$secrets` falls through so a declared external secret can carry a session value.
-  if (special && special !== '$secrets') return { ...base, scope: special, valid: true };
-  if (!special && !isValidVariableName(name)) return { ...base, scope: 'undefined', valid: false };
+  if (special) return { ...base, scope: special, valid: true };
+  if (!isValidVariableName(name)) return { ...base, scope: 'undefined', valid: false };
 
   const entry = model.entries[name];
-  if (!entry) return { ...base, scope: special ?? 'undefined', valid: true };
+  if (!entry) return { ...base, scope: 'undefined', valid: true };
 
   const safeValue = formatEntryValue(entry, model.values);
   const secret = entry.secret || model.secretNames.has(name) || referencesSecret(safeValue, model.secretNames);
@@ -111,23 +110,26 @@ const makeResolver = (
 };
 
 /**
- * External secrets are declared as `{ name, secretName }` pointers with no value
- * of their own. They surface as `$secrets.<name>` entries so the hover card can
- * show and edit the session value typed into the in-memory collection.
+ * External secrets are `{ name, secretName }` pointers: `name` is the variable
+ * the collection references as `{{name}}`, `secretName` only says where the
+ * provider would fetch it. The browser cannot reach the provider, so they carry
+ * whatever value was typed into the playground this session.
  */
 const externalSecretVariables = (environment: Environment | undefined): SecretVariable[] =>
   ((environment?.externalSecrets?.variables ?? []) as { name?: string; disabled?: boolean; value?: string }[])
     .filter((entry) => entry.name && entry.disabled !== true)
-    .map((entry) => ({ name: `$secrets.${entry.name}`, secret: true, value: entry.value ?? '' }) as unknown as SecretVariable);
+    .map((entry) => ({ name: entry.name, secret: true, value: entry.value ?? '' }) as unknown as SecretVariable);
 
 const collectionAndEnvSources = (collection: OpenCollection | null, activeEnvName: string | null): VariableSource[] => {
   const collectionVariables = (collection?.request?.variables ?? []) as (Variable | SecretVariable)[];
   const environments = (collection?.config?.environments ?? []) as Environment[];
   const activeEnvironment = environments.find((environment) => environment.name === activeEnvName);
+  // External secrets sit below the environment's own variables: an explicitly
+  // declared variable of the same name is the more specific answer.
   return [
     { scope: 'collection', variables: collectionVariables },
-    { scope: 'environment', variables: activeEnvironment?.variables },
-    { scope: '$secrets', variables: externalSecretVariables(activeEnvironment) }
+    { scope: '$secrets', variables: externalSecretVariables(activeEnvironment) },
+    { scope: 'environment', variables: activeEnvironment?.variables }
   ];
 };
 
@@ -220,9 +222,7 @@ export const ItemVariableResolverProvider: React.FC<{
     (name: string, value: string) => {
       const { name: varName, scope } = resolver.lookup(name);
       if (scope === '$secrets') {
-        // The store keys external secrets by their bare name, not the `$secrets.` reference.
-        const secretName = varName.slice('$secrets.'.length);
-        if (activeEnvName) dispatch(setPlaygroundVariable({ scope, name: secretName, value, envName: activeEnvName }));
+        if (activeEnvName) dispatch(setPlaygroundVariable({ scope, name: varName, value, envName: activeEnvName }));
       } else if (scope === 'environment') {
         if (activeEnvName) dispatch(setPlaygroundVariable({ scope, name: varName, value, envName: activeEnvName }));
       } else if (scope === 'collection') {
diff --git a/packages/bruno-api-docs/src/runner/index.ts b/packages/bruno-api-docs/src/runner/index.ts
index fa2f3d2e..c1a711bb 100644
--- a/packages/bruno-api-docs/src/runner/index.ts
+++ b/packages/bruno-api-docs/src/runner/index.ts
@@ -101,8 +101,7 @@ export class RequestRunner {
         processEnvVars,
         collectionVariables,
         folderVariables,
-        requestVariables,
-        externalSecrets: this.getExternalSecrets(environment)
+        requestVariables
       };
       
       // Get scripts in object format for easier access
@@ -212,9 +211,21 @@ export class RequestRunner {
   }
 
   private getEnvironmentVariables(environment?: Environment): Record<string, any> {
-    if (!environment?.variables) return {};
-    
-    return environment.variables.reduce((vars, variable: any) => {
+    if (!environment) return {};
+
+    // External secrets are ordinary `{{name}}` references whose value a provider
+    // would supply; the browser can't reach one, so only a value typed into the
+    // playground resolves them. An explicit variable of the same name wins.
+    const externalSecrets = ((environment.externalSecrets?.variables ?? []) as {
+      name?: string;
+      disabled?: boolean;
+      value?: string;
+    }[]).reduce((vars, variable) => {
+      if (variable.name && !variable.disabled && variable.value) vars[variable.name] = variable.value;
+      return vars;
+    }, {} as Record<string, any>);
+
+    return (environment.variables ?? []).reduce((vars, variable: any) => {
       const name = variable.name;
       if (name && !variable.disabled) {
         // Coerce typed values (number/boolean/object) to native, like folder/collection/request vars.
@@ -225,25 +236,7 @@ export class RequestRunner {
           : coerceVariableValue(variable.value);
       }
       return vars;
-    }, {} as Record<string, any>);
-  }
-
-
-  /**
-   * External secrets are pointers to a provider the browser cannot reach, so only a
-   * value typed into the playground this session can resolve `{{$secrets.name}}`.
-   */
-  private getExternalSecrets(environment?: Environment): Record<string, string> {
-    const variables = (environment?.externalSecrets?.variables ?? []) as {
-      name?: string;
-      disabled?: boolean;
-      value?: string;
-    }[];
-
-    return variables.reduce((secrets, variable) => {
-      if (variable.name && !variable.disabled && variable.value) secrets[variable.name] = variable.value;
-      return secrets;
-    }, {} as Record<string, string>);
+    }, externalSecrets);
   }
 
   private async preprocessRequest(
diff --git a/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts b/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts
index c975a851..41b044e4 100644
--- a/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts
+++ b/packages/bruno-api-docs/src/runner/utils/variable-interpolator.ts
@@ -126,7 +126,6 @@ export const interpolateVars = (
     runtimeVariables?: Record<string, any>;
     processEnvVars?: Record<string, any>;
     promptVariables?: Record<string, any>;
-    externalSecrets?: Record<string, string>;
   } = {}
 ): HttpRequest => {
   // Clone the request to avoid mutation
@@ -142,8 +141,7 @@ export const interpolateVars = (
     environmentVariables = {},
     runtimeVariables = {},
     processEnvVars = {},
-    promptVariables = {},
-    externalSecrets = {}
+    promptVariables = {}
   } = variableSources;
 
   const combinedVariables = {
@@ -159,10 +157,6 @@ export const interpolateVars = (
       env: {
         ...processEnvVars
       }
-    },
-    // `{{$secrets.name}}` resolves through the same dot-path lookup as process.env.
-    $secrets: {
-      ...externalSecrets
     }
   };
 

From 5a63ab3632674c36032d8e3e0bcaa253eb21e3cc Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 03:32:13 +0530
Subject: [PATCH 08/25] fix(playground): keep the secret changes out of the
 rendered docs

Masking, reveal and copy for secrets are gated on the card's editable
prop, and external secrets only enter the resolver for the playground
provider. The docs card keeps its original (Secret) placeholder with no
reveal or copy, and leaves external secrets unresolved.
---
 .../variableInfoPopup.spec.ts                 | 21 ++++------
 .../VariableInfoCard.spec.tsx                 | 41 +++++++++++--------
 .../VariableInfoCard/VariableInfoCard.tsx     | 17 +++++---
 .../src/hooks/useVariableResolver.tsx         | 27 ++++++++----
 4 files changed, 62 insertions(+), 44 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index d1c0a57e..aa40104e 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -65,14 +65,14 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.value).toHaveText('https://api.dev.example.com');
   });
 
-  test('masks a secret referenced in the request body', async ({ requestPage }) => {
+  test('shows a (Secret) placeholder for a secret referenced in the request body', async ({ requestPage }) => {
     const { bodyVariableCard: variableCard } = requestPage;
     await variableCard.hoverToken('bearer_token');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
-    await expect(variableCard.value).toHaveText('*'.repeat('super-secret-token'.length));
-    await expect(variableCard.copyButton).toHaveCount(1);
+    await expect(variableCard.value).toHaveText('(Secret)');
+    await expect(variableCard.copyButton).toHaveCount(0);
   });
 
   test('shows an (empty) placeholder with no copy for a defined variable that has no value', async ({ requestPage }) => {
@@ -110,19 +110,16 @@ test.describe('Variable hover card', () => {
     await expect(variableCard.note).toContainText('random value');
   });
 
-  test('masks a secret until the reveal control is used', async ({ requestPage }) => {
+  test('shows a (Secret) placeholder with no reveal or copy, never exposing the value', async ({ requestPage }) => {
     const { variableCard } = requestPage;
     await variableCard.pinToken('bearer_token');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
-    await expect(variableCard.value).toHaveText('*'.repeat('super-secret-token'.length));
+    await expect(variableCard.value).toHaveText('(Secret)');
     await expect(variableCard.card).not.toContainText('super-secret-token');
-    await expect(variableCard.copyButton).toHaveCount(1);
-
-    await variableCard.revealToggle.click();
-
-    await expect(variableCard.value).toHaveText('super-secret-token');
+    await expect(variableCard.revealToggle).toHaveCount(0);
+    await expect(variableCard.copyButton).toHaveCount(0);
   });
 
   test('copies the resolved value from the copy button', async ({ page, requestPage }) => {
@@ -243,13 +240,13 @@ test.describe('Variable hover card — Overview page', () => {
     await expect(variableCard.value).toHaveText('2024-01');
   });
 
-  test('masks a secret referenced in a collection header', async ({ overviewPage }) => {
+  test('shows a (Secret) placeholder for a secret referenced in a collection header', async ({ overviewPage }) => {
     const { variableCard } = overviewPage;
     await variableCard.hoverToken('bearer_token');
 
     await expect(variableCard.card).toBeVisible();
     await expect(variableCard.scopeBadge).toHaveText('Environment');
-    await expect(variableCard.value).toHaveText('*'.repeat('super-secret-token'.length));
+    await expect(variableCard.value).toHaveText('(Secret)');
   });
 });
 
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index 216e6bbe..7edae823 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -74,11 +74,12 @@ describe('VariableInfoCard', () => {
     expect(part(useRenderToDom(cardTree('endpoint')), 'value').text).toBe('https://dev.test/v1');
   });
 
-  it('masks a secret by length and offers reveal, without printing the plaintext', () => {
+  it('shows a (Secret) placeholder with no reveal/copy and never prints the plaintext', () => {
     const root = useRenderToDom(cardTree('bearer_token'));
-    expect(part(root, 'value').text).toBe('*'.repeat('super-secret'.length));
+    expect(part(root, 'value').text).toBe('(Secret)');
     expect(root.toString()).not.toContain('super-secret');
-    expect(root.querySelector(selector('reveal'))).not.toBeNull();
+    expect(root.querySelector(selector('reveal'))).toBeNull();
+    expect(root.querySelector(selector('copy'))).toBeNull();
   });
 
   it('shows an (empty) placeholder with no copy control when the value is blank', () => {
@@ -88,18 +89,9 @@ describe('VariableInfoCard', () => {
     expect(root.querySelector(selector('copy'))).toBeNull();
   });
 
-  it('offers the copy control on a secret, which has a value to copy', () => {
-    expect(useRenderToDom(cardTree('bearer_token')).querySelector(selector('copy'))).not.toBeNull();
-  });
-
-  // An external secret is referenced by its bare name, like any other variable.
-  it('shows a declared external secret as blank with a reveal and no copy', () => {
-    const root = useRenderToDom(cardTree('vaultKey'));
-    expect(part(root, 'scope').text).toBe('Secret');
-    expect(part(root, 'value').text).toBe('');
-    expect(root.querySelector(selector('reveal'))).not.toBeNull();
-    expect(root.querySelector(selector('copy'))).toBeNull();
-    expect(root.querySelector(selector('note'))).toBeNull();
+  // External secrets are a playground affordance; the docs leave them unresolved.
+  it('does not resolve an external secret', () => {
+    expect(part(useRenderToDom(cardTree('vaultKey')), 'scope').text).toBe('Undefined');
   });
 
   it('pretty-prints an object-typed value', () => {
@@ -200,10 +192,25 @@ describe('VariableInfoCard (editable)', () => {
     expect(value.classList.contains('var-value-placeholder')).toBe(false);
   });
 
-  it('makes a secret editable so a value can be supplied for the request', () => {
-    const value = part(useRenderToDom(editableCardTree('bearer_token')), 'value');
+  it('masks a secret, offers reveal and copy, and makes it editable', () => {
+    const root = useRenderToDom(editableCardTree('bearer_token'));
+    const value = part(root, 'value');
     expect(value.text).toBe('*'.repeat('super-secret'.length));
+    expect(root.toString()).not.toContain('super-secret');
     expect(value.classList.contains('var-value-editable')).toBe(true);
+    expect(root.querySelector(selector('reveal'))).not.toBeNull();
+    expect(root.querySelector(selector('copy'))).not.toBeNull();
+  });
+
+  // An external secret is referenced by its bare name, like any other variable.
+  it('shows a declared external secret as blank, editable, with reveal but no copy', () => {
+    const root = useRenderToDom(editableCardTree('vaultKey'));
+    expect(part(root, 'scope').text).toBe('Secret');
+    expect(part(root, 'value').text).toBe('');
+    expect(part(root, 'value').classList.contains('var-value-editable')).toBe(true);
+    expect(root.querySelector(selector('reveal'))).not.toBeNull();
+    expect(root.querySelector(selector('copy'))).toBeNull();
+    expect(root.querySelector(selector('note'))).toBeNull();
   });
 
   it('never makes a read-only scope (process.env) editable', () => {
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index a0719074..3a9b55f2 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -60,7 +60,10 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
       && EDITABLE_SCOPES.has(info.scope)
       && (!ENV_BOUND_SCOPES.has(info.scope) || !!activeEnvName);
 
-  const masked = info.secret && !revealed;
+  // Only the playground fills secrets in; the rendered docs keep the original
+  // opaque "(Secret)" treatment, with no mask, reveal or copy.
+  const secretFillable = editable && info.secret;
+  const masked = secretFillable && !revealed;
   const displayValue = masked ? maskValue(info.value) : info.value;
 
   const startEditing = () => {
@@ -129,12 +132,14 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   }
 
   const readOnlyNote = getReadOnlyNote(info.scope, activeEnvName);
-  const emptyLabel = !info.secret && info.value === '' ? '(empty)' : null;
-  const placeholder = canEdit ? null : emptyLabel;
+  const emptyLabel = !secretFillable && info.value === '' ? '(empty)' : null;
+  const placeholder = info.secret && !editable ? '(Secret)' : canEdit ? null : emptyLabel;
 
-  const icons = (info.value !== '' || info.secret) && (
+  const showCopy = info.value !== '' && !(info.secret && !editable);
+
+  const icons = (showCopy || secretFillable) && (
     <div className="var-icons">
-      {info.secret && (
+      {secretFillable && (
         <button
           type="button"
           className="reveal-button"
@@ -147,7 +152,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
           {revealed ? <EyeOffIcon /> : <EyeIcon />}
         </button>
       )}
-      {info.value !== '' && (
+      {showCopy && (
         <CopyButton
           text={info.value}
           label="Copy value"
diff --git a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
index 71b2a582..3388def9 100644
--- a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
+++ b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
@@ -120,17 +120,26 @@ 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);
 
-const collectionAndEnvSources = (collection: OpenCollection | null, activeEnvName: string | null): VariableSource[] => {
+/**
+ * `withExternalSecrets` is playground-only: the rendered docs leave external
+ * secrets unresolved, exactly as they were before they became fillable.
+ * They sit below the environment's own variables, so an explicitly declared
+ * variable of the same name is the more specific answer.
+ */
+const collectionAndEnvSources = (
+  collection: OpenCollection | null,
+  activeEnvName: string | null,
+  withExternalSecrets = false
+): VariableSource[] => {
   const collectionVariables = (collection?.request?.variables ?? []) as (Variable | SecretVariable)[];
   const environments = (collection?.config?.environments ?? []) as Environment[];
   const activeEnvironment = environments.find((environment) => environment.name === activeEnvName);
-  // External secrets sit below the environment's own variables: an explicitly
-  // declared variable of the same name is the more specific answer.
-  return [
-    { scope: 'collection', variables: collectionVariables },
-    { scope: '$secrets', variables: externalSecretVariables(activeEnvironment) },
-    { scope: 'environment', variables: activeEnvironment?.variables }
-  ];
+  const sources: VariableSource[] = [{ scope: 'collection', variables: collectionVariables }];
+  if (withExternalSecrets) {
+    sources.push({ scope: '$secrets', variables: externalSecretVariables(activeEnvironment) });
+  }
+  sources.push({ scope: 'environment', variables: activeEnvironment?.variables });
+  return sources;
 };
 
 const folderVariables = (folder: Item): (Variable | SecretVariable)[] =>
@@ -208,7 +217,7 @@ export const ItemVariableResolverProvider: React.FC<{
   const showVars = useAppSelector(selectShowVars);
 
   const model = useMemo(() => {
-    const sources: VariableSource[] = collectionAndEnvSources(collection, activeEnvName);
+    const sources: VariableSource[] = collectionAndEnvSources(collection, activeEnvName, true);
     for (const folder of ancestry) {
       sources.push({ scope: 'folder', variables: folderVariables(folder) });
     }

From d64138f7ba455e46fd02258e28848eb3bba2a968 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 03:39:41 +0530
Subject: [PATCH 09/25] chore(playground): trim duplicated comments from the
 secret changes

---
 .../VariableInfoCard/VariableInfoCard.spec.tsx    |  1 -
 .../VariableInfoCard/VariableInfoCard.tsx         |  3 +--
 .../src/hooks/useVariableResolver.tsx             | 15 +++++----------
 packages/bruno-api-docs/src/runner/index.ts       |  5 ++---
 .../src/store/slices/playground.spec.ts           |  2 --
 5 files changed, 8 insertions(+), 18 deletions(-)

diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index 7edae823..9a8e1ba6 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -202,7 +202,6 @@ describe('VariableInfoCard (editable)', () => {
     expect(root.querySelector(selector('copy'))).not.toBeNull();
   });
 
-  // An external secret is referenced by its bare name, like any other variable.
   it('shows a declared external secret as blank, editable, with reveal but no copy', () => {
     const root = useRenderToDom(editableCardTree('vaultKey'));
     expect(part(root, 'scope').text).toBe('Secret');
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 3a9b55f2..429ae4d2 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -60,8 +60,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
       && EDITABLE_SCOPES.has(info.scope)
       && (!ENV_BOUND_SCOPES.has(info.scope) || !!activeEnvName);
 
-  // Only the playground fills secrets in; the rendered docs keep the original
-  // opaque "(Secret)" treatment, with no mask, reveal or copy.
+  // Docs keep the opaque "(Secret)" treatment; only the playground fills them in.
   const secretFillable = editable && info.secret;
   const masked = secretFillable && !revealed;
   const displayValue = masked ? maskValue(info.value) : info.value;
diff --git a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
index 3388def9..1b221749 100644
--- a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
+++ b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
@@ -110,22 +110,17 @@ const makeResolver = (
 };
 
 /**
- * External secrets are `{ name, secretName }` pointers: `name` is the variable
- * the collection references as `{{name}}`, `secretName` only says where the
- * provider would fetch it. The browser cannot reach the provider, so they carry
- * whatever value was typed into the playground this session.
+ * External secrets are `{ name, secretName }` pointers: `name` is what the
+ * collection references as `{{name}}`, `secretName` only says where a provider
+ * would fetch it. The browser cannot reach the provider, so the only value they
+ * can carry is one typed into the playground this session.
  */
 const externalSecretVariables = (environment: Environment | undefined): SecretVariable[] =>
   ((environment?.externalSecrets?.variables ?? []) as { name?: string; disabled?: boolean; value?: string }[])
     .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 rendered docs leave external
- * secrets unresolved, exactly as they were before they became fillable.
- * They sit below the environment's own variables, so an explicitly declared
- * variable of the same name is the more specific answer.
- */
+/** `withExternalSecrets` is playground-only; the docs leave them unresolved. */
 const collectionAndEnvSources = (
   collection: OpenCollection | null,
   activeEnvName: string | null,
diff --git a/packages/bruno-api-docs/src/runner/index.ts b/packages/bruno-api-docs/src/runner/index.ts
index c1a711bb..7d5164de 100644
--- a/packages/bruno-api-docs/src/runner/index.ts
+++ b/packages/bruno-api-docs/src/runner/index.ts
@@ -213,9 +213,8 @@ export class RequestRunner {
   private getEnvironmentVariables(environment?: Environment): Record<string, any> {
     if (!environment) return {};
 
-    // External secrets are ordinary `{{name}}` references whose value a provider
-    // would supply; the browser can't reach one, so only a value typed into the
-    // playground resolves them. An explicit variable of the same name wins.
+    // External secrets resolve as ordinary `{{name}}` references. An explicitly
+    // declared variable of the same name wins.
     const externalSecrets = ((environment.externalSecrets?.variables ?? []) as {
       name?: string;
       disabled?: boolean;
diff --git a/packages/bruno-api-docs/src/store/slices/playground.spec.ts b/packages/bruno-api-docs/src/store/slices/playground.spec.ts
index 073d3842..5dd21a27 100644
--- a/packages/bruno-api-docs/src/store/slices/playground.spec.ts
+++ b/packages/bruno-api-docs/src/store/slices/playground.spec.ts
@@ -155,8 +155,6 @@ describe('setPlaygroundVariable', () => {
     expect(item.variables.find((v) => v.name === 'rv').value).toBe('2');
   });
 
-  // The value lives only on this in-memory copy, so a request can be sent with a
-  // secret the published collection never carries.
   it('writes a session value to a secret variable, keeping it marked secret', () => {
     const collection = makeCollection();
     collection.config.environments[0].variables.push({ name: 'sec', secret: true });

From 949451a1f4f5bbc6cfe0588f1b1089f585b36375 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 03:56:06 +0530
Subject: [PATCH 10/25] fix(playground): allow $secrets as a concrete variable
 scope

The declaration-site scope union did not include external secrets, so
tsc -p tsconfig.build.json rejected the new variable source.
---
 packages/bruno-api-docs/src/utils/variableResolution.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/bruno-api-docs/src/utils/variableResolution.ts b/packages/bruno-api-docs/src/utils/variableResolution.ts
index 5eb03104..da75b0c3 100644
--- a/packages/bruno-api-docs/src/utils/variableResolution.ts
+++ b/packages/bruno-api-docs/src/utils/variableResolution.ts
@@ -103,7 +103,8 @@ export type VariableScope =
   | '$secrets'
   | 'undefined';
 
-export type ConcreteScope = 'collection' | 'environment' | 'folder' | 'request';
+/** Scopes a variable can actually be declared in, `$secrets` being an environment's external secrets. */
+export type ConcreteScope = 'collection' | 'environment' | 'folder' | 'request' | '$secrets';
 
 export interface VariableSource {
   scope: ConcreteScope;

From 880a39b4ef2deb97046684d594ff9bfa8bfb86a9 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 07:44:06 +0530
Subject: [PATCH 11/25] 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.
---
 .../playground/playground-variables.spec.ts   |  8 +++-
 .../variableInfoPopup.spec.ts                 | 10 +++++
 .../EnvironmentsView/EnvironmentsView.tsx     |  8 +---
 .../VariableInfoCard.spec.tsx                 | 16 +++++++-
 .../VariableInfoCard/VariableInfoCard.tsx     | 10 ++++-
 .../src/hooks/useVariableResolver.tsx         |  8 ++--
 .../src/utils/environments.spec.ts            | 39 ++++++++++++++++++-
 .../bruno-api-docs/src/utils/environments.ts  | 19 +++++++++
 8 files changed, 102 insertions(+), 16 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 796e08ad..788df2db 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/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');
   });
 });
diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index aa40104e..d57bab00 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/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');
diff --git a/packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx b/packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx
index 21de7b6a..13da6aee 100644
--- a/packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx
+++ b/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)
       }
     });
 
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index 9a8e1ba6..bfb9947b 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/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', () => {
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 429ae4d2..54ae4314 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/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;
 
diff --git a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
index 1b221749..d71ab924 100644
--- a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
+++ b/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]);
 
diff --git a/packages/bruno-api-docs/src/utils/environments.spec.ts b/packages/bruno-api-docs/src/utils/environments.spec.ts
index 48263e0e..a012cd3a 100644
--- a/packages/bruno-api-docs/src/utils/environments.spec.ts
+++ b/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 }]);
+  });
+});
diff --git a/packages/bruno-api-docs/src/utils/environments.ts b/packages/bruno-api-docs/src/utils/environments.ts
index cc4eea7c..f5f9879b 100644
--- a/packages/bruno-api-docs/src/utils/environments.ts
+++ b/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;

From 05448132e7fa639f130723745b0a1f2c3cfc0bb7 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 10:33:49 +0530
Subject: [PATCH 12/25] fix(playground): mask secrets by making the field's
 content the mask

The mirror layer painted asterisks over a transparent-text textarea, so
the real secret stayed in the DOM: visible under selection, read out by
screen readers, and exposed in forced-colors mode where author colours
are overridden. The asterisks were also drawn in a proportional font, so
they drifted from the caret by about 8px over an 18-character value.

The field now contains the mask itself and the real string lives in
component state. Display and real indices line up one to one, so an edit
is replayed onto the real value by splicing what the browser inserted at
the recorded selection. Nothing to drift, and no plaintext on the page.

Also from review: a cleared external secret is no longer dropped on the
way to the request, both spellings of the enable toggle are honoured, the
copy button no longer claims success for text it did not copy, and the
copied tint moved from an inline style to CSS.
---
 .../playground/playground-variables.spec.ts   | 29 +++++++
 .../variableInfoPopup.spec.ts                 |  2 -
 .../VariableInfoCard/StyledWrapper.ts         | 30 +-------
 .../VariableInfoCard/VariableInfoCard.tsx     | 77 ++++++++++++++-----
 .../src/hooks/useVariableResolver.tsx         | 10 +--
 packages/bruno-api-docs/src/runner/index.ts   | 37 +++++----
 .../src/ui/CopyButton/CopyButton.tsx          |  9 ++-
 .../src/ui/CopyButton/StyledWrapper.ts        |  1 +
 .../src/utils/variableResolution.test.ts      | 39 ++++++++++
 .../src/utils/variableResolution.ts           | 29 +++++++
 10 files changed, 190 insertions(+), 73 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 788df2db..40483ea2 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -133,6 +133,35 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.value).toHaveText('*'.repeat('vault-value'.length));
   });
 
+  // The field's own content is the mask, so the real value is never in the DOM
+  // and the caret cannot drift away from the end of the asterisks.
+  test('the edit field holds only mask characters while the secret is hidden', async ({ playground }) => {
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.startEditing('typed-secret');
+
+    const state = await playground.variable.editField.evaluate((el: HTMLTextAreaElement) => ({
+      value: el.value,
+      caret: el.selectionStart
+    }));
+
+    expect(state.value).toBe('*'.repeat('typed-secret'.length));
+    expect(state.caret).toBe(state.value.length);
+  });
+
+  test('typing into the middle of a masked secret edits the real value', async ({ playground }) => {
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.startEditing('abcdef');
+
+    await playground.variable.editField.evaluate((el: HTMLTextAreaElement) => el.setSelectionRange(3, 3));
+    await playground.variable.editField.pressSequentially('XY');
+    await playground.variable.editField.press('Enter');
+
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.revealToggle.click();
+
+    await expect(playground.variable.value).toHaveText('abcXYdef');
+  });
+
   test('a typed secret stays masked in the card until revealed', async ({ playground }) => {
     await playground.variable.hoverInputToken('unsetSecret');
     await playground.variable.editTo('typed-secret');
diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index d57bab00..8395c5a3 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -157,8 +157,6 @@ test.describe('Variable hover card', () => {
 
     await expect(variableCard.copyButton).toHaveAttribute('data-copied', 'true');
     await expect(tick).toHaveCount(1);
-    // The tick is stroke="currentColor", so the button's colour is the tick's colour.
-    await expect(variableCard.copyButton).toHaveAttribute('style', /--oc-status-success-text/);
 
     await expect(variableCard.copyButton).not.toHaveAttribute('data-copied', 'true', { timeout: 3000 });
     await expect(tick).toHaveCount(0);
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
index 5beecd5b..db70bf67 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
@@ -114,35 +114,6 @@ export const StyledWrapper = styled.div`
     outline: none;
   }
 
-  .var-value-editor {
-    position: relative;
-  }
-
-  .var-value-mirror {
-    position: absolute;
-    top: 0;
-    right: 1.5rem;
-    left: 0;
-    visibility: hidden;
-    pointer-events: none;
-    font-family: var(--font-sans);
-    font-size: 0.8125rem;
-    font-weight: 400;
-    line-height: 1.25rem;
-    color: var(--text-primary);
-    white-space: pre-wrap;
-    word-break: break-all;
-  }
-
-  .var-value-editor--masked .var-value-mirror {
-    visibility: visible;
-  }
-
-  .var-value-editor--masked .var-value-edit {
-    color: transparent;
-    caret-color: var(--text-primary);
-  }
-
   .var-icons {
     position: absolute;
     top: 50%;
@@ -181,6 +152,7 @@ export const StyledWrapper = styled.div`
 
   .var-icons .copy-button[data-copied] {
     opacity: 1;
+    color: var(--oc-status-success-text);
     cursor: default;
   }
 
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 54ae4314..e4b40c5d 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -43,6 +43,11 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   const [revealed, setRevealed] = useState(false);
   const [draft, setDraft] = useState('');
   const editRef = useRef<HTMLTextAreaElement>(null);
+  // Selection before the pending edit, and the caret to restore after it. The
+  // textarea shows the mask, so React re-renders it with substituted content and
+  // the browser's own caret position is lost.
+  const selectionRef = useRef({ start: 0, end: 0 });
+  const caretRef = useRef<number | null>(null);
 
   useLayoutEffect(() => {
     const el = editRef.current;
@@ -58,6 +63,14 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     el.setSelectionRange(end, end);
   }, [editing]);
 
+  useLayoutEffect(() => {
+    const el = editRef.current;
+    const caret = caretRef.current;
+    if (!el || caret === null) return;
+    caretRef.current = null;
+    el.setSelectionRange(caret, caret);
+  }, [draft]);
+
   const canEdit
     = editable
       && canWrite
@@ -70,6 +83,10 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   const secretFillable = editable && info.secret;
   const masked = secretFillable && !revealed;
   const displayValue = masked ? maskValue(info.value) : info.value;
+  // A variable that is secret only because it references one has a raw value
+  // like `Bearer {{token}}`, which holds no secret material, so editing it plainly.
+  const maskWhileEditing = masked && info.rawValue === info.value;
+  const editValue = maskWhileEditing ? maskValue(draft) : draft;
 
   const startEditing = () => {
     setDraft(info.rawValue);
@@ -81,7 +98,33 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     if (draft !== info.rawValue) updateVariable(info.name, draft);
   };
 
+  const rememberSelection = (event: React.SyntheticEvent<HTMLTextAreaElement>) => {
+    const el = event.currentTarget;
+    selectionRef.current = { start: el.selectionStart ?? 0, end: el.selectionEnd ?? 0 };
+  };
+
+  /**
+   * The field shows one mask character per real character, so display and real
+   * indices line up. That lets the edit be replayed onto the real string: take
+   * what the browser inserted at the old selection and splice it in at the same
+   * offsets.
+   */
+  const handleEditChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const next = event.target.value;
+    if (!maskWhileEditing) {
+      setDraft(next);
+      return;
+    }
+
+    const { start, end } = selectionRef.current;
+    const insertedLength = next.length - draft.length + (end - start);
+    const inserted = insertedLength > 0 ? next.slice(start, start + insertedLength) : '';
+    caretRef.current = start + inserted.length;
+    setDraft(draft.slice(0, start) + inserted + draft.slice(end));
+  };
+
   const handleEditKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    rememberSelection(event);
     if (event.key === 'Enter' && !event.shiftKey) {
       event.preventDefault();
       commit();
@@ -176,24 +219,22 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   );
 
   const editFieldNode = (
-    <div className={`var-value-editor${masked ? ' var-value-editor--masked' : ''}`}>
-      <div className="var-value-mirror" aria-hidden="true">
-        {maskValue(draft)}
-      </div>
-      <textarea
-        ref={editRef}
-        className="var-value-edit"
-        data-testid={`${testId}-edit`}
-        aria-label={`Edit ${info.name}`}
-        value={draft}
-        autoFocus
-        rows={1}
-        spellCheck={false}
-        onChange={(event) => setDraft(event.target.value)}
-        onKeyDown={handleEditKeyDown}
-        onBlur={commit}
-      />
-    </div>
+    <textarea
+      ref={editRef}
+      className="var-value-edit"
+      data-testid={`${testId}-edit`}
+      aria-label={`Edit ${info.name}`}
+      value={editValue}
+      autoFocus
+      rows={1}
+      spellCheck={false}
+      autoComplete="off"
+      onChange={handleEditChange}
+      onKeyDown={handleEditKeyDown}
+      onSelect={rememberSelection}
+      onMouseDown={rememberSelection}
+      onBlur={commit}
+    />
   );
 
   const editableDisplayNode = (
diff --git a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
index d71ab924..a62ffa8f 100644
--- a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
+++ b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
@@ -16,8 +16,10 @@ import {
   singleReferenceName,
   detectSpecialScope,
   isValidVariableName,
+  isExternalSecretActive,
   formatEntryValue,
   referencesSecret,
+  type ExternalSecretEntry,
   type ScopedVariableModel,
   type VariableScope,
   type VariableSource
@@ -116,8 +118,8 @@ const makeResolver = (
  * can carry is one typed into the playground this session.
  */
 const externalSecretVariables = (environment: Environment | undefined): SecretVariable[] =>
-  ((environment?.externalSecrets?.variables ?? []) as { name?: string; disabled?: boolean; value?: string }[])
-    .filter((entry) => entry.name && entry.disabled !== true)
+  ((environment?.externalSecrets?.variables ?? []) as ExternalSecretEntry[])
+    .filter((entry) => entry.name && isExternalSecretActive(entry))
     .map((entry) => ({ name: entry.name, secret: true, value: entry.value ?? '' }) as unknown as SecretVariable);
 
 /** `withExternalSecrets` tracks the writable (playground) mount; docs leave them unresolved. */
@@ -227,9 +229,7 @@ export const ItemVariableResolverProvider: React.FC<{
   const updateVariable = useCallback(
     (name: string, value: string) => {
       const { name: varName, scope } = resolver.lookup(name);
-      if (scope === '$secrets') {
-        if (activeEnvName) dispatch(setPlaygroundVariable({ scope, name: varName, value, envName: activeEnvName }));
-      } else if (scope === 'environment') {
+      if (scope === 'environment' || scope === '$secrets') {
         if (activeEnvName) dispatch(setPlaygroundVariable({ scope, name: varName, value, envName: activeEnvName }));
       } else if (scope === 'collection') {
         dispatch(setPlaygroundVariable({ scope, name: varName, value }));
diff --git a/packages/bruno-api-docs/src/runner/index.ts b/packages/bruno-api-docs/src/runner/index.ts
index 7d5164de..0ce0764b 100644
--- a/packages/bruno-api-docs/src/runner/index.ts
+++ b/packages/bruno-api-docs/src/runner/index.ts
@@ -6,9 +6,19 @@ import ScriptRuntime from '../scripting/runtime/script-runtime';
 import AssertRuntime, { type AssertionResult } from '../scripting/runtime/assert-runtime';
 import { getTreePathFromCollectionToItem, mergeHeaders, mergeScripts, mergeAuth, interpolateVars } from './utils';
 import { getCollectionFolderRequestVariables } from './utils/variable-merger';
-import { coerceVariableValue, parseValueByDataType } from '../utils/variableDataType';
+import { coerceVariableValue, parseValueByDataType, type CoercedVariableValue } from '../utils/variableDataType';
+import { externalSecretValues, type ExternalSecretEntry } from '../utils/variableResolution';
+import type { VariableValueOrVariants, VariableValueType } from '@opencollection/types/common/variables';
 import { getRequestScripts, getRequestAssertions, scriptsArrayToObject } from '../utils/schemaHelpers';
 
+interface DeclaredEnvironmentVariable {
+  name?: string;
+  value?: VariableValueOrVariants;
+  type?: VariableValueType;
+  secret?: boolean;
+  disabled?: boolean;
+}
+
 export interface RunRequestOptions {
   item: HttpRequest;
   collection: OpenCollectionCollection;
@@ -210,32 +220,27 @@ export class RequestRunner {
     return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
   }
 
+  /** A secret carries its data type as a sibling `type`; a plain one nests it in `value`. */
   private getEnvironmentVariables(environment?: Environment): Record<string, any> {
-    if (!environment) return {};
-
-    // External secrets resolve as ordinary `{{name}}` references. An explicitly
-    // declared variable of the same name wins.
-    const externalSecrets = ((environment.externalSecrets?.variables ?? []) as {
-      name?: string;
-      disabled?: boolean;
-      value?: string;
-    }[]).reduce((vars, variable) => {
-      if (variable.name && !variable.disabled && variable.value) vars[variable.name] = variable.value;
-      return vars;
-    }, {} as Record<string, any>);
+    // External secrets resolve as ordinary `{{name}}` references, so they seed
+    // the map and an explicitly declared variable of the same name overwrites.
+    const externalSecrets = externalSecretValues(
+      environment?.externalSecrets?.variables as ExternalSecretEntry[] | undefined
+    );
+    if (!environment?.variables) return externalSecrets;
 
-    return (environment.variables ?? []).reduce((vars, variable: any) => {
+    return environment.variables.reduce((vars, variable: DeclaredEnvironmentVariable) => {
       const name = variable.name;
       if (name && !variable.disabled) {
         // Coerce typed values (number/boolean/object) to native, like folder/collection/request vars.
         // A secret carries its data type as a sibling `type` (value is a plain string), whereas a
         // non-secret nests it inside the value — so coerce each from the right place.
         vars[name] = variable.secret
-          ? parseValueByDataType(variable.value, variable.type)
+          ? parseValueByDataType(variable.value as CoercedVariableValue, variable.type)
           : coerceVariableValue(variable.value);
       }
       return vars;
-    }, externalSecrets);
+    }, { ...externalSecrets } as Record<string, unknown>);
   }
 
   private async preprocessRequest(
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
index ef7b9688..0c85b850 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
@@ -48,8 +48,11 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
     []
   );
 
+  // A new value clears the tick, so it never claims success for text that was
+  // not the text copied.
+  useEffect(() => setCopied(false), [text]);
+
   const handleCopy = useCallback(async () => {
-    if (copied) return;
     if (!navigator.clipboard) return;
     const value = getText ? getText() : text;
     if (!value) return;
@@ -61,7 +64,7 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
     } catch {
       // Clipboard unavailable (e.g. insecure context) — fail silently.
     }
-  }, [copied, text, getText, resetAfterMs]);
+  }, [text, getText, resetAfterMs]);
 
   return (
     <StyledWrapper
@@ -71,7 +74,7 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
       aria-label={copied ? copiedLabel : label}
       data-copied={copied ? 'true' : undefined}
       data-testid={testId}
-      style={copied ? { color: 'var(--oc-status-success-text)', ...style } : style}
+      style={style}
     >
       {copied ? <CheckGlyph /> : <CopyGlyph />}
     </StyledWrapper>
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts b/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts
index 236d8a25..6928ea6e 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/ui/CopyButton/StyledWrapper.ts
@@ -19,6 +19,7 @@ export const StyledWrapper = styled.button`
   }
 
   &[data-copied] {
+    color: var(--oc-status-success-text);
     cursor: default;
   }
 
diff --git a/packages/bruno-api-docs/src/utils/variableResolution.test.ts b/packages/bruno-api-docs/src/utils/variableResolution.test.ts
index 4f7ae2b5..eb8c8b12 100644
--- a/packages/bruno-api-docs/src/utils/variableResolution.test.ts
+++ b/packages/bruno-api-docs/src/utils/variableResolution.test.ts
@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import {
+  isExternalSecretActive,
+  externalSecretValues,
   resolveVariables,
   singleReferenceName,
   unwrapVariableTyped,
@@ -132,3 +134,40 @@ describe('formatEntryValue', () => {
     expect(formatEntryValue(entry, {})).toBe(JSON.stringify(JSON.parse(entry.value), null, 2));
   });
 });
+
+describe('isExternalSecretActive', () => {
+  it('treats an entry with neither toggle as active', () => {
+    expect(isExternalSecretActive({ name: 'apiKey' })).toBe(true);
+  });
+
+  it('honours the disabled spelling written by the environments editor', () => {
+    expect(isExternalSecretActive({ name: 'apiKey', disabled: true })).toBe(false);
+    expect(isExternalSecretActive({ name: 'apiKey', disabled: false })).toBe(true);
+  });
+
+  // The repo's own sample collection authors these with `enabled`, so an entry
+  // switched off that way must not reach the request.
+  it('honours the enabled spelling written by the sample collection', () => {
+    expect(isExternalSecretActive({ name: 'apiKey', enabled: false })).toBe(false);
+    expect(isExternalSecretActive({ name: 'apiKey', enabled: true })).toBe(true);
+  });
+});
+
+describe('externalSecretValues', () => {
+  it('keeps a secret deliberately cleared to an empty string', () => {
+    expect(externalSecretValues([{ name: 'apiKey', value: '' }])).toEqual({ apiKey: '' });
+  });
+
+  it('skips a secret that was never filled in, leaving the reference unresolved', () => {
+    expect(externalSecretValues([{ name: 'apiKey' }])).toEqual({});
+  });
+
+  it('skips a switched-off secret under either spelling', () => {
+    expect(externalSecretValues([{ name: 'a', value: 'x', disabled: true }])).toEqual({});
+    expect(externalSecretValues([{ name: 'b', value: 'x', enabled: false }])).toEqual({});
+  });
+
+  it('returns an empty map when the environment declares none', () => {
+    expect(externalSecretValues(undefined)).toEqual({});
+  });
+});
diff --git a/packages/bruno-api-docs/src/utils/variableResolution.ts b/packages/bruno-api-docs/src/utils/variableResolution.ts
index da75b0c3..90b68d88 100644
--- a/packages/bruno-api-docs/src/utils/variableResolution.ts
+++ b/packages/bruno-api-docs/src/utils/variableResolution.ts
@@ -106,6 +106,35 @@ export type VariableScope =
 /** Scopes a variable can actually be declared in, `$secrets` being an environment's external secrets. */
 export type ConcreteScope = 'collection' | 'environment' | 'folder' | 'request' | '$secrets';
 
+/**
+ * An environment's external secret entry. `name` is what the collection
+ * references as `{{name}}`; the pointer field (`secretName`, `path`, …) names
+ * the provider key. `value` only exists for a value typed in this session.
+ * Older collections spell the toggle `enabled`, newer ones `disabled`.
+ */
+export interface ExternalSecretEntry {
+  name?: string;
+  value?: string;
+  disabled?: boolean;
+  enabled?: boolean;
+}
+
+/** Both spellings of the toggle appear in the wild, so honour whichever is present. */
+export const isExternalSecretActive = (entry: ExternalSecretEntry): boolean =>
+  entry.disabled !== true && entry.enabled !== false;
+
+/**
+ * The session values an environment's external secrets carry, keyed by the name
+ * the collection references. An entry cleared to '' is a deliberate empty value
+ * and is kept; one that was never filled in has no value and is skipped, leaving
+ * `{{name}}` unresolved.
+ */
+export const externalSecretValues = (entries: ExternalSecretEntry[] | undefined): Record<string, string> =>
+  (entries ?? []).reduce((values, entry) => {
+    if (entry.name && isExternalSecretActive(entry) && entry.value !== undefined) values[entry.name] = entry.value;
+    return values;
+  }, {} as Record<string, string>);
+
 export interface VariableSource {
   scope: ConcreteScope;
   variables: (Variable | SecretVariable)[] | undefined;

From a6e04e43e23b72e38c4dcbe646a4d9a4b1e07075 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 10:46:41 +0530
Subject: [PATCH 13/25] test(playground): cover the secret reaching the
 request, plus review cleanups

The runner's new path had no end-to-end cover, so nothing checked the
thing the ticket exists for. The new test routes the outgoing request and
asserts both a typed environment secret and a typed external secret
appear in it.

Also: re-masking on a second reveal click is now asserted; the copied
tick is one locator requiring both the marker and the checkmark, so the
test no longer races three assertions against the one-second reset;
the tick locator moved into the page object; .reveal-button stopped
duplicating every .copy-button declaration; the spec's optional-chained
assertions and an inline cast chain are gone.
---
 .../variable-card/variable-card.component.ts  |  4 ++
 .../playground/playground-variables.spec.ts   | 32 ++++++++++++++++
 .../variableInfoPopup.spec.ts                 | 10 ++---
 .../VariableInfoCard/StyledWrapper.ts         | 38 ++++---------------
 .../src/store/slices/playground.spec.ts       | 12 +++---
 .../src/ui/CopyButton/CopyButton.spec.tsx     |  8 ++--
 6 files changed, 58 insertions(+), 46 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts b/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
index 1f1ea38f..c9515e67 100644
--- a/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
+++ b/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
@@ -7,6 +7,10 @@ export class VariableCardComponent extends BaseComponent {
   readonly scopeBadge = this.card.getByTestId('variable-info-card-scope');
   readonly value = this.card.getByTestId('variable-info-card-value');
   readonly copyButton = this.card.getByTestId('variable-info-card-copy');
+  // Both facts of the copied state in one locator, so a test asserts it once
+  // rather than racing several assertions against the one-second reset: the
+  // button carries data-copied, and its glyph is the checkmark (a polyline).
+  readonly copiedTick = this.card.locator('[data-testid="variable-info-card-copy"][data-copied] polyline');
   readonly revealToggle = this.card.getByTestId('variable-info-card-reveal');
   readonly note = this.card.getByTestId('variable-info-card-note');
   readonly warning = this.card.getByTestId('variable-info-card-warning');
diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 40483ea2..66f536a2 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -171,5 +171,37 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await playground.variable.revealToggle.click();
 
     await expect(playground.variable.card).toContainText('typed-secret');
+
+    await playground.variable.revealToggle.click();
+
+    await expect(playground.variable.card).not.toContainText('typed-secret');
+    await expect(playground.variable.value).toHaveText('*'.repeat('typed-secret'.length));
+  });
+
+  // The point of making secrets fillable: the value has to reach the wire.
+  test('sends a typed secret with the request', async ({ page, playground, responsePane }) => {
+    const sent: string[] = [];
+    await page.route('**/customers/**', (route) => {
+      sent.push(route.request().url());
+      return route.fulfill({ status: 200, headers: { 'content-type': 'application/json' }, body: '{}' });
+    });
+
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.editTo('typed-secret');
+
+    await expect(playground.variable.value).toHaveText('*'.repeat('typed-secret'.length));
+
+    // A card is already open, so hoverInputToken's visibility wait returns at
+    // once; wait for it to be showing this variable before editing.
+    await playground.variable.hoverInputToken('vaultKey');
+    await expect(playground.variable.name).toHaveText('vaultKey');
+    await playground.variable.editTo('vault-value');
+    await expect(playground.variable.value).toHaveText('*'.repeat('vault-value'.length));
+
+    await responsePane.send();
+
+    await expect.poll(() => sent.length).toBeGreaterThan(0);
+    expect(sent[0]).toContain('s=typed-secret');
+    expect(sent[0]).toContain('k=vault-value');
   });
 });
diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index 8395c5a3..ded6934a 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -150,16 +150,12 @@ test.describe('Variable hover card', () => {
     await variableCard.pinToken('apiVersion');
     await expect(variableCard.card).toBeVisible();
 
-    const tick = variableCard.copyButton.locator('polyline');
-    await expect(tick).toHaveCount(0);
+    await expect(variableCard.copiedTick).toHaveCount(0);
 
     await variableCard.copyButton.click();
 
-    await expect(variableCard.copyButton).toHaveAttribute('data-copied', 'true');
-    await expect(tick).toHaveCount(1);
-
-    await expect(variableCard.copyButton).not.toHaveAttribute('data-copied', 'true', { timeout: 3000 });
-    await expect(tick).toHaveCount(0);
+    await expect(variableCard.copiedTick).toHaveCount(1);
+    await expect(variableCard.copiedTick).toHaveCount(0, { timeout: 3000 });
   });
 
   test('is read-only — no editor inside the card', async ({ requestPage }) => {
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
index db70bf67..2d97f4df 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/StyledWrapper.ts
@@ -129,33 +129,7 @@ export const StyledWrapper = styled.div`
     height: 1em;
   }
 
-  .var-icons .copy-button {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    padding: 0.125rem;
-    font-size: 0.875rem;
-    color: var(--text-secondary);
-    background: transparent;
-    border: none;
-    border-radius: var(--oc-radius);
-    opacity: 0.7;
-    cursor: pointer;
-    transition: opacity 0.15s ease, color 0.15s ease;
-  }
-
-  .var-icons .copy-button:hover {
-    opacity: 1;
-    color: var(--text-primary);
-    background: transparent;
-  }
-
-  .var-icons .copy-button[data-copied] {
-    opacity: 1;
-    color: var(--oc-status-success-text);
-    cursor: default;
-  }
-
+  .var-icons .copy-button,
   .var-icons .reveal-button {
     display: inline-flex;
     align-items: center;
@@ -171,19 +145,23 @@ export const StyledWrapper = styled.div`
     transition: opacity 0.15s ease, color 0.15s ease;
   }
 
+  .var-icons .copy-button:hover,
   .var-icons .reveal-button:hover {
     opacity: 1;
     color: var(--text-primary);
+    background: transparent;
   }
 
+  .var-icons .copy-button:focus-visible,
   .var-icons .reveal-button:focus-visible {
     outline: 0.125rem solid var(--primary-color);
     outline-offset: 0.0625rem;
   }
 
-  .var-icons .copy-button:focus-visible {
-    outline: 0.125rem solid var(--primary-color);
-    outline-offset: 0.0625rem;
+  .var-icons .copy-button[data-copied] {
+    opacity: 1;
+    color: var(--oc-status-success-text);
+    cursor: default;
   }
 
   .var-readonly-note {
diff --git a/packages/bruno-api-docs/src/store/slices/playground.spec.ts b/packages/bruno-api-docs/src/store/slices/playground.spec.ts
index 5dd21a27..f6fcd42b 100644
--- a/packages/bruno-api-docs/src/store/slices/playground.spec.ts
+++ b/packages/bruno-api-docs/src/store/slices/playground.spec.ts
@@ -31,6 +31,10 @@ const makeCollection = () =>
 const envVariables = (store: ReturnType<typeof createOpenCollectionStore>) =>
   selectHydratedCollection(store.getState())!.config!.environments![0].variables!;
 
+const envExternalSecrets = (store: ReturnType<typeof createOpenCollectionStore>) =>
+  (selectHydratedCollection(store.getState())!.config!.environments![0].externalSecrets!
+    .variables as unknown) as { name: string; value?: string; secretName?: string }[];
+
 describe('resetPlaygroundEnvironments', () => {
   it('restores the original environments after an edit', () => {
     const store = createOpenCollectionStore();
@@ -179,11 +183,9 @@ describe('setPlaygroundVariable', () => {
 
     store.dispatch(setPlaygroundVariable({ scope: '$secrets', name: 'vaultKey', value: 'typed', envName: 'Dev' }));
 
-    const env = selectHydratedCollection(store.getState())!.config!.environments![0] as unknown as {
-      externalSecrets: { variables: { value: string; secretName: string }[] };
-    };
-    expect(env.externalSecrets.variables[0].value).toBe('typed');
-    expect(env.externalSecrets.variables[0].secretName).toBe('prod/api-key');
+    const [vaultKey] = envExternalSecrets(store);
+    expect(vaultKey.value).toBe('typed');
+    expect(vaultKey.secretName).toBe('prod/api-key');
   });
 });
 
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx
index 406e43fa..13f9a00d 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.spec.tsx
@@ -1,7 +1,7 @@
 import React from 'react';
 import { describe, it, expect } from 'vitest';
 import { useRenderToDom } from '../../hooks/useRenderToDom';
-import { getByTestId } from '../../test-utils/dom';
+import { getByTestId, query } from '../../test-utils/dom';
 import { CopyButton } from './CopyButton';
 
 describe('CopyButton', () => {
@@ -24,8 +24,8 @@ describe('CopyButton', () => {
 
   it('renders rounded stroke ends so the glyph matches the desktop app', () => {
     const root = useRenderToDom(<CopyButton text="hello" />);
-    const svg = getByTestId(root, 'copy-button').querySelector('svg');
-    expect(svg?.getAttribute('stroke-linecap')).toBe('round');
-    expect(svg?.getAttribute('stroke-linejoin')).toBe('round');
+    const svg = query(getByTestId(root, 'copy-button'), 'svg');
+    expect(svg.getAttribute('stroke-linecap')).toBe('round');
+    expect(svg.getAttribute('stroke-linejoin')).toBe('round');
   });
 });

From b25ced2693544b27c5be10fb3adc06dd905de96e Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 11:05:13 +0530
Subject: [PATCH 14/25] fix(playground): make Backspace and Delete work on a
 masked secret

The change handler rebuilt the real value by splicing the browser's
insertion into the selection captured before the edit. With a collapsed
caret that range is empty, so a deletion spliced nothing into nothing and
the value was left unchanged while the field visibly shrank.

The replaced range now comes from the caret after the edit, which
describes a Backspace, a forward Delete, typing and a range replacement
alike.

The existing tests missed this because fill() sets the value in one shot;
the new test presses the keys.

Also: the copy button clears its tick when a getText-driven value changes,
and presence checks use toBeVisible rather than counting elements.
---
 .../playground/playground-variables.spec.ts   | 26 ++++++++++++++++---
 .../VariableInfoCard/VariableInfoCard.tsx     | 22 +++++++++-------
 .../src/ui/CopyButton/CopyButton.tsx          |  7 +++--
 3 files changed, 41 insertions(+), 14 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 66f536a2..7646e755 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -100,19 +100,19 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
 
   test('the copy control stays available while the value is being edited', async ({ playground }) => {
     await playground.variable.hoverInputToken('host');
-    await expect(playground.variable.copyButton).toHaveCount(1);
+    await expect(playground.variable.copyButton).toBeVisible();
 
     await playground.variable.startEditing('https://edited.example.com');
 
     await expect(playground.variable.editField).toBeVisible();
-    await expect(playground.variable.copyButton).toHaveCount(1);
+    await expect(playground.variable.copyButton).toBeVisible();
   });
 
   test('an unset secret starts blank with a reveal control and takes a typed value', async ({ playground }) => {
     await playground.variable.hoverInputToken('unsetSecret');
 
     await expect(playground.variable.value).toHaveText('');
-    await expect(playground.variable.revealToggle).toHaveCount(1);
+    await expect(playground.variable.revealToggle).toBeVisible();
 
     await playground.variable.editTo('typed-secret');
 
@@ -148,6 +148,26 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     expect(state.caret).toBe(state.value.length);
   });
 
+  // fill() replaces the value in one shot, so only per-key presses exercise the
+  // deletion path through the mask.
+  test('Backspace and Delete remove characters from a masked secret', async ({ playground }) => {
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.startEditing('abcdef');
+
+    await playground.variable.editField.press('Backspace');
+    await expect(playground.variable.editField).toHaveValue('*'.repeat(5));
+
+    await playground.variable.editField.evaluate((el: HTMLTextAreaElement) => el.setSelectionRange(0, 0));
+    await playground.variable.editField.press('Delete');
+    await expect(playground.variable.editField).toHaveValue('*'.repeat(4));
+
+    await playground.variable.editField.press('Enter');
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.revealToggle.click();
+
+    await expect(playground.variable.value).toHaveText('bcde');
+  });
+
   test('typing into the middle of a masked secret edits the real value', async ({ playground }) => {
     await playground.variable.hoverInputToken('unsetSecret');
     await playground.variable.startEditing('abcdef');
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index e4b40c5d..89115f83 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -105,22 +105,26 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
 
   /**
    * The field shows one mask character per real character, so display and real
-   * indices line up. That lets the edit be replayed onto the real string: take
-   * what the browser inserted at the old selection and splice it in at the same
-   * offsets.
+   * indices line up and an edit can be replayed onto the real string.
+   *
+   * The replaced range is derived from the caret after the edit rather than the
+   * selection before it: a Backspace on a collapsed caret removes a character
+   * outside that selection, which the selection alone cannot describe.
    */
   const handleEditChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
-    const next = event.target.value;
+    const el = event.target;
+    const next = el.value;
     if (!maskWhileEditing) {
       setDraft(next);
       return;
     }
 
-    const { start, end } = selectionRef.current;
-    const insertedLength = next.length - draft.length + (end - start);
-    const inserted = insertedLength > 0 ? next.slice(start, start + insertedLength) : '';
-    caretRef.current = start + inserted.length;
-    setDraft(draft.slice(0, start) + inserted + draft.slice(end));
+    const caret = el.selectionStart ?? 0;
+    const from = Math.min(selectionRef.current.start, caret);
+    const inserted = next.slice(from, caret);
+    const removedCount = draft.length - (next.length - inserted.length);
+    caretRef.current = caret;
+    setDraft(draft.slice(0, from) + inserted + draft.slice(from + removedCount));
   };
 
   const handleEditKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
index 0c85b850..979dcbf5 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
@@ -49,8 +49,11 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
   );
 
   // A new value clears the tick, so it never claims success for text that was
-  // not the text copied.
-  useEffect(() => setCopied(false), [text]);
+  // not the text copied. `getText` is expected to be stable, as it already is
+  // for the copy handler below.
+  useEffect(() => {
+    setCopied(false);
+  }, [text, getText]);
 
   const handleCopy = useCallback(async () => {
     if (!navigator.clipboard) return;

From 934bce93ae3ba8049b27f072503e0ef6428792f6 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 11:23:35 +0530
Subject: [PATCH 15/25] test(playground): assert the copied tick is visible
 rather than counted

---
 .../e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index ded6934a..bae271ac 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -154,7 +154,7 @@ test.describe('Variable hover card', () => {
 
     await variableCard.copyButton.click();
 
-    await expect(variableCard.copiedTick).toHaveCount(1);
+    await expect(variableCard.copiedTick).toBeVisible();
     await expect(variableCard.copiedTick).toHaveCount(0, { timeout: 3000 });
   });
 

From 8c66c431c2511bcac25b6d956c75a91a40e2d0f1 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 11:34:41 +0530
Subject: [PATCH 16/25] fix(playground): stop the environments editor writing
 contradictory toggles

The external-secret merge carried the whole existing entry, including a
legacy enabled key, while the row is written as disabled. An entry
authored enabled:false round-tripped to { enabled: false, disabled: false },
which the active check reads as off, so the secret silently stopped
resolving while the checkbox showed it on. The merge now drops enabled,
and the editor builds its rows with the same predicate the resolver uses.

Also records the agreed semantics for an unfilled secret: environment and
external secrets alike leave the reference unresolved rather than sending
an empty value.
---
 .../playground/playground-variables.spec.ts   | 17 ++++++++++++++
 .../EnvironmentsView/EnvironmentsView.tsx     | 11 ++++++----
 .../src/utils/environments.spec.ts            | 14 ++++++++++++
 .../bruno-api-docs/src/utils/environments.ts  | 22 ++++++++++++-------
 4 files changed, 52 insertions(+), 12 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 7646e755..cd539b34 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -198,6 +198,23 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.value).toHaveText('*'.repeat('typed-secret'.length));
   });
 
+  // A secret nobody filled in has no value to send, so it stays an unresolved
+  // reference rather than silently becoming an empty parameter. Environment and
+  // external secrets agree on this.
+  test('leaves an unfilled secret unresolved in the request', async ({ page, responsePane }) => {
+    const sent: string[] = [];
+    await page.route('**/customers/**', (route) => {
+      sent.push(route.request().url());
+      return route.fulfill({ status: 200, headers: { 'content-type': 'application/json' }, body: '{}' });
+    });
+
+    await responsePane.send();
+
+    await expect.poll(() => sent.length).toBeGreaterThan(0);
+    expect(sent[0]).toContain('s={{unsetSecret}}');
+    expect(sent[0]).toContain('k={{vaultKey}}');
+  });
+
   // The point of making secrets fillable: the value has to reach the wire.
   test('sends a typed secret with the request', async ({ page, playground, responsePane }) => {
     const sent: string[] = [];
diff --git a/packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx b/packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx
index 13da6aee..676ab107 100644
--- a/packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx
+++ b/packages/bruno-api-docs/src/components/Playground/Content/Views/EnvironmentsView/EnvironmentsView.tsx
@@ -14,7 +14,7 @@ import { GlobeIcon } from '../../../../../assets/icons';
 import { useAppDispatch } from '../../../../../store/hooks';
 import { cx } from '../../../../../utils/cx';
 import { envVariableToRow, envRowToVariable, mergeExternalSecretRows } from '../../../../../utils/environments';
-import { isSecretVariable } from '../../../../../utils/variableResolution';
+import { isSecretVariable, isExternalSecretActive, type ExternalSecretEntry } from '../../../../../utils/variableResolution';
 import { updateCollectionEnvironments } from '@slices/playground';
 
 const ENV_TABS = [
@@ -65,12 +65,15 @@ const EnvironmentsView: React.FC<EnvironmentsViewProps> = ({ collection, compact
   const secretProviderType = selectedEnvironment?.externalSecrets?.type as SecretProviderType | undefined;
   const secretPointerField = (secretProviderType && SECRET_POINTER_FIELD[secretProviderType]) || 'secretName';
 
-  const externalRows: KeyValueRow[] = (selectedEnvironment?.externalSecrets?.variables ?? []).map(
-    (variable: { name?: string; disabled?: boolean }, index: number) => ({
+  // Same predicate the resolver uses, so the checkbox and the request agree on
+  // which entries are live.
+  const externalEntries = (selectedEnvironment?.externalSecrets?.variables ?? []) as ExternalSecretEntry[];
+  const externalRows: KeyValueRow[] = externalEntries.map(
+    (variable, index: number) => ({
       id: `ext-${index}`,
       name: variable.name ?? '',
       value: (variable as Record<string, string | undefined>)[secretPointerField] ?? '',
-      enabled: variable.disabled !== true
+      enabled: isExternalSecretActive(variable)
     })
   );
 
diff --git a/packages/bruno-api-docs/src/utils/environments.spec.ts b/packages/bruno-api-docs/src/utils/environments.spec.ts
index a012cd3a..f0059ff7 100644
--- a/packages/bruno-api-docs/src/utils/environments.spec.ts
+++ b/packages/bruno-api-docs/src/utils/environments.spec.ts
@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { getEnvironmentVariables, envVariableToRow, envRowToVariable, mergeExternalSecretRows } from './environments';
+import { isExternalSecretActive } from './variableResolution';
 
 describe('getEnvironmentVariables', () => {
   it('splits regular and secret variables', () => {
@@ -303,6 +304,19 @@ describe('mergeExternalSecretRows', () => {
     expect(out[0].disabled).toBe(true);
   });
 
+  // Carrying `enabled` alongside the row's `disabled` would leave the two
+  // contradicting each other, switching the secret off behind the user's back.
+  it('drops a legacy enabled key rather than contradicting the row toggle', () => {
+    const legacy = [{ name: 'apiKey', secretName: 'prod/api-key', enabled: false }];
+    const rows = [{ name: 'apiKey', value: 'prod/api-key', enabled: true }];
+
+    const [out] = mergeExternalSecretRows(legacy, rows, 'secretName') as Record<string, unknown>[];
+
+    expect(out.enabled).toBeUndefined();
+    expect(out.disabled).toBe(false);
+    expect(isExternalSecretActive(out as { disabled?: boolean; enabled?: boolean })).toBe(true);
+  });
+
   it('adds a brand new row with no carried fields', () => {
     const rows = [{ name: 'fresh', value: 'prod/fresh', enabled: true }];
 
diff --git a/packages/bruno-api-docs/src/utils/environments.ts b/packages/bruno-api-docs/src/utils/environments.ts
index f5f9879b..75a89531 100644
--- a/packages/bruno-api-docs/src/utils/environments.ts
+++ b/packages/bruno-api-docs/src/utils/environments.ts
@@ -3,7 +3,7 @@ import type { Variable, VariableValueType } from '@opencollection/types/common/v
 import { MANAGER_LABELS } from '../constants';
 import { getDescription, getVariableTypeLabel } from './request';
 import { descriptionText, resolveDescription } from './description';
-import { isSecretVariable, unwrapVariableValue } from './variableResolution';
+import { isSecretVariable, unwrapVariableValue, type ExternalSecretEntry } from './variableResolution';
 import { rowToVariable, toDataType } from './variableDataType';
 
 const humanizeManager = (type: string | undefined): string => {
@@ -80,19 +80,25 @@ interface ExternalSecretsConfig {
  * 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.
+ *
+ * The legacy `enabled` key is deliberately dropped: the row's toggle is written
+ * as `disabled`, and keeping both would leave the pair contradicting each other.
  */
 export const mergeExternalSecretRows = (
-  existing: { name?: string }[] | undefined,
+  existing: ExternalSecretEntry[] | 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
-  }));
+  return rows.map((row) => {
+    const { enabled: _legacyToggle, ...carried } = byName.get(row.name) ?? {};
+    return {
+      ...carried,
+      name: row.name,
+      [pointerField]: row.value,
+      disabled: !row.enabled
+    };
+  });
 };
 
 export interface EnvironmentVariableRow {

From 8bb03e3510897c6913fd3e3908507e130a2298dd Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 11:48:42 +0530
Subject: [PATCH 17/25] refactor(playground): fold the two caret effects into
 one and rewrite comments

Seeding the caret position when editing starts lets a single effect handle
both cases, since placing the caret at the end of a fresh edit is just
another position to restore.

Comments across the change are rewritten to explain the code to someone
reading it for the first time, rather than narrating how it came to be
written, and two that repeated an explanation given elsewhere are removed.
---
 .../variable-card/variable-card.component.ts  |  6 +--
 .../playground/playground-variables.spec.ts   | 20 ++++----
 .../variableInfoPopup.spec.ts                 |  2 +-
 .../VariableInfoCard.spec.tsx                 |  4 +-
 .../VariableInfoCard/VariableInfoCard.tsx     | 49 ++++++++++---------
 .../src/hooks/useVariableResolver.tsx         | 12 ++---
 packages/bruno-api-docs/src/runner/index.ts   |  6 +--
 .../src/store/slices/playground.ts            |  5 +-
 .../src/ui/CopyButton/CopyButton.tsx          |  6 +--
 .../src/utils/environments.spec.ts            |  4 +-
 .../bruno-api-docs/src/utils/environments.ts  | 12 +++--
 .../src/utils/variableResolution.test.ts      |  4 +-
 .../src/utils/variableResolution.ts           | 19 +++----
 13 files changed, 74 insertions(+), 75 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts b/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
index c9515e67..3fc95fca 100644
--- a/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
+++ b/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
@@ -7,9 +7,9 @@ export class VariableCardComponent extends BaseComponent {
   readonly scopeBadge = this.card.getByTestId('variable-info-card-scope');
   readonly value = this.card.getByTestId('variable-info-card-value');
   readonly copyButton = this.card.getByTestId('variable-info-card-copy');
-  // Both facts of the copied state in one locator, so a test asserts it once
-  // rather than racing several assertions against the one-second reset: the
-  // button carries data-copied, and its glyph is the checkmark (a polyline).
+  // Matches only while the copy button is showing its confirmation: the button
+  // is marked copied and its icon has become the checkmark. The confirmation
+  // clears itself after a second, so a test should assert it in one step.
   readonly copiedTick = this.card.locator('[data-testid="variable-info-card-copy"][data-copied] polyline');
   readonly revealToggle = this.card.getByTestId('variable-info-card-reveal');
   readonly note = this.card.getByTestId('variable-info-card-note');
diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index cd539b34..8a2aeb5a 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -133,8 +133,8 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.value).toHaveText('*'.repeat('vault-value'.length));
   });
 
-  // The field's own content is the mask, so the real value is never in the DOM
-  // and the caret cannot drift away from the end of the asterisks.
+  // The field contains the asterisks themselves rather than the secret, so the
+  // secret is never present in the page while it is hidden.
   test('the edit field holds only mask characters while the secret is hidden', async ({ playground }) => {
     await playground.variable.hoverInputToken('unsetSecret');
     await playground.variable.startEditing('typed-secret');
@@ -148,8 +148,8 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     expect(state.caret).toBe(state.value.length);
   });
 
-  // fill() replaces the value in one shot, so only per-key presses exercise the
-  // deletion path through the mask.
+  // Use key presses, not fill(): fill() replaces the whole value at once and so
+  // never exercises deleting a single character through the mask.
   test('Backspace and Delete remove characters from a masked secret', async ({ playground }) => {
     await playground.variable.hoverInputToken('unsetSecret');
     await playground.variable.startEditing('abcdef');
@@ -198,9 +198,9 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.value).toHaveText('*'.repeat('typed-secret'.length));
   });
 
-  // A secret nobody filled in has no value to send, so it stays an unresolved
-  // reference rather than silently becoming an empty parameter. Environment and
-  // external secrets agree on this.
+  // A secret nobody filled in has no value to send, so the request keeps the
+  // `{{name}}` reference instead of quietly sending an empty value. Environment
+  // secrets and external secrets behave the same way here.
   test('leaves an unfilled secret unresolved in the request', async ({ page, responsePane }) => {
     const sent: string[] = [];
     await page.route('**/customers/**', (route) => {
@@ -215,7 +215,6 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     expect(sent[0]).toContain('k={{vaultKey}}');
   });
 
-  // The point of making secrets fillable: the value has to reach the wire.
   test('sends a typed secret with the request', async ({ page, playground, responsePane }) => {
     const sent: string[] = [];
     await page.route('**/customers/**', (route) => {
@@ -228,8 +227,9 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
 
     await expect(playground.variable.value).toHaveText('*'.repeat('typed-secret'.length));
 
-    // A card is already open, so hoverInputToken's visibility wait returns at
-    // once; wait for it to be showing this variable before editing.
+    // A card is already open from the edit above, so the hover helper's wait for
+    // a visible card returns immediately. Wait for the name to change before
+    // editing, or the edit lands on the previous variable.
     await playground.variable.hoverInputToken('vaultKey');
     await expect(playground.variable.name).toHaveText('vaultKey');
     await playground.variable.editTo('vault-value');
diff --git a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
index bae271ac..3c06e409 100644
--- a/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/variableInfoPopup/variableInfoPopup.spec.ts
@@ -75,7 +75,7 @@ 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.
+  // Only the playground can fill an external secret in, so the docs leave it unresolved.
   test('leaves an external secret undefined', async ({ requestPage }) => {
     const { variableCard } = requestPage;
     await variableCard.hoverToken('vaultKey');
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index bfb9947b..8dc88cfb 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -89,8 +89,8 @@ describe('VariableInfoCard', () => {
     expect(root.querySelector(selector('copy'))).toBeNull();
   });
 
-  // PageRouter wraps the docs pages in ItemVariableResolverProvider without
-  // `writable`, so that mount must leave external secrets unresolved too.
+  // The docs reach this card through two different providers, so both have to
+  // leave external secrets unresolved. PageRouter uses the second one.
   it('does not resolve an external secret on either docs provider', () => {
     expect(part(useRenderToDom(cardTree('vaultKey')), 'scope').text).toBe('Undefined');
 
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 89115f83..aab95a41 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -8,7 +8,7 @@ import { StyledWrapper } from './StyledWrapper';
 
 const EDITABLE_SCOPES = new Set<VariableScope>(['environment', 'collection', 'folder', 'request', '$secrets']);
 
-/** Scopes whose value the active environment supplies, so editing needs one selected. */
+/** These scopes read their values from the active environment, so one must be selected to edit them. */
 const ENV_BOUND_SCOPES = new Set<VariableScope>(['environment', '$secrets']);
 
 interface VariableInfoCardProps {
@@ -18,9 +18,10 @@ interface VariableInfoCardProps {
 }
 
 /**
- * `$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.
+ * The `$secrets` scope covers two different things. A literal `{{$secrets.x}}`
+ * reference points at a secrets provider that a browser cannot reach, so it is
+ * read-only. An external secret declared on the environment can be filled in
+ * from the playground, so it is not. `canEdit` is what tells them apart.
  */
 const getReadOnlyNote = (scope: VariableScope, activeEnvName: string | null, canEdit: boolean): string | null => {
   if (scope === 'process.env' || scope === 'oauth2') return 'read-only';
@@ -29,7 +30,7 @@ const getReadOnlyNote = (scope: VariableScope, activeEnvName: string | null, can
   return null;
 };
 
-/** Masks per character so newlines survive and the mask lines up with the value. */
+/** One asterisk per character, keeping line breaks so a multi-line value still looks multi-line. */
 const maskValue = (value: string): string => value.replace(/[^\n]/g, '*');
 
 export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
@@ -43,10 +44,8 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   const [revealed, setRevealed] = useState(false);
   const [draft, setDraft] = useState('');
   const editRef = useRef<HTMLTextAreaElement>(null);
-  // Selection before the pending edit, and the caret to restore after it. The
-  // textarea shows the mask, so React re-renders it with substituted content and
-  // the browser's own caret position is lost.
   const selectionRef = useRef({ start: 0, end: 0 });
+  // Where the caret should sit after the next render, or null to leave it alone.
   const caretRef = useRef<number | null>(null);
 
   useLayoutEffect(() => {
@@ -56,20 +55,15 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     el.style.height = `${el.scrollHeight}px`;
   }, [editing, draft]);
 
-  useLayoutEffect(() => {
-    const el = editRef.current;
-    if (!editing || !el) return;
-    const end = el.value.length;
-    el.setSelectionRange(end, end);
-  }, [editing]);
-
+  // Setting a textarea's value moves the caret to the end, so any position we
+  // want to keep has to be reapplied once React has written the new value.
   useLayoutEffect(() => {
     const el = editRef.current;
     const caret = caretRef.current;
     if (!el || caret === null) return;
     caretRef.current = null;
     el.setSelectionRange(caret, caret);
-  }, [draft]);
+  }, [editing, draft]);
 
   const canEdit
     = editable
@@ -79,17 +73,21 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
       && EDITABLE_SCOPES.has(info.scope)
       && (!ENV_BOUND_SCOPES.has(info.scope) || !!activeEnvName);
 
-  // Docs keep the opaque "(Secret)" treatment; only the playground fills them in.
+  // Secrets are only fillable in the playground. The rendered docs show the
+  // original "(Secret)" placeholder with no mask, reveal or copy.
   const secretFillable = editable && info.secret;
   const masked = secretFillable && !revealed;
   const displayValue = masked ? maskValue(info.value) : info.value;
-  // A variable that is secret only because it references one has a raw value
-  // like `Bearer {{token}}`, which holds no secret material, so editing it plainly.
+  // A variable can be secret because it *is* one, or because its value mentions
+  // one. In the second case the raw value is a template such as
+  // `Bearer {{token}}`, which holds nothing sensitive, so it is edited in plain
+  // text rather than masked.
   const maskWhileEditing = masked && info.rawValue === info.value;
   const editValue = maskWhileEditing ? maskValue(draft) : draft;
 
   const startEditing = () => {
     setDraft(info.rawValue);
+    caretRef.current = info.rawValue.length;
     setEditing(true);
   };
 
@@ -104,12 +102,15 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   };
 
   /**
-   * The field shows one mask character per real character, so display and real
-   * indices line up and an edit can be replayed onto the real string.
+   * While masked, the field contains asterisks rather than the secret, so an
+   * edit has to be translated back onto the real string. There is one asterisk
+   * per character, so a position in the field is the same position in the value.
    *
-   * The replaced range is derived from the caret after the edit rather than the
-   * selection before it: a Backspace on a collapsed caret removes a character
-   * outside that selection, which the selection alone cannot describe.
+   * The edited range runs from wherever the change began to wherever the caret
+   * ended up. Reading it from the caret afterwards, rather than from the
+   * selection beforehand, is what makes Backspace and Delete work: they remove a
+   * character next to an empty selection, which the selection alone cannot
+   * describe.
    */
   const handleEditChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
     const el = event.target;
diff --git a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
index a62ffa8f..816fab12 100644
--- a/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
+++ b/packages/bruno-api-docs/src/hooks/useVariableResolver.tsx
@@ -111,18 +111,12 @@ const makeResolver = (
   };
 };
 
-/**
- * External secrets are `{ name, secretName }` pointers: `name` is what the
- * collection references as `{{name}}`, `secretName` only says where a provider
- * would fetch it. The browser cannot reach the provider, so the only value they
- * can carry is one typed into the playground this session.
- */
+/** Presents an environment's external secrets as ordinary secret variables. */
 const externalSecretVariables = (environment: Environment | undefined): SecretVariable[] =>
   ((environment?.externalSecrets?.variables ?? []) as ExternalSecretEntry[])
     .filter((entry) => entry.name && isExternalSecretActive(entry))
     .map((entry) => ({ name: entry.name, secret: true, value: entry.value ?? '' }) as unknown as SecretVariable);
 
-/** `withExternalSecrets` tracks the writable (playground) mount; docs leave them unresolved. */
 const collectionAndEnvSources = (
   collection: OpenCollection | null,
   activeEnvName: string | null,
@@ -213,8 +207,8 @@ 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.
+  // Both the docs pages and the playground mount this provider; only the
+  // playground passes `writable`, and only it can supply an external secret.
   const model = useMemo(() => {
     const sources: VariableSource[] = collectionAndEnvSources(collection, activeEnvName, writable);
     for (const folder of ancestry) {
diff --git a/packages/bruno-api-docs/src/runner/index.ts b/packages/bruno-api-docs/src/runner/index.ts
index 0ce0764b..372d97df 100644
--- a/packages/bruno-api-docs/src/runner/index.ts
+++ b/packages/bruno-api-docs/src/runner/index.ts
@@ -220,10 +220,10 @@ export class RequestRunner {
     return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
   }
 
-  /** A secret carries its data type as a sibling `type`; a plain one nests it in `value`. */
   private getEnvironmentVariables(environment?: Environment): Record<string, any> {
-    // External secrets resolve as ordinary `{{name}}` references, so they seed
-    // the map and an explicitly declared variable of the same name overwrites.
+    // External secrets are referenced as ordinary `{{name}}` variables, so they
+    // go in first and a variable declared on the environment with the same name
+    // takes precedence over them.
     const externalSecrets = externalSecretValues(
       environment?.externalSecrets?.variables as ExternalSecretEntry[] | undefined
     );
diff --git a/packages/bruno-api-docs/src/store/slices/playground.ts b/packages/bruno-api-docs/src/store/slices/playground.ts
index 0143ea87..fa2a2699 100644
--- a/packages/bruno-api-docs/src/store/slices/playground.ts
+++ b/packages/bruno-api-docs/src/store/slices/playground.ts
@@ -238,8 +238,9 @@ const playgroundSlice = createSlice({
       }>
     ) => {
       const { scope, name, value, envName, itemUuid } = action.payload;
-      // Secrets are writable here: the value lives only on this in-memory copy,
-      // which is rebuilt from the source collection on reload and never serialized.
+      // Secret variables are writable. Their values only ever live on this
+      // in-memory copy of the collection, which is rebuilt from the source on
+      // reload and never written back, so nothing typed here is persisted.
       const setInList = (list: (Variable | SecretVariable)[] | undefined): void => {
         const enabled = (list ?? []).filter((v) => v.name === name && !v.disabled);
         const variable = enabled[enabled.length - 1] as (Variable & { value?: string }) | undefined;
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
index 979dcbf5..15f813b5 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
@@ -48,9 +48,9 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
     []
   );
 
-  // A new value clears the tick, so it never claims success for text that was
-  // not the text copied. `getText` is expected to be stable, as it already is
-  // for the copy handler below.
+  // Clear the confirmation when the value changes, so the tick never vouches for
+  // text that was not the text copied. Callers passing `getText` should keep the
+  // reference stable, as the copy handler below already requires.
   useEffect(() => {
     setCopied(false);
   }, [text, getText]);
diff --git a/packages/bruno-api-docs/src/utils/environments.spec.ts b/packages/bruno-api-docs/src/utils/environments.spec.ts
index f0059ff7..530b5c8e 100644
--- a/packages/bruno-api-docs/src/utils/environments.spec.ts
+++ b/packages/bruno-api-docs/src/utils/environments.spec.ts
@@ -304,8 +304,8 @@ describe('mergeExternalSecretRows', () => {
     expect(out[0].disabled).toBe(true);
   });
 
-  // Carrying `enabled` alongside the row's `disabled` would leave the two
-  // contradicting each other, switching the secret off behind the user's back.
+  // An entry holding both `enabled: false` and `disabled: false` reads as off,
+  // which would switch the secret off even though the table shows it on.
   it('drops a legacy enabled key rather than contradicting the row toggle', () => {
     const legacy = [{ name: 'apiKey', secretName: 'prod/api-key', enabled: false }];
     const rows = [{ name: 'apiKey', value: 'prod/api-key', enabled: true }];
diff --git a/packages/bruno-api-docs/src/utils/environments.ts b/packages/bruno-api-docs/src/utils/environments.ts
index 75a89531..d57d889b 100644
--- a/packages/bruno-api-docs/src/utils/environments.ts
+++ b/packages/bruno-api-docs/src/utils/environments.ts
@@ -77,12 +77,14 @@ interface ExternalSecretsConfig {
 }
 
 /**
- * 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.
+ * Rebuild an environment's external secrets after the table has been edited.
  *
- * The legacy `enabled` key is deliberately dropped: the row's toggle is written
- * as `disabled`, and keeping both would leave the pair contradicting each other.
+ * A table row holds only a name, a pointer and a toggle, so anything else on the
+ * entry has to be carried across by hand. In particular the hover card stores a
+ * typed-in `value` there, which a plain rebuild would throw away.
+ *
+ * `enabled` is the exception and is dropped on purpose: the toggle is written
+ * back as `disabled`, and an entry carrying both could contradict itself.
  */
 export const mergeExternalSecretRows = (
   existing: ExternalSecretEntry[] | undefined,
diff --git a/packages/bruno-api-docs/src/utils/variableResolution.test.ts b/packages/bruno-api-docs/src/utils/variableResolution.test.ts
index eb8c8b12..6205a1a5 100644
--- a/packages/bruno-api-docs/src/utils/variableResolution.test.ts
+++ b/packages/bruno-api-docs/src/utils/variableResolution.test.ts
@@ -145,8 +145,8 @@ describe('isExternalSecretActive', () => {
     expect(isExternalSecretActive({ name: 'apiKey', disabled: false })).toBe(true);
   });
 
-  // The repo's own sample collection authors these with `enabled`, so an entry
-  // switched off that way must not reach the request.
+  // The sample collection in this repo writes `enabled`, so a secret switched
+  // off that way must not reach the request.
   it('honours the enabled spelling written by the sample collection', () => {
     expect(isExternalSecretActive({ name: 'apiKey', enabled: false })).toBe(false);
     expect(isExternalSecretActive({ name: 'apiKey', enabled: true })).toBe(true);
diff --git a/packages/bruno-api-docs/src/utils/variableResolution.ts b/packages/bruno-api-docs/src/utils/variableResolution.ts
index 90b68d88..7bf193cb 100644
--- a/packages/bruno-api-docs/src/utils/variableResolution.ts
+++ b/packages/bruno-api-docs/src/utils/variableResolution.ts
@@ -107,10 +107,11 @@ export type VariableScope =
 export type ConcreteScope = 'collection' | 'environment' | 'folder' | 'request' | '$secrets';
 
 /**
- * An environment's external secret entry. `name` is what the collection
- * references as `{{name}}`; the pointer field (`secretName`, `path`, …) names
- * the provider key. `value` only exists for a value typed in this session.
- * Older collections spell the toggle `enabled`, newer ones `disabled`.
+ * One external secret declared on an environment. `name` is what the collection
+ * references as `{{name}}`, and a pointer field (`secretName`, `path`, and so
+ * on) names the key to fetch from the provider. `value` appears only when
+ * someone types one into the playground. Collections spell the on/off toggle
+ * either `enabled` or `disabled`, so both are optional here.
  */
 export interface ExternalSecretEntry {
   name?: string;
@@ -119,15 +120,15 @@ export interface ExternalSecretEntry {
   enabled?: boolean;
 }
 
-/** Both spellings of the toggle appear in the wild, so honour whichever is present. */
+/** True unless either spelling of the toggle says the secret is switched off. */
 export const isExternalSecretActive = (entry: ExternalSecretEntry): boolean =>
   entry.disabled !== true && entry.enabled !== false;
 
 /**
- * The session values an environment's external secrets carry, keyed by the name
- * the collection references. An entry cleared to '' is a deliberate empty value
- * and is kept; one that was never filled in has no value and is skipped, leaving
- * `{{name}}` unresolved.
+ * External secret values for interpolation, keyed by the name the collection
+ * references. An entry someone cleared to an empty string is kept, because that
+ * is a value they chose. An entry nobody ever filled in is skipped, so
+ * `{{name}}` is sent as-is rather than as an empty string.
  */
 export const externalSecretValues = (entries: ExternalSecretEntry[] | undefined): Record<string, string> =>
   (entries ?? []).reduce((values, entry) => {

From 7a3d4ce7cee665d438073943bf2cc405113bf327 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 12:22:54 +0530
Subject: [PATCH 18/25] test(ui): give the copied checkmark its own test id

Replaces a compound attribute-and-element selector in the page object.
The id is derived from the button's own testId, matching how other child
ids in this codebase are built.
---
 .../components/variable-card/variable-card.component.ts    | 7 +++----
 packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx   | 6 +++---
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts b/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
index 3fc95fca..debc4ce5 100644
--- a/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
+++ b/packages/bruno-api-docs/e2e/components/variable-card/variable-card.component.ts
@@ -7,10 +7,9 @@ export class VariableCardComponent extends BaseComponent {
   readonly scopeBadge = this.card.getByTestId('variable-info-card-scope');
   readonly value = this.card.getByTestId('variable-info-card-value');
   readonly copyButton = this.card.getByTestId('variable-info-card-copy');
-  // Matches only while the copy button is showing its confirmation: the button
-  // is marked copied and its icon has become the checkmark. The confirmation
-  // clears itself after a second, so a test should assert it in one step.
-  readonly copiedTick = this.card.locator('[data-testid="variable-info-card-copy"][data-copied] polyline');
+  // Present only while the copy button is showing its confirmation, which clears
+  // itself after a second, so a test should assert it in one step.
+  readonly copiedTick = this.card.getByTestId('variable-info-card-copy-tick');
   readonly revealToggle = this.card.getByTestId('variable-info-card-reveal');
   readonly note = this.card.getByTestId('variable-info-card-note');
   readonly warning = this.card.getByTestId('variable-info-card-warning');
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
index 15f813b5..15e7f7b9 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
@@ -22,8 +22,8 @@ const CopyGlyph: React.FC = () => (
   </svg>
 );
 
-const CheckGlyph: React.FC = () => (
-  <svg {...glyphProps}>
+const CheckGlyph: React.FC<{ testId?: string }> = ({ testId }) => (
+  <svg {...glyphProps} data-testid={testId}>
     <polyline points="20 6 9 17 4 12" />
   </svg>
 );
@@ -79,7 +79,7 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
       data-testid={testId}
       style={style}
     >
-      {copied ? <CheckGlyph /> : <CopyGlyph />}
+      {copied ? <CheckGlyph testId={testId ? `${testId}-tick` : undefined} /> : <CopyGlyph />}
     </StyledWrapper>
   );
 };

From 62dd01018eeb53c0fa2a9d83b8808eb838a53f3d Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 12:33:54 +0530
Subject: [PATCH 19/25] docs(playground): explain the external secret entry
 shape more plainly

---
 .../src/utils/variableResolution.ts           | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/packages/bruno-api-docs/src/utils/variableResolution.ts b/packages/bruno-api-docs/src/utils/variableResolution.ts
index 7bf193cb..2dc355a8 100644
--- a/packages/bruno-api-docs/src/utils/variableResolution.ts
+++ b/packages/bruno-api-docs/src/utils/variableResolution.ts
@@ -107,11 +107,20 @@ export type VariableScope =
 export type ConcreteScope = 'collection' | 'environment' | 'folder' | 'request' | '$secrets';
 
 /**
- * One external secret declared on an environment. `name` is what the collection
- * references as `{{name}}`, and a pointer field (`secretName`, `path`, and so
- * on) names the key to fetch from the provider. `value` appears only when
- * someone types one into the playground. Collections spell the on/off toggle
- * either `enabled` or `disabled`, so both are optional here.
+ * One entry from an environment's "external secrets" list: a secret whose real
+ * value lives in a secrets manager such as AWS Secrets Manager or Vault, rather
+ * than in the collection itself.
+ *
+ * - `name` is how the collection refers to it, written as `{{name}}`.
+ * - `value` is filled in only when someone types one in the playground. A browser
+ *   cannot reach the secrets manager, so there is no other way to get a value.
+ * - The on/off switch is written as `enabled` by some collections and `disabled`
+ *   by others, so either may be present. Read it with `isExternalSecretActive`
+ *   rather than checking a field directly.
+ *
+ * The key used to look the secret up in the manager is stored under a field whose
+ * name varies by provider (`secretName`, `path`, and others), so it is not listed
+ * here. Nothing in the playground reads it.
  */
 export interface ExternalSecretEntry {
   name?: string;

From 4c68bc94a16e54970542258db72ef117e5e2c8df Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 16:43:52 +0530
Subject: [PATCH 20/25] refactor(ui): move copy state into a useCopy hook

Copy state and its reset timer are needed by more than one control, so
they move out of CopyButton into a hook. The signature and return shape
match the one being added in #21 so the two can be reconciled easily; the
hook additionally clears its confirmation when the value changes, which
CopyButton needed and any other caller wants too.
---
 packages/bruno-api-docs/src/hooks/index.ts    |  1 +
 packages/bruno-api-docs/src/hooks/useCopy.ts  | 55 +++++++++++++++++++
 .../src/ui/CopyButton/CopyButton.tsx          | 36 ++----------
 3 files changed, 60 insertions(+), 32 deletions(-)
 create mode 100644 packages/bruno-api-docs/src/hooks/useCopy.ts

diff --git a/packages/bruno-api-docs/src/hooks/index.ts b/packages/bruno-api-docs/src/hooks/index.ts
index d7bf5e4f..434f480b 100644
--- a/packages/bruno-api-docs/src/hooks/index.ts
+++ b/packages/bruno-api-docs/src/hooks/index.ts
@@ -16,6 +16,7 @@ export {
 } from './useCanRunBrunoApp';
 export { useSearchHotkey } from './useSearchHotkey';
 export { useClickOutside } from './useClickOutside';
+export { useCopy } from './useCopy';
 export { useEscapeKey } from './useEscapeKey';
 export { useLockBodyScroll } from './useLockBodyScroll';
 export { useStorage, useLocalStorage, useSessionStorage, type StorageArea, type SetStoredValue } from './useStorage';
diff --git a/packages/bruno-api-docs/src/hooks/useCopy.ts b/packages/bruno-api-docs/src/hooks/useCopy.ts
new file mode 100644
index 00000000..dbd91ed9
--- /dev/null
+++ b/packages/bruno-api-docs/src/hooks/useCopy.ts
@@ -0,0 +1,55 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface UseCopyArg {
+  text?: string;
+  getText?: () => string;
+  disabled?: boolean;
+  resetAfterMs?: number;
+}
+
+/**
+ * Clipboard copying for a control that confirms the copy for a moment
+ * afterwards, usually by swapping its icon for a tick.
+ *
+ * Pass `text` for a value that is already to hand, or `getText` for one that
+ * has to be produced at click time, such as a large response body. `getText`
+ * should be a stable reference, so wrap it in `useCallback`.
+ *
+ * A copy that fails, which happens when the page is not in a secure context,
+ * leaves `copied` false rather than throwing.
+ */
+export const useCopy = ({ text, getText, disabled, resetAfterMs = 2000 }: UseCopyArg) => {
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    },
+    []
+  );
+
+  // Drop the confirmation as soon as the value changes, so it can never vouch
+  // for text other than the text that was copied.
+  useEffect(() => {
+    setCopied(false);
+  }, [text, getText]);
+
+  const copyResponse = useCallback(async () => {
+    if (disabled || !navigator.clipboard) return;
+    const value = getText ? getText() : text;
+    if (!value) return;
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => setCopied(false), resetAfterMs);
+    } catch {
+      // Clipboard unavailable (e.g. insecure context) — fail silently.
+    }
+  }, [disabled, text, getText, resetAfterMs]);
+
+  return { copied, copyResponse };
+};
+
+export default useCopy;
diff --git a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
index 15e7f7b9..875e6cd5 100644
--- a/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
+++ b/packages/bruno-api-docs/src/ui/CopyButton/CopyButton.tsx
@@ -1,5 +1,6 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React from 'react';
 import { baseIconProps } from '../../assets/icons/baseIconProps';
+import { useCopy } from '../../hooks/useCopy';
 import { StyledWrapper } from './StyledWrapper';
 
 interface CopyButtonProps {
@@ -38,42 +39,13 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
   style,
   className
 }) => {
-  const [copied, setCopied] = useState(false);
-  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-
-  useEffect(
-    () => () => {
-      if (timeoutRef.current) clearTimeout(timeoutRef.current);
-    },
-    []
-  );
-
-  // Clear the confirmation when the value changes, so the tick never vouches for
-  // text that was not the text copied. Callers passing `getText` should keep the
-  // reference stable, as the copy handler below already requires.
-  useEffect(() => {
-    setCopied(false);
-  }, [text, getText]);
-
-  const handleCopy = useCallback(async () => {
-    if (!navigator.clipboard) return;
-    const value = getText ? getText() : text;
-    if (!value) return;
-    try {
-      await navigator.clipboard.writeText(value);
-      setCopied(true);
-      if (timeoutRef.current) clearTimeout(timeoutRef.current);
-      timeoutRef.current = setTimeout(() => setCopied(false), resetAfterMs);
-    } catch {
-      // Clipboard unavailable (e.g. insecure context) — fail silently.
-    }
-  }, [text, getText, resetAfterMs]);
+  const { copied, copyResponse } = useCopy({ text, getText, resetAfterMs });
 
   return (
     <StyledWrapper
       type="button"
       className={['copy-button', className].filter(Boolean).join(' ')}
-      onClick={handleCopy}
+      onClick={copyResponse}
       aria-label={copied ? copiedLabel : label}
       data-copied={copied ? 'true' : undefined}
       data-testid={testId}

From e9b8d6723e1de12bf1947e6cf63ddc4a5ba05639 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 17:12:42 +0530
Subject: [PATCH 21/25] refactor(ui): drop the comments from useCopy and make
 its reset render-safe

The reset now returns the existing state when nothing has been copied, so
React bails out instead of scheduling a render. CodeEditor passes the
editor contents as `text`, so this effect runs on every keystroke.
---
 packages/bruno-api-docs/src/hooks/useCopy.ts | 15 +--------------
 1 file changed, 1 insertion(+), 14 deletions(-)

diff --git a/packages/bruno-api-docs/src/hooks/useCopy.ts b/packages/bruno-api-docs/src/hooks/useCopy.ts
index dbd91ed9..3ad42876 100644
--- a/packages/bruno-api-docs/src/hooks/useCopy.ts
+++ b/packages/bruno-api-docs/src/hooks/useCopy.ts
@@ -7,17 +7,6 @@ interface UseCopyArg {
   resetAfterMs?: number;
 }
 
-/**
- * Clipboard copying for a control that confirms the copy for a moment
- * afterwards, usually by swapping its icon for a tick.
- *
- * Pass `text` for a value that is already to hand, or `getText` for one that
- * has to be produced at click time, such as a large response body. `getText`
- * should be a stable reference, so wrap it in `useCallback`.
- *
- * A copy that fails, which happens when the page is not in a secure context,
- * leaves `copied` false rather than throwing.
- */
 export const useCopy = ({ text, getText, disabled, resetAfterMs = 2000 }: UseCopyArg) => {
   const [copied, setCopied] = useState(false);
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
@@ -29,10 +18,8 @@ export const useCopy = ({ text, getText, disabled, resetAfterMs = 2000 }: UseCop
     []
   );
 
-  // Drop the confirmation as soon as the value changes, so it can never vouch
-  // for text other than the text that was copied.
   useEffect(() => {
-    setCopied(false);
+    setCopied((was) => (was ? false : was));
   }, [text, getText]);
 
   const copyResponse = useCallback(async () => {

From fbb125ec45fa1e6ea6ee099aa63d5bdef4f5ac29 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 18:24:01 +0530
Subject: [PATCH 22/25] fix(playground): reorder the large response actions and
 tighten the icon spacing

Copy now sits after Download, and the warning icon loses its bottom
margin.
---
 .../LargeResponseWarning.tsx                  | 24 +++++++++----------
 .../LargeResponseWarning/StyledWrapper.ts     |  1 -
 2 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/LargeResponseWarning.tsx b/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/LargeResponseWarning.tsx
index ff20d1cb..98e21488 100644
--- a/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/LargeResponseWarning.tsx
+++ b/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/LargeResponseWarning.tsx
@@ -50,18 +50,6 @@ export const LargeResponseWarning: React.FC<LargeResponseWarningProps> = ({ resp
           </span>
           <span>View</span>
         </button>
-        <button
-          type="button"
-          className="large-response-copy"
-          onClick={copyResponse}
-          aria-label={copied ? 'Copied response' : 'Copy response'}
-          data-testid="large-response-copy"
-        >
-          <span className="button-icon">
-            {copied ? <IconCheck size={13} strokeWidth={1} /> : <IconCopy size={13} strokeWidth={1} />}
-          </span>
-          <span>{copied ? 'Copied' : 'Copy'}</span>
-        </button>
         <button
           type="button"
           className="large-response-download"
@@ -75,6 +63,18 @@ export const LargeResponseWarning: React.FC<LargeResponseWarningProps> = ({ resp
           </span>
           <span>Download</span>
         </button>
+        <button
+          type="button"
+          className="large-response-copy"
+          onClick={copyResponse}
+          aria-label={copied ? 'Copied response' : 'Copy response'}
+          data-testid="large-response-copy"
+        >
+          <span className="button-icon">
+            {copied ? <IconCheck size={13} strokeWidth={1} /> : <IconCopy size={13} strokeWidth={1} />}
+          </span>
+          <span>{copied ? 'Copied' : 'Copy'}</span>
+        </button>
       </div>
     </StyledWrapper>
   );
diff --git a/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/StyledWrapper.ts b/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/StyledWrapper.ts
index 36869169..8fe95177 100644
--- a/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/StyledWrapper.ts
+++ b/packages/bruno-api-docs/src/components/Playground/Content/Views/Common/LargeResponseWarning/StyledWrapper.ts
@@ -11,7 +11,6 @@ export const StyledWrapper = styled.div`
   text-align: center;
 
   .warning-icon {
-    margin-bottom: 1rem;
     color: var(--oc-status-warning-text);
   }
 

From d50f77ee22b3a1f1950b5e6edfc6d6d438a4ad67 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 19:55:34 +0530
Subject: [PATCH 23/25] fix(playground): always offer copy, and copy the real
 value out of a mask

The card now shows the copy control whenever it is editable, matching the
app, so a secret waiting to be filled in still has one.

Selecting inside a masked field and copying put asterisks on the
clipboard, because the field contains the mask rather than the secret.
Copy and cut now take the selected range from the real value, which works
because a position in the field is the same position in the value.
---
 .../playground/playground-variables.spec.ts   | 33 +++++++++++++++++++
 .../VariableInfoCard.spec.tsx                 | 12 +++++--
 .../VariableInfoCard/VariableInfoCard.tsx     | 33 ++++++++++++++++++-
 3 files changed, 75 insertions(+), 3 deletions(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 8a2aeb5a..17b776d3 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -168,6 +168,39 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.value).toHaveText('bcde');
   });
 
+  // The field holds asterisks, so a plain selection copy would put those on the
+  // clipboard instead of the secret.
+  test('copying a selection out of a masked secret yields the real value', async ({ page, playground, context }) => {
+    await context.grantPermissions(['clipboard-read', 'clipboard-write']);
+
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.startEditing('abcdef');
+
+    await playground.variable.editField.press('ControlOrMeta+a');
+    await playground.variable.editField.press('ControlOrMeta+c');
+
+    await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe('abcdef');
+  });
+
+  test('cutting from a masked secret removes the real characters', async ({ page, playground, context }) => {
+    await context.grantPermissions(['clipboard-read', 'clipboard-write']);
+
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.startEditing('abcdef');
+
+    await playground.variable.editField.evaluate((el: HTMLTextAreaElement) => el.setSelectionRange(2, 4));
+    await playground.variable.editField.press('ControlOrMeta+x');
+
+    await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe('cd');
+    await expect(playground.variable.editField).toHaveValue('*'.repeat(4));
+
+    await playground.variable.editField.press('Enter');
+    await playground.variable.hoverInputToken('unsetSecret');
+    await playground.variable.revealToggle.click();
+
+    await expect(playground.variable.value).toHaveText('abef');
+  });
+
   test('typing into the middle of a masked secret edits the real value', async ({ playground }) => {
     await playground.variable.hoverInputToken('unsetSecret');
     await playground.variable.startEditing('abcdef');
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
index 8dc88cfb..276df54f 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.spec.tsx
@@ -214,16 +214,24 @@ describe('VariableInfoCard (editable)', () => {
     expect(root.querySelector(selector('copy'))).not.toBeNull();
   });
 
-  it('shows a declared external secret as blank, editable, with reveal but no copy', () => {
+  it('shows a declared external secret as blank and editable, with reveal and copy', () => {
     const root = useRenderToDom(editableCardTree('vaultKey'));
     expect(part(root, 'scope').text).toBe('Secret');
     expect(part(root, 'value').text).toBe('');
     expect(part(root, 'value').classList.contains('var-value-editable')).toBe(true);
     expect(root.querySelector(selector('reveal'))).not.toBeNull();
-    expect(root.querySelector(selector('copy'))).toBeNull();
+    expect(root.querySelector(selector('copy'))).not.toBeNull();
     expect(root.querySelector(selector('note'))).toBeNull();
   });
 
+  // The app shows copy on every card, so an unfilled secret keeps it too.
+  it('offers copy on a secret with no value yet', () => {
+    const root = useRenderToDom(editableCardTree('unsetSecret'));
+    expect(part(root, 'value').text).toBe('');
+    expect(root.querySelector(selector('copy'))).not.toBeNull();
+    expect(root.querySelector(selector('reveal'))).not.toBeNull();
+  });
+
   it('never makes a read-only scope (process.env) editable', () => {
     const root = useRenderToDom(editableCardTree('process.env.HOME'));
     expect(part(root, 'note').text).toBe('read-only');
diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index aab95a41..11968932 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -128,6 +128,33 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     setDraft(draft.slice(0, from) + inserted + draft.slice(from + removedCount));
   };
 
+  /**
+   * Copying out of a masked field would otherwise put asterisks on the
+   * clipboard. Because a position in the field is the same position in the
+   * value, the selected range can be taken from the real string instead.
+   */
+  const writeSelectionToClipboard = (event: React.ClipboardEvent<HTMLTextAreaElement>): [number, number] | null => {
+    const el = event.currentTarget;
+    const start = el.selectionStart ?? 0;
+    const end = el.selectionEnd ?? 0;
+    if (!maskWhileEditing || start === end) return null;
+    event.preventDefault();
+    event.clipboardData.setData('text/plain', draft.slice(start, end));
+    return [start, end];
+  };
+
+  const handleEditCopy = (event: React.ClipboardEvent<HTMLTextAreaElement>) => {
+    writeSelectionToClipboard(event);
+  };
+
+  const handleEditCut = (event: React.ClipboardEvent<HTMLTextAreaElement>) => {
+    const range = writeSelectionToClipboard(event);
+    if (!range) return;
+    const [start, end] = range;
+    caretRef.current = start;
+    setDraft(draft.slice(0, start) + draft.slice(end));
+  };
+
   const handleEditKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
     rememberSelection(event);
     if (event.key === 'Enter' && !event.shiftKey) {
@@ -188,7 +215,9 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   const emptyLabel = !secretFillable && info.value === '' ? '(empty)' : null;
   const placeholder = info.secret && !editable ? '(Secret)' : canEdit ? null : emptyLabel;
 
-  const showCopy = info.value !== '' && !(info.secret && !editable);
+  // The playground always offers copy, matching the app, even with nothing yet to
+  // copy. The docs keep their original rule: a value, and never for a secret.
+  const showCopy = editable || (info.value !== '' && !info.secret);
 
   const icons = (showCopy || secretFillable) && (
     <div className="var-icons">
@@ -238,6 +267,8 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
       onKeyDown={handleEditKeyDown}
       onSelect={rememberSelection}
       onMouseDown={rememberSelection}
+      onCopy={handleEditCopy}
+      onCut={handleEditCut}
       onBlur={commit}
     />
   );

From 4280a122930a99ea8ed834568397691f35fa0953 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 20:17:14 +0530
Subject: [PATCH 24/25] fix(ui): confirm a copy even when there is no value

The app ticks on every copy, whatever the variable holds, so the empty
value guard is gone. A caller that needs to block a copy passes disabled,
which ResponseActions already does for an empty response.
---
 .../tests/playground/playground-variables.spec.ts  | 14 ++++++++++++++
 packages/bruno-api-docs/src/hooks/useCopy.ts       |  2 +-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
index 17b776d3..9f8a1536 100644
--- a/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
+++ b/packages/bruno-api-docs/e2e/tests/playground/playground-variables.spec.ts
@@ -168,6 +168,20 @@ test.describe('Playground variables: highlight, hover card and inline edit', ()
     await expect(playground.variable.value).toHaveText('bcde');
   });
 
+  // The app confirms every copy, so a variable with nothing in it still ticks.
+  test('confirms a copy even when the secret has no value yet', async ({ playground, context }) => {
+    await context.grantPermissions(['clipboard-read', 'clipboard-write']);
+
+    await playground.variable.hoverInputToken('unsetSecret');
+    await expect(playground.variable.value).toHaveText('');
+    await expect(playground.variable.copyButton).toBeVisible();
+    await expect(playground.variable.copiedTick).toHaveCount(0);
+
+    await playground.variable.copyButton.click();
+
+    await expect(playground.variable.copiedTick).toBeVisible();
+  });
+
   // The field holds asterisks, so a plain selection copy would put those on the
   // clipboard instead of the secret.
   test('copying a selection out of a masked secret yields the real value', async ({ page, playground, context }) => {
diff --git a/packages/bruno-api-docs/src/hooks/useCopy.ts b/packages/bruno-api-docs/src/hooks/useCopy.ts
index 1820c771..2fc03c2f 100644
--- a/packages/bruno-api-docs/src/hooks/useCopy.ts
+++ b/packages/bruno-api-docs/src/hooks/useCopy.ts
@@ -25,7 +25,7 @@ function useCopy({
   }, [text, getText]);
 
   const copyResponse = useCallback(async () => {
-    if (disabled || !navigator.clipboard || !(text || getText)) return;
+    if (disabled || !navigator.clipboard) return;
     try {
       await navigator.clipboard.writeText(text ? text : getText ? getText() : '');
       setCopied(true);

From 424e3b9f9037e9d39620ec74668852adcdbcd4f3 Mon Sep 17 00:00:00 2001
From: Sundram Gupta <sundram@usebruno.com>
Date: Fri, 31 Jul 2026 22:30:29 +0530
Subject: [PATCH 25/25] refactor(playground): drop dead code from the variable
 card

The icons row was guarded by `showCopy || secretFillable`, but a fillable
secret is always editable and an editable card always offers copy, so the
second term could never decide anything.

Selection was also captured on mousedown, which fires before the click has
moved the caret, so it only ever stored a value that onSelect immediately
replaced. The copy handler was a wrapper that discarded its return value.
---
 .../src/components/VariableInfoCard/VariableInfoCard.tsx | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
index 11968932..0f48053e 100644
--- a/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
+++ b/packages/bruno-api-docs/src/components/VariableInfoCard/VariableInfoCard.tsx
@@ -143,10 +143,6 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
     return [start, end];
   };
 
-  const handleEditCopy = (event: React.ClipboardEvent<HTMLTextAreaElement>) => {
-    writeSelectionToClipboard(event);
-  };
-
   const handleEditCut = (event: React.ClipboardEvent<HTMLTextAreaElement>) => {
     const range = writeSelectionToClipboard(event);
     if (!range) return;
@@ -219,7 +215,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
   // copy. The docs keep their original rule: a value, and never for a secret.
   const showCopy = editable || (info.value !== '' && !info.secret);
 
-  const icons = (showCopy || secretFillable) && (
+  const icons = showCopy && (
     <div className="var-icons">
       {secretFillable && (
         <button
@@ -266,8 +262,7 @@ export const VariableInfoCard: React.FC<VariableInfoCardProps> = ({
       onChange={handleEditChange}
       onKeyDown={handleEditKeyDown}
       onSelect={rememberSelection}
-      onMouseDown={rememberSelection}
-      onCopy={handleEditCopy}
+      onCopy={writeSelectionToClipboard}
       onCut={handleEditCut}
       onBlur={commit}
     />