Make desktop_mode_is_enabled() honor the desktop_mode_mode_enabled filter

[epeicher]

Summary

• desktop_mode_is_enabled() now ANDs the user-meta gate with apply_filters( 'desktop_mode_mode_enabled', true, $user_id ).
• Adds an optional $user_id arg (default current user) so the filter can be consulted for any user.
• Restores the originally-documented "filter denies access centrally" contract; render-time gates (chromeless, shell payload, recycle-bin REST, PWA, presence, admin-bar toggle) now all honor filter denials.

Changes

• includes/helpers.php — helper rewritten; @since 0.7.3 note on the new filter behavior + $user_id arg.
• tests/phpunit/tests/desktopMode.php — four new helper tests (filter-false overrides positive meta, filter-true with positive meta, meta gate not bypassable, $user_id forwarding); remove_all_filters( 'desktop_mode_mode_enabled' ) in tearDown.
• docs/hooks-reference.md — desktop_mode_mode_enabled entry updated to describe central enforcement, lists consulting render-time gates, calls out the 0.7.3 change.
• docs/examples/gate-by-role.md — restores the central-helper claim with a since-0.7.3 note.
• readme.txt — 0.7.3 changelog entry with explicit behavior-change call-out.

Behavior change

Sites already using the desktop_mode_mode_enabled filter to deny a user: previously, if that user's desktop_mode_mode user-meta had been set to '1' before the filter was added, render-time gates still treated them as enabled. After this change, every gate that consults desktop_mode_is_enabled() honors the filter denial. The user is rendered as classic admin with the toggle visible but inert (AJAX continues to deny). To preserve the pre-0.7.3 leaky behavior, leave the filter off and clear user meta directly when revoking access.

Verified

• npm run build passing (all 6 vite targets).
• npm run lint passing.
• tsc --noEmit passing.
• npm run test:js: 803/803 passing.
• npm run test:php not run locally (wp-env port conflict with another worktree); relying on CI.

Carve-out audit

Trunk's includes/admin-bar.php does not yet contain PR #102's carve-out (PR #102 is the parent of this work in spirit but unmerged). The toggle's "active" label uses desktop_mode_is_enabled(). After this change, a filter-denied user with stale meta=1 sees the toggle as "Switch to Desktop Mode" (label flips because helper returns false) and is rendered as classic admin; clicking still hits the AJAX filter and is denied. No regression vs trunk: pre-this-change, the same user was already trapped because the AJAX filter blocks both enable and disable.

When PR #102 merges, its carve-out will need its own direct user-meta query rather than desktop_mode_is_enabled() for the "already inside the shell, allow exit" affordance.

Open question (out of scope)

The AJAX endpoint runs the filter unconditionally on both enable and disable, which means filter-denied users with stale meta=1 cannot disable through the toggle. Worth a separate carve-out (let a denied user clear their own meta on the way out).

Closes #105

[github-actions]

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

---

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check