From 582f72104e7725d29bdc838848c59b4d865cf6a7 Mon Sep 17 00:00:00 2001
From: fly1d <zhanghui121383@gmail.com>
Date: Tue, 11 Aug 2026 09:52:34 +0800
Subject: [PATCH 1/3] fix(onboarding): advance Chromium install guide

---
 src/chrome/src/ui/install.html |  2 +-
 src/chrome/src/ui/install.js   | 19 ++++++++++++++++++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/chrome/src/ui/install.html b/src/chrome/src/ui/install.html
index 20fe94e8b..4561b6b6a 100644
--- a/src/chrome/src/ui/install.html
+++ b/src/chrome/src/ui/install.html
@@ -24,7 +24,7 @@
       <div class="install-copy">
         <p id="browser-label" class="eyebrow" aria-live="polite" data-i18n="install.checking">Checking your browser…</p>
         <h1 id="install-title" data-i18n="install.installed">WebBrain installed</h1>
-        <p class="intro" data-i18n="install.open_panel.body">Open WebBrain next to this page to finish setup.</p>
+        <p id="install-intro" class="intro" aria-live="polite" data-i18n="install.open_panel.body">Open WebBrain next to this page to finish setup.</p>
 
         <button id="open-panel-button" class="open-panel-button" type="button" disabled>
           <span id="open-panel-label" data-i18n="install.open_panel">Open Side Panel</span>
diff --git a/src/chrome/src/ui/install.js b/src/chrome/src/ui/install.js
index 07e5036b3..c597bd617 100644
--- a/src/chrome/src/ui/install.js
+++ b/src/chrome/src/ui/install.js
@@ -39,6 +39,22 @@ export function getBrowserGuide(browserKey) {
   return GUIDES[browserKey] || GUIDES.unknown;
 }
 
+export function advanceInstallGuide({
+  guide,
+  documentLike = globalThis.document,
+  translate = t,
+} = {}) {
+  const title = documentLike?.getElementById?.('install-title');
+  const intro = documentLike?.getElementById?.('install-intro');
+  if (!guide?.nextKey || !title || !intro) return false;
+
+  title.dataset.i18n = 'install.pin.title';
+  intro.dataset.i18n = guide.nextKey;
+  title.textContent = translate('install.pin.title');
+  intro.textContent = translate(guide.nextKey);
+  return true;
+}
+
 /**
  * Keep the open calls in the click handler's synchronous turn. Both Chrome's
  * sidePanel.open() and Firefox's sidebarAction.open() require a user gesture.
@@ -124,7 +140,8 @@ async function hydrateGuide() {
       openButton.classList.remove('is-opening');
       openButton.disabled = false;
       openButton.removeAttribute('aria-busy');
-      status.textContent = t(guide.nextKey);
+      advanceInstallGuide({ guide });
+      status.textContent = '';
       reportInstalledPanelOpened({ build, tabId: installTab?.id }).catch(() => {});
     }).catch(() => {
       openButton.classList.remove('is-opening');

From 246e5699de6e9003512c5745fb804ab82d727a0d Mon Sep 17 00:00:00 2001
From: fly1d <zhanghui121383@gmail.com>
Date: Tue, 11 Aug 2026 09:53:14 +0800
Subject: [PATCH 2/3] fix(onboarding): advance Firefox install guide

---
 src/firefox/src/ui/install.html |  2 +-
 src/firefox/src/ui/install.js   | 19 ++++++++++++++++++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/firefox/src/ui/install.html b/src/firefox/src/ui/install.html
index d7aa8d075..e125b6ca2 100644
--- a/src/firefox/src/ui/install.html
+++ b/src/firefox/src/ui/install.html
@@ -24,7 +24,7 @@
       <div class="install-copy">
         <p id="browser-label" class="eyebrow" aria-live="polite" data-i18n="install.checking">Checking your browser…</p>
         <h1 id="install-title" data-i18n="install.installed">WebBrain installed</h1>
-        <p class="intro" data-i18n="install.open_panel.body">Open WebBrain next to this page to finish setup.</p>
+        <p id="install-intro" class="intro" aria-live="polite" data-i18n="install.open_panel.body">Open WebBrain next to this page to finish setup.</p>
 
         <button id="open-panel-button" class="open-panel-button" type="button" disabled>
           <span id="open-panel-label" data-i18n="install.open_sidebar">Open Sidebar</span>
diff --git a/src/firefox/src/ui/install.js b/src/firefox/src/ui/install.js
index 07e5036b3..c597bd617 100644
--- a/src/firefox/src/ui/install.js
+++ b/src/firefox/src/ui/install.js
@@ -39,6 +39,22 @@ export function getBrowserGuide(browserKey) {
   return GUIDES[browserKey] || GUIDES.unknown;
 }
 
+export function advanceInstallGuide({
+  guide,
+  documentLike = globalThis.document,
+  translate = t,
+} = {}) {
+  const title = documentLike?.getElementById?.('install-title');
+  const intro = documentLike?.getElementById?.('install-intro');
+  if (!guide?.nextKey || !title || !intro) return false;
+
+  title.dataset.i18n = 'install.pin.title';
+  intro.dataset.i18n = guide.nextKey;
+  title.textContent = translate('install.pin.title');
+  intro.textContent = translate(guide.nextKey);
+  return true;
+}
+
 /**
  * Keep the open calls in the click handler's synchronous turn. Both Chrome's
  * sidePanel.open() and Firefox's sidebarAction.open() require a user gesture.
@@ -124,7 +140,8 @@ async function hydrateGuide() {
       openButton.classList.remove('is-opening');
       openButton.disabled = false;
       openButton.removeAttribute('aria-busy');
-      status.textContent = t(guide.nextKey);
+      advanceInstallGuide({ guide });
+      status.textContent = '';
       reportInstalledPanelOpened({ build, tabId: installTab?.id }).catch(() => {});
     }).catch(() => {
       openButton.classList.remove('is-opening');

From f9826077a4eec48b7623301a11b65018941bb909 Mon Sep 17 00:00:00 2001
From: fly1d <zhanghui121383@gmail.com>
Date: Tue, 11 Aug 2026 09:53:57 +0800
Subject: [PATCH 3/3] test(onboarding): cover install guide transition

---
 test/run.js | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/test/run.js b/test/run.js
index beea63292..edf6321b5 100644
--- a/test/run.js
+++ b/test/run.js
@@ -20474,6 +20474,7 @@ test('first install opens a browser-aware panel launcher without fake toolbar co
       `${label}: onInstalled should pass install details to the guide gate`,
     );
     assert.match(html, /id="open-panel-button"/, `${label}: install guide should provide a real panel-open action`);
+    assert.match(html, /id="install-intro"[^>]*aria-live="polite"/, `${label}: changing install guidance should be announced accessibly`);
     assert.match(html, /id="open-panel-button"[^>]*\sdisabled(?:\s|>)/, `${label}: install CTA should start disabled until hydration binds its click handler`);
     assert.match(
       installJs,
@@ -20496,8 +20497,8 @@ test('first install opens a browser-aware panel launcher without fake toolbar co
     assert.doesNotMatch(installJs, /classList\.(?:add|remove)\('is-open'\)/, `${label}: install logic should not apply the retired success-green state`);
     assert.match(
       installJs,
-      /Promise\.resolve\(opening\)\.then\(\(\) => \{[\s\S]*?reportInstalledPanelOpened\(\{ build, tabId: installTab\?\.id \}\)[\s\S]*?\}\)\.catch/,
-      `${label}: install page should report panel bookkeeping only after a successful open`,
+      /Promise\.resolve\(opening\)\.then\(\(\) => \{[\s\S]*?advanceInstallGuide\(\{ guide \}\);[\s\S]*?reportInstalledPanelOpened\(\{ build, tabId: installTab\?\.id \}\)[\s\S]*?\}\)\.catch/,
+      `${label}: a successful panel open should advance the guide before background bookkeeping`,
     );
 
     assert.equal(
@@ -20547,6 +20548,25 @@ test('first install opens a browser-aware panel launcher without fake toolbar co
     assert.equal(installModule.getBrowserGuide('vivaldi').nextKey, 'install.pin.next', `${label}: Chromium install pages should preview the pin step without coachmark-only spatial copy`);
     assert.equal(installModule.getBrowserGuide('vivaldi').failureKey, 'install.open_failed_chromium', `${label}: Chromium browsers should receive shortcut and Extensions-menu recovery`);
 
+    const guideCopy = {
+      'install.pin.title': 'Pin WebBrain',
+      [installModule.getBrowserGuide(label === 'firefox' ? 'firefox' : 'chrome').nextKey]: 'Browser-specific next step',
+    };
+    const guideNodes = {
+      'install-title': { dataset: { i18n: 'install.installed' }, textContent: 'WebBrain installed' },
+      'install-intro': { dataset: { i18n: 'install.open_panel.body' }, textContent: 'Open WebBrain' },
+    };
+    const guideAdvanced = installModule.advanceInstallGuide({
+      guide: installModule.getBrowserGuide(label === 'firefox' ? 'firefox' : 'chrome'),
+      documentLike: { getElementById: (id) => guideNodes[id] || null },
+      translate: (key) => guideCopy[key],
+    });
+    assert.equal(guideAdvanced, true, `${label}: successful open should advance the install guide`);
+    assert.equal(guideNodes['install-title'].textContent, 'Pin WebBrain', `${label}: successful open should replace the stale installed heading`);
+    assert.equal(guideNodes['install-intro'].textContent, 'Browser-specific next step', `${label}: successful open should show native next-step guidance`);
+    assert.equal(guideNodes['install-title'].dataset.i18n, 'install.pin.title', `${label}: locale refresh should preserve the advanced heading`);
+    assert.equal(guideNodes['install-intro'].dataset.i18n, installModule.getBrowserGuide(label === 'firefox' ? 'firefox' : 'chrome').nextKey, `${label}: locale refresh should preserve the browser-specific guidance`);
+
     const calls = [];
     const messages = [];
     if (label === 'chrome') {