feat(uve): Page Scanner — a11y and GEO report tools with private URL handling by fmontes · Pull Request #35212 · dotCMS/core

fmontes · 2026-04-04T22:23:56Z

What

Adds two new Page Scanner tools to the Universal Visual Editor: an Accessibility (a11y) report and a GEO routing report, accessible from the Page Tools panel.

Why

Editors working in UVE need actionable feedback on WCAG compliance and geographic content performance without leaving the editor. The scanner calls an external API, so the feature needs to handle cases where the page URL is not publicly reachable.

Key decisions

Private URL detection: local/private addresses (localhost, 127.0.0.1, RFC-1918 ranges, .local) are detected client-side before any API call, immediately surfacing a consent gate and cloudflared tunnel setup guide — covers both local dotCMS instances and local headless webapps connected via UVE.
Consent gate: users must explicitly acknowledge the security implications of opening a tunnel before instructions are shown; resets on dialog close.
State model: uses signalState with a status: 'idle' | 'pending' | 'done' enum instead of boolean flags, per the Kent C. Dodds pattern.
Loading animation: dedicated dot-page-scan-loading component with an animated browser illustration and scan line — shared between both report types.
Chip styles decoupled from data models: color/style decisions live in the template, not the API response models.
Tailwind-only: SCSS dropped from page-tools and scanner components (except ::ng-deep dialog overrides).

Scope

New components: dot-page-scanner-report, dot-page-scanner-a11y-report, dot-page-scanner-geo-report, dot-page-scan-loading
New service: dot-page-scanner.service
i18n keys added to Language.properties
No backend Java changes

- Add DOT_PAGE_SCANNER_API_URL and DOT_PAGE_SCANNER_API_AUTH_TOKEN env vars with whitelist exemption for token key - Add FEATURE_FLAG_PAGE_SCANNER boolean feature flag - Add PageScannerResource proxy endpoints POST /api/v1/page-scanner/a11y/check and /geo/check with short-lived JWT injection and 503 guard when env vars are missing - Add DotPageScannerReportComponent modal (90vh p-dialog) with skeleton loading, a11y accordion grouped by violation code, and GEO report with doughnut chart + category breakdown + top issues - Refactor dot-page-tools-seo panel: add prominent Accessibility/GEO tiles at top (gated by flag), clamp existing tool descriptions to 2 lines - Wire up in DotEmaShellComponent with feature flag guard Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…tokens Replace Tailwind bg-* classes on styleClass with [style] bindings overriding --p-chip-background and --p-chip-color design tokens. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ervice URL - Simplified HTML structure in dot-page-scanner-report.component.html for better readability. - Updated CLOUDFLARE_BASE URL in dot-page-scanner.service.ts to a new endpoint. - Added new i18n message keys for GEO score in Language.properties. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…child components - Extract DotPageScannerA11yReportComponent and DotPageScannerGeoReportComponent - Move shared types to models.ts and CHIP_STYLES to chip-styles.ts - Parent keeps dialog shell, loading/error state and HTTP orchestration - Fix chart colors: Chart.js requires hex values, not CSS variables - Add GEO score heading and description i18n keys Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replace all getXxx() template calls with computed() signals and pre-computed data properties to avoid re-evaluation on every change detection cycle. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…anner templates Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ynamically in template Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…l styling to templates

…to template Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ture - Changed line height in styles.scss to 1.4rem for better readability. - Updated CLOUDFLARE_BASE URL in dot-page-scanner.service.ts. - Added 'message' field to A11yGroup interface in models.ts for improved data handling. - Refactored dot-page-scanner-a11y-report.component.html for better layout and accessibility. - Enhanced dot-page-scanner-a11y-report.component.ts to include message descriptions in the report.

…blocks for element/selector Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…canner service Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… enum in page scanner report Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…nent, remove tags from model Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… scanner button design Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…l instructions Instead of sending localhost/private IPs to the scanner API and getting a 400, detect private URLs before making the HTTP call and immediately show the tunnel setup UI. Also adds the private URL error UI with 3-step cloudflared instructions and i18n keys. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…tions Show a warning screen with two paragraphs (factual + safety note) and an outlined accept button before revealing the tunnel setup steps. Resets consent on dialog close. Also splits the consent message into two i18n keys for clarity. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…omponent Add dot-page-scan-loading with a browser illustration and a scan line that animates up and down in a loop, shared between a11y and geo reports. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…iption Consent message now clearly mentions both dotCMS and headless apps in one short sentence. Removed the duplicate description paragraph from the instructions screen. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…Link Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove hardcoded default for DOT_PAGE_SCANNER_API_AUTH_TOKEN so unconfigured installs correctly return 503. Remove the token from ConfigurationResource whitelist and drop BLACKLIST_EXEMPTIONS to prevent token exposure via /api/v1/configuration/config. API URL remains in the whitelist as it is safe to expose. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Import DotMessageService from @dotcms/data-access (not @dotcms/ui) - Store takeUntilDestroyed() as field to satisfy injection context requirement - Type scan$ as Observable union to resolve subscribe overload ambiguity Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Use standard dotCMS ResponseEntityView<ErrorEntity> for all error responses instead of plain strings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Detect PAGE_SCANNER_NOT_CONFIGURED error code from the 503 response and show a dedicated UI telling the user to contact their administrator. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove client-side private URL pre-check so the not-configured error takes priority. Private URL detection now relies solely on the server error response. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Map external API auth errors to 502 BAD_GATEWAY before returning to the browser. A raw 401 from the upstream service would be intercepted by the Angular HTTP interceptor and log the user out of dotCMS. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Detect PAGE_SCANNER_AUTH_FAILED error code and show a dedicated UI with key_off icon telling the user credentials are invalid and to contact their administrator. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replace repeated icon+title+description divs with a reusable DotPageScannerMessageComponent that supports ng-content for optional extra content like buttons and warnings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…plate Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

...i/src/lib/dot-page-scanner-report/dot-page-scan-loading/dot-page-scan-loading.component.html

.../ui/src/lib/dot-page-scanner-report/dot-page-scan-loading/dot-page-scan-loading.component.ts

zJaaal · 2026-04-06T20:48:50Z

core-web/libs/portlets/edit-ema/ui/src/lib/dot-page-tools-seo/dot-page-tools-seo.component.scss

+                margin-right: 2.25rem;
            }
        }

        .p-dialog {
            .p-dialog-header {
-                padding: spacing.$spacing-4;
-                border-bottom: 1px solid colors.$color-palette-gray-300;
+                padding: 1rem;
+                border-bottom: 1px solid var(--p-gray-300);

                .p-dialog-header-icon {
                    opacity: 0;
                }
            }

            .p-dialog-content {
-                padding: 0 spacing.$spacing-3;
+                padding: 0 0.75rem;
            }


use vars if possible

zJaaal · 2026-04-06T20:49:26Z

dotcms-integration/src/test/java/com/dotmarketing/filters/FiltersTest.java

why did we removed tests?

…timization - Button title: 'GEO Routing' -> 'Generative Engine Optimization' - Button subtitle: 'Analyze geographic performance' -> 'Optimize content for AI-powered search engines' - Dialog title: 'GEO Report' -> 'Generative Engine Optimization (GEO) Report' - Score description: updated to name specific AI engines (Google AI Overviews, Perplexity, ChatGPT) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

nollymar · 2026-04-06T21:00:10Z

dotCMS/src/main/java/com/dotmarketing/business/StaticPageCacheImpl.java

        long ttl = page.getCacheTTL() > 0 ? page.getCacheTTL() * 1000 : 60 * 60 * 24 * 7 * 1000; // 1 week

-        Logger.debug(this.getClass(), () -> "PageCache Put: ttl:" + ttl + " key:" + cacheKey);
+        Logger.info(this.getClass(), () -> "PageCache Put: ttl:" + ttl + " key:" + cacheKey);


Changing the logging level here can generate too much noise. Do you really need this?

yeah, this is from a bad merge - I think I just turned this to debug

revert this

Not ours — this change came in via a merge, we did not modify StaticPageCacheImpl.java.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dotCMS/src/main/java/com/dotcms/rest/api/v1/pagescanner/PageScannerResource.java

Restored files that were dropped during a merge conflict resolution: - Task260403SetLz4CompressionOnTextColumns.java - Task260403SetPermissionReferenceUnlogged.java - FiltersTest.java (restored shouldResolvePageWithTrailingSlash test) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

wezell

This is a bad merge, you are overwriting what was just merged into main, specifically:

#35187
#35151

dotCMS/src/main/java/com/dotcms/rest/api/v1/pagescanner/PageScannerResource.java

wezell · 2026-04-06T21:11:27Z

dotCMS/src/main/java/com/dotmarketing/business/StaticPageCacheImpl.java

        long ttl = page.getCacheTTL() > 0 ? page.getCacheTTL() * 1000 : 60 * 60 * 24 * 7 * 1000; // 1 week

-        Logger.debug(this.getClass(), () -> "PageCache Put: ttl:" + ttl + " key:" + cacheKey);
+        Logger.info(this.getClass(), () -> "PageCache Put: ttl:" + ttl + " key:" + cacheKey);


yeah, this is from a bad merge - I think I just turned this to debug

dotCMS/src/main/java/com/dotmarketing/filters/CMSFilter.java

dotCMS/src/main/java/com/dotmarketing/filters/CMSUrlUtil.java

dotCMS/src/main/java/com/dotmarketing/servlets/InitServlet.java

dotCMS/src/main/java/com/dotmarketing/util/TaskLocatorUtil.java

dotCMS/src/main/resources/postgres.sql

wezell · 2026-04-06T21:14:50Z

dotCMS/src/main/java/com/dotmarketing/business/StaticPageCacheImpl.java

        long ttl = page.getCacheTTL() > 0 ? page.getCacheTTL() * 1000 : 60 * 60 * 24 * 7 * 1000; // 1 week

-        Logger.debug(this.getClass(), () -> "PageCache Put: ttl:" + ttl + " key:" + cacheKey);
+        Logger.info(this.getClass(), () -> "PageCache Put: ttl:" + ttl + " key:" + cacheKey);


revert this

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fmontes · 2026-04-06T21:20:40Z

@wezell all bad merged files reverted, good now.

fixed: 18233ac

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

wezell · 2026-04-06T21:57:49Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/pagescanner/PageScannerResource.java

+            final HttpServletRequest request,
+            final HttpServletResponse response,
+            final Map<String, Object> body,
+            final String checkType) {


checktype should be an enum I think

Fixed — added CheckType enum with a11y and geo values.

wezell · 2026-04-06T21:59:37Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/pagescanner/PageScannerResource.java

+    public Response a11yCheck(
+            @Context final HttpServletRequest request,
+            @Context final HttpServletResponse response,
+            final Map<String, Object> body) {


Probably want a typed Form object here? Back at you Mr. Freddy Typescript!

Fixed — replaced Map<String, Object> with typed PageScanCheckForm DTO.

Replace string checkType param with CheckType enum (a11y/geo) and replace Map<String, Object> request body with typed PageScanCheckForm. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

wezell

Let's go!

fmontes and others added 30 commits March 30, 2026 15:13

feat(uve): add i18n message keys for Page Scanner UI

d99ab6a

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(uve): fix p-chip colors in Page Scanner report using PrimeNG CSS …

7fd0ca2

…tokens Replace Tailwind bg-* classes on styleClass with [style] bindings overriding --p-chip-background and --p-chip-color design tokens. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor(uve): remove method calls from Page Scanner templates

4962c90

Replace all getXxx() template calls with computed() signals and pre-computed data properties to avoid re-evaluation on every change detection cycle. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(uve): remove non-existent text-color-secondary class from Page Sc…

eb94417

…anner templates Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(uve): improve GEO report accordion layout and category card design

6cfbfcd

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(uve): add i18n keys for GEO category descriptions and use them d…

e5db060

…ynamically in template Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor(uve): update layout and styling in GEO report component

39636d6

refactor(uve): decouple styles from Page Scanner data models, move al…

7182770

…l styling to templates

refactor(uve): improve GEO report layout and move chip styles inline …

0e46b08

…to template Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(uve): restyle a11y report accordion to match target design

2e3364b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'uve-experiment' into a11y-geo-report

049bc69

fix comflict issue

b5a0340

feat(uve): refine a11y accordion layout and update Cloudflare tunnel URL

a6810de

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'uve-experiment' into a11y-geo-report

b2a56d1

fix(ema): prevent a11y scanner accordion modal overflow

b5449c8

feat(uve): refine a11y accordion — inline message/fix link, pre/code …

c3c5be4

…blocks for element/selector Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor(uve): remove Cloudflare tunnel hack, pass full page URL to s…

be6421d

…canner service Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor(uve): replace individual signals with signalState and status…

aa3b9fc

… enum in page scanner report Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor(uve): replace SCSS classes with Tailwind in page-tools compo…

9d12536

…nent, remove tags from model Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(uve): update icons, add external tools i18n key, and refine page…

3f050ed

… scanner button design Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix color

f32d5bb

feat(uve): replace skeleton loaders with animated page scan loading c…

6bc9e2e

…omponent Add dot-page-scan-loading with a browser illustration and a scan line that animates up and down in a loop, shared between a11y and geo reports. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'main' into a11y-geo-report

2613e8b

fmontes and others added 14 commits April 4, 2026 17:37

fix(uve): remove unused ChipModule, restore Security Headers runnable…

8a0cbf8

…Link Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(page-scanner): hide env var names from 503 response body

2d1e968

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(page-scanner): wrap error responses in ResponseEntityView

190cb21

Use standard dotCMS ResponseEntityView<ErrorEntity> for all error responses instead of plain strings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(page-scanner): show not-configured error with admin contact message

8acf249

Detect PAGE_SCANNER_NOT_CONFIGURED error code from the 503 response and show a dedicated UI telling the user to contact their administrator. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(page-scanner): always call API before showing private URL error

806a376

Remove client-side private URL pre-check so the not-configured error takes priority. Private URL detection now relies solely on the server error response. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'uve-experiment' into a11y-geo-report

16dc2d1

clean up

10b0f44

fix bad merge

2bc26ee

fix(page-scanner): remove duplicate dot-page-tools-seo from shell tem…

8f64c7d

…plate Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

zJaaal requested changes Apr 6, 2026

View reviewed changes

nollymar reviewed Apr 6, 2026

View reviewed changes

fix(page-tools): replace hardcoded values with SCSS vars

14f08a4

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

nollymar reviewed Apr 6, 2026

View reviewed changes

dotCMS/src/main/java/com/dotcms/rest/api/v1/pagescanner/PageScannerResource.java Outdated Show resolved Hide resolved

fmontes and others added 2 commits April 6, 2026 15:06

fix bad merge

18233ac

wezell requested changes Apr 6, 2026

View reviewed changes

fix(page-scanner): read token TTL from config with 5min default

4cd1a1f

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(uve): constrain browser URL bar width to max-w-4xl

5cbbe31

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

wezell reviewed Apr 6, 2026

View reviewed changes

refactor(page-scanner): use CheckType enum and PageScanCheckForm DTO

f80cffa

Replace string checkType param with CheckType enum (a11y/geo) and replace Map<String, Object> request body with typed PageScanCheckForm. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

wezell approved these changes Apr 6, 2026

View reviewed changes

wezell merged commit 2c49161 into uve-experiment Apr 6, 2026
14 checks passed

wezell deleted the a11y-geo-report branch April 6, 2026 22:31

Conversation

fmontes commented Apr 4, 2026

What

Why

Key decisions

Scope

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wezell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmontes commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wezell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

fmontes commented Apr 6, 2026 •

edited

Loading