Skip to content

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.

feat(content): read the draft's Readability and show it in Instructions › Quality (CE-036, CE-039) (#1411)

Cihancfc2c89ba00c
diff --git a/web/.env.example b/web/.env.example
index 251a9bbcf..6e88e399d 100644
--- a/web/.env.example
+++ b/web/.env.example
@@ -59,6 +59,12 @@ NEXT_PUBLIC_IS_CLOUD=false
# -----------------------------------------------------------------------------
NEXT_PUBLIC_ACTION_TASKS_AI=
+# -----------------------------------------------------------------------------
+# Content Editor Quality (Drive quality spec): which phase is live, 0 (unset)
+# for none. 1 shows Instructions › Quality and the header's Quality chip.
+# -----------------------------------------------------------------------------
+NEXT_PUBLIC_CONTENT_QUALITY_PHASE=
+
# -----------------------------------------------------------------------------
# AEO Server (backend API)
# -----------------------------------------------------------------------------
diff --git a/web/messages/en.json b/web/messages/en.json
index 7dadeae31..3c20c5d79 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -3851,9 +3851,11 @@
"impact": "Live page"
},
"segmentsLabel": "Brief or rules",
+ "segmentsLabelQuality": "Brief, rules or quality",
"segments": {
"brief": "Brief",
"rules": "Rules",
+ "quality": "Quality",
"open": "{count, number} open"
}
},
@@ -4084,6 +4086,67 @@
},
"rulesChip": "Rules {met}/{total}",
"rulesChipHint": "Rules this page meets now. Open the Rules tab.",
+ "qualityChip": "Quality {score}",
+ "qualityChipHint": "An Ansvisor estimate of this page's quality. Open Quality.",
+ "quality": {
+ "scores": "Quality scores",
+ "names": {
+ "readability": "Readability"
+ },
+ "bands": {
+ "strong": "Strong",
+ "improve": "Can improve",
+ "needsWork": "Needs work"
+ },
+ "estimate": "Ansvisor estimates based on Google's published quality signals. Not a Google score.",
+ "tooShort": "Write a few paragraphs: Readability is read from the page as you write.",
+ "notThisLanguage": "Readability isn't read for this language yet.",
+ "suggestionsLabel": "What would raise it",
+ "nothingToRaise": "Nothing to raise here: the page reads well.",
+ "gain": "+{gain, number} {score}",
+ "band": "{score, number}, {band}",
+ "show": "Show",
+ "formulas": {
+ "flesch": "Flesch Reading Ease",
+ "atesman": "Ateşman",
+ "amstad": "Amstad",
+ "kandelMoles": "Kandel–Moles",
+ "fernandezHuerta": "Fernández-Huerta"
+ },
+ "checks": {
+ "avgSentence": {
+ "line": "Sentences average {words, number} words",
+ "detail": "Aim for 15–20 words: shorter sentences read faster, and AI answers quote them whole.",
+ "detailShort": "Aim for 15–20 words: join some short ones, so each says one whole thing."
+ },
+ "longSentences": {
+ "line": "{count, plural, one {# sentence} other {# sentences}} over 35 words",
+ "detail": "Split each into two. Show goes to the first."
+ },
+ "readingLevel": {
+ "line": "Reading level {score, number} ({formula})",
+ "detail": "Aim for {target} or more: shorter words and sentences.",
+ "lineLength": "Long words and sentences",
+ "detailLength": "No reading-level formula for this language yet: read by sentence and word length."
+ },
+ "answerFirst": {
+ "line": "The first paragraph doesn't answer the H1",
+ "detail": "Open with a short paragraph, 60 words or fewer, that answers the H1."
+ },
+ "shortParagraphs": {
+ "line": "{count, plural, one {# paragraph} other {# paragraphs}} over 4 sentences",
+ "detail": "Break them up: short paragraphs are easier to read and to quote."
+ },
+ "headingSpacing": {
+ "line": "{count, plural, one {# section} other {# sections}} over {words, number} words without a heading",
+ "detail": "Add an H2 or H3 every 200–300 words."
+ },
+ "passiveJargon": {
+ "line": "{passive, plural, one {# passive sentence} other {# passive sentences}} · {jargon, plural, one {# jargon word} other {# jargon words}}",
+ "detail": "Say who does what, in plain words."
+ }
+ }
+ },
"rules": {
"set": "Rule set",
"setName": "{type} · Ansvisor default",
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx
index 3494ffd14..563ecced3 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx
@@ -70,11 +70,15 @@ import {
import { PAGE_READ_DELAY_MS, draftTitleFromDoc, safeLinkHref } from '@/lib/content/editor';
import { JsonLd } from '@/lib/content/json-ld-node';
import { detectPageType } from '@/lib/content/page-types';
+import { BAND_CLASSES, qualityAverage, qualityBand, qualityPhase } from '@/lib/content/quality';
+import { readability } from '@/lib/content/readability';
import { aiTracesFound, fanoutsToUse, lengthWarns, openRulesForAgent } from '@/lib/content/rules';
import { saveBlob } from '@/lib/download';
import { cn } from '@/lib/utils';
+import { useBrandStore } from '@/stores/use-brand-store';
import { AgentCard } from './_agent-card';
import { AgentDrafting, draftingKey } from './_agent-drafting';
+import { FlashBlock, findBlock, flashKey } from './_flash-block';
import { useAgentRun } from './_use-agent-run';
import { WorkingDots } from './_working-dots';
import { DropOverlay, useAttachments } from './_attach';
@@ -203,6 +207,8 @@ export function DraftEditor({
// The page as written now, for the side panel's Sources.
const [pageHtml, setPageHtml] = useState(draft.bodyHtml);
const pageReadTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+ // Quality's Show marks a block for a moment: a second Show starts the moment again.
+ const flashTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
useEffect(() => () => clearTimeout(pageReadTimer.current), []);
const [status, setStatus] = useState(draft.status);
const [marking, setMarking] = useState(false);
@@ -316,6 +322,7 @@ export function DraftEditor({
}),
OneH1,
AgentDrafting,
+ FlashBlock,
],
content: draft.bodyHtml,
// Rendered on the client only, so the server's HTML can't disagree with it.
@@ -388,6 +395,22 @@ export function DraftEditor({
pageType,
reads,
});
+ // How well the page reads as written (Quality spec, CE-036/039): read in the
+ // browser, no AI cost; off until Quality's first phase is live. Read in the
+ // language the page is written in: its Language rule when that is on (the
+ // agent writes in it, and it can differ per draft), else the brand's.
+ const brandLanguage = useBrandStore(
+ (s) => s.brands.find((b) => b.id === draft.brandId)?.language,
+ );
+ const languageRule = rules.rules.find(({ rule }) => rule.key === 'language')?.rule;
+ const language =
+ languageRule?.on && languageRule.current.trim() ? languageRule.current : brandLanguage;
+ const qualityOn = qualityPhase() >= 1;
+ const readable = useMemo(
+ () => (qualityOn ? readability(pageHtml, language) : null),
+ [qualityOn, pageHtml, language],
+ );
+ const qualityScore = qualityAverage([readable?.score ?? null]);
useEffect(() => {
attachRef.current = (files) => void attachments.attach(files);
onDecide.current = (id, decision) => void decide([id], decision);
@@ -712,6 +735,25 @@ export function DraftEditor({
setTimeout(() => card.classList.remove(...mark), 1200);
};
+ /**
+ * Quality's Show: the block of the page holding the passage (never a
+ * suggestion's card), scrolled to and marked for a moment.
+ */
+ const showInPage = (text: string) => {
+ if (!editor) return;
+ const at = findBlock(editor.state.doc, text);
+ if (!at) return;
+ (editor.view.nodeDOM(at.from) as HTMLElement | null)?.scrollIntoView({
+ block: 'center',
+ behavior: 'smooth',
+ });
+ clearTimeout(flashTimer.current);
+ editor.view.dispatch(editor.state.tr.setMeta(flashKey, at));
+ flashTimer.current = setTimeout(() => {
+ if (!editor.isDestroyed) editor.view.dispatch(editor.state.tr.setMeta(flashKey, null));
+ }, 1200);
+ };
+
/**
* A whole page rewritten (Rewrite the whole page): Accept puts it
* in place of the page the agent read (History keeps that first), Reject
@@ -1341,6 +1383,24 @@ export function DraftEditor({
<span aria-hidden className="h-1.5 w-1.5 rounded-full bg-current" />
{t('rulesChip', { met: rules.met, total: rules.total })}
</button>
+ {qualityScore !== null && (
+ <button
+ type="button"
+ onClick={() => openPanelTab('quality')}
+ title={t('qualityChipHint')}
+ className={cn(
+ 'inline-flex h-5 shrink-0 items-center gap-1.5 rounded-full border px-2 text-xs font-medium tabular-nums',
+ BAND_CLASSES[qualityBand(qualityScore)],
+ )}
+ >
+ <span aria-hidden className="h-1.5 w-1.5 rounded-full bg-current" />
+ {t('qualityChip', { score: qualityScore })}
+ <span className="sr-only">
+ {' · '}
+ {t(`quality.bands.${qualityBand(qualityScore)}`)}
+ </span>
+ </button>
+ )}
{citedCount > 0 && (
<span
title={t('cited.chipHint')}
@@ -1515,6 +1575,8 @@ export function DraftEditor({
}
onBriefRebuilding={onBriefRebuilding}
briefBlocked={agentBusy && !briefRebuilding ? t('suggestions.agentBusy') : null}
+ readability={readable}
+ onShowInPage={showInPage}
/>
) : (
<EditorPanelRail onOpen={openPanelTab} />
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_flash-block.test.ts b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_flash-block.test.ts
new file mode 100644
index 000000000..ae6b8f7d4
--- /dev/null
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_flash-block.test.ts
@@ -0,0 +1,50 @@
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { afterEach, describe, expect, it } from 'vitest';
+import { findBlock } from './_flash-block';
+
+let editor: Editor | null = null;
+afterEach(() => {
+ editor?.destroy();
+ editor = null;
+});
+
+const open = (content: string) => {
+ editor?.destroy();
+ editor = new Editor({ extensions: [StarterKit], content });
+ return editor.state.doc;
+};
+
+/** Quality's Show (CE-039): the block of the page a passage is in. */
+describe('findBlock', () => {
+ it('finds the smallest block holding the passage', () => {
+ const doc = open('<h1>Title</h1><blockquote><p>Quoted words.</p><p>More.</p></blockquote>');
+ const at = findBlock(doc, 'Quoted words.')!;
+ expect(doc.nodeAt(at.from)?.type.name).toBe('paragraph');
+ expect(doc.nodeAt(at.from)?.textContent).toBe('Quoted words.');
+ });
+
+ it('goes to the first copy of a passage the page has twice', () => {
+ // Title, then the passage, a paragraph between, and the passage again.
+ let doc = open(
+ '<h1>Title</h1><p>Check deals weekly.</p><p>Between.</p><p>Check deals weekly.</p>',
+ );
+ const first = doc.child(0).nodeSize;
+ expect(findBlock(doc, 'Check deals weekly.')).toEqual({
+ from: first,
+ to: first + doc.child(1).nodeSize,
+ });
+ // Inside a quote too: its first paragraph, not its second.
+ doc = open('<blockquote><p>Check deals weekly.</p><p>Check deals weekly.</p></blockquote>');
+ expect(findBlock(doc, 'Check deals weekly.')).toEqual({
+ from: 1,
+ to: 1 + doc.child(0).child(0).nodeSize,
+ });
+ });
+
+ it('finds nothing for a passage the page no longer has', () => {
+ const doc = open('<p>Check deals weekly.</p>');
+ expect(findBlock(doc, 'Gone now.')).toBeNull();
+ expect(findBlock(doc, ' ')).toBeNull();
+ });
+});
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_flash-block.ts b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_flash-block.ts
new file mode 100644
index 000000000..0b326f068
--- /dev/null
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_flash-block.ts
@@ -0,0 +1,70 @@
+import { Extension } from '@tiptap/core';
+import type { Node as PmNode } from '@tiptap/pm/model';
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+
+/**
+ * A block of the page marked for a moment (Quality's Show, CE-039): a
+ * decoration, never the page's, so no save, export or copy has it, and the
+ * editor doesn't redraw it away.
+ */
+
+export interface BlockRange {
+ from: number;
+ to: number;
+}
+
+export const flashKey = new PluginKey<DecorationSet>('flashBlock');
+
+const FLASH = 'rounded-sm ring-2 ring-amber-300 dark:ring-amber-700';
+
+/** Words without their spacing: the page's text and a check's read alike. */
+const squeeze = (text: string) => text.replace(/\s+/g, '');
+
+/**
+ * The smallest block of the page that holds `text` (its first 80 characters),
+ * at its first place: a passage the page has twice is shown where it comes first.
+ */
+export function findBlock(doc: PmNode, text: string): BlockRange | null {
+ const probe = squeeze(text).slice(0, 80);
+ if (!probe) return null;
+ let best: BlockRange | null = null;
+ doc.descendants((node, pos) => {
+ // Past the first block that holds it: only one inside that may hold it better.
+ if (best && pos >= best.to) return false;
+ if (!node.isBlock) return false;
+ if (!squeeze(node.textContent).includes(probe)) return false;
+ best = { from: pos, to: pos + node.nodeSize };
+ // A smaller one inside may hold it too.
+ return true;
+ });
+ return best;
+}
+
+export const FlashBlock = Extension.create({
+ name: 'flashBlock',
+
+ addProseMirrorPlugins() {
+ return [
+ new Plugin<DecorationSet>({
+ key: flashKey,
+ state: {
+ init: () => DecorationSet.empty,
+ apply: (tr, set) => {
+ const meta = tr.getMeta(flashKey) as BlockRange | null | undefined;
+ if (meta === null) return DecorationSet.empty;
+ if (meta) {
+ return DecorationSet.create(tr.doc, [
+ Decoration.node(meta.from, meta.to, { class: FLASH }),
+ ]);
+ }
+ return set.map(tr.mapping, tr.doc);
+ },
+ },
+ props: {
+ decorations: (state) => flashKey.getState(state) ?? null,
+ },
+ }),
+ ];
+ },
+});
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.tsx
new file mode 100644
index 000000000..bb355cf87
--- /dev/null
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx
@@ -0,0 +1,108 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { NextIntlClientProvider } from 'next-intl';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import messages from '../../../../../../../../messages/en.json';
+import type { Readability } from '@/lib/content/readability';
+import { QualityTab } from './_quality-tab';
+
+/** Instructions › Quality (Quality spec §3, CE-039): the score, its label, what would raise it. */
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+const result: Readability = {
+ score: 71,
+ words: 420,
+ checks: [
+ { id: 'avgSentence', points: 20, max: 25, value: 22.4, count: 0 },
+ { id: 'longSentences', points: 6, max: 15, value: 41, count: 3, at: 'A very long sentence.' },
+ {
+ id: 'readingLevel',
+ points: 15,
+ max: 20,
+ value: 52,
+ count: 0,
+ formula: 'flesch',
+ target: 60,
+ },
+ { id: 'answerFirst', points: 15, max: 15, value: 30, count: 0, at: null },
+ { id: 'shortParagraphs', points: 10, max: 10, value: 6, count: 0, at: null },
+ { id: 'headingSpacing', points: 10, max: 10, value: 3, count: 0, at: null },
+ { id: 'passiveJargon', points: 5, max: 5, value: 0, count: 0, at: null },
+ ],
+};
+
+let container: HTMLDivElement;
+let root: Root;
+const onShow = vi.fn();
+
+async function render(readability: Readability | null) {
+ await act(async () => {
+ root.render(
+ <NextIntlClientProvider locale="en" messages={messages}>
+ <QualityTab readability={readability} onShow={onShow} />
+ </NextIntlClientProvider>,
+ );
+ });
+}
+
+beforeEach(() => {
+ onShow.mockReset();
+ container = document.createElement('div');
+ root = createRoot(container);
+});
+afterEach(() => act(() => root.unmount()));
+
+describe('QualityTab', () => {
+ it('shows the score with its band, labelled an Ansvisor estimate', async () => {
+ await render(result);
+ const scores = container.querySelector('[aria-label="Quality scores"]')!;
+ expect(scores.textContent).toContain('Readability71Can improve');
+ expect(scores.textContent).toContain(
+ "Ansvisor estimates based on Google's published quality signals. Not a Google score.",
+ );
+ });
+
+ it('lists what would raise it, the biggest gain first, each with what to do', async () => {
+ await render(result);
+ const rows = [...container.querySelectorAll('li')].map((li) => li.textContent);
+ expect(rows).toEqual([
+ '+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 () => container.querySelector<HTMLButtonElement>('li button')!.click());
+ expect(onShow).toHaveBeenCalledWith('A very long sentence.');
+ });
+
+ it('asks to join short sentences when they run under the range', async () => {
+ await render({
+ ...result,
+ checks: result.checks.map((c) =>
+ c.id === 'avgSentence' ? { ...c, value: 8, count: -1 } : c,
+ ),
+ });
+ expect(container.textContent).toContain('Sentences average 8 words');
+ expect(container.textContent).toContain('join some short ones');
+ });
+
+ it('says when the page is too short to read, or reads well', async () => {
+ await render({ score: null, unscored: 'tooShort', checks: [], words: 12 });
+ expect(container.textContent).toContain('Write a few paragraphs');
+ expect(container.querySelector('li')).toBeNull();
+ await render({
+ ...result,
+ score: 100,
+ checks: result.checks.map((c) => ({ ...c, points: c.max })),
+ });
+ expect(container.textContent).toContain('Nothing to raise here: the page reads well.');
+ });
+
+ it('says when the page’s language isn’t read yet, not that it is too short', async () => {
+ await render({ score: null, unscored: 'language', checks: [], words: 240 });
+ expect(container.textContent).toContain("Readability isn't read for this language yet.");
+ expect(container.textContent).not.toContain('Write a few paragraphs');
+ expect(container.querySelector('li')).toBeNull();
+ });
+});
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.tsx
new file mode 100644
index 000000000..1ff0cc5b0
--- /dev/null
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx
@@ -0,0 +1,139 @@
+'use client';
+
+import { useTranslations } from 'next-intl';
+import { Button } from '@/components/ui/button';
+import { BAND_CLASSES, qualityBand } from '@/lib/content/quality';
+import {
+ readabilityGain,
+ SECTION_WORDS,
+ type Readability,
+ type ReadabilityCheck,
+} from '@/lib/content/readability';
+import { cn } from '@/lib/utils';
+
+/**
+ * Instructions › Quality (Quality spec §3, CE-039): the scores read from the
+ * draft, each labelled an Ansvisor estimate, then what would raise them, the
+ * biggest gain first. Phase 1 reads Readability; E-E-A-T and Trust join as
+ * their checks go live.
+ */
+export function QualityTab({
+ readability,
+ onShow,
+}: {
+ /** The draft's Readability as written, or null before it is read. */
+ readability: Readability | null;
+ /** Scrolls the draft to a passage and marks it. */
+ onShow: (text: string) => void;
+}) {
+ const t = useTranslations('contentEditor.editor.quality');
+ const score = readability?.score ?? null;
+ const suggestions = (readability?.checks ?? [])
+ .map((check) => ({ check, gain: readabilityGain(readability!, check.id) }))
+ .filter(({ gain }) => gain > 0)
+ .sort((a, b) => b.gain - a.gain);
+
+ return (
+ <div className="space-y-4 text-sm">
+ <section aria-label={t('scores')} className="space-y-2">
+ {score === null ? (
+ <p className="rounded-xl border border-dashed px-3 py-2.5 text-xs text-muted-foreground">
+ {t(readability?.unscored === 'language' ? 'notThisLanguage' : 'tooShort')}
+ </p>
+ ) : (
+ <div className="flex flex-wrap gap-2">
+ <div className="min-w-[8.5rem] rounded-xl border bg-card px-3 py-2">
+ <p className="text-xs text-muted-foreground">{t('names.readability')}</p>
+ <p className="mt-0.5 flex items-center gap-2">
+ <span className="text-xl font-semibold tabular-nums">{score}</span>
+ <span
+ className={cn(
+ 'rounded-full border px-2 text-[11px] font-medium',
+ BAND_CLASSES[qualityBand(score)],
+ )}
+ >
+ {t(`bands.${qualityBand(score)}`)}
+ </span>
+ </p>
+ </div>
+ </div>
+ )}
+ <p className="text-xs text-muted-foreground">{t('estimate')}</p>
+ </section>
+
+ {score !== null && (
+ <section aria-label={t('suggestionsLabel')} className="space-y-2">
+ <h4 className="text-xs font-medium text-muted-foreground">{t('suggestionsLabel')}</h4>
+ {suggestions.length === 0 ? (
+ <p className="text-xs text-muted-foreground">{t('nothingToRaise')}</p>
+ ) : (
+ <ul className="space-y-2">
+ {suggestions.map(({ check, gain }) => (
+ <li
+ key={check.id}
+ className="flex items-start gap-2.5 rounded-xl border px-3 py-2.5"
+ >
+ <span className="mt-0.5 shrink-0 rounded-md bg-emerald-50 px-1.5 text-[11px] font-medium text-emerald-700 tabular-nums dark:bg-emerald-950 dark:text-emerald-300">
+ {t('gain', { gain, score: t('names.readability') })}
+ </span>
+ <div className="min-w-0 flex-1">
+ <p className="font-medium [overflow-wrap:anywhere]">{line(t, check)}</p>
+ <p className="text-xs text-muted-foreground">{detail(t, check)}</p>
+ </div>
+ {check.at && (
+ <Button
+ variant="outline"
+ size="sm"
+ className="h-7 shrink-0"
+ onClick={() => onShow(check.at!)}
+ >
+ {t('show')}
+ </Button>
+ )}
+ </li>
+ ))}
+ </ul>
+ )}
+ </section>
+ )}
+ </div>
+ );
+}
+
+type T = ReturnType<typeof useTranslations<'contentEditor.editor.quality'>>;
+
+/** A check's one line: what the draft does now. */
+function line(t: T, check: ReadabilityCheck): string {
+ switch (check.id) {
+ case 'avgSentence':
+ return t('checks.avgSentence.line', { words: check.value });
+ case 'longSentences':
+ return t('checks.longSentences.line', { count: check.count });
+ case 'readingLevel':
+ return check.formula
+ ? t('checks.readingLevel.line', {
+ score: check.value,
+ formula: t(`formulas.${check.formula}`),
+ })
+ : t('checks.readingLevel.lineLength');
+ case 'answerFirst':
+ return t('checks.answerFirst.line');
+ case 'shortParagraphs':
+ return t('checks.shortParagraphs.line', { count: check.count });
+ case 'headingSpacing':
+ return t('checks.headingSpacing.line', { count: check.count, words: SECTION_WORDS });
+ case 'passiveJargon':
+ return t('checks.passiveJargon.line', { passive: check.count, jargon: check.value });
+ }
+}
+
+/** Its detail line: what to do. */
+function detail(t: T, check: ReadabilityCheck): string {
+ if (check.id === 'avgSentence' && check.count < 0) return t('checks.avgSentence.detailShort');
+ if (check.id === 'readingLevel') {
+ return check.formula
+ ? t('checks.readingLevel.detail', { target: check.target ?? 60 })
+ : t('checks.readingLevel.detailLength');
+ }
+ return t(`checks.${check.id}.detail`);
+}
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx
index 4914e2359..435712308 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx
@@ -6,10 +6,13 @@ import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
import { isPageType, type ContentDraft } from '@/lib/content/drafts';
import { buildSourceGroups, includedCounts, type DraftSourceKind } from '@/lib/content/sources';
import { formatNumber } from '@/lib/format';
+import { BAND_CLASSES, qualityBand, qualityPhase } from '@/lib/content/quality';
+import type { Readability } from '@/lib/content/readability';
import { cn } from '@/lib/utils';
import { BriefTab, type AgentRewrite } from './_brief-tab';
import { DataNote, UsesYourData } from './_data-note';
import { ImpactTab } from './_impact-tab';
+import { QualityTab } from './_quality-tab';
import { RulesTab, type AgentFix, type PageRewrite } from './_rules-tab';
import { SourcesTab } from './_sources-tab';
import { useBriefRebuild, type PageNow } from './_use-brief-rebuild';
@@ -52,8 +55,11 @@ export function useSidePanelOpen(): [boolean, () => void] {
// the agent follows, in one tab, which the panel opens on (on Rules).
const PANEL_TABS = ['instructions', 'sources', 'impact'] as const;
export type PanelTab = (typeof PANEL_TABS)[number];
-/** Instructions' two segments: what to write (Brief), then how to write it (Rules). */
-const SEGMENTS = ['brief', 'rules'] as const;
+/**
+ * Instructions' segments: what to write (Brief), how to write it (Rules), and
+ * how well it reads (Quality, Quality spec §3, once its first phase is live).
+ */
+const SEGMENTS = ['brief', 'rules', 'quality'] as const;
export type InstructionSegment = (typeof SEGMENTS)[number];
/** What the panel can be asked to open: a tab, or one of Instructions' segments. */
export type PanelTarget = PanelTab | InstructionSegment;
@@ -113,6 +119,8 @@ export function EditorSidePanel({
onSourceShown,
onBriefRebuilding,
briefBlocked = null,
+ readability = null,
+ onShowInPage,
}: {
draft: ContentDraft;
/** The draft's title, page and type as written now: Sources and Brief read them. */
@@ -146,8 +154,13 @@ export function EditorSidePanel({
onBriefRebuilding?: (rebuilding: boolean) => void;
/** Why the brief's Run Agent waits (another agent run from this page), or null. */
briefBlocked?: string | null;
+ /** The draft's Readability as written, for Quality (CE-036/039). */
+ readability?: Readability | null;
+ /** Scrolls the draft to a passage and marks it: Quality's Show. */
+ onShowInPage?: (text: string) => void;
}) {
const t = useTranslations('contentEditor.editor.panel');
+ const tEditor = useTranslations('contentEditor.editor');
const [tab, setTab] = useState<PanelTab>('instructions');
const [segment, setSegment] = useState<InstructionSegment>('rules');
const [opened, setOpened] = useState<Set<PanelTarget>>(() => new Set(['instructions', 'rules']));
@@ -167,6 +180,9 @@ export function EditorSidePanel({
);
};
const rulesOpen = Math.max(0, rules.total - rules.met);
+ // Quality shows once its first phase is live (NEXT_PUBLIC_CONTENT_QUALITY_PHASE).
+ const segments = SEGMENTS.filter((value) => value !== 'quality' || qualityPhase() >= 1);
+ const qualityScore = readability?.score ?? null;
// The sources the agent writes from, as the Sources tab keeps them (v1.1
// CE-032/034): counted under each Run Agent and on the tab, so turning one
@@ -270,18 +286,20 @@ export function EditorSidePanel({
<DataNote />
<div
role="radiogroup"
- aria-label={t('segmentsLabel')}
+ aria-label={t(segments.length > 2 ? 'segmentsLabelQuality' : 'segmentsLabel')}
className="flex rounded-[10px] border bg-muted p-[3px]"
- // Arrow keys move between the two, as in any radio group.
+ // Arrow keys move between them, as in any radio group.
onKeyDown={(e) => {
if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(e.key)) return;
e.preventDefault();
- const next = SEGMENTS[(SEGMENTS.indexOf(segment) + 1) % SEGMENTS.length];
+ const step = e.key === 'ArrowLeft' || e.key === 'ArrowUp' ? -1 : 1;
+ const next =
+ segments[(segments.indexOf(segment) + step + segments.length) % segments.length];
open(next);
e.currentTarget.querySelector<HTMLElement>(`[data-segment="${next}"]`)?.focus();
}}
>
- {SEGMENTS.map((value) => (
+ {segments.map((value) => (
<button
key={value}
type="button"
@@ -301,6 +319,20 @@ export function EditorSidePanel({
{t('segments.open', { count: rulesOpen })}
</span>
)}
+ {value === 'quality' && qualityScore !== null && (
+ <span
+ className={cn(
+ 'rounded-md border px-1.5 text-[10.5px] font-medium tabular-nums',
+ BAND_CLASSES[qualityBand(qualityScore)],
+ )}
+ >
+ {qualityScore}
+ <span className="sr-only">
+ {' · '}
+ {tEditor(`quality.bands.${qualityBand(qualityScore)}`)}
+ </span>
+ </span>
+ )}
</button>
))}
</div>
@@ -323,6 +355,11 @@ export function EditorSidePanel({
/>
</div>
)}
+ {opened.has('quality') && (
+ <div hidden={segment !== 'quality'}>
+ <QualityTab readability={readability} onShow={(text) => onShowInPage?.(text)} />
+ </div>
+ )}
{opened.has('rules') && (
<div hidden={segment !== 'rules'}>
<RulesTab
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx
index ad40eeab3..9fe096e36 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx
@@ -2172,6 +2172,124 @@ describe('the side panel', () => {
}
});
+ describe('Quality (CE-036/039)', () => {
+ const readable = draft({
+ bodyHtml:
+ '<h1>How do small teams forecast pipeline?</h1>' +
+ '<p>Small teams forecast pipeline by looking at the deals they can close this month. They count each deal once and check it every week.</p>' +
+ '<h2>Start with the deals you trust</h2>' +
+ '<p>Pick the deals with a clear next step. Leave out the ones that went quiet. Write down the date you expect each one to close.</p>' +
+ '<h2>Check the numbers every week</h2>' +
+ '<p>Look at the list on the same day each week. Move a deal out when it slips. Add new deals only when the buyer has agreed to a date.</p>',
+ });
+ afterEach(() => {
+ delete process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE;
+ });
+
+ it('shows nothing of Quality until its first phase is live', async () => {
+ getContentDraft.mockResolvedValue(readable);
+ window.innerWidth = 1440;
+ await renderPage();
+ expect(container.querySelector('header')!.textContent).not.toContain('Quality');
+ expect(
+ [...panel()!.querySelectorAll('[role="radio"]')].map((el) => el.textContent),
+ ).not.toContainEqual(expect.stringContaining('Quality'));
+ });
+
+ it('scores the page as written, in the header and Instructions › Quality', async () => {
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '1';
+ getContentDraft.mockResolvedValue(readable);
+ window.innerWidth = 1440;
+ await renderPage();
+ const chip = [...container.querySelectorAll<HTMLButtonElement>('header button')].find((b) =>
+ b.textContent?.startsWith('Quality'),
+ )!;
+ // Its band is read out too, not only shown in colour.
+ expect(chip.textContent).toMatch(/^Quality \d+ · (Strong|Can improve|Needs work)$/);
+ await act(async () => chip.click());
+ expect(selectedSegment()).toMatch(/^Quality\d+ · (Strong|Can improve|Needs work)$/);
+ expect(panel()!.textContent).toContain('Readability');
+ expect(panel()!.textContent).toContain('Not a Google score.');
+ });
+
+ /** The draft above, its Language rule changed for this draft. */
+ const inLanguage = (language: { on?: boolean; value?: string }) => ({
+ ...readable,
+ rules: { set: null, source: 'default' as const, overrides: { language }, textRules: [] },
+ });
+ const qualityChip = () =>
+ [...container.querySelectorAll<HTMLButtonElement>('header button')].find((b) =>
+ b.textContent?.startsWith('Quality'),
+ );
+
+ it('reads the page in its Language rule’s language, not the brand’s', async () => {
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '1';
+ // The brand writes in Japanese; this draft is in English, and is scored.
+ brandState.brands = [{ id: 'b1', language: 'ja' } as never, { id: 'b2' }];
+ try {
+ getContentDraft.mockResolvedValue(inLanguage({ value: 'English (US)' }));
+ window.innerWidth = 1440;
+ await renderPage();
+ expect(qualityChip()?.textContent).toMatch(/^Quality \d+/);
+ } finally {
+ brandState.brands = [{ id: 'b1' }, { id: 'b2' }];
+ }
+ });
+
+ it('reads the brand’s language with the rule off, and says when it can’t read it yet', async () => {
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '1';
+ brandState.brands = [{ id: 'b1', language: 'ja' } as never, { id: 'b2' }];
+ try {
+ getContentDraft.mockResolvedValue(inLanguage({ on: false, value: 'English (US)' }));
+ window.innerWidth = 1440;
+ await renderPage();
+ // Japanese has no spaces between words: no score, and no chip.
+ expect(qualityChip()).toBeUndefined();
+ const segment = [...panel()!.querySelectorAll<HTMLElement>('[role="radio"]')].find((el) =>
+ el.textContent?.startsWith('Quality'),
+ )!;
+ await act(async () => segment.click());
+ expect(panel()!.textContent).toContain("Readability isn't read for this language yet.");
+ } finally {
+ brandState.brands = [{ id: 'b1' }, { id: 'b2' }];
+ }
+ });
+
+ it('marks the passage Show goes to for a moment, a second Show starting it again', async () => {
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '1';
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ const original = Element.prototype.scrollIntoView;
+ Element.prototype.scrollIntoView = vi.fn();
+ try {
+ const long = `Teams ${Array.from({ length: 39 }, () => 'plan').join(' ')}.`;
+ getContentDraft.mockResolvedValue({
+ ...readable,
+ bodyHtml: `${readable.bodyHtml}<p>${long}</p>`,
+ });
+ window.innerWidth = 1440;
+ await renderPage();
+ await act(async () => qualityChip()!.click());
+ const show = [...panel()!.querySelectorAll<HTMLButtonElement>('li button')].find(
+ (b) => b.textContent === 'Show',
+ )!;
+ const marked = () => container.querySelector('.ProseMirror .ring-amber-300');
+
+ await act(async () => show.click());
+ expect(marked()!.textContent).toBe(long);
+ await act(async () => vi.advanceTimersByTime(1000));
+ await act(async () => show.click());
+ // The first Show's timer doesn't take the second's mark away early.
+ await act(async () => vi.advanceTimersByTime(500));
+ expect(marked()).not.toBeNull();
+ await act(async () => vi.advanceTimersByTime(700));
+ expect(marked()).toBeNull();
+ } finally {
+ Element.prototype.scrollIntoView = original;
+ vi.useRealTimers();
+ }
+ });
+ });
+
describe('Run Agent: fix open rules', () => {
const traced = draft({
pageType: 'blog_post',
diff --git a/web/src/lib/content/quality.test.ts b/web/src/lib/content/quality.test.ts
new file mode 100644
index 000000000..50b669817
--- /dev/null
+++ b/web/src/lib/content/quality.test.ts
@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { qualityAverage, qualityBand, qualityPhase } from './quality';
+
+/** The Quality scores' bands, the header chip's average, and the phase flag (Quality spec §2). */
+describe('quality', () => {
+ afterEach(() => {
+ delete process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE;
+ });
+
+ it('bands a score: 80+ Strong, 60–79 Can improve, under 60 Needs work', () => {
+ expect(qualityBand(80)).toBe('strong');
+ expect(qualityBand(79)).toBe('improve');
+ expect(qualityBand(60)).toBe('improve');
+ expect(qualityBand(59)).toBe('needsWork');
+ });
+
+ it('averages only the scores that could be read', () => {
+ expect(qualityAverage([78, null, 60])).toBe(69);
+ expect(qualityAverage([null])).toBeNull();
+ });
+
+ it('reads the live phase from the flag, none when unset or odd', () => {
+ expect(qualityPhase()).toBe(0);
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '1';
+ expect(qualityPhase()).toBe(1);
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '7';
+ expect(qualityPhase()).toBe(3);
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = 'yes';
+ expect(qualityPhase()).toBe(0);
+ });
+});
diff --git a/web/src/lib/content/quality.ts b/web/src/lib/content/quality.ts
new file mode 100644
index 000000000..2fdd0a89e
--- /dev/null
+++ b/web/src/lib/content/quality.ts
@@ -0,0 +1,34 @@
+/**
+ * The Content Editor's Quality scores (Quality spec §2): E-E-A-T, Trust and
+ * Readability, 0–100 each, shown in Instructions › Quality and as one
+ * "Quality {avg}" chip in the header. Ansvisor estimates, not Google scores.
+ */
+
+/** Which of the spec's three phases are live (NEXT_PUBLIC_CONTENT_QUALITY_PHASE): 0 is none. */
+export function qualityPhase(): number {
+ const phase = Number(process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE ?? 0);
+ return Number.isInteger(phase) && phase > 0 ? Math.min(phase, 3) : 0;
+}
+
+export type QualityBand = 'strong' | 'improve' | 'needsWork';
+
+/** 80+ Strong, 60–79 Can improve, under 60 Needs work (spec §2). */
+export function qualityBand(score: number): QualityBand {
+ return score >= 80 ? 'strong' : score >= 60 ? 'improve' : 'needsWork';
+}
+
+/** The band's colours: green, amber, red, each with its dark mode. */
+export const BAND_CLASSES: Record<QualityBand, string> = {
+ strong:
+ 'border-emerald-200 bg-emerald-50 text-emerald-700 dark:border-emerald-900 dark:bg-emerald-950 dark:text-emerald-300',
+ improve:
+ 'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-300',
+ needsWork:
+ 'border-red-200 bg-red-50 text-red-700 dark:border-red-900 dark:bg-red-950 dark:text-red-300',
+};
+
+/** The header chip's figure: the scores that could be read, averaged; null with none. */
+export function qualityAverage(scores: (number | null)[]): number | null {
+ const read = scores.filter((s): s is number => s !== null);
+ return read.length ? Math.round(read.reduce((a, b) => a + b, 0) / read.length) : null;
+}
diff --git a/web/src/lib/content/readability.test.ts b/web/src/lib/content/readability.test.ts
new file mode 100644
index 000000000..2572cbfa5
--- /dev/null
+++ b/web/src/lib/content/readability.test.ts
@@ -0,0 +1,369 @@
+import { describe, expect, it } from 'vitest';
+import { LANGUAGES } from '@/config/prompt-options';
+import { languageRuleValue } from './rules';
+import {
+ MIN_WORDS,
+ READABILITY_WEIGHTS,
+ languageCode,
+ readability,
+ readabilityGain,
+ sentencesOf,
+ syllablesOf,
+} from './readability';
+
+/** Readability (Quality spec §2.3, CE-036): seven checks read from the draft as written. */
+
+const p = (text: string) => `<p>${text}</p>`;
+/** A plain sentence of `n` words. */
+const sentence = (n: number) =>
+ `${Array.from({ length: n }, (_, i) => (i === 0 ? 'Teams' : 'plan')).join(' ')}.`;
+const check = (html: string, id: string, language = 'en') =>
+ readability(html, language).checks.find((c) => c.id === id);
+
+const EASY =
+ '<h1>How do small teams forecast pipeline?</h1>' +
+ p(
+ 'Small teams forecast pipeline by looking at deals they can close this month. They count each deal once and check it every week.',
+ ) +
+ '<h2>Start with the deals you trust</h2>' +
+ p(
+ 'Pick the deals with a clear next step. Leave out the ones that went quiet. Write down the date you expect each one to close.',
+ ) +
+ '<h2>Check the numbers every week</h2>' +
+ p(
+ 'Look at the list on the same day each week. Move a deal out when it slips. Add new deals only when the buyer has agreed to a date.',
+ );
+
+describe('readability', () => {
+ it('scores a plain page high, over its seven checks', () => {
+ const result = readability(EASY, 'en');
+ expect(result.checks.map((c) => c.id)).toEqual([
+ 'avgSentence',
+ 'longSentences',
+ 'readingLevel',
+ 'answerFirst',
+ 'shortParagraphs',
+ 'headingSpacing',
+ 'passiveJargon',
+ ]);
+ expect(result.checks.find((c) => c.id === 'readingLevel')).toMatchObject({
+ formula: 'flesch',
+ });
+ 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);
+ });
+
+ it('counts each sentence over 35 words, and shows the first', () => {
+ const html = `<h1>Pipeline</h1>${p(`${sentence(40)} ${sentence(38)} ${sentence(12)}`)}`;
+ const long = check(html, 'longSentences')!;
+ expect(long.count).toBe(2);
+ expect(long.points).toBe(READABILITY_WEIGHTS.longSentences - 6);
+ expect(long.at).toBe(sentence(40));
+ });
+
+ it('gives no score to a page too short to read', () => {
+ const html = p('Pipeline forecasting for small teams, in short.');
+ expect(readability(html, 'en')).toMatchObject({
+ score: null,
+ unscored: 'tooShort',
+ checks: [],
+ });
+ expect(MIN_WORDS).toBe(50);
+ });
+
+ it('gives no score in a language written without spaces between words', () => {
+ // Each Japanese clause reads as one word: six paragraphs once scored 66.
+ const ja =
+ '<h1>小さなチームの売上予測</h1>' +
+ Array.from({ length: 6 }, () =>
+ p(
+ '小さなチームは、今月、成約できる商談を見て、売上を予測します。毎週、同じ曜日に、リストを確認します。止まった商談は、すぐに、外します。',
+ ),
+ ).join('');
+ // Read as a spaced language, it would get a made-up score.
+ expect(readability(ja, 'en').score).not.toBeNull();
+ for (const language of ['ja', 'Japanese', 'zh-CN', 'Chinese', 'Thai']) {
+ expect(readability(ja, language)).toMatchObject({
+ score: null,
+ unscored: 'language',
+ checks: [],
+ });
+ }
+ });
+
+ it('scores Hindi by its own sentences and words', () => {
+ // Ten words, each with its vowel signs, ending in a danda.
+ const line = 'छोटी टीमें हर हफ्ते अपनी बिक्री की सूची देखती हैं।';
+ const html = `<h1>बिक्री का अनुमान</h1>${p(Array.from({ length: 6 }, () => line).join(' '))}`;
+ const result = readability(html, 'Hindi');
+ expect(result.words).toBe(60);
+ expect(result.score).not.toBeNull();
+ expect(result.checks.find((c) => c.id === 'avgSentence')!.value).toBe(10);
+ expect(result.checks.find((c) => c.id === 'longSentences')!.count).toBe(0);
+ expect(result.checks.find((c) => c.id === 'readingLevel')!.formula).toBeNull();
+ });
+
+ it('reads Turkish with Ateşman’s formula, and leaves out what it can’t read there', () => {
+ const tr =
+ '<h1>Küçük ekipler satış tahminini nasıl yapar?</h1>' +
+ p(
+ 'Küçük ekipler satış tahminini bu ay kapanabilecek fırsatlara bakarak yapar. Her fırsatı bir kez sayar ve her hafta kontrol eder.',
+ ) +
+ p(
+ 'Net bir sonraki adımı olan fırsatları seçin. Sessizleşenleri listeden çıkarın. Her fırsatın kapanmasını beklediğiniz tarihi yazın.',
+ ) +
+ p('Listeye her hafta aynı gün bakın. Kayan bir fırsatı çıkarın ve yenisini ekleyin.') +
+ p(
+ 'Tahmini ekiple paylaşın ve farkları birlikte konuşun. Böylece herkes aynı rakama bakar ve ay sonunda sürpriz yaşanmaz.',
+ );
+ const result = readability(tr, 'tr');
+ expect(result.checks.find((c) => c.id === 'readingLevel')!.formula).toBe('atesman');
+ // Passive voice and jargon read English only: left out, the score rescaled.
+ expect(result.checks.map((c) => c.id)).not.toContain('passiveJargon');
+ const max = result.checks.reduce((sum, c) => sum + c.max, 0);
+ expect(max).toBe(95);
+ expect(result.score).toBeGreaterThan(0);
+ });
+
+ it('falls back to sentence and word length for a language with no formula', () => {
+ const html = `<h1>Pipeline</h1>${p(Array.from({ length: 8 }, () => sentence(10)).join(' '))}`;
+ const level = check(html, 'readingLevel', 'nl')!;
+ expect(level.formula).toBeNull();
+ expect(level.points).toBe(READABILITY_WEIGHTS.readingLevel);
+ });
+
+ it('asks for a heading at least every 300 words', () => {
+ const html = `<h1>Pipeline</h1>${p(Array.from({ length: 32 }, () => sentence(10)).join(' '))}`;
+ expect(check(html, 'headingSpacing')).toMatchObject({ count: 1, points: 0 });
+ });
+
+ it('wants the first block under the H1 to answer it, briefly', () => {
+ const list = `<h1>How do small teams forecast pipeline?</h1><ul><li>${sentence(30)}</li></ul>${p(
+ Array.from({ length: 4 }, () => sentence(15)).join(' '),
+ )}`;
+ expect(check(list, 'answerFirst')).toMatchObject({ points: 0, count: 1 });
+ });
+
+ it('counts long paragraphs, passive sentences and jargon', () => {
+ const html =
+ '<h1>Pipeline</h1>' +
+ p(
+ `${sentence(12)} ${sentence(12)} ${sentence(12)} ${sentence(12)} ${sentence(12)} The plan was approved by the team.`,
+ ) +
+ p('We leverage synergy and a robust, seamless, holistic paradigm to empower teams.');
+ expect(check(html, 'shortParagraphs')).toMatchObject({ count: 1, points: 5 });
+ const style = check(html, 'passiveJargon')!;
+ expect(style.count).toBe(1);
+ expect(style.value).toBeGreaterThan(2);
+ expect(style.points).toBe(0);
+ });
+
+ it('says how much a check would add, rescaled as the score is', () => {
+ const html = `<h1>Pipeline</h1>${p(`${sentence(40)} ${sentence(38)} ${Array.from({ length: 4 }, () => sentence(14)).join(' ')}`)}`;
+ const result = readability(html, 'en');
+ expect(readabilityGain(result, 'longSentences')).toBe(6);
+ expect(readabilityGain(result, 'passiveJargon')).toBe(0);
+ });
+});
+
+describe('reading the page as written', () => {
+ it('reads a quote’s and a list item’s paragraphs apart, and a nested list once', () => {
+ const quote = `<h1>Pipeline</h1><blockquote><p>${sentence(20)}</p><p>${sentence(20)}</p></blockquote>${p(Array.from({ length: 3 }, () => sentence(15)).join(' '))}`;
+ expect(check(quote, 'longSentences')!.count).toBe(0);
+ const nested =
+ '<h1>Pipeline</h1><ul><li><p>Plan deals weekly.</p><ul><li><p>Check each one.</p></li></ul></li></ul>' +
+ p(Array.from({ length: 4 }, () => sentence(15)).join(' '));
+ expect(readability(nested, 'en').words).toBe(3 + 3 + 60);
+ });
+
+ it('measures sentence length on running text, not a list’s points', () => {
+ const html =
+ '<h1>How small teams forecast</h1>' +
+ p(`Small teams forecast pipeline every week. ${sentence(17)} ${sentence(17)}`) +
+ `<ul>${Array.from({ length: 12 }, () => '<li><p>Check deals weekly</p></li>').join('')}</ul>`;
+ const avg = check(html, 'avgSentence')!;
+ expect(avg.value).toBeGreaterThan(12);
+ expect(avg.count).toBeLessThanOrEqual(0);
+ });
+
+ it('reads Spanish, German and French higher for shorter sentences', () => {
+ const page = (n: number, word: string) =>
+ `<h1>${word}</h1>${p(Array.from({ length: Math.ceil(120 / n) }, () => `${Array.from({ length: n }, () => word).join(' ')}.`).join(' '))}`;
+ // Each sentence opens in upper case: after a dot, a lower-case word carries the sentence on.
+ for (const [lang, word] of [
+ ['es', 'Casa'],
+ ['de', 'Haus'],
+ ['fr', 'Maison'],
+ ]) {
+ const short = check(page(10, word), 'readingLevel', lang)!.value;
+ const long = check(page(30, word), 'readingLevel', lang)!.value;
+ expect(short).toBeGreaterThan(long);
+ }
+ });
+
+ it('wants a short first paragraph under an H1 that names its subject', () => {
+ const body = p(Array.from({ length: 4 }, () => sentence(15)).join(' '));
+ // An empty line after the H1 is no block.
+ const empty = `<h1>Pipeline forecasting for small teams</h1><p></p>${p('Pipeline forecasting is how a small team guesses what will close.')}${body}`;
+ expect(check(empty, 'answerFirst')!.points).toBe(15);
+ // Too long, or about something else.
+ const long = `<h1>Pipeline forecasting</h1>${p(`Pipeline ${sentence(70)}`)}${body}`;
+ expect(check(long, 'answerFirst')!.points).toBe(0);
+ const other = `<h1>Pipeline forecasting</h1>${p('Teams like a calm Monday.')}${body}`;
+ expect(check(other, 'answerFirst')!.points).toBe(0);
+ // No H1: nothing to answer.
+ expect(check(body, 'answerFirst')!.points).toBe(0);
+ // A short H1 is read by all its words.
+ const short = `<h1>What is AI?</h1>${p('AI is software that answers questions.')}${body}`;
+ expect(check(short, 'answerFirst')!.points).toBe(15);
+ });
+
+ it('keeps an abbreviation inside its sentence, and reads passive voice and jargon closely', () => {
+ expect(sentencesOf('Use a ratio, e.g. 1:16. Then brew.')).toEqual([
+ 'Use a ratio, e.g. 1:16.',
+ 'Then brew.',
+ ]);
+ const html =
+ '<h1>Pipeline</h1>' +
+ p(Array.from({ length: 4 }, () => sentence(15)).join(' ')) +
+ p(
+ 'It is indeed simple. We are leveraging tools and utilized synergies with empowering, streamlined plans.',
+ );
+ const style = check(html, 'passiveJargon')!;
+ expect(style.count).toBe(0);
+ expect(style.value).toBe(5);
+ // Only the jargon falls short: Show goes there.
+ expect(style.at).toContain('leveraging');
+ });
+
+ it('reads irregular participles as passive', () => {
+ const participles = [
+ ...['sent', 'found', 'held', 'kept', 'paid', 'put', 'set', 'left', 'lost', 'sold', 'said'],
+ ...['heard', 'brought', 'bought', 'caught', 'taught', 'spent', 'meant', 'led', 'won'],
+ ...['broken', 'spoken', 'hidden'],
+ ];
+ const html =
+ '<h1>Pipeline</h1>' +
+ p(Array.from({ length: 4 }, () => sentence(15)).join(' ')) +
+ p(participles.map((w) => `The deal was ${w} today.`).join(' '));
+ const style = check(html, 'passiveJargon')!;
+ expect(style.count).toBe(participles.length);
+ expect(style.at).toBe('The deal was sent today.');
+ });
+
+ it('reads a passive sentence that says not or never', () => {
+ const html =
+ '<h1>Pipeline</h1>' +
+ p(Array.from({ length: 5 }, () => sentence(15)).join(' ')) +
+ p("Stages are not defined. Deals weren't closed. Notes were never checked.");
+ const style = check(html, 'passiveJargon')!;
+ expect(style.count).toBe(3);
+ expect(style.at).toBe('Stages are not defined.');
+ });
+});
+
+describe('the parts', () => {
+ it('splits sentences after . ! ? and …', () => {
+ expect(sentencesOf('One. Two! Three? Four… Five')).toEqual([
+ 'One.',
+ 'Two!',
+ 'Three?',
+ 'Four…',
+ 'Five',
+ ]);
+ });
+
+ it('splits after 。!? with no space, and after । and ؟', () => {
+ expect(sentencesOf('一つです。二つです!三つですか?', 'ja')).toEqual([
+ '一つです。',
+ '二つです!',
+ '三つですか?',
+ ]);
+ expect(sentencesOf('यह पहला वाक्य है। यह दूसरा है।', 'hi')).toEqual([
+ 'यह पहला वाक्य है।',
+ 'यह दूसरा है।',
+ ]);
+ expect(sentencesOf('ما هذا؟ هذا كتاب.', 'ar')).toEqual(['ما هذا؟', 'هذا كتاب.']);
+ });
+
+ it('keeps a sentence whole when the next word starts in lower case', () => {
+ 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('reads a number and a dot before a word as an ordinal in German and Turkish', () => {
+ expect(sentencesOf('Wir starten am 3. Oktober mit der Liste. Dann prüfen wir.', 'de')).toEqual([
+ 'Wir starten am 3. Oktober mit der Liste.',
+ 'Dann prüfen wir.',
+ ]);
+ expect(sentencesOf('Toplantı 2. Kat salonunda. Herkes gelir.', 'tr')).toEqual([
+ 'Toplantı 2. Kat salonunda.',
+ 'Herkes gelir.',
+ ]);
+ // Not in English, where it ends a sentence.
+ expect(sentencesOf('Read chapter 3. Then stop.', 'en')).toEqual([
+ 'Read chapter 3.',
+ 'Then stop.',
+ ]);
+ });
+
+ it('keeps each language’s common abbreviations inside their sentence', () => {
+ expect(sentencesOf('Nutzen Sie z. B. Listen. Vgl. Kapitel Zwei. Dann weiter.', 'de')).toEqual([
+ 'Nutzen Sie z. B. Listen.',
+ 'Vgl. Kapitel Zwei.',
+ 'Dann weiter.',
+ ]);
+ expect(sentencesOf('Örn. Ankara gibi bir şehir seçin. Dr. Ayşe onaylar.', 'tr')).toEqual([
+ 'Örn. Ankara gibi bir şehir seçin.',
+ 'Dr. Ayşe onaylar.',
+ ]);
+ expect(sentencesOf('Une ville, p. ex. Paris. Appelez M. Dupont. Puis partez.', 'fr')).toEqual([
+ 'Une ville, p. ex. Paris.',
+ 'Appelez M. Dupont.',
+ 'Puis partez.',
+ ]);
+ expect(
+ sentencesOf('Una ciudad, p. ej. Madrid. Llame a la Sra. García. Luego vaya.', 'es'),
+ ).toEqual(['Una ciudad, p. ej. Madrid.', 'Llame a la Sra. García.', 'Luego vaya.']);
+ // One before a number counts only there: "no." still ends a sentence.
+ expect(sentencesOf('Say no. Then see No. 5 below.')).toEqual([
+ 'Say no.',
+ 'Then see No. 5 below.',
+ ]);
+ });
+
+ it('ends a sentence after a closing quote or bracket', () => {
+ 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.',
+ ]);
+ });
+
+ it('counts syllables by vowel groups, each vowel in Turkish', () => {
+ expect(syllablesOf('the', 'en')).toBe(1);
+ expect(syllablesOf('readable', 'en')).toBe(3);
+ expect(syllablesOf('quickly', 'en')).toBe(2);
+ expect(syllablesOf('kitaplık', 'tr')).toBe(3);
+ expect(syllablesOf('wanted', 'en')).toBe(2);
+ expect(syllablesOf('moment', 'fr')).toBe(2);
+ expect(syllablesOf('kâr', 'tr')).toBe(1);
+ expect(syllablesOf('Haus', 'de')).toBe(1);
+ });
+
+ it('reads the brand’s language or the Language rule as a code', () => {
+ expect(languageCode(null)).toBe('en');
+ expect(languageCode('English (US)')).toBe('en');
+ expect(languageCode('tr-TR')).toBe('tr');
+ expect(languageCode('Deutsch')).toBe('de');
+ expect(languageCode('ja')).toBe('ja');
+ expect(languageCode('Brazilian Portuguese')).toBe('pt');
+ expect(languageCode('Klingon')).toBeNull();
+ // Each brand language, as its Language rule says it.
+ for (const { code } of LANGUAGES) expect(languageCode(languageRuleValue(code))).toBe(code);
+ });
+});
diff --git a/web/src/lib/content/readability.ts b/web/src/lib/content/readability.ts
new file mode 100644
index 000000000..2734d6d5f
--- /dev/null
+++ b/web/src/lib/content/readability.ts
@@ -0,0 +1,517 @@
+import { LANGUAGES } from '@/config/prompt-options';
+
+/**
+ * Readability, one of the Quality scores (Content Editor Quality spec §2.3,
+ * CE-036): seven checks read from the draft as written, in the browser, with
+ * no AI cost. Each gives points up to its weight; a check the draft's
+ * language can't be read for is left out and the score rescaled to 100, so
+ * no points are made up. An Ansvisor estimate, not a Google score.
+ */
+
+export const READABILITY_CHECKS = [
+ 'avgSentence',
+ 'longSentences',
+ 'readingLevel',
+ 'answerFirst',
+ 'shortParagraphs',
+ 'headingSpacing',
+ 'passiveJargon',
+] as const;
+export type ReadabilityCheckId = (typeof READABILITY_CHECKS)[number];
+
+/** Each check's weight (spec §2.3): 100 in all. */
+export const READABILITY_WEIGHTS: Record<ReadabilityCheckId, number> = {
+ avgSentence: 25,
+ longSentences: 15,
+ readingLevel: 20,
+ answerFirst: 15,
+ shortParagraphs: 10,
+ headingSpacing: 10,
+ passiveJargon: 5,
+};
+
+/** A sentence longer than this is long (spec: "No sentence over 35 words"). */
+export const LONG_SENTENCE_WORDS = 35;
+/** The average a sentence aims for. */
+export const SENTENCE_WORDS = { min: 15, max: 20 } as const;
+/** A paragraph longer than this many sentences is long. */
+export const PARAGRAPH_SENTENCES = 4;
+/** The most words under one heading before the next one is due. */
+export const SECTION_WORDS = 300;
+/** A page shorter than this gets no Readability score yet: too little to read. */
+export const MIN_WORDS = 50;
+
+export type ReadingFormula = 'flesch' | 'atesman' | 'amstad' | 'kandelMoles' | 'fernandezHuerta';
+
+/** What one check found: its points out of its weight, and what it counted. */
+export interface ReadabilityCheck {
+ id: ReadabilityCheckId;
+ points: number;
+ max: number;
+ /** What it counted: words, sentences, a formula's score… */
+ value: number;
+ /** How many of what it looks for fall short (long sentences, long sections…). */
+ count: number;
+ /** The reading-level formula used, for readingLevel, and the score that reads as easy. */
+ formula?: ReadingFormula | null;
+ target?: number;
+ /** The first block that falls short, to show it in the draft. */
+ at?: string | null;
+}
+
+export interface Readability {
+ /** 0–100 over the checks that could be read; null for a page it can't score. */
+ score: number | null;
+ /**
+ * Why there is no score: a page too short to read, or a language written
+ * without spaces between words (Japanese, Chinese, Thai), whose words and
+ * sentences aren't counted yet.
+ */
+ unscored?: 'tooShort' | 'language';
+ checks: ReadabilityCheck[];
+ words: number;
+}
+
+/** A block as Readability reads it: its tag and its own words. */
+export interface ReadBlock {
+ tag: 'h1' | 'h2' | 'h3' | 'p' | 'li' | 'blockquote';
+ text: string;
+ words: number;
+}
+
+/**
+ * Words as the rules count them (rules.ts countWords), a vowel sign or other
+ * mark kept inside its word: Hindi's are marks, not letters, and would break
+ * each word in two or three.
+ */
+const WORD = /[\p{L}\p{N}][\p{L}\p{M}\p{N}'’-]*/gu;
+const countWords = (text: string) => text.match(WORD)?.length ?? 0;
+
+/**
+ * Text joined as a reader sees it: a space between paragraphs and at a line
+ * break (the editor's HTML has none between tags), a list item's own words
+ * without the list nested in it.
+ */
+function ownText(el: Element): string {
+ let out = '';
+ for (const node of el.childNodes) {
+ if (node.nodeType === 3) out += node.textContent ?? '';
+ else if (node.nodeType === 1) {
+ const child = node as Element;
+ const tag = child.tagName.toLowerCase();
+ if (tag === 'ul' || tag === 'ol') continue;
+ if (tag === 'br') out += ' ';
+ else out += ` ${ownText(child)} `;
+ }
+ }
+ return out;
+}
+
+/** The page's headings and prose, in order: a quote once, each list item on its own. */
+export function readBlocks(html: string): ReadBlock[] {
+ const doc = new DOMParser().parseFromString(html, 'text/html');
+ const blocks: ReadBlock[] = [];
+ for (const el of doc.body.querySelectorAll('h1, h2, h3, p, li, blockquote')) {
+ const tag = el.tagName.toLowerCase() as ReadBlock['tag'];
+ // 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')) continue;
+ if (tag === 'li' && el.closest('td, th')) continue;
+ const text = ownText(el).replace(/\s+/g, ' ').trim();
+ if (text) blocks.push({ tag, text, words: countWords(text) });
+ }
+ return blocks;
+}
+
+const isHeading = (b: ReadBlock) => b.tag === 'h1' || b.tag === 'h2' || b.tag === 'h3';
+const isProse = (b: ReadBlock) => !isHeading(b);
+/** Running text: a list item is a point, not a sentence to measure. */
+const isRunning = (b: ReadBlock) => b.tag === 'p' || b.tag === 'blockquote';
+
+/**
+ * Abbreviations whose dot ends no sentence, by language; English's are read
+ * in all. A dot inside one may take a space ("z. B."), and one starting in
+ * lower case may open a sentence in upper case ("Vgl.").
+ */
+const ABBREVIATIONS: Record<string, string[]> = {
+ en: [
+ ...['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'],
+ ],
+ de: [
+ ...['z.B', 'd.h', 'u.a', 'u.U', 'z.T', 'o.Ä', 'i.d.R', 'bzw', 'ca', 'usw', 'ggf', 'evtl'],
+ ...['inkl', 'vgl', 'bspw', 'sog', 'Hr', 'Fr', 'Str', 'Mio', 'Mrd'],
+ ],
+ tr: ['vb', 'örn', 'bkz', 'yy', 'Doç', 'Yrd', 'Av', 'Sn', 'T.C', 'Mah', 'Cad', 'Sok', 'Apt'],
+ fr: ['p.ex', 'c.-à-d', 'M', 'Mme', 'Mlle', 'MM', 'env', 'av.J.-C', 'apr.J.-C', 'Ste'],
+ es: [
+ ...['p.ej', 'Sr', 'Sra', 'Srta', 'Dra', 'Ud', 'Uds', 'aprox', 'EE.UU', 'a.C', 'd.C'],
+ ...['Avda', 'Lic', 'Ing'],
+ ],
+ pt: ['p.ex', 'Sr', 'Sra', 'Dra', 'aprox', 'Av'],
+ it: ['ad es', 'ecc', 'Sig', 'Sig.ra', 'Dott', 'Dott.ssa'],
+ nl: ['bijv', 'bv', 'o.a', 'd.w.z', 'enz', 'm.b.t', 'i.p.v', 'Dhr', 'Mevr'],
+ sv: ['t.ex', 'bl.a', 'm.m', 'osv', 'dvs', 'ca', 's.k'],
+};
+/** These end no sentence before a number only ("No. 5", "S. 12"), so "Say no." still does. */
+const BEFORE_NUMBER: Record<string, string[]> = {
+ en: ['No', 'p', 'pp', 'Fig', 'Vol', 'Ch'],
+ de: ['Nr', 'S', 'Abb', 'Kap', 'Bd'],
+ tr: ['s', 'Md'],
+ fr: ['p', 'n', 'fig', 'chap', 'vol'],
+ es: ['pág', 'núm', 'art', 'cap', 'fig'],
+ pt: ['pág', 'n', 'art', 'cap'],
+ it: ['pag', 'n', 'art', 'cap'],
+ nl: ['nr', 'blz', 'art'],
+ sv: ['nr', 's'],
+};
+/** Languages whose ordinals are a number and a dot ("am 3. Oktober", "3. Kat"). */
+const DOT_ORDINALS = new Set(['de', 'tr']);
+
+const escapeRe = (s: string) => 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: string[], lang: string): string {
+ return list
+ .flatMap((a) => {
+ const upper = a[0].toLocaleUpperCase(lang) + 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 abbreviationsRe = new Map<string, RegExp>();
+/** The dots that end no sentence in a language: its abbreviations', and its ordinals'. */
+function protectedDots(lang: string): RegExp {
+ let re = abbreviationsRe.get(lang);
+ if (!re) {
+ const own = (table: Record<string, string[]>) =>
+ alternation([...table.en, ...(lang === 'en' ? [] : (table[lang] ?? []))], lang);
+ const parts = [
+ `(?:${own(ABBREVIATIONS)})\\.(?=\\s)`,
+ `(?:${own(BEFORE_NUMBER)})\\.(?=\\s*\\p{N})`,
+ ...(DOT_ORDINALS.has(lang) ? ['\\p{N}+\\.(?=\\s+\\p{L})'] : []),
+ ];
+ re = new RegExp(`(?<![\\p{L}\\p{N}])(?:${parts.join('|')})`, 'gu');
+ abbreviationsRe.set(lang, re);
+ }
+ return re;
+}
+
+/** 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, and right after 。!? (Japanese, Chinese), । (Hindi) or ؟
+ * (Arabic), which need no space; 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: split after . ! ? … 。!? । or ؟, an abbreviation's
+ * or an ordinal's dot aside. `language` is a two-letter code; null reads
+ * English's abbreviations only.
+ */
+export function sentencesOf(text: string, language: string | null = 'en'): string[] {
+ return text
+ .replace(protectedDots(language ?? 'en'), (m) => m.replace(/\./g, '\u2024'))
+ .split(SENTENCE_END)
+ .map((s) => s.replace(/\u2024/g, '.').trim())
+ .filter((s) => countWords(s) > 0);
+}
+
+const VOWELS: Record<string, RegExp> = {
+ en: /[aeiouy]+/g,
+ tr: /[aeıioöuüâîû]/g,
+ de: /[aeiouäöüy]+/g,
+ fr: /[aeiouyàâäéèêëîïôöùûüœæ]+/g,
+ es: /[aeiouáéíóúü]+/g,
+};
+
+/**
+ * A word's syllables, as each formula counts them: vowel groups (each
+ * vowel in Turkish), an English silent final e left out. Never under one.
+ */
+export function syllablesOf(word: string, language: string): number {
+ let w = word.toLocaleLowerCase(language).replace(/[^\p{L}]/gu, '');
+ if (!w) return 0;
+ if (language === 'en') {
+ 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]);
+ }
+ if (language === 'fr') w = w.replace(/(?:es|e)$/, (m) => (w.length > 3 ? '' : m));
+ const groups = w.match(VOWELS[language] ?? VOWELS.en)?.length ?? 0;
+ return Math.max(1, groups);
+}
+
+/** 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 },
+ // Ateşman's "medium" band starts at 50; Turkish words run longer.
+ tr: { formula: 'atesman', target: 50 },
+ de: { formula: 'amstad', target: 60 },
+ fr: { formula: 'kandelMoles', target: 60 },
+ es: { formula: 'fernandezHuerta', target: 60 },
+};
+
+/**
+ * Language names as a Language rule or a brand says them: each brand
+ * language's (LANGUAGES), in English and in its own, and Chinese and Thai,
+ * written without spaces between words as Japanese is.
+ */
+const LANGUAGE_NAMES = new Map<string, string>([
+ ...LANGUAGES.map((l) => [l.label.replace(/\s*\(.*$/, '').toLowerCase(), l.code] as const),
+ ...Object.entries({
+ deutsch: 'de',
+ français: 'fr',
+ español: 'es',
+ türkçe: 'tr',
+ 日本語: 'ja',
+ português: 'pt',
+ हिन्दी: 'hi',
+ हिंदी: 'hi',
+ 한국어: 'ko',
+ italiano: 'it',
+ nederlands: 'nl',
+ svenska: 'sv',
+ العربية: 'ar',
+ chinese: 'zh',
+ mandarin: 'zh',
+ 中文: 'zh',
+ thai: 'th',
+ ไทย: 'th',
+ }),
+]);
+
+/**
+ * The language as a two-letter code: a name anywhere in it ("English (US)",
+ * "Brazilian Portuguese"), else a code first ("en-US", "pt_BR"); English
+ * when unset, null when unknown.
+ */
+export function languageCode(language: string | null | undefined): string | null {
+ const value = (language ?? '').trim().toLowerCase();
+ if (!value) return 'en';
+ const words = value.split(/[^\p{L}\p{M}]+/u).filter(Boolean);
+ const named = words.find((w) => LANGUAGE_NAMES.has(w));
+ if (named) return LANGUAGE_NAMES.get(named)!;
+ return /^[a-z]{2}$/.test(words[0] ?? '') ? words[0] : null;
+}
+
+/** Languages written without spaces between words: their words and sentences can't be counted yet. */
+const UNSPACED = new Set(['ja', 'zh', 'th']);
+
+/** A formula's score from the average sentence length and syllables per word. */
+function formulaScore(formula: ReadingFormula, asl: number, asw: number): number {
+ switch (formula) {
+ case 'flesch':
+ return 206.835 - 1.015 * asl - 84.6 * asw;
+ case 'atesman':
+ return 198.825 - 40.175 * asw - 2.61 * asl;
+ case 'amstad':
+ return 180 - asl - 58.5 * asw;
+ case 'kandelMoles':
+ return 207 - 1.015 * asl - 73.6 * asw;
+ case 'fernandezHuerta':
+ // Syllables per 100 words, and words per sentence: the corrected form
+ // (the published one subtracts sentences per 100 words, which rewards
+ // long sentences).
+ return 206.84 - 0.6 * (asw * 100) - 1.02 * asl;
+ }
+}
+
+/** Points on a line: full at `full`, none `span` away, in between in proportion. */
+const toward = (value: number, full: number, span: number, max: number) =>
+ Math.max(0, Math.min(1, 1 - (full - value) / span)) * max;
+
+const PASSIVE =
+ /\b(?:am|is|are|was|were|be|been|being)(?:n['’]t)?\s+(?:(?:not|never)\s+)?(?:\w+ly\s+)?(?:(?!(?:indeed|need|speed|seed|feed|bleed|breed|proceed|exceed|succeed)\b)\w+ed|been|born|bought|brought|broken|built|caught|chosen|done|drawn|driven|found|given|grown|heard|held|hidden|kept|known|led|left|lost|made|meant|paid|put|said|seen|sent|set|shown|sold|spent|spoken|taken|taught|thought|told|won|written)\b/i;
+/** Words that say little in English business writing, in each of their forms. */
+const JARGON =
+ /\b(?:leverag\w*|synerg\w*|utili[sz]\w*|paradigm\w*|best-in-class|cutting-edge|world-class|next-generation|game-chang\w*|seamless\w*|holistic\w*|robust\w*|streamlin\w*|empower\w*|disruptive\w*)\b/gi;
+
+/** Question words and the commonest words, in the languages read: no H1's subject. */
+const COMMON = new Set([
+ ...['what', 'how', 'why', 'when', 'where', 'which', 'who', 'is', 'are', 'was', 'were'],
+ ...['do', 'does', 'can', 'the', 'and', 'for', 'with', 'your', 'you', 'best', 'to', 'of'],
+ ...['nedir', 'nasıl', 'neden', 'hangi', 'için', 'ile', 'mi', 'mı', 'mu', 'mü', 've', 'en'],
+ ...['wie', 'warum', 'wann', 'welche', 'ist', 'sind', 'der', 'die', 'das', 'und', 'für'],
+ ...['quoi', 'comment', 'pourquoi', 'quand', 'quel', 'quelle', 'est', 'les', 'des', 'pour'],
+ ...['qué', 'cómo', 'por', 'cuándo', 'cuál', 'es', 'son', 'los', 'las', 'para', 'con'],
+]);
+
+/**
+ * The draft's Readability: its checks and the score over the ones that could
+ * be read. `language` is the one the draft is written in (its Language rule,
+ * else the brand's), English when unset.
+ */
+export function readability(html: string, language: string | null | undefined): Readability {
+ const blocks = readBlocks(html);
+ const lang = languageCode(language);
+ const prose = blocks.filter(isProse);
+ const sentences = prose.flatMap((b) => sentencesOf(b.text, lang).map((s) => ({ s, block: b })));
+ const sentenceWords = sentences.map(({ s }) => countWords(s));
+ const words = sentenceWords.reduce((a, b) => a + b, 0);
+ // A Japanese clause reads as one word: no score rather than a made-up one.
+ if (lang && UNSPACED.has(lang)) return { score: null, unscored: 'language', checks: [], words };
+ if (words < MIN_WORDS || sentences.length === 0) {
+ return { score: null, unscored: 'tooShort', checks: [], words };
+ }
+
+ const checks: ReadabilityCheck[] = [];
+ const check = (c: Omit<ReadabilityCheck, 'max'>) =>
+ checks.push({ ...c, max: READABILITY_WEIGHTS[c.id] });
+
+ // Average sentence, 15–20 words, over running text: a list's points are no
+ // sentences. Full inside, none 10 words outside.
+ const running = sentences.filter(({ block }) => isRunning(block));
+ const measured = running.length > 0 ? running : sentences;
+ const runningWords = measured.reduce((sum, { s }) => sum + countWords(s), 0);
+ const asl = runningWords / measured.length;
+ const off =
+ asl < SENTENCE_WORDS.min ? SENTENCE_WORDS.min - asl : Math.max(0, asl - SENTENCE_WORDS.max);
+ check({
+ id: 'avgSentence',
+ points: toward(-off, 0, 10, READABILITY_WEIGHTS.avgSentence),
+ value: Math.round(asl * 10) / 10,
+ // Under the range (-1), in it (0) or over it (1): what the detail says to do.
+ count: asl < SENTENCE_WORDS.min ? -1 : asl > SENTENCE_WORDS.max ? 1 : 0,
+ });
+
+ // No sentence over 35 words, a list item's too: 3 points off for each.
+ const long = sentences.filter((_, i) => sentenceWords[i] > LONG_SENTENCE_WORDS);
+ check({
+ id: 'longSentences',
+ points: Math.max(0, READABILITY_WEIGHTS.longSentences - 3 * long.length),
+ value: Math.max(...sentenceWords),
+ count: long.length,
+ at: long[0]?.s ?? null,
+ });
+
+ // Reading level, by the language's formula; else sentence and word length only.
+ const allAsl = words / sentences.length;
+ const known = lang ? FORMULAS[lang] : undefined;
+ if (known && lang) {
+ const syllables = sentences
+ .flatMap(({ s }) => s.match(WORD) ?? [])
+ .reduce((sum, w) => sum + syllablesOf(w, lang), 0);
+ const score = formulaScore(known.formula, allAsl, syllables / words);
+ check({
+ id: 'readingLevel',
+ points: toward(score, known.target, 30, READABILITY_WEIGHTS.readingLevel),
+ value: Math.round(score),
+ count: 0,
+ formula: known.formula,
+ target: known.target,
+ });
+ } else {
+ const letters = sentences
+ .flatMap(({ s }) => s.match(/[\p{L}\p{M}]+/gu) ?? [])
+ .reduce((sum, w) => sum + w.length, 0);
+ const awl = letters / words;
+ const short = (allAsl <= SENTENCE_WORDS.max ? 0.5 : 0) + (awl <= 6.5 ? 0.5 : 0);
+ check({
+ id: 'readingLevel',
+ points: short * READABILITY_WEIGHTS.readingLevel,
+ value: Math.round(awl * 10) / 10,
+ count: 0,
+ formula: null,
+ });
+ }
+
+ // Answer first: the first block under the H1 is a short paragraph that
+ // names what the H1 asks (a heuristic; Phase 2 reads it with a model). A
+ // page without an H1 has nothing to answer, and doesn't pass.
+ const h1 = blocks.findIndex((b) => b.tag === 'h1');
+ const first = h1 === -1 ? undefined : blocks[h1 + 1];
+ const wordsOf = (text: string) => text.toLocaleLowerCase(lang ?? 'en').match(/\p{L}{2,}/gu) ?? [];
+ // The H1's subject: its words but the question words and the commonest
+ // ones, the longer ones when it has any ("What is AI?" is about "ai").
+ const h1Words = (h1 === -1 ? [] : wordsOf(blocks[h1].text)).filter((w) => !COMMON.has(w));
+ const subject = new Set(
+ h1Words.some((w) => w.length >= 4) ? h1Words.filter((w) => w.length >= 4) : h1Words,
+ );
+ const answers =
+ !!first &&
+ first.tag === 'p' &&
+ first.words <= 60 &&
+ wordsOf(first.text).some((w) => subject.has(w));
+ check({
+ id: 'answerFirst',
+ points: answers ? READABILITY_WEIGHTS.answerFirst : 0,
+ value: first?.words ?? 0,
+ count: answers ? 0 : 1,
+ at: answers ? null : (first?.text ?? (h1 === -1 ? null : blocks[h1].text)),
+ });
+
+ // Short paragraphs: the share with at most 4 sentences.
+ const paragraphs = blocks.filter((b) => b.tag === 'p');
+ if (paragraphs.length > 0) {
+ const longParagraphs = paragraphs.filter(
+ (b) => sentencesOf(b.text, lang).length > PARAGRAPH_SENTENCES,
+ );
+ check({
+ id: 'shortParagraphs',
+ points:
+ READABILITY_WEIGHTS.shortParagraphs *
+ ((paragraphs.length - longParagraphs.length) / paragraphs.length),
+ value: paragraphs.length,
+ count: longParagraphs.length,
+ at: longParagraphs[0]?.text ?? null,
+ });
+ }
+
+ // A heading every 200–300 words: the share of sections within 300.
+ const sections: { words: number; first: string | null }[] = [{ words: 0, first: null }];
+ for (const b of blocks) {
+ if (isHeading(b) && b.tag !== 'h1') sections.push({ words: 0, first: null });
+ else if (isProse(b)) {
+ const last = sections[sections.length - 1];
+ last.words += b.words;
+ last.first ??= b.text;
+ }
+ }
+ const filled = sections.filter((s) => s.words > 0);
+ const longSections = filled.filter((s) => s.words > SECTION_WORDS);
+ check({
+ id: 'headingSpacing',
+ points:
+ READABILITY_WEIGHTS.headingSpacing *
+ (filled.length ? (filled.length - longSections.length) / filled.length : 1),
+ value: filled.length,
+ count: longSections.length,
+ at: longSections[0]?.first ?? null,
+ });
+
+ // Passive voice and jargon: English only; left out for other languages.
+ if (lang === 'en') {
+ const passive = sentences.filter(({ s }) => PASSIVE.test(s));
+ const jargonIn = sentences.filter(({ s }) => (s.match(JARGON)?.length ?? 0) > 0);
+ const jargon = sentences.reduce((n, { s }) => n + (s.match(JARGON)?.length ?? 0), 0);
+ const passiveOk = passive.length <= sentences.length * 0.1;
+ const jargonOk = jargon <= 2;
+ check({
+ id: 'passiveJargon',
+ points: (READABILITY_WEIGHTS.passiveJargon * ((passiveOk ? 1 : 0) + (jargonOk ? 1 : 0))) / 2,
+ value: jargon,
+ count: passive.length,
+ // Show goes to what falls short: a passive sentence, else one with jargon.
+ at: !passiveOk ? (passive[0]?.s ?? null) : !jargonOk ? (jargonIn[0]?.s ?? null) : null,
+ });
+ }
+
+ const max = checks.reduce((sum, c) => sum + c.max, 0);
+ const points = checks.reduce((sum, c) => sum + c.points, 0);
+ return { score: Math.round((points / max) * 100), checks, words };
+}
+
+/** How much a check would add to the score if it were met, rescaled as the score is. */
+export function readabilityGain(result: Readability, id: ReadabilityCheckId): number {
+ const c = result.checks.find((x) => x.id === id);
+ if (!c) return 0;
+ const max = result.checks.reduce((sum, x) => sum + x.max, 0);
+ return Math.round(((c.max - c.points) / max) * 100);
+}
diff --git a/web/src/lib/content/rules.ts b/web/src/lib/content/rules.ts
index 1d2945cb5..ea74e9043 100644
--- a/web/src/lib/content/rules.ts
+++ b/web/src/lib/content/rules.ts
@@ -572,7 +572,8 @@ export function readPage(html: string, characters: number): PageRead {
};
}
-function countWords(text: string): number {
+/** Words as the rules count them: letters or digits, with inner apostrophes and hyphens. */
+export function countWords(text: string): number {
return text.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu)?.length ?? 0;
}