OCPBUGS-86491: Fix macOS Option key in pod terminal

[logonoff]

Closes #16486

Analysis / Root cause:

The NodePolyfillPlugin in webpack.config.ts injects a process polyfill (with additionalAliases: ['process']) that sets process.title = 'browser'. xterm.js 5.5.0 detects Node.js via typeof process !== 'undefined' && 'title' in process, which returns true due to the polyfill. This causes xterm to set isMac = false, so the macOS Option key is treated as Meta (sending ESC sequences) instead of functioning as a compose key.

Solution description:

Trick @xterm/term by deleting process.title at the app.tsx entrypoint, before any terminal gets loaded. That way isNode gets set to false

Test setup:

• macOS with a non-US keyboard layout (e.g., German QWERTZ) or any layout that uses Option as a compose key
• Navigate to a running Pod → Terminal tab

Test cases:

• Verify Option+key combinations produce the expected composed characters (e.g., @, {, }, |, \, ~) instead of ESC sequences
• Verify the pod terminal still functions correctly on Linux and Windows
• Verify the web terminal operator terminal still functions correctly

Browser conformance:

• Chrome
• Firefox
• Safari (or Epiphany on Linux)

Additional info:

This PR should be reverted when the upstream fix lands a stable xterm release (likely @xterm/xterm 7.0.0).

Summary by CodeRabbit

• Chores
  • Applied a minor update to the application startup sequence.

[openshift-ci-robot]

@logonoff: This pull request references Jira Issue OCPBUGS-86491, which is valid. The bug has been moved to the POST state.

3 validation(s) were run on this bug

• bug is open, matching expected state (open)
• bug target version (5.0.0) matches configured target version for branch (5.0.0)
• bug is in the state New, which is one of the valid states (NEW, ASSIGNED, POST)

The bug has been updated to refer to the pull request using the external bug tracker.

Details

In response to this:

Analysis / Root cause:

The NodePolyfillPlugin in webpack.config.ts injects a process polyfill (with additionalAliases: ['process']) that sets process.title = 'browser'. xterm.js 5.5.0 detects Node.js via typeof process !== 'undefined' && 'title' in process, which returns true due to the polyfill. This causes xterm to set isMac = false, so the macOS Option key is treated as Meta (sending ESC sequences) instead of functioning as a compose key.

#16486

Solution description:

Backport the upstream xterm.js fix via a yarn patch. The patch adds a navigator.userAgent check to the isNode detection, so that even with a process polyfill present, xterm correctly identifies the browser environment and preserves isMac = true.

Test setup:

• macOS with a non-US keyboard layout (e.g., German QWERTZ) or any layout that uses Option as a compose key
• Navigate to a running Pod → Terminal tab

Test cases:

• Verify Option+key combinations produce the expected composed characters (e.g., @, {, }, |, \, ~) instead of ESC sequences
• Verify the pod terminal still functions correctly on Linux and Windows
• Verify the web terminal operator terminal still functions correctly

Browser conformance:

• Chrome
• Firefox
• Safari (or Epiphany on Linux)

Additional info:

The upstream fix is merged into xterm.js master but not yet included in a stable release. This yarn patch can be removed when upgrading to a future xterm.js version that includes the fix.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[coderabbitai]

Walkthrough

The PR removes process.title during app bootstrap, guarded by a comment referencing an Xterm 7.0.0 issue. This statement executes after the initial authenticated fetch and before i18n initialization.

Changes

Process title cleanup

Layer / File(s)	Summary
Delete process.title in early bootstrap frontend/public/components/app.tsx	A delete statement removes process.title early in the application bootstrap sequence to address an Xterm 7.0.0 compatibility issue.

🎯 1 (Trivial) | ⏱️ ~2 minutes

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Stable And Deterministic Test Names	❌ Error	PR contains 49+ test names with variable references via template literals (e.g., ${invalidName}, ${ALL_NAMESPACES_KEY}), violating deterministic test naming requirements.	Remove variable references from test names; use static descriptive strings. Move specific values to test bodies and assertions instead.

✅ Passed checks (11 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly references the linked Jira issue (OCPBUGS-86491) and accurately describes the main change: fixing the macOS Option key in pod terminal.
Linked Issues check	✅ Passed	The code change (deleting process.title) backports the upstream xterm.js fix via yarn patch, directly addressing the root cause identified in issue #16486 where the process polyfill was causing xterm to misdetect the environment.
Out of Scope Changes check	✅ Passed	The change is narrowly scoped to fixing the process.title polyfill issue in app.tsx; all modifications directly address the macOS Option key bug without introducing unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Test Structure And Quality	✅ Passed	Custom check not applicable: PR modifies only frontend/public/components/app.tsx (TypeScript), not Ginkgo test files. No tests are added or modified.
Microshift Test Compatibility	✅ Passed	No Ginkgo e2e tests are added in this PR. The change is a frontend TypeScript fix in app.tsx. The MicroShift test compatibility check applies only to new Ginkgo e2e tests, which are not present.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	PR modifies frontend component app.tsx to fix macOS Option key handling; no Ginkgo e2e tests are added, so SNO test compatibility check does not apply.
Topology-Aware Scheduling Compatibility	✅ Passed	PR modifies only frontend/public/components/app.tsx (one-line browser fix). No deployment manifests, operators, controllers, or scheduling constraints are added. Topology-aware check does not apply.
Ote Binary Stdout Contract	✅ Passed	PR does not modify OTE binaries; changes are to frontend (TypeScript/React) and backend server code, not test infrastructure with stdout contracts.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	No Ginkgo e2e tests are added in this PR; only a frontend TypeScript component is modified to remove process.title. Check does not apply.
Description check	✅ Passed	The PR description is comprehensive and well-structured, covering analysis, solution, test setup, test cases, browser conformance, and additional info as per the template requirements.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[openshift-ci-robot]

@logonoff: This pull request references Jira Issue OCPBUGS-86491, which is valid.

3 validation(s) were run on this bug

• bug is open, matching expected state (open)
• bug target version (5.0.0) matches configured target version for branch (5.0.0)
• bug is in the state POST, which is one of the valid states (NEW, ASSIGNED, POST)

Details

In response to this:

Closes #16486

Analysis / Root cause:

The NodePolyfillPlugin in webpack.config.ts injects a process polyfill (with additionalAliases: ['process']) that sets process.title = 'browser'. xterm.js 5.5.0 detects Node.js via typeof process !== 'undefined' && 'title' in process, which returns true due to the polyfill. This causes xterm to set isMac = false, so the macOS Option key is treated as Meta (sending ESC sequences) instead of functioning as a compose key.

Solution description:

Backport the upstream xterm.js fix via a yarn patch. The patch adds a navigator.userAgent check to the isNode detection, so that even with a process polyfill present, xterm correctly identifies the browser environment and preserves isMac = true.

Test setup:

• macOS with a non-US keyboard layout (e.g., German QWERTZ) or any layout that uses Option as a compose key
• Navigate to a running Pod → Terminal tab

Test cases:

• Verify Option+key combinations produce the expected composed characters (e.g., @, {, }, |, \, ~) instead of ESC sequences
• Verify the pod terminal still functions correctly on Linux and Windows
• Verify the web terminal operator terminal still functions correctly

Browser conformance:

• Chrome
• Firefox
• Safari (or Epiphany on Linux)

Additional info:

The upstream fix is merged into xterm.js master but not yet included in a stable release. This yarn patch can be removed when upgrading to a future xterm.js version that includes the fix.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[logonoff]

A cherrypick of xtermjs/xterm.js@b522e25

[logonoff]

/hold

Need to discuss if we want to set a precedent of patching packages

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

frontend/package.json (1)

174-174: ⚡ Quick win

Document the patch purpose and removal timing.

Consider adding a comment in this file or in a dedicated PATCHES.md document explaining:

1. Why the patch is needed (webpack process polyfill breaks macOS Option key)
2. What upstream fix it backports
3. When it can be removed (after upgrading to xterm.js version that includes the fix)

📝 Suggested inline documentation

     "`@xterm/addon-fit`": "0.10.0",
+    // Patched to fix macOS Option key handling when webpack's process polyfill is present.
+    // TODO: Remove patch when upgrading to xterm.js version that includes the upstream fix
+    // for isNode detection (adds navigator.userAgent check). See OCPBUGS-86491.
     "`@xterm/xterm`": "patch:`@xterm/xterm`@npm%3A5.5.0#~/.yarn/patches/@xterm-xterm-npm-5.5.0-106735eff7.patch",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@frontend/package.json` at line 174, Add documentation explaining the purpose
and removal timing of the `@xterm/xterm` patch referenced as
"patch:`@xterm/xterm`@npm%3A5.5.0#~/.yarn/patches/@xterm-xterm-npm-5.5.0-106735eff7.patch":
state that the patch fixes the webpack process polyfill breaking macOS Option
key, cite the upstream PR/commit hash or link that this patch backports, and
specify the removal condition (e.g., remove this patch after upgrading to
xterm.js version that contains the upstream fix—include the minimum version
number). Put this comment either inline near the dependency entry in
package.json or in a dedicated PATCHES.md that references the exact patch
filename and the target xterm.js version to drop the patch.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@frontend/package.json`:
- Line 174: The package.json references a missing Yarn patch entry for
"`@xterm/xterm`" (~/.yarn/patches/@xterm-xterm-npm-5.5.0-106735eff7.patch); add
the corresponding patch file into the repo under .yarn/patches using the
original patch contents or remove the patch entry and update the dependency to a
version that contains the upstream fix. Ensure the patch (or the replacement
xterm version) implements the upstream isNode detection using
process.versions.node-style detection (not only navigator.userAgent) so behavior
matches upstream fixes for Node v21+.

---

Nitpick comments:
In `@frontend/package.json`:
- Line 174: Add documentation explaining the purpose and removal timing of the
`@xterm/xterm` patch referenced as
"patch:`@xterm/xterm`@npm%3A5.5.0#~/.yarn/patches/@xterm-xterm-npm-5.5.0-106735eff7.patch":
state that the patch fixes the webpack process polyfill breaking macOS Option
key, cite the upstream PR/commit hash or link that this patch backports, and
specify the removal condition (e.g., remove this patch after upgrading to
xterm.js version that contains the upstream fix—include the minimum version
number). Put this comment either inline near the dependency entry in
package.json or in a dedicated PATCHES.md that references the exact patch
filename and the target xterm.js version to drop the patch.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: openshift/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5611490e-fdf7-4841-855f-a212eab37e2a

📥 Commits

Reviewing files that changed from the base of the PR and between 6ba2a16 and 0c63e33.

⛔ Files ignored due to path filters (2)

• frontend/.yarn/patches/@xterm-xterm-npm-5.5.0-106735eff7.patch is excluded by !**/.yarn/**
• frontend/yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (1)

• frontend/package.json

[logonoff]

/cherry-pick release-4.22
/cherry-pick release-4.21
/cherry-pick release-4.20

[openshift-cherrypick-robot]

@logonoff: once the present PR merges, I will cherry-pick it on top of release-4.20, release-4.21, release-4.22 in new PRs and assign them to you.

Details

In response to this:

/cherry-pick release-4.22
/cherry-pick release-4.21
/cherry-pick release-4.20

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[Leo6Leo]

Tested this locally — the patch doesn't work as-is. Using German keyboard and type Option + 8 will produce (arg:8) instead of {

It targets src/common/Platform.ts, but webpack resolves xterm via "main": "lib/xterm.js" (a pre-compiled bundle), so the patched source is never consumed during the build.

After manually patching lib/xterm.js instead and rebuilding with a clean cache, the fix works correctly — verified with German QWERTZ layout (Option+8 → {, Option+L → @, etc.).

@logonoff

[logonoff]

Tested this locally — the patch doesn't work as-is. Using German keyboard and type Option + 8 will produce (arg:8) instead of {

It targets src/common/Platform.ts, but webpack resolves xterm via "main": "lib/xterm.js" (a pre-compiled bundle), so the patched source is never consumed during the build.

After manually patching lib/xterm.js instead and rebuilding with a clean cache, the fix works correctly — verified with German QWERTZ layout (Option+8 → {, Option+L → @, etc.).

@logonoff

Damn... so it was caching when I had patched lib/xterm.js and then reverted it cause the patch ended up being 1 MiB...

[logonoff]

/unhold

[vojtechszocs]

/lgtm

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: logonoff, vojtechszocs

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• frontend/OWNERS [logonoff,vojtechszocs]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[logonoff]

QA Verification Evidence

	Details
Branch	OCPBUGS-86491-xterm
Baseline	main @ fe05918cb1
Candidate	OCPBUGS-86491-xterm @ 7aed026ffc
Verified	2026-05-26
Browser	Playwright 1.60.0 / Chrome for Testing 148.0.7778.96 (playwright chromium v1223)
OS	Darwin 25.5.0
Jira	OCPBUGS-86491

Verification Steps

#	Route	Action	Status
number	route	action	status
1	/dashboards	Navigate, wait load	pass
2	/k8s/ns/openshift-console/pods	Navigate, wait load	pass
3	/k8s/ns/openshift-console/pods/console-7cd75f8fc9-pv4j2/terminal	Navigate to terminal tab	pass
4	/k8s/ns/openshift-console/pods/console-7cd75f8fc9-pv4j2/terminal	Type echo hi + Enter	pass

Animated overview (click to expand)

Baseline	Candidate

Step 1: description (status)

Baseline (main)	Candidate (OCPBUGS-86491-xterm)

Step 2: Dashboard overview (pass)

Baseline (main)	Candidate (OCPBUGS-86491-xterm)

Step 3: Pod list page (pass)

Baseline (main)	Candidate (OCPBUGS-86491-xterm)

Step 4: Pod terminal renders (pass)

Baseline (main)	Candidate (OCPBUGS-86491-xterm)

---

Warning

This verification was performed by an AI agent. Results may contain false positives or miss
regressions that require human judgment. Always review the screenshots manually before approving.

Automated QA verification by Claude Code

[Leo6Leo]

Verified the new approach locally. delete process.title in app.tsx works — Option+8 produces {, Option+L produces @, etc. on macOS with German QWERTZ layout. Much simpler fix than the yarn patch approach.

/verified by @Leo6Leo

[openshift-ci-robot]

@Leo6Leo: This PR has been marked as verified by @Leo6Leo.

Details

In response to this:

Verified the new approach locally. delete process.title in app.tsx works — Option+8 produces {, Option+L produces @, etc. on macOS with German QWERTZ layout. Much simpler fix than the yarn patch approach.

/verified by @Leo6Leo

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[logonoff]

/test all

[openshift-ci]

@logonoff: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[openshift-ci-robot]

@logonoff: Jira Issue OCPBUGS-86491: Some pull requests linked via external trackers have merged:

• openshift/console#16492

The following pull request, linked via external tracker, has not merged:

• openshift/console#16498 is open

All associated pull requests must be merged or unlinked from the Jira bug in order for it to move to the next state. Once unlinked, request a bug refresh with /jira refresh.

Jira Issue OCPBUGS-86491 has not been moved to the MODIFIED state.

This PR is marked as verified. If the remaining PRs listed above are marked as verified before merging, the issue will automatically be moved to VERIFIED after all of the changes from the PRs are available in an accepted nightly payload.

Details

In response to this:

Closes #16486

Analysis / Root cause:

The NodePolyfillPlugin in webpack.config.ts injects a process polyfill (with additionalAliases: ['process']) that sets process.title = 'browser'. xterm.js 5.5.0 detects Node.js via typeof process !== 'undefined' && 'title' in process, which returns true due to the polyfill. This causes xterm to set isMac = false, so the macOS Option key is treated as Meta (sending ESC sequences) instead of functioning as a compose key.

Solution description:

Trick @xterm/term by deleting process.title at the app.tsx entrypoint, before any terminal gets loaded. That way isNode gets set to false

Test setup:

• macOS with a non-US keyboard layout (e.g., German QWERTZ) or any layout that uses Option as a compose key
• Navigate to a running Pod → Terminal tab

Test cases:

• Verify Option+key combinations produce the expected composed characters (e.g., @, {, }, |, \, ~) instead of ESC sequences
• Verify the pod terminal still functions correctly on Linux and Windows
• Verify the web terminal operator terminal still functions correctly

Browser conformance:

• Chrome
• Firefox
• Safari (or Epiphany on Linux)

Additional info:

This PR should be reverted when the upstream fix lands a stable xterm release (likely @xterm/xterm 7.0.0).

Summary by CodeRabbit

• Chores
• Applied a minor update to the application startup sequence.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-cherrypick-robot]

@logonoff: #16492 failed to apply on top of branch "release-4.22":

Applying: OCPBUGS-86491: Fix macOS Option key in pod terminal
Using index info to reconstruct a base tree...
M	frontend/public/components/app.tsx
Falling back to patching base and 3-way merge...
Auto-merging frontend/public/components/app.tsx
CONFLICT (content): Merge conflict in frontend/public/components/app.tsx
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Patch failed at 0001 OCPBUGS-86491: Fix macOS Option key in pod terminal

Details

In response to this:

/cherry-pick release-4.22
/cherry-pick release-4.21
/cherry-pick release-4.20

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@logonoff: #16492 failed to apply on top of branch "release-4.21":

Applying: OCPBUGS-86491: Fix macOS Option key in pod terminal
Using index info to reconstruct a base tree...
M	frontend/public/components/app.tsx
Falling back to patching base and 3-way merge...
Auto-merging frontend/public/components/app.tsx
CONFLICT (content): Merge conflict in frontend/public/components/app.tsx
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Patch failed at 0001 OCPBUGS-86491: Fix macOS Option key in pod terminal

Details

In response to this:

/cherry-pick release-4.22
/cherry-pick release-4.21
/cherry-pick release-4.20

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@logonoff: new pull request created: #16499

Details

In response to this:

/cherry-pick release-4.22
/cherry-pick release-4.21
/cherry-pick release-4.20

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.