Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
fix(audit): read a page's readability as the editor's Quality does, with one Flesch band (#1411 follow-up) (#1442)
Cihan181cf75bebb3
diff --git a/server/src/lib/audit/audit.test.js b/server/src/lib/audit/audit.test.jsindex c886798f3..73dc4345b 100644--- a/server/src/lib/audit/audit.test.js+++ b/server/src/lib/audit/audit.test.js@@ -1,10 +1,11 @@import { describe, it, expect } from 'vitest';import * as cheerio from 'cheerio';import { scoreAudit } from './scorer.js';-import { fleschReadingEase, classifyLinks, jsonLd, countPhrases } from './signals/helpers.js';+import { classifyLinks, jsonLd, countPhrases } from './signals/helpers.js';import { jsonLdPresence, h1Quality } from './signals/structure.js';import { https, metaDescription } from './signals/trust.js';-import { length } from './signals/content.js';+import { length, readability } from './signals/content.js';+import { fleschReadingEase, readingBlocks } from './signals/readability.js';import { withRetry } from '../retry.js';/** Build a minimal audit context from an HTML string (no network). */@@ -56,13 +57,65 @@ describe('scoreAudit', () => {});});-describe('helpers', () => {- it('fleschReadingEase returns null for short text and a number for enough text', () => {- expect(fleschReadingEase('Too short.')).toBeNull();- const text = Array.from({ length: 40 }, () => 'the cat sat on the mat').join('. ') + '.';- expect(typeof fleschReadingEase(text)).toBe('number');+// Shared with web/src/lib/content/readability.test.ts: Flesch 82 in both.+const FIXTURE = `<h1>How to brew pour-over coffee at home</h1>+<p>Pour-over coffee is simple to make, and it tastes clean and bright. You need a dripper, a paper filter, a kettle and fresh beans. Most people wanted a cup that tasted like the café, so we created this guide.</p>+<h2>What you need</h2>+<ul>+<li>A dripper, e.g. a ceramic cone or a flat-bottom brewer.</li>+<li>Twenty grams of medium-fine coffee for one large mug.</li>+<li>Water just off the boil, around ninety-four degrees.</li>+</ul>+<h2>Step by step</h2>+<p>Rinse the filter with hot water first. This removes the papery taste and warms the dripper. Then add the coffee and shake it level.</p>+<p>Start with a short pour, just enough to wet the grounds. Wait thirty seconds while the coffee blooms. Fresh coffee releases gas, and the bloom lets it escape before the main pour.</p>+<p>Pour slowly in small circles, keeping the water level steady. The whole brew should take about three minutes. If it runs faster, grind finer; if it stalls, grind coarser.</p>+<blockquote><p>"Taste is the only rule that matters," says our head roaster. "Adjust one thing at a time."</p></blockquote>+<h2>Common mistakes</h2>+<p>Many beginners pour too fast, which makes a weak and sour cup. Others use water that is far too hot, which makes the coffee bitter. A beautiful, quiet morning ritual needs a little patience. Measure your coffee, watch the clock and keep notes on each cup.</p>`;++const frame = (main, links = 3) =>+ `<!doctype html><html><body><nav><ul>${'<li><a href="/x">Menu link</a></li>'.repeat(links)}</ul></nav><main><article>${main}</article></main><footer><ul>${'<li><a href="/y">Footer link</a></li>'.repeat(links)}</ul></footer></body></html>`;++describe('readability (as the editor reads it)', () => {+ it('scores the page the editor’s test reads, as the editor does', () => {+ expect(Math.round(fleschReadingEase(readingBlocks(FIXTURE)))).toBe(82);+ expect(readability.evaluate(ctxFromHtml(frame(FIXTURE)))).toEqual({+ status: 'fail',+ score: 0,+ evidence: { fleschReadingEase: 82 },+ });+ });++ it('reads no menus or footer: a page with little text of its own has no score', () => {+ const page = frame('<h1>Blue mug</h1><p>A blue mug for coffee, tea and cocoa.</p>', 40);+ expect(readability.evaluate(ctxFromHtml(page))).toEqual({+ status: 'na',+ score: null,+ evidence: { reason: 'not enough text' },+ });+ });++ it('reads a page builder’s div text as the editor’s import does', () => {+ const divs = FIXTURE.replace(/<(\/?)p>/g, '<$1div>');+ expect(readability.evaluate(ctxFromHtml(frame(divs))).evidence).toEqual({+ fleschReadingEase: 82,+ });+ });++ it('reads no page past 2 MB once its scripts and styles are gone', () => {+ const big = frame(`${FIXTURE}<script>${'x'.repeat(3_000_000)}</script>`);+ expect(readability.evaluate(ctxFromHtml(big)).evidence).toEqual({ fleschReadingEase: 82 });+ const huge = frame(`${FIXTURE}<div>${'word '.repeat(450_000)}</div>`);+ expect(readability.evaluate(ctxFromHtml(huge))).toEqual({+ status: 'na',+ score: null,+ evidence: { reason: 'page too large to read' },+ });});+});+describe('helpers', () => {it('classifyLinks splits internal vs external', () => {const ctx = ctxFromHtml(`<a href="/about">a</a><a href="https://example.com/x">b</a>diff --git a/server/src/lib/audit/recommendations.js b/server/src/lib/audit/recommendations.jsindex 02b7c92a5..749aebcc5 100644--- a/server/src/lib/audit/recommendations.js+++ b/server/src/lib/audit/recommendations.js@@ -107,7 +107,7 @@ When the fix is content the user can paste, put the ready-to-use text in "draft"- faq-schema → 3–5 Q&A pairs in "draft" AND a valid FAQPage JSON-LD block in "code"- definitions → the key terms defined inline- outbound-authority-links / citation-density → specific authoritative sources to cite-- readability → a simplified rewrite of one representative paragraph (shorter sentences, plainer words)+- readability → a rewrite of one representative paragraph toward Flesch 50–70: shorter sentences and plainer words when the page's score is under 50, fuller sentences with the detail readers expect when it is over 70- length → which specific sections to expand or trim (draft can be null)- product-description-opening → a new opening for the product description, at most 40 words, that starts with the product type and names at least two key attributes from the page (a measure, a material, a fit or a use)@@ -207,7 +207,13 @@ export async function generateRecommendations(ctx, { results, brand = null, audiconst issues = failing.map((r) => {const s = signalsByKey[r.key] ?? {};- const finding = r.evidence?.reason ? ` | finding: ${r.evidence.reason}` : '';+ // Readability's score: which way to rewrite depends on its side of 50–70.+ const flesch = r.evidence?.fleschReadingEase;+ const finding = r.evidence?.reason+ ? ` | finding: ${r.evidence.reason}`+ : typeof flesch === 'number'+ ? ` | finding: Flesch Reading Ease ${flesch}`+ : '';return `- ${r.key} [${r.status}, impact: ${s.impactTier ?? 'standard'}]: ${s.what ?? ''}${finding}`;}).join('\n');diff --git a/server/src/lib/audit/recommendations.test.js b/server/src/lib/audit/recommendations.test.jsindex d184c0ec4..0a8e05854 100644--- a/server/src/lib/audit/recommendations.test.js+++ b/server/src/lib/audit/recommendations.test.js@@ -137,6 +137,18 @@ describe('generateRecommendations', () => {expect(prompt).toContain('- Domains: ansvisor.com');});+ it('tells the model which side of 50–70 a page reads, to rewrite it that way', async () => {+ modelReturns([]);+ await generateRecommendations(ctx, {+ results: [{ key: 'readability', status: 'fail', evidence: { fleschReadingEase: 86 } }],+ brand,+ });+ const { system, prompt } = generateObject.mock.calls[0][0];+ expect(prompt).toContain('- readability [fail, impact: standard]');+ expect(prompt).toContain('| finding: Flesch Reading Ease 86');+ expect(system).toContain('fuller sentences with the detail readers expect when it is over 70');+ });+it('sends no brand data for another site, and the brand name there is unknown', async () => {modelReturns([{diff --git a/server/src/lib/audit/rubric.json b/server/src/lib/audit/rubric.jsonindex d3ecf38c8..15ea27477 100644--- a/server/src/lib/audit/rubric.json+++ b/server/src/lib/audit/rubric.json@@ -296,7 +296,7 @@"label": "Readability (Flesch)","what": "Flesch Reading Ease score (target 50–70 for general audiences).","why": "Engines extract from content humans can read. Sub-30 (academic) and 80+ (childlike) both underperform.",- "howToFix": "Shorten sentences. Cut adverbs. Aim for 16-word average sentence length.",+ "howToFix": "Aim for 50–70. Under 50: shorten sentences and cut adverbs, about 16 words a sentence. Over 70: write fuller sentences with the detail readers expect.","source": "Flesch (1948) + adapted by SGE","impactTier": "standard"},diff --git a/server/src/lib/audit/signals/content.js b/server/src/lib/audit/signals/content.jsindex cb0e76e79..091537673 100644--- a/server/src/lib/audit/signals/content.js+++ b/server/src/lib/audit/signals/content.js@@ -9,27 +9,41 @@* See structure.js for the evaluator shape.*/-import { fleschReadingEase, jsonLd, typesOf } from './helpers.js';+import { jsonLd, typesOf } from './helpers.js';+import { fleschBand, fleschReadingEase, readingBlocks } from './readability.js';import { OPENING, checkDescriptionOpening } from '../product-description.js';+import { extractPageContent } from '../../page-content.js';+/** Past this, after its scripts and styles, a page isn't read: its content takes too long to find. */+const MAX_READ_HTML = 2_000_000;+/** What holds no text: most of a page's bytes. */+const NO_TEXT = /<(script|style|svg|noscript|template)\b[\s\S]*?<\/\1\s*>/gi;++/**+ * Flesch Reading Ease of the page's main content, as the Content Editor+ * imports the page and its Quality reads it (signals/readability.js), so a+ * page scores the same in both. A page whose content can't be found, or has+ * too few words, gets none: its menus and footer aren't its text.+ */export const readability = {key: 'readability',evaluate(ctx) {- const flesch = fleschReadingEase(ctx.text);+ const html = (ctx.html ?? '').replace(NO_TEXT, ' ');+ if (html.length > MAX_READ_HTML) {+ return { status: 'na', score: null, evidence: { reason: 'page too large to read' } };+ }+ let content = '';+ try {+ content = extractPageContent(html, ctx.url).html;+ } catch {+ // No content found: no score below.+ }+ const flesch = fleschReadingEase(readingBlocks(content));if (flesch === null) {return { status: 'na', score: null, evidence: { reason: 'not enough text' } };}- const rounded = Math.round(flesch);- let status = 'fail';- let score = 0;- if (flesch >= 50 && flesch <= 70) {- status = 'pass';- score = 1;- } else if ((flesch >= 30 && flesch < 50) || (flesch > 70 && flesch <= 80)) {- status = 'warn';- score = 0.5;- }- return { status, score, evidence: { fleschReadingEase: rounded } };+ const { status, score } = fleschBand(flesch);+ return { status, score, evidence: { fleschReadingEase: Math.round(flesch) } };},};diff --git a/server/src/lib/audit/signals/helpers.js b/server/src/lib/audit/signals/helpers.jsindex e1af0ee5b..f0945d575 100644--- a/server/src/lib/audit/signals/helpers.js+++ b/server/src/lib/audit/signals/helpers.js@@ -1,7 +1,7 @@/**- * Shared helpers for signal evaluators — JSON-LD extraction, link analysis,- * and readability math. Kept dependency-free (cheerio + plain JS) so signals- * stay fast and deterministic.+ * Shared helpers for signal evaluators — JSON-LD extraction and link+ * analysis (readability's math is in readability.js). Kept dependency-free+ * (cheerio + plain JS) so signals stay fast and deterministic.*//**@@ -92,29 +92,6 @@ export function metaContent(ctx, key) {return typeof v === 'string' ? v.trim() : null;}-// --- Readability (Flesch Reading Ease) -----function countSyllables(word) {- const w = word.toLowerCase().replace(/[^a-z]/g, '');- if (!w) return 0;- if (w.length <= 3) return 1;- const stripped = w.replace(/(?:[^laeiouy]es|ed|[^laeiouy]e)$/, '').replace(/^y/, '');- const groups = stripped.match(/[aeiouy]{1,2}/g);- return groups ? groups.length : 1;-}--/**- * Flesch Reading Ease for an English-ish body of text. Returns null when there- * isn't enough text to score.- */-export function fleschReadingEase(text) {- const words = text.split(/\s+/).filter(Boolean);- if (words.length < 30) return null;- const sentences = (text.match(/[.!?]+(?:\s|$)/g) || []).length || 1;- const syllables = words.reduce((acc, w) => acc + countSyllables(w), 0);- return 206.835 - 1.015 * (words.length / sentences) - 84.6 * (syllables / words.length);-}-/** Count occurrences of a list of phrases (case-insensitive) in text. */export function countPhrases(text, phrases) {const lower = text.toLowerCase();diff --git a/server/src/lib/audit/signals/readability.js b/server/src/lib/audit/signals/readability.jsnew file mode 100644index 000000000..4f6736fd0--- /dev/null+++ b/server/src/lib/audit/signals/readability.js@@ -0,0 +1,178 @@+import * as cheerio from 'cheerio';++/**+ * Readability (Flesch Reading Ease) as the Content Editor's Quality reads an+ * English page, so a page scores the same in Site Audit and in the editor:+ * its prose blocks (headings aside, a list item on its own), its sentences+ * (an abbreviation's dot ends none) and its syllables, and one band.+ * Mirrors web/src/lib/content/readability.ts (readBlocks, sentencesOf,+ * syllablesOf for 'en', FLESCH_BAND): keep the two in step. Both tests read+ * the same page and expect the same score.+ */++/**+ * The rubric's target (rubric.json, readability: 50–70 for general+ * audiences): inside it passes; 30–50 and 70–80 warn; past them, fails.+ */+const FLESCH_BAND = { pass: [50, 70], warn: [30, 80] };++/** Fewer words than this give no score. */+const MIN_WORDS = 30;++/** Words as the editor counts them, a vowel sign or other mark kept inside its word. */+const WORD = /[\p{L}\p{N}][\p{L}\p{M}\p{N}'’-]*/gu;+const countWords = (text) => text.match(WORD)?.length ?? 0;++/**+ * Text joined as a reader sees it: a space between blocks and at a line+ * break, a list item's own words without the list nested in it.+ */+function ownText(el) {+ let out = '';+ for (const node of el.children ?? []) {+ if (node.type === 'text') out += node.data;+ else if (node.type === 'tag') {+ const tag = node.name.toLowerCase();+ if (tag === 'ul' || tag === 'ol') continue;+ if (tag === 'br') out += ' ';+ else out += ` ${ownText(node)} `;+ }+ }+ return out;+}++/** Elements whose words stay in the line around them. */+const INLINE = new Set(+ 'a abbr b bdi bdo cite code data dfn em i kbd mark q s samp small span strong sub sup time u var wbr'.split(+ ' ',+ ),+);++/** A block's own words, without the blocks inside it: a div's loose text. */+function inlineText(el) {+ let out = '';+ for (const node of el.children ?? []) {+ if (node.type === 'text') out += node.data;+ else if (node.type === 'tag' && INLINE.has(node.name.toLowerCase())) out += inlineText(node);+ else if (node.type === 'tag' && node.name.toLowerCase() === 'br') out += ' ';+ }+ return out;+}++/**+ * The page's headings and prose, in order: a quote once, each list item on+ * its own, a table's cells not at all. Text a page builder leaves loose in+ * a div, a figure's caption or a definition list is a paragraph, as the+ * editor's import makes it one.+ * @param {string} html+ * @returns {{ tag: string, text: string }[]}+ */+export function readingBlocks(html) {+ const $ = cheerio.load(html ?? '');+ $('script, style, noscript, template, svg').remove();+ const blocks = [];+ $('body')+ .find('h1, h2, h3, p, li, blockquote, div, section, article, figcaption, dd, dt')+ .each((_, el) => {+ const tag = el.name.toLowerCase();+ if (['div', 'section', 'article', 'figcaption', 'dd', 'dt'].includes(tag)) {+ // Inside a block read whole, or a table, it is read with it, or not at all.+ if ($(el).parents('p, li, blockquote, td, th').length) return;+ const loose = inlineText(el).replace(/\s+/g, ' ').trim();+ if (loose) blocks.push({ tag: 'p', text: loose });+ return;+ }+ // A paragraph in a list item, a quote or a cell is read with it, or not at all.+ if (tag === 'p' && $(el).closest('li, blockquote, td, th').length) return;+ if (tag === 'li' && $(el).closest('td, th').length) return;+ const text = ownText(el).replace(/\s+/g, ' ').trim();+ if (text) blocks.push({ tag, text });+ });+ return blocks;+}++/** English abbreviations whose dot ends no sentence, and those before a number only ("No. 5"). */+const ABBREVIATIONS = [+ ...['e.g', 'i.e', 'etc', 'vs', 'approx', 'cf', 'et al', 'Dr', 'Mr', 'Mrs', 'Ms', 'Prof'],+ ...['Jr', 'Sr', 'St', 'Inc', 'Ltd', 'Co', 'Corp', 'U.S', 'U.K'],+];+const BEFORE_NUMBER = ['No', 'p', 'pp', 'Fig', 'Vol', 'Ch'];++const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');++/** A list as one alternation, each with its upper-case opening and a space allowed after an inner dot. */+function alternation(list) {+ return list+ .flatMap((a) => {+ const upper = a[0].toLocaleUpperCase('en') + a.slice(1);+ return upper !== a && a.replace(/\P{L}/gu, '').length > 1 ? [a, upper] : [a];+ })+ .map((a) => escapeRe(a).replace(/\\\./g, '\\.\\s?').replace(/ /g, '\\s'))+ .join('|');+}++const PROTECTED_DOTS = new RegExp(+ `(?<![\\p{L}\\p{N}])(?:(?:${alternation(ABBREVIATIONS)})\\.(?=\\s)|(?:${alternation(BEFORE_NUMBER)})\\.(?=\\s*\\p{N}))`,+ 'gu',+);++/** What may close a sentence after its mark: a quote or a bracket. */+const CLOSE = `["'”’»)\\]」』]`;+/**+ * A sentence ends after . ! ? or … and a space, unless the next word starts+ * in lower case; a closing quote or bracket may come between.+ */+const SENTENCE_END = new RegExp(+ `(?<=[.!?…]${CLOSE}?)\\s+(?![\\s(\\["'“‘«¿¡]*\\p{Ll})|(?<=[。!?।؟]${CLOSE}?)(?!${CLOSE})\\s*`,+ 'u',+);++/** A block's sentences, an abbreviation's dot aside. */+export function sentencesOf(text) {+ return text+ .replace(PROTECTED_DOTS, (m) => m.replace(/\./g, '․'))+ .split(SENTENCE_END)+ .map((s) => s.replace(/․/g, '.').trim())+ .filter((s) => countWords(s) > 0);+}++/** An English word's syllables: vowel groups, a silent final e left out. Never under one. */+export function syllablesOf(word) {+ let w = word.toLocaleLowerCase('en').replace(/[^\p{L}]/gu, '');+ if (!w) return 0;+ if (w.length <= 3) return 1;+ // A silent final e ("make", "makes"); "-ted"/"-ded" keep their syllable ("wanted").+ w = w.replace(/(?:[^laeiouy]es|[^laeiouytd]ed|[^laeiouy]e)$/, (m) => m[0]);+ return Math.max(1, w.match(/[aeiouy]+/g)?.length ?? 0);+}++/**+ * Flesch Reading Ease of the prose blocks' sentences, or null under 30 words.+ * @param {{ tag: string, text: string }[]} blocks+ * @returns {number|null}+ */+export function fleschReadingEase(blocks) {+ const sentences = blocks+ .filter((b) => b.tag !== 'h1' && b.tag !== 'h2' && b.tag !== 'h3')+ .flatMap((b) => sentencesOf(b.text));+ const words = sentences.reduce((sum, s) => sum + countWords(s), 0);+ if (words < MIN_WORDS || sentences.length === 0) return null;+ const syllables = sentences+ .flatMap((s) => s.match(WORD) ?? [])+ .reduce((sum, w) => sum + syllablesOf(w), 0);+ return 206.835 - 1.015 * (words / sentences.length) - 84.6 * (syllables / words);+}++/**+ * A score's place in the band, as it shows (rounded): pass (1), warn (0.5)+ * or fail (0).+ * @param {number} flesch+ */+export function fleschBand(flesch) {+ const shown = Math.round(flesch);+ const [passFrom, passTo] = FLESCH_BAND.pass;+ const [warnFrom, warnTo] = FLESCH_BAND.warn;+ if (shown >= passFrom && shown <= passTo) return { status: 'pass', score: 1 };+ if (shown >= warnFrom && shown <= warnTo) return { status: 'warn', score: 0.5 };+ return { status: 'fail', score: 0 };+}diff --git a/server/src/lib/audit/signals/readability.test.js b/server/src/lib/audit/signals/readability.test.jsnew file mode 100644index 000000000..db7547a3f--- /dev/null+++ b/server/src/lib/audit/signals/readability.test.js@@ -0,0 +1,93 @@+import { describe, expect, it } from 'vitest';+import {+ fleschBand,+ fleschReadingEase,+ readingBlocks,+ sentencesOf,+ syllablesOf,+} from './readability.js';++/**+ * Site Audit's readability reads a page as the Content Editor's Quality+ * does (web/src/lib/content/readability.ts): the same blocks, sentences,+ * syllables and band. The page both read alike is in audit.test.js.+ */++describe('readability as the editor reads it', () => {+ it('has no score under 30 words, nor for headings alone', () => {+ expect(fleschReadingEase(readingBlocks('<p>Too short.</p>'))).toBeNull();+ expect(fleschReadingEase(readingBlocks(`<h2>${'Word '.repeat(40)}</h2>`))).toBeNull();+ });++ it('reads each prose block on its own: list items yes, headings and cells no', () => {+ expect(+ readingBlocks(+ '<h2>Steps</h2><ul><li>Rinse it.<ul><li>Nested.</li></ul></li></ul><blockquote><p>Taste it.</p></blockquote><table><tr><td><p>Cell.</p></td></tr></table><script>x()</script>',+ ),+ ).toEqual([+ { tag: 'h2', text: 'Steps' },+ { tag: 'li', text: 'Rinse it.' },+ { tag: 'li', text: 'Nested.' },+ { tag: 'blockquote', text: 'Taste it.' },+ ]);+ });++ it('splits sentences as the editor does', () => {+ expect(sentencesOf('Use a ratio, e.g. 1:16. Then brew.')).toEqual([+ 'Use a ratio, e.g. 1:16.',+ 'Then brew.',+ ]);+ expect(sentencesOf('Say no. Then see No. 5 below.')).toEqual([+ 'Say no.',+ 'Then see No. 5 below.',+ ]);+ expect(sentencesOf('He said "stop." Then he left. (It was late.) Nobody spoke.')).toEqual([+ 'He said "stop."',+ 'Then he left.',+ '(It was late.)',+ 'Nobody spoke.',+ ]);+ // A lower-case word goes on the sentence.+ expect(sentencesOf('Prices rose 3 pct. in May. Then they fell… and rose.')).toEqual([+ 'Prices rose 3 pct. in May.',+ 'Then they fell… and rose.',+ ]);+ });++ it('counts syllables as the editor does', () => {+ expect(syllablesOf('the')).toBe(1);+ expect(syllablesOf('readable')).toBe(3);+ expect(syllablesOf('quickly')).toBe(2);+ // "-ted" and "-ded" keep their syllable; a silent final e doesn't count.+ expect(syllablesOf('wanted')).toBe(2);+ expect(syllablesOf('makes')).toBe(1);+ });++ it('reads text left loose in a div, a caption or a definition list as a paragraph', () => {+ expect(+ readingBlocks(+ '<div>Loose <b>words</b> here.<div>Inner words.</div><p>A paragraph.</p></div><figure><figcaption>A caption.</figcaption></figure><dl><dt>Term</dt><dd>Its meaning.</dd></dl><ul><li><div>Item words.</div></li></ul>',+ ),+ ).toEqual([+ { tag: 'p', text: 'Loose words here.' },+ { tag: 'p', text: 'Inner words.' },+ { tag: 'p', text: 'A paragraph.' },+ { tag: 'p', text: 'A caption.' },+ { tag: 'p', text: 'Term' },+ { tag: 'p', text: 'Its meaning.' },+ { tag: 'li', text: 'Item words.' },+ ]);+ });++ it('passes 50–70, warns 30–50 and 70–80, and fails past them, as the score shows', () => {+ expect(fleschBand(50)).toEqual({ status: 'pass', score: 1 });+ expect(fleschBand(70)).toEqual({ status: 'pass', score: 1 });+ expect(fleschBand(45)).toEqual({ status: 'warn', score: 0.5 });+ expect(fleschBand(75)).toEqual({ status: 'warn', score: 0.5 });+ expect(fleschBand(81)).toEqual({ status: 'fail', score: 0 });+ expect(fleschBand(29)).toEqual({ status: 'fail', score: 0 });+ // Rounded, as it shows: 70.4 reads 70, 49.6 reads 50.+ expect(fleschBand(70.4)).toEqual({ status: 'pass', score: 1 });+ expect(fleschBand(49.6)).toEqual({ status: 'pass', score: 1 });+ });+});diff --git a/web/messages/en.json b/web/messages/en.jsonindex f8a529e7d..fac6df714 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -4550,6 +4550,8 @@"readingLevel": {"line": "Reading level {score, number} ({formula})","detail": "Aim for {target} or more: shorter words and sentences.",+ "detailBand": "Aim for {min}–{max}: shorter words and sentences.",+ "detailSimple": "Aim for {min}–{max}: the page reads simpler than most readers of it expect. Keep the detail they look for.","lineLength": "Long words and sentences","detailLength": "No reading-level formula for this language yet: read by sentence and word length."},diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsxindex 38ed4cb48..34a159050 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx@@ -33,12 +33,13 @@ const result: Readability = {{ id: 'longSentences', points: 6, max: 15, value: 41, count: 3, at: 'A very long sentence.' },{id: 'readingLevel',- points: 15,+ points: 10,max: 20,- value: 52,- count: 0,+ value: 77,+ count: 1,formula: 'flesch',- target: 60,+ target: 50,+ band: { min: 50, max: 70 },},{ id: 'answerFirst', points: 15, max: 15, value: 30, count: 0, at: null },{ id: 'shortParagraphs', points: 10, max: 10, value: 6, count: 0, at: null },@@ -129,14 +130,27 @@ describe('QualityTab', () => {const suggestions = container.querySelector('[aria-label="What would raise it"]')!;const rows = [...suggestions.querySelectorAll('li')].map((li) => li.textContent);expect(rows).toEqual([+ '+10 ReadabilityReading level 77 (Flesch Reading Ease)Aim for 50–70: the page reads simpler than most readers of it expect. Keep the detail they look for.','+9 Readability3 sentences over 35 wordsSplit each into two. Show goes to the first.Show','+5 ReadabilitySentences average 22.4 wordsAim for 15–20 words: shorter sentences read faster, and AI answers quote them whole.',- '+5 ReadabilityReading level 52 (Flesch Reading Ease)Aim for 60 or more: shorter words and sentences.',]);await act(async () => suggestions.querySelector<HTMLButtonElement>('li button')!.click());expect(onShow).toHaveBeenCalledWith('A very long sentence.');});+ it('asks for shorter words and sentences under English’s band', async () => {+ await render({+ ...result,+ checks: result.checks.map((c) =>+ c.id === 'readingLevel' ? { ...c, value: 42, count: -1 } : c,+ ),+ });+ const suggestions = container.querySelector('[aria-label="What would raise it"]')!;+ expect(suggestions.textContent).toContain(+ 'Reading level 42 (Flesch Reading Ease)Aim for 50–70: shorter words and sentences.',+ );+ });+it('asks to join short sentences when they run under the range', async () => {await render({...result,diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsxindex cd66ea2b6..3522ae4f8 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx@@ -461,6 +461,12 @@ function line(t: T, check: ReadabilityCheck): string {function detail(t: T, check: ReadabilityCheck): string {if (check.id === 'avgSentence' && check.count < 0) return t('checks.avgSentence.detailShort');if (check.id === 'readingLevel') {+ // English reads by its band (as Site Audit does): over it, the page reads too simple.+ if (check.band) {+ return check.count > 0+ ? t('checks.readingLevel.detailSimple', check.band)+ : t('checks.readingLevel.detailBand', check.band);+ }return check.formula? t('checks.readingLevel.detail', { target: check.target ?? 60 }): t('checks.readingLevel.detailLength');diff --git a/web/src/lib/content/readability.test.ts b/web/src/lib/content/readability.test.tsindex 2572cbfa5..dcc595e74 100644--- a/web/src/lib/content/readability.test.ts+++ b/web/src/lib/content/readability.test.ts@@ -20,6 +20,23 @@ const sentence = (n: number) =>const check = (html: string, id: string, language = 'en') =>readability(html, language).checks.find((c) => c.id === id);+// Shared with server/src/lib/audit/signals/readability.test.js: Flesch 82 in both.+const FIXTURE = `<h1>How to brew pour-over coffee at home</h1>+<p>Pour-over coffee is simple to make, and it tastes clean and bright. You need a dripper, a paper filter, a kettle and fresh beans. Most people wanted a cup that tasted like the café, so we created this guide.</p>+<h2>What you need</h2>+<ul>+<li>A dripper, e.g. a ceramic cone or a flat-bottom brewer.</li>+<li>Twenty grams of medium-fine coffee for one large mug.</li>+<li>Water just off the boil, around ninety-four degrees.</li>+</ul>+<h2>Step by step</h2>+<p>Rinse the filter with hot water first. This removes the papery taste and warms the dripper. Then add the coffee and shake it level.</p>+<p>Start with a short pour, just enough to wet the grounds. Wait thirty seconds while the coffee blooms. Fresh coffee releases gas, and the bloom lets it escape before the main pour.</p>+<p>Pour slowly in small circles, keeping the water level steady. The whole brew should take about three minutes. If it runs faster, grind finer; if it stalls, grind coarser.</p>+<blockquote><p>"Taste is the only rule that matters," says our head roaster. "Adjust one thing at a time."</p></blockquote>+<h2>Common mistakes</h2>+<p>Many beginners pour too fast, which makes a weak and sour cup. Others use water that is far too hot, which makes the coffee bitter. A beautiful, quiet morning ritual needs a little patience. Measure your coffee, watch the clock and keep notes on each cup.</p>`;+const EASY ='<h1>How do small teams forecast pipeline?</h1>' +p(@@ -35,7 +52,7 @@ const EASY =);describe('readability', () => {- it('scores a plain page high, over its seven checks', () => {+ it('reads a plain page over its seven checks', () => {const result = readability(EASY, 'en');expect(result.checks.map((c) => c.id)).toEqual(['avgSentence',@@ -46,12 +63,39 @@ describe('readability', () => {'headingSpacing','passiveJargon',]);+ // Flesch 101: simpler than the band Site Audit passes (50–70), so no reading-level points.expect(result.checks.find((c) => c.id === 'readingLevel')).toMatchObject({formula: 'flesch',+ value: 101,+ count: 1,+ points: 0,});expect(result.checks.find((c) => c.id === 'longSentences')).toMatchObject({ count: 0 });expect(result.checks.find((c) => c.id === 'answerFirst')!.points).toBe(15);- expect(result.score).toBeGreaterThanOrEqual(80);+ expect(result.score).toBe(67);+ });++ it('scores the page Site Audit’s test reads, as Site Audit does', () => {+ // Shared with server/src/lib/audit/signals/readability.test.js: Flesch 82 in both.+ expect(check(FIXTURE, 'readingLevel')).toMatchObject({+ formula: 'flesch',+ value: 82,+ count: 1,+ points: 0,+ band: { min: 50, max: 70 },+ });+ });++ it('reads English by Site Audit’s band: full 50–70, half 30–50 and 70–80, none past', () => {+ const level = (n: number, times: number) =>+ check(p(Array.from({ length: times }, () => sentence(n)).join(' ')), 'readingLevel')!;+ const full = READABILITY_WEIGHTS.readingLevel;+ // One-syllable words: the sentence's length sets the score.+ expect(level(55, 1)).toMatchObject({ value: 66, points: full, count: 0 });+ expect(level(45, 2)).toMatchObject({ value: 77, points: full / 2, count: 1 });+ expect(level(20, 3)).toMatchObject({ value: 102, points: 0, count: 1 });+ expect(level(75, 1)).toMatchObject({ value: 46, points: full / 2, count: -1 });+ expect(level(110, 1)).toMatchObject({ value: 11, points: 0, count: -1 });});it('counts each sentence over 35 words, and shows the first', () => {diff --git a/web/src/lib/content/readability.ts b/web/src/lib/content/readability.tsindex 4b02db9d2..b0666a02b 100644--- a/web/src/lib/content/readability.ts+++ b/web/src/lib/content/readability.ts@@ -55,6 +55,8 @@ export interface ReadabilityCheck {/** The reading-level formula used, for readingLevel, and the score that reads as easy. */formula?: ReadingFormula | null;target?: number;+ /** English's band instead of a target: the score that reads right for most readers. */+ band?: { min: number; max: number };/** The first block that falls short, to show it in the draft. */at?: string | null;}@@ -249,9 +251,29 @@ export function syllablesOf(word: string, language: string): number {return Math.max(1, groups);}+/**+ * English's reading level, as Site Audit's readability signal reads it+ * (server/src/lib/audit/signals/readability.js; rubric.json: 50–70 for+ * general audiences), so a page scores the same in both: full points inside+ * the pass band, half in the warn band, none past it. Keep the two in step.+ */+const FLESCH_BAND = { pass: [50, 70], warn: [30, 80] } as const;++/** Points for a Flesch score in its band, as it shows (rounded), and which side of it the score is on. */+function fleschPoints(score: number, max: number): { points: number; count: number } {+ const shown = Math.round(score);+ const [passFrom, passTo] = FLESCH_BAND.pass;+ const [warnFrom, warnTo] = FLESCH_BAND.warn;+ // Under the band (-1: harder than most readers want), in it (0), over it (1: simpler).+ const count = shown < passFrom ? -1 : shown > passTo ? 1 : 0;+ if (count === 0) return { points: max, count };+ return { points: shown >= warnFrom && shown <= warnTo ? max / 2 : 0, count };+}+/** The formula each language's reading level is read with, and the score that reads as easy. */const FORMULAS: Record<string, { formula: ReadingFormula; target: number }> = {- en: { formula: 'flesch', target: 60 },+ // Read by its band (FLESCH_BAND); the target is the band's start.+ en: { formula: 'flesch', target: FLESCH_BAND.pass[0] },// Ateşman's "medium" band starts at 50; Turkish words run longer.tr: { formula: 'atesman', target: 50 },de: { formula: 'amstad', target: 60 },@@ -400,11 +422,16 @@ export function readability(html: string, language: string | null | undefined):.flatMap(({ s }) => s.match(WORD) ?? []).reduce((sum, w) => sum + syllablesOf(w, lang), 0);const score = formulaScore(known.formula, allAsl, syllables / words);+ const max = READABILITY_WEIGHTS.readingLevel;check({id: 'readingLevel',- points: toward(score, known.target, 30, READABILITY_WEIGHTS.readingLevel),+ ...(known.formula === 'flesch'+ ? {+ ...fleschPoints(score, max),+ band: { min: FLESCH_BAND.pass[0], max: FLESCH_BAND.pass[1] },+ }+ : { points: toward(score, known.target, 30, max), count: 0 }),value: Math.round(score),- count: 0,formula: known.formula,target: known.target,});