Refresh browser automation docs for current navigation flow

web/app/[locale]/docs/browser-automation/page.tsx

@@ -102,10 +102,14 @@ cmux browser surface:2 url
 cmux browser --surface surface:2 url`}</CodeBlock>
 
       <h2>{t("navigation")}</h2>
-      <CodeBlock lang="bash">{`cmux browser open https://example.com
+      <p>{t("navigationDesc")}</p>
+      <CodeBlock lang="bash">{`# Create a new browser surface and load a URL
+cmux browser open https://example.com
 cmux browser open-split https://news.ycombinator.com
 
-cmux browser surface:2 navigate https://example.org/docs --snapshot-after
+# Reuse an existing surface for a new page
+cmux browser surface:2 navigate https://example.org/docs
+cmux browser surface:2 get url
 cmux browser surface:2 back
 cmux browser surface:2 forward
 cmux browser surface:2 reload --snapshot-after
@@ -240,7 +244,9 @@ cmux browser surface:2 download --path /tmp/report.csv --timeout-ms 30000`}</Cod
       <h2>{t("commonPatterns")}</h2>
 
       <h3>{t("patternNavigate")}</h3>
+      <p>{t("patternNavigateDesc")}</p>
       <CodeBlock lang="bash">{`cmux browser open https://example.com/login
+cmux browser surface:2 get url
 cmux browser surface:2 wait --load-state complete --timeout-ms 15000
 cmux browser surface:2 snapshot --interactive --compact
 cmux browser surface:2 get title`}</CodeBlock>
@@ -253,7 +259,8 @@ cmux browser surface:2 wait --text "Welcome"
 cmux browser surface:2 is visible "#dashboard"`}</CodeBlock>
 
       <h3>{t("patternDebug")}</h3>
-      <CodeBlock lang="bash">{`cmux browser surface:2 console list
+      <CodeBlock lang="bash">{`cmux browser surface:2 get url
+cmux browser surface:2 console list
 cmux browser surface:2 errors list
 cmux browser surface:2 screenshot --out /tmp/cmux-failure.png
 cmux browser surface:2 snapshot --interactive --compact`}</CodeBlock>
@@ -263,6 +270,23 @@ cmux browser surface:2 snapshot --interactive --compact`}</CodeBlock>
 # ...later...
 cmux browser surface:2 state load /tmp/session.json
 cmux browser surface:2 reload`}</CodeBlock>
+
+      <h2>{t("troubleshooting")}</h2>
+
+      <h3>{t("troubleBlankPage")}</h3>
+      <p>{t("troubleBlankPageDesc")}</p>
+      <CodeBlock lang="bash">{`cmux browser surface:2 get url
+# If the URL is empty or about:blank, navigate before waiting
+cmux browser surface:2 navigate https://example.com
+cmux browser surface:2 get url
+cmux browser surface:2 wait --load-state complete --timeout-ms 15000
+cmux browser surface:2 snapshot --interactive --compact`}</CodeBlock>
+
+      <h3>{t("troubleJsError")}</h3>
+      <p>{t("troubleJsErrorDesc")}</p>
+      <CodeBlock lang="bash">{`cmux browser surface:2 get url
+cmux browser surface:2 get text body
+cmux browser surface:2 get html body`}</CodeBlock>
     </>
   );
 }

web/messages/ar.json

@@ -536,7 +536,14 @@
       "patternForm": "ملء نموذج والتحقق من نص النجاح",
       "patternDebug": "التقاط مواد التصحيح عند الفشل",
       "patternSession": "حفظ واستعادة جلسة المتصفح",
-      "metaTitle": "أتمتة المتصفح"
+      "metaTitle": "أتمتة المتصفح",
+      "navigationDesc": "استخدم open أو open-split لإنشاء سطح متصفح جديد وتحميل عنوان URL. استخدم navigate عندما يكون لديك سطح بالفعل وتريد تغيير الصفحة. بعد أي من الطريقتين، أكّد عنوان URL قبل الانتظار أو أخذ لقطة.",
+      "patternNavigateDesc": "الدورة المستقرة هي: navigate ثم التحقق عبر get url ثم wait ثم snapshot.",
+      "troubleshooting": "استكشاف الأخطاء وإصلاحها",
+      "troubleBlankPage": "الصفحات الفارغة واللقطات الفارغة",
+      "troubleBlankPageDesc": "إذا كانت مخرجات snapshot فارغة أو استمر wait على load-state في انتهاء المهلة، فتحقق من عنوان URL الحالي أولاً. عنوان URL الفارغ أو about:blank يعني عادة أن الصفحة لم تنتقل.",
+      "troubleJsError": "js_error عند snapshot أو eval",
+      "troubleJsErrorDesc": "بعض الصفحات تحظر أو تكسر JavaScript المستخدم للقطات الغنية وعمليات eval السريعة. استخدم استخراج النص أو HTML أولاً، ثم أعد المحاولة على صفحة أبسط إذا لزم الأمر."
     },
     "changelog": {
       "title": "سجل التغييرات",

web/messages/bs.json

@@ -536,7 +536,14 @@
       "patternForm": "Popuni formu i provjeri tekst uspjeha",
       "patternDebug": "Uhvati debug artefakte pri neuspjehu",
       "patternSession": "Sačuvaj i obnovi sesiju preglednika",
-      "metaTitle": "Automatizacija preglednika"
+      "metaTitle": "Automatizacija preglednika",
+      "navigationDesc": "Koristite open ili open-split da napravite novu površinu preglednika i učitate URL. Koristite navigate kada već imate površinu i želite promijeniti stranicu. Nakon bilo koje od tih komandi, potvrdite URL prije čekanja ili pravljenja snapshota.",
+      "patternNavigateDesc": "Stabilna petlja je: navigate, provjera sa get url, wait, pa snapshot.",
+      "troubleshooting": "Rješavanje problema",
+      "troubleBlankPage": "Prazne stranice i prazni snapshoti",
+      "troubleBlankPageDesc": "Ako je izlaz snapshota prazan ili wait za load-state stalno timeouta, prvo provjerite trenutni URL. Prazan URL ili about:blank obično znači da se stranica nije navigirala.",
+      "troubleJsError": "js_error na snapshotu ili eval",
+      "troubleJsErrorDesc": "Neke stranice blokiraju ili kvare JavaScript koji se koristi za bogate snapshote i ad-hoc eval. Prvo pređite na izdvajanje teksta ili HTML-a, pa pokušajte ponovo na jednostavnijoj stranici ako treba."
     },
     "changelog": {
       "title": "Zapisnik promjena",

web/messages/da.json

@@ -536,7 +536,14 @@
       "patternForm": "Udfyld en formular og verificér succestekst",
       "patternDebug": "Indfang debug-artefakter ved fejl",
       "patternSession": "Gem og gendan browsersession",
-      "metaTitle": "Browserautomatisering"
+      "metaTitle": "Browserautomatisering",
+      "navigationDesc": "Brug open eller open-split til at oprette en ny browserflade og indlæse en URL. Brug navigate, når du allerede har en flade og vil skifte side. Bekræft URL'en efter begge, før du venter eller tager et snapshot.",
+      "patternNavigateDesc": "Den stabile løkke er: navigate, bekræft med get url, wait og derefter snapshot.",
+      "troubleshooting": "Fejlfinding",
+      "troubleBlankPage": "Tomme sider og tomme snapshots",
+      "troubleBlankPageDesc": "Hvis snapshot-output er tomt, eller wait på load-state bliver ved med at time out, så tjek først den aktuelle URL. En tom URL eller about:blank betyder som regel, at siden aldrig blev indlæst.",
+      "troubleJsError": "js_error ved snapshot eller eval",
+      "troubleJsErrorDesc": "Nogle sider blokerer eller ødelægger den JavaScript, der bruges til rige snapshots og ad hoc-eval. Brug tekst- eller HTML-udtræk først, og prøv derefter igen på en enklere side, hvis det er nødvendigt."
     },
     "changelog": {
       "title": "Ændringslog",

web/messages/de.json

@@ -536,7 +536,14 @@
       "patternForm": "Formular ausfüllen und Erfolgstext überprüfen",
       "patternDebug": "Debug-Artefakte bei Fehler erfassen",
       "patternSession": "Browser-Sitzung speichern und wiederherstellen",
-      "metaTitle": "Browser-Automatisierung"
+      "metaTitle": "Browser-Automatisierung",
+      "navigationDesc": "Verwenden Sie open oder open-split, um eine neue Browser-Oberfläche zu erstellen und eine URL zu laden. Verwenden Sie navigate, wenn bereits eine Oberfläche vorhanden ist und Sie die Seite wechseln möchten. Bestätigen Sie danach zuerst die URL, bevor Sie warten oder einen Snapshot erstellen.",
+      "patternNavigateDesc": "Der stabile Ablauf ist: navigate, mit get url prüfen, wait, dann snapshot.",
+      "troubleshooting": "Fehlerbehebung",
+      "troubleBlankPage": "Leere Seiten und leere Snapshots",
+      "troubleBlankPageDesc": "Wenn die Snapshot-Ausgabe leer ist oder wait auf load-state ständig ausläuft, prüfen Sie zuerst die aktuelle URL. Eine leere URL oder about:blank bedeutet meist, dass die Seite nie navigiert wurde.",
+      "troubleJsError": "js_error bei snapshot oder eval",
+      "troubleJsErrorDesc": "Einige Seiten blockieren oder beschädigen das JavaScript, das für umfangreiche Snapshots und ad-hoc-eval verwendet wird. Weichen Sie zunächst auf Text- oder HTML-Extraktion aus und versuchen Sie es dann bei Bedarf erneut auf einer einfacheren Seite."
     },
     "changelog": {
       "title": "Changelog",

web/messages/en.json

@@ -517,6 +517,7 @@
       "targetingSurface": "Targeting a browser surface",
       "targetingDesc": "Most subcommands require a target surface. You can pass it positionally or with --surface.",
       "navigation": "Navigation",
+      "navigationDesc": "Use open or open-split to create a new browser surface and load a URL. Use navigate when you already have a surface and want to change pages. After either one, confirm the URL before waiting or snapshotting.",
       "waitingSection": "Waiting",
       "waitingDesc": "Use wait to block until selectors, text, URL fragments, load state, or a JavaScript condition is satisfied.",
       "domSection": "DOM Interaction",
@@ -534,9 +535,15 @@
       "downloadsSection": "Downloads",
       "commonPatterns": "Common Patterns",
       "patternNavigate": "Navigate, wait, inspect",
+      "patternNavigateDesc": "The stable loop is navigate, verify with get url, wait, then snapshot.",
       "patternForm": "Fill a form and verify success text",
       "patternDebug": "Capture debug artifacts on failure",
-      "patternSession": "Persist and restore browser session"
+      "patternSession": "Persist and restore browser session",
+      "troubleshooting": "Troubleshooting",
+      "troubleBlankPage": "Blank pages and empty snapshots",
+      "troubleBlankPageDesc": "If snapshot output is empty or load-state waits keep timing out, check the current URL first. An empty URL or about:blank usually means the page never navigated.",
+      "troubleJsError": "js_error on snapshot or eval",
+      "troubleJsErrorDesc": "Some pages block or break the JavaScript used for rich snapshots and ad-hoc eval. Fall back to text or HTML extraction first, then retry on a simpler page if needed."
     },
     "changelog": {
       "title": "Changelog",

web/messages/es.json

@@ -536,7 +536,14 @@
       "patternForm": "Llenar un formulario y verificar el texto de éxito",
       "patternDebug": "Capturar artefactos de depuración en caso de error",
       "patternSession": "Persistir y restaurar sesión del navegador",
-      "metaTitle": "Automatización del navegador"
+      "metaTitle": "Automatización del navegador",
+      "navigationDesc": "Usa open u open-split para crear una nueva superficie del navegador y cargar una URL. Usa navigate cuando ya tengas una superficie y quieras cambiar de página. Después de cualquiera de ellas, confirma la URL antes de esperar o tomar un snapshot.",
+      "patternNavigateDesc": "El flujo estable es: navigate, verificar con get url, wait y luego snapshot.",
+      "troubleshooting": "Solución de problemas",
+      "troubleBlankPage": "Páginas en blanco y snapshots vacíos",
+      "troubleBlankPageDesc": "Si la salida de snapshot está vacía o wait sobre load-state sigue agotando el tiempo, comprueba primero la URL actual. Una URL vacía o about:blank suele significar que la página nunca navegó.",
+      "troubleJsError": "js_error en snapshot o eval",
+      "troubleJsErrorDesc": "Algunas páginas bloquean o rompen el JavaScript usado para snapshots enriquecidos y eval ad hoc. Prueba primero con extracción de texto o HTML y luego vuelve a intentarlo en una página más simple si hace falta."
     },
     "changelog": {
       "title": "Changelog",

web/messages/fr.json

@@ -536,7 +536,14 @@
       "patternForm": "Remplir un formulaire et vérifier le texte de succès",
       "patternDebug": "Capturer les artefacts de debug en cas d'échec",
       "patternSession": "Persister et restaurer la session du navigateur",
-      "metaTitle": "Automatisation du navigateur"
+      "metaTitle": "Automatisation du navigateur",
+      "navigationDesc": "Utilisez open ou open-split pour créer une nouvelle surface navigateur et charger une URL. Utilisez navigate lorsque vous avez déjà une surface et souhaitez changer de page. Après l'une ou l'autre, confirmez l'URL avant d'attendre ou de prendre un snapshot.",
+      "patternNavigateDesc": "La boucle stable est : navigate, vérifier avec get url, wait, puis snapshot.",
+      "troubleshooting": "Dépannage",
+      "troubleBlankPage": "Pages vides et snapshots vides",
+      "troubleBlankPageDesc": "Si la sortie de snapshot est vide ou que wait sur load-state expire sans cesse, vérifiez d'abord l'URL actuelle. Une URL vide ou about:blank signifie généralement que la page n'a jamais navigué.",
+      "troubleJsError": "js_error sur snapshot ou eval",
+      "troubleJsErrorDesc": "Certaines pages bloquent ou cassent le JavaScript utilisé pour les snapshots enrichis et les eval ad hoc. Passez d'abord à l'extraction de texte ou de HTML, puis réessayez sur une page plus simple si nécessaire."
     },
     "changelog": {
       "title": "Changelog",

web/messages/it.json

@@ -536,7 +536,14 @@
       "patternForm": "Compila un form e verifica il testo di successo",
       "patternDebug": "Cattura artefatti di debug in caso di errore",
       "patternSession": "Persisti e ripristina la sessione del browser",
-      "metaTitle": "Automazione del browser"
+      "metaTitle": "Automazione del browser",
+      "navigationDesc": "Usa open o open-split per creare una nuova superficie browser e caricare un URL. Usa navigate quando hai già una superficie e vuoi cambiare pagina. Dopo una delle due azioni, conferma l'URL prima di attendere o acquisire uno snapshot.",
+      "patternNavigateDesc": "Il flusso stabile è: navigate, verifica con get url, wait, poi snapshot.",
+      "troubleshooting": "Risoluzione dei problemi",
+      "troubleBlankPage": "Pagine vuote e snapshot vuoti",
+      "troubleBlankPageDesc": "Se l'output di snapshot è vuoto o wait su load-state continua ad andare in timeout, controlla prima l'URL corrente. Un URL vuoto o about:blank di solito significa che la pagina non ha mai navigato.",
+      "troubleJsError": "js_error su snapshot o eval",
+      "troubleJsErrorDesc": "Alcune pagine bloccano o rompono il JavaScript usato per snapshot ricchi ed eval ad hoc. Usa prima l'estrazione di testo o HTML, poi riprova su una pagina più semplice se necessario."
     },
     "changelog": {
       "title": "Changelog",

web/messages/ja.json

@@ -516,6 +516,7 @@
       "targetingSurface": "ブラウザサーフェスの指定",
       "targetingDesc": "ほとんどのサブコマンドにはターゲットサーフェスが必要です。位置引数または--surfaceで指定できます。",
       "navigation": "ナビゲーション",
+      "navigationDesc": "openとopen-splitは新しいブラウザサーフェスを作成してURLを読み込みます。既存サーフェスでページを切り替えるときはnavigateを使います。どちらの場合も、waitやsnapshotの前にURLを確認してください。",
       "waitingSection": "待機",
       "waitingDesc": "waitを使用して、セレクタ、テキスト、URLフラグメント、ロード状態、またはJavaScript条件が満たされるまでブロックします。",
       "domSection": "DOM操作",
@@ -533,9 +534,15 @@
       "downloadsSection": "ダウンロード",
       "commonPatterns": "よくあるパターン",
       "patternNavigate": "ナビゲート、待機、インスペクト",
+      "patternNavigateDesc": "安定したループは、ナビゲートしてget urlで確認し、waitしてからsnapshotする流れです。",
       "patternForm": "フォーム入力と成功テキストの確認",
       "patternDebug": "失敗時のデバッグアーティファクトの取得",
       "patternSession": "ブラウザセッションの保存と復元",
+      "troubleshooting": "トラブルシューティング",
+      "troubleBlankPage": "空白ページと空のスナップショット",
+      "troubleBlankPageDesc": "snapshotの出力が空だったり、load-stateのwaitがタイムアウトし続ける場合は、まず現在のURLを確認してください。URLが空、またはabout:blankなら、ページ遷移が起きていない可能性が高いです。",
+      "troubleJsError": "snapshotやevalのjs_error",
+      "troubleJsErrorDesc": "一部のページでは、リッチスナップショットやad-hoc evalに使うJavaScriptが拒否されたり壊れたりします。まずはテキストやHTMLの取得に切り替え、それでも難しければより単純なページで再試行してください。",
       "metaTitle": "ブラウザ自動化"
     },
     "changelog": {

web/messages/km.json

@@ -536,7 +536,14 @@
       "patternForm": "បំពេញទម្រង់និងផ្ទៀងផ្ទាត់អត្ថបទជោគជ័យ",
       "patternDebug": "ចាប់យកវត្ថុ debug នៅពេលបរាជ័យ",
       "patternSession": "រក្សាទុកនិងស្ដារវគ្គកម្មវិធីរុករក",
-      "metaTitle": "ស្វ័យប្រវត្តិកម្មកម្មវិធីរុករក"
+      "metaTitle": "ស្វ័យប្រវត្តិកម្មកម្មវិធីរុករក",
+      "navigationDesc": "ប្រើ open ឬ open-split ដើម្បីបង្កើតផ្ទៃកម្មវិធីរុករកថ្មី ហើយផ្ទុក URL។ ប្រើ navigate នៅពេលអ្នកមានផ្ទៃរួចហើយ ហើយចង់ប្ដូរទំព័រ។ បន្ទាប់ពីវិធីណាមួយ សូមផ្ទៀងផ្ទាត់ URL មុនពេលរង់ចាំ ឬថត snapshot។",
+      "patternNavigateDesc": "លំនាំដែលមានស្ថិរភាពគឺ៖ navigate បន្ទាប់មកផ្ទៀងផ្ទាត់ដោយ get url បន្ទាប់មក wait ហើយបន្ទាប់មក snapshot។",
+      "troubleshooting": "ដោះស្រាយបញ្ហា",
+      "troubleBlankPage": "ទំព័រទទេ និង snapshot ទទេ",
+      "troubleBlankPageDesc": "បើលទ្ធផល snapshot ទទេ ឬ wait លើ load-state តែងតែអស់ពេល សូមពិនិត្យ URL បច្ចុប្បន្នជាមុន។ URL ទទេ ឬ about:blank ជាទូទៅមានន័យថាទំព័រមិនបានប្ដូរទិសទេ។",
+      "troubleJsError": "js_error នៅលើ snapshot ឬ eval",
+      "troubleJsErrorDesc": "ទំព័រខ្លះអាចទប់ស្កាត់ ឬបំបែក JavaScript ដែលប្រើសម្រាប់ snapshot កម្រិតខ្ពស់ និង eval បណ្ដោះអាសន្ន។ សូមសាកល្បងយកអត្ថបទ ឬ HTML មុនសិន ហើយបន្ទាប់មកសាកល្បងម្ដងទៀតលើទំព័រដែលសាមញ្ញជាង ប្រសិនបើចាំបាច់។"
     },
     "changelog": {
       "title": "កំណត់ត្រាផ្លាស់ប្ដូរ",