gracepress/wordpress-public-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update public WordPress workspace working changes

Browse Source 
- GRACEPRESS-PUBLIC-PLUGIN-STANDARDS.md
- PUBLIC-PLUGIN-WORKFLOW.md
- WORDPRESS-ORG-REQUIREMENTS.md
- WORDPRESS-PUBLIC-CONVENTIONS.md
- design/dark-mode-admin-v1.1.0-spec.md
- plugins/bible-reference-tooltips/CHANGELOG.md
- plugins/bible-reference-tooltips/bible-reference-tooltips.php
- plugins/bible-reference-tooltips/readme.txt
This commit is contained in:
Jason Eugene Garrison
2026-10-02 15:57:02 -05:00
parent f2bc638509
commit 331edafb60
11 changed files with 2069 additions and 1110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
reports/dark-mode-by-gracepress-1.0.0-baseline.md
+148
View File
@@ -0,0 +1,148 @@
# Dark Mode by GracePress 1.0.0 Baseline
Date: 2026-08-22
Scope: Phase 1 factual baseline only
Release action: none
## Artifact and environment
- Canonical source: /Workspace/gracepress-workspace/wordpress-plugins/dark-mode-by-gracepress/
- Installed artifact: /Workspace/gracepress-workspace/dist/wp-org/dark-mode-by-gracepress.zip
- Package contents: one top-level dark-mode-by-gracepress directory containing the main PHP file, CHANGELOG.md, and readme.txt.
- Installed status: active, version 1.0.0.
- Declared compatibility: WordPress 6.0+, PHP 7.4+, tested through WordPress 7.0.
- Lab runtime: WordPress 7.1, PHP 8.3.33, Twenty Twenty-Five 1.5.
- Lab URL: http://100.64.0.9:8890/
- Exposure: Desktop Tailnet address only.
## Current architecture
- The runtime is one 38 KB PHP file containing PHP, HTML, CSS, and JavaScript.
- It registers activation and deactivation hooks, init translation loading, wp_head/admin_head output, wp_footer/admin_footer output, an admin settings page, an admin-bar node, a menu-item filter, a shortcode, and plugin action links.
- It stores 19 small WordPress options. Every current option is autoloaded.
- It retains legacy option names beginning gracepress_dark_ and gp_dm_ to preserve migration compatibility.
- It has no database tables, REST routes, AJAX actions, scheduled tasks, filesystem writes, uploads, or direct remote HTTP calls.
- It retains conditional calls to private gp_omnilog() and gp_log() functions when those functions exist.
- It retains private-era routing checks for GracePress_Central_Hub, gracepress-theme, and GracePress-specific front-end selectors.
## Current saved configuration
- Default state: follow operating-system preference.
- Front-end floating control: enabled.
- WordPress admin dark mode: enabled.
- Admin/menu integration: enabled.
- Floating pulse: enabled.
- Keyboard shortcut: enabled.
- Toggle: classic icon, normal size, bottom-right.
- Brightness: 95 percent.
- Contrast: 90 percent.
- Media opacity: 85 percent.
- Transition: fade, 250 ms.
- Page exclusions, element exclusions, and custom CSS: empty.
## Admin interface in light mode
The valid visual baseline was captured only after removing the gracepress-dark-active root class. The earlier black rendering was the plugin actively filtering wp-admin and was not the page's native palette.
Strengths:
- Clear two-column desktop layout.
- Large local-only navy hero with cyan accent.
- Four named settings groups.
- Readable white cards and standard form controls.
- Working filter preview.
- Visible primary save and secondary reset actions.
- Responsive intent is present.
- GracePress footer includes John 1:5 and the plugin version.
Weaknesses:
- The hero is visually large but carries no operational status, current mode, quick action, or navigation.
- Information architecture follows implementation categories rather than user goals.
- All controls are presented at once; advanced selectors and custom CSS receive no progressive disclosure or risk explanation.
- There is no concise summary of active behavior, precedence, schedule, exclusions, or where toggles are currently displayed.
- The preview is small and demonstrates only filter values, not toggle styles, theme content, media correction, system preference, or transitions.
- Some labels use engineering language such as "absolute Anti-FOUC synchronization" and "hardware-accelerated CSS inversion" instead of user outcomes.
- Save feedback is generic and the page has no dirty-state indication.
- Reset Filters resets only three filter values, not all settings, but the distinction is easy to miss.
- The full-page browser capture repeated moving sections while stitching the image. The semantic DOM contained one set of controls, so this is recorded as a capture artifact rather than a plugin duplication defect.
## Front-end baseline
- The stock Twenty Twenty-Five homepage renders normally in light mode.
- A floating moon button appears at bottom-right.
- A Dark Mode item appears in the WordPress toolbar for logged-in users.
- The floating button's accessible name is only the moon glyph; it has no descriptive label or pressed-state semantics.
- The pill-switch variant is emitted as a div rather than a native button.
- Front-end and admin scripts use one localStorage key: gracepressDarkMode.
- No external network dependency is required for ordinary rendering.
## Confirmed implementation concerns
These are baseline findings, not the complete Phase 5 security review.
### High-priority functional issues
1. The "Enable in WordPress Admin" setting is not enforced. admin_head and admin_footer always run the dark-mode engine, and the admin-bar toggle is always registered for logged-in users.
2. admin_init force-enables the admin setting once and records gp_dm_adminbar_toggle_restored, overriding the expected role of an administrator-controlled preference.
3. The settings form always posts to admin.php?page=dark-mode-by-gracepress even when the public plugin registered its page under options-general.php. This needs direct workflow testing and likely correction.
4. Time-based mode calculates the WordPress site hour while PHP renders the page. Full-page caching can preserve a stale hour and produce incorrect schedule behavior.
5. In automatic-time mode, the schedule is evaluated before the stored manual preference, so a visitor's manual choice does not persist across page loads while automatic mode is selected.
### Security and review concerns
1. The nonce value is passed directly from POST to wp_verify_nonce() without wp_unslash() and scalar sanitization.
2. Several numeric POST values use absint() without checking that the fields exist first.
3. Enumerated settings such as default state, icon style, button size, position, and transition speed are sanitized as generic text on save rather than rejected against allow-lists.
4. Transition speed is interpolated into CSS without strict CSS-time validation.
5. Element-exclusion text is concatenated into generated selector CSS. It needs bounded selector validation and graceful handling of invalid selectors.
6. Custom CSS is intentionally emitted into every applicable page. The capability boundary is strong, but allowed syntax, external URL behavior, privacy implications, and closing-tag safety require explicit review.
7. Conditional gp_omnilog()/gp_log() integration contradicts the goal of a fully independent public plugin and complicates the readme's no-telemetry assurance.
8. Large inline CSS and JavaScript blocks are emitted on all front-end pages and broadly across wp-admin rather than being scoped and enqueued where practical.
### Accessibility and compatibility concerns
1. Floating icon buttons need descriptive accessible names and state semantics.
2. The pill-switch variant must be a keyboard-operable native control or implement complete button semantics.
3. Ctrl+Alt+D is captured globally, including while users work in form fields and editors, and may conflict with browser, operating-system, or assistive-technology commands.
4. Motion does not currently honor prefers-reduced-motion.
5. Many admin strings remain untranslated.
6. GracePress-specific media selectors remain in the public plugin and need either generalization, documented compatibility purpose, or removal.
7. The readme describes "accessible toggle controls," which is not yet fully supported by the observed controls.
8. The package declares Tested up to 7.0 while the current lab is WordPress 7.1; compatibility metadata must follow completed testing rather than assumption.
## Initial checklist disposition
Pass or substantially present:
- Independent public slug and renamed dmbg_ PHP identifiers.
- GPL-compatible declared license.
- Correct top-level installable ZIP structure.
- No direct executable-code downloads.
- No direct remote HTTP request in the current source.
- manage_options gate on the settings renderer.
- Nonce generation and basic verification are present.
- Stable tag, main header version, runtime constant, and package version agree at 1.0.0.
- Local WordPress.org icons and banners exist outside the runtime ZIP.
- No embedded credentials or API tokens observed.
- Active installation on the isolated lab succeeds.
Needs repair or proof:
- Private logging and routing remnants.
- Strict input validation and nonce handling.
- Admin-enable behavior.
- Settings form action.
- Accessibility semantics and reduced-motion behavior.
- Complete internationalization.
- Admin/front-end asset scoping and performance.
- Privacy statement reconciliation with conditional private logging.
- Readme claims versus actual accessibility.
- Uninstall/data-retention policy.
- Minimum-version matrix.
- Plugin Check, readme validator, PHPCS, debug, upgrade, deactivation, uninstall, and multisite testing.
- Exact final ZIP inspection after the redesign.
## Baseline conclusion
Version 1.0.0 is a working independent installation candidate and a sound behavioral starting point, but it is not yet a WordPress.org submission candidate. The next approved phase is competitor and user-value research, followed by an admin information-architecture proposal. No source repair or redesign was performed during this baseline.
reports/dark-mode-competitor-feature-matrix-2026-08-22.md
+155
View File
@@ -0,0 +1,155 @@
# Dark Mode Competitor and Feature Matrix
Date: 2026-08-22
Scope: Phase 2 research only
Target: Dark Mode by GracePress
Source changes: none
## Name clarification
No current WordPress.org plugin listing named "Vampire Dark Mode" was found. The likely intended reference is Dracula Dark Mode. Dracula is retained here only as a historical feature and support-case reference because its WordPress.org listing is closed. ProWritingAid also calls its own application theme "Vampire Mode," but that is not a WordPress plugin.
## Comparison set
### WP Dark Mode by WPPOOL
- Current version observed: 5.3.9.
- Active installations observed: 20,000+.
- Current strengths: mature frontend/admin product, OS preference, persistence, blocks, Elementor, presets, media tuning, device visibility, custom triggers, caching awareness, and broad compatibility work.
- Useful lessons: placement flexibility, accessibility repair history, caching awareness, and compatibility testing.
- Poor fit for GracePress: analytics, social sharing, AI preset generation, extensive commercial upsell surfaces, telemetry SDK complexity, and broad feature sprawl.
- Source: https://wordpress.org/plugins/wp-dark-mode/
### Darkify
- Current version observed: 2.0.1.
- Active installations observed: 600+.
- Current strengths: modern sectioned admin, live site preview, settings search, section/all reset, backup/restore, independent frontend/admin/editor controls, mobile controls, selected menu placement, Gutenberg block, and zero frontend output when disabled.
- Useful lessons: information architecture, preview workflow, independent surfaces, bounded reset, and no-output disabled state.
- Caution: very large breadth, React build complexity, many commercial features, and a much larger maintenance surface than GracePress currently needs.
- Source: https://wordpress.org/plugins/darkify/
### Dark Mode Toggle by ScriptsTown
- Current version observed: 1.7.5.
- Active installations observed: 2,000+.
- Tested through WordPress 7.1.
- Current strengths: lightweight activation, persistent user choice, basic switch sizing/position, simple exclusions, and a small administration surface.
- Useful lesson: the free plugin's value proposition is simplicity.
- Public review cautions: limited customization, image inversion complaints, and mobile visibility complaints.
- Source: https://wordpress.org/plugins/dark-mode-toggle/
### Dark Mode for WP Dashboard by Naiche
- Current version observed: 1.3.4.
- Active installations observed: 3,000+.
- Current strengths: per-user Light/Dark/Auto preference, instant toolbar toggle, block editor and Site Editor support, CSS custom-property design tokens, developer filters, and no settings-page bloat.
- Useful lessons: admin preference belongs to each user, editor behavior should be separable, and a stable public body class gives integrations a clean hook.
- Current support caution: third-party screens and editor canvases still need ongoing compatibility work.
- Source: https://wordpress.org/plugins/dark-mode-for-wp-dashboard/
### Dracula Dark Mode, historical reference
- Current status: closed on WordPress.org.
- Useful historical features: frontend/admin mode, menu and floating controls, custom CSS, and extensive styling options.
- High-value caution cases: dark elements active after admin mode was disabled, preference resetting between pages, visual regression after updates, image degradation, editor/media incompatibility, scrollbar changes, excessive toggle z-index, and collisions with browser dark-mode extensions.
- The admin-disable complaint closely matches a defect already confirmed in Dark Mode by GracePress.
- Source: https://wordpress.org/support/plugin/dracula-dark-mode/
## Feature decision matrix
| Feature | Evidence | Decision | Complexity | GracePress direction |
|---|---|---:|---:|---|
| Reliable visitor preference | All maintained competitors | ADOPT | Low | Define and document deterministic precedence across URL override, manual choice, OS preference, schedule, and default. |
| Per-user admin preference | Dashboard plugin | ADOPT | Moderate | Store Light/Dark/Auto in user meta rather than forcing one site-wide admin state. |
| Enforced frontend/admin enable switches | Darkify and competitor bug reports | ADOPT | Low | Disabled must mean no corresponding CSS, JS, toolbar control, or output. |
| Independent block/classic editor controls | Darkify and Dashboard plugin | ADAPT | Moderate | Separate editor-canvas behavior from general wp-admin after the base admin setting is repaired. |
| Configurable schedule range | Darkify and WP Dark Mode | ADOPT | Moderate | Replace fixed 6 PM to 6 AM with start/end controls and explicit site-timezone behavior. |
| Cache-safe schedule evaluation | WP Dark Mode caching feature | ADAPT | Moderate | Do not control caching plugins. Emit stable configuration and calculate current mode safely at runtime. |
| Live preview | Darkify | ADOPT | Moderate | Preview representative text, links, forms, media, toggle, and transition in desktop/mobile frames. |
| Settings section navigation | Darkify | ADOPT | Low | Use native server-rendered tabs or sidebar sections; React is unnecessary for the current scale. |
| Settings search | Darkify | REJECT FOR NOW | Moderate | Eighteen settings do not justify command-palette complexity. Revisit only if the surface grows materially. |
| Section reset and reset-all | Darkify | ADOPT | Low | Make scope explicit, add confirmation, and preserve unrelated settings. |
| Unsaved-change indication | Modern settings behavior | ADOPT | Low | Show dirty state, save success, and validation errors clearly. |
| Import/export settings | Darkify | INVESTIGATE LATER | Moderate | Useful for agencies, but not required for the first public candidate. |
| Clean uninstall option | Darkify | ADOPT | Low | Add an explicit retention/removal policy and an opt-in cleanup choice. |
| Device visibility controls | WP Dark Mode and Darkify | ADOPT | Low | Desktop/mobile visibility is sufficient; avoid unreliable user-agent dependence. |
| Floating offsets and safe z-index | Competitors and Dracula support | ADOPT | Low | Add horizontal/vertical offsets and use a documented, non-aggressive stacking level. |
| Dozens of switch styles | Commercial competitors | REJECT | High maintenance | Keep three or four accessible, distinctive, fully tested controls. |
| Switch color customization | WP Dark Mode and Darkify | ADAPT | Moderate | Offer a small palette and accessible custom accent, not unrestricted style sprawl. |
| Selected-menu placement | Darkify and Dracula | ADAPT | Moderate | Replace automatic injection into every menu with an explicit block/menu-item placement model. |
| Shortcode placement | Existing GracePress feature | KEEP | Low | Preserve shortcode compatibility and improve accessible output. |
| Gutenberg toggle block | WP Dark Mode and Darkify | INVESTIGATE | Moderate | Valuable public-ecosystem integration, but schedule after the core engine and admin redesign stabilize. |
| Elementor widget | WP Dark Mode and Darkify | REJECT FOR FIRST RELEASE | High | Shortcode and block cover the immediate need without vendor-specific maintenance. |
| Custom CSS selector trigger | WP Dark Mode | INVESTIGATE | Moderate | Potentially useful for existing buttons; requires a safe, understandable binding model. |
| Page/post picker exclusions | Darkify and DarkMySite | ADAPT | Moderate | Replace comma-separated IDs with searchable WordPress content selection plus a validated advanced fallback. |
| Element exclusions | All broad competitors | KEEP AND REPAIR | Moderate | Validate bounded selectors, report invalid entries, and provide common presets. |
| Allow-only mode | DarkMySite/Darkify | INVESTIGATE | Moderate | Useful for difficult sites but can complicate the mental model. |
| Color presets | WP Dark Mode and Darkify | INVESTIGATE | High | Our inversion engine does not naturally map to theme palettes; this implies an engine-level design decision. |
| Manual background/text/link colors | Darkify | INVESTIGATE | High | Do not bolt palette controls onto an inversion engine without a coherent rendering model. |
| Image brightness/contrast/grayscale | Darkify, DarkMySite, WP Dark Mode | ADAPT | Low | Replace the ambiguous media-opacity slider with clearer image/media controls and safe defaults. |
| Image/video replacement | Commercial competitors | REJECT | High | Media-library mapping and responsive source handling are disproportionate for this plugin. |
| Scrollbar styling | Darkify | REJECT BY DEFAULT | Low | It creates browser inconsistency and was a Dracula support complaint; allow custom CSS instead. |
| Reduced-motion support | Accessibility requirement | ADOPT | Low | Disable pulse and veil motion under prefers-reduced-motion unless the user explicitly opts back in. |
| Descriptive ARIA and pressed state | WP Dark Mode repair history | ADOPT | Low | Use native buttons with accessible names, aria-pressed, focus styles, and keyboard operation. |
| Custom keyboard shortcut recorder | Darkify | REJECT | Moderate | Prefer no global shortcut by default; if retained, make it optional and ignore typing/editor contexts. |
| Stable public CSS class and filters | Dashboard plugin | ADOPT | Low | Publish a stable root class and a small documented filter/action contract. |
| Full Site Editor support | Dashboard plugin | ADAPT | Moderate | Add to compatibility testing and repair scope rather than claiming universal support immediately. |
| Third-party plugin compatibility packs | Dashboard plugin | INVESTIGATE LATER | Ongoing | Begin with WordPress core surfaces; add integrations only from reproducible issues. |
| Analytics and usage counters | WP Dark Mode | REJECT | Privacy/maintenance | No tracking or usage analytics belongs in the first public GracePress plugin. |
| AI color generation | WP Dark Mode | REJECT | High/external | Unnecessary external-service, privacy, cost, and review complexity. |
| Social sharing | WP Dark Mode | REJECT | Unrelated | Outside the dark-mode product boundary. |
| Remote fonts/images/CDN assets | Historical competitor cleanups | REJECT | Privacy | Keep every runtime/admin visual asset local and license-compatible. |
| Premium comparison/upsell panels | Commercial competitors | REJECT | Product policy | The public GracePress interface should remain focused and non-spammy. |
## Recommended 1.1.0 product scope
The first redesigned candidate should remain bounded to these changes:
1. Repair and actually enforce frontend and admin enable settings.
2. Move admin preference to per-user Light, Dark, or Auto behavior.
3. Establish and document mode precedence.
4. Replace fixed schedule behavior with configurable start/end times evaluated safely at runtime.
5. Reorganize the admin page into Overview, Behavior, Toggle, Rendering, Advanced, and Help sections.
6. Build a representative live preview with desktop/mobile width controls.
7. Add visible dirty, saving, saved, and validation states.
8. Add section reset and reset-all with explicit scope.
9. Add desktop/mobile toggle visibility and safe floating offsets.
10. Keep a small set of accessible toggle styles and add accent-color control.
11. Replace automatic all-menu injection with a deliberate placement explanation; preserve shortcode support.
12. Repair page/element exclusions and provide clearer validation.
13. Replace media opacity language with image/media brightness, contrast, and grayscale controls where technically coherent.
14. Add reduced-motion behavior.
15. Repair button semantics, labels, state, keyboard behavior, and shortcut conflicts.
16. Emit no frontend assets when frontend mode is disabled and no admin engine when admin mode is disabled.
17. Remove private logging/routing remnants and publish only a small stable integration contract.
18. Add explicit data-retention and clean-uninstall policy.
## Deferred candidates
- Gutenberg block.
- Import/export.
- Custom existing-element triggers.
- Allow-only rendering.
- Color-preset or native recoloring engine.
- Third-party compatibility packs.
- Multisite network policy UI.
## Explicitly rejected direction
- Analytics or telemetry.
- AI-generated themes.
- Social-sharing features.
- Remote runtime assets.
- Large premium-style upsell surfaces.
- Dozens of decorative switches.
- Image/video replacement.
- Vendor-specific page-builder widgets in the first release.
- React solely for the settings page.
- Claims of universal theme/plugin compatibility without a maintained test matrix.
## Phase 2 conclusion
The strongest product opportunity is not matching commercial feature count. It is a smaller, trustworthy dark-mode plugin with deterministic behavior, a much better native admin experience, accessible controls, cache-safe scheduling, no telemetry, and disciplined compatibility claims.
The next phase should convert the recommended 1.1.0 scope into an admin information-architecture specification and visual direction before source edits begin.