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): list the placeholders the agent left as the first to-do (CE-044) (#1422)

Cihan7de1b1215b84
diff --git a/web/messages/en.json b/web/messages/en.json
index 6c58b3855..bf1c3869a 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -4218,6 +4218,12 @@
"left": "{count, plural, =0 {All done} other {# left · only you can do these}}",
"done": "Done",
"open": "To do",
+ "placeholders": {
+ "title": "{count, plural, =0 {Fill the placeholders} one {Fill # placeholder} other {Fill # placeholders}}",
+ "next": "{count, plural, =0 {fill the placeholders} one {fill # placeholder} other {fill # placeholders}}",
+ "detail": "Words in [brackets] stand where a real name, quote or number goes. Put in the real one, or take the sentence out",
+ "done": "All filled in"
+ },
"byline": {
"title": {
"pickAuthor": "Pick the page's author",
@@ -4256,6 +4262,7 @@
"label": "Your next step",
"text": "Next for you: <b>{todo}</b> · {position} of {count}",
"act": {
+ "showPlaceholder": "Show now",
"pickAuthor": "Pick now",
"addAuthor": "Add now",
"editAuthor": "Edit now"
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 30a6385d9..f380fd015 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
@@ -75,6 +75,7 @@ import {
import { PAGE_READ_DELAY_MS, draftTitleFromDoc, safeLinkHref } from '@/lib/content/editor';
import { JsonLd } from '@/lib/content/json-ld-node';
import { firstImage } from '@/lib/content/page-schema';
+import { PLACEHOLDER, pagePlaceholders } from '@/lib/content/placeholders';
import { detectPageType } from '@/lib/content/page-types';
import { BAND_CLASSES, qualityAverage, qualityBand, qualityPhase } from '@/lib/content/quality';
import { eeat, linksToCheck, trust, trustBlocks } from '@/lib/content/quality-checks';
@@ -501,11 +502,25 @@ export function DraftEditor({
const hasAuthors = (authorsRead?.authors.length ?? 0) > 0;
// What only the person can do (CE-040), and the nudge to the first of it
// when the agent's run ends, after Accept all and on Mark ready.
+ // The placeholders the agent left (CE-044): the person fills them. Once
+ // the page has had some, the to-do stays, checked when they are filled.
+ const placeholderCount = useMemo(
+ () => (qualityOn ? pagePlaceholders(pageHtml).count : 0),
+ [qualityOn, pageHtml],
+ );
+ const [hadPlaceholders, setHadPlaceholders] = useState(false);
+ if (placeholderCount > 0 && !hadPlaceholders) setHadPlaceholders(true);
// Who may edit the page's author: only they get Edit author (CE-037's rule).
const canEditPageAuthor =
!!pageAuthor && !!authorsRead && canEditAuthor(pageAuthor, authorsRead.me);
const todos = qualityOn
- ? qualityTodos({ eeat: eeatScore, author: pageAuthor, hasAuthors, canEdit: canEditPageAuthor })
+ ? qualityTodos({
+ eeat: eeatScore,
+ author: pageAuthor,
+ hasAuthors,
+ canEdit: canEditPageAuthor,
+ placeholders: { count: placeholderCount, had: hadPlaceholders },
+ })
: [];
const quality: QualityRead | null = qualityOn
? {
@@ -524,13 +539,25 @@ export function DraftEditor({
const [authorMenuOpen, setAuthorMenuOpen] = useState(false);
const nudge = useNextNudge(draft.id, todos);
const { at: nudgeAt } = nudge;
- const todosRead = todos.length > 0;
+ // The author's to-dos wait for E-E-A-T: the nudge waits for them.
+ const todosRead = eeatScore !== null;
const agentNudged = useRef(false);
useEffect(() => {
if (!agentFinished || !todosRead || agentNudged.current) return;
agentNudged.current = true;
nudgeAt('agent');
}, [agentFinished, todosRead, nudgeAt]);
+ // Accept all's moment waits for the page as read after it: the placeholders
+ // the accepted words brought are to-dos by then.
+ const acceptedAt = useRef<string | null>(null);
+ const nudgeAfterRead = () => {
+ acceptedAt.current = pageHtml;
+ };
+ useEffect(() => {
+ if (acceptedAt.current === null || acceptedAt.current === pageHtml) return;
+ acceptedAt.current = null;
+ nudgeAt('acceptAll');
+ }, [pageHtml, nudgeAt]);
const byline = authorsRead
? [
t('author.by', {
@@ -857,7 +884,7 @@ export function DraftEditor({
}
setSuggestions(next);
// The last open one accepted (Accept all, or one by one): the nudge's moment.
- if (decision === 'accept' && !next.some((s) => s.status === 'open')) nudgeAt('acceptAll');
+ if (decision === 'accept' && !next.some((s) => s.status === 'open')) nudgeAfterRead();
if (decision === 'accept')
toast.success(t('suggestions.acceptedToast', { count: changed.length }));
else if (decision === 'reject')
@@ -906,6 +933,52 @@ export function DraftEditor({
setTimeout(() => card.classList.remove(...mark), 1200);
};
+ /**
+ * The page's first placeholder (CE-044), selected to type over: in order,
+ * across the marks in its line, its block flashed as Show's are.
+ */
+ const showFirstPlaceholder = () => {
+ if (!editor) return;
+ const one = new RegExp(PLACEHOLDER.source, 'iu');
+ let found: { from: number; to: number; block: { from: number; to: number } } | null = null;
+ editor.state.doc.descendants((block, pos) => {
+ if (found) return false;
+ if (!block.isTextblock) return true;
+ // The line's text, with where each piece of it starts in the page.
+ let text = '';
+ const pieces: { at: number; pos: number }[] = [];
+ block.forEach((child, offset) => {
+ if (!child.isText) return;
+ pieces.push({ at: text.length, pos: pos + 1 + offset });
+ text += child.text;
+ });
+ const m = one.exec(text);
+ if (!m) return false;
+ const posOf = (i: number) => {
+ const piece = pieces.findLast((p) => p.at <= i)!;
+ return piece.pos + (i - piece.at);
+ };
+ found = {
+ from: posOf(m.index),
+ to: posOf(m.index + m[0].length - 1) + 1,
+ block: { from: pos, to: pos + block.nodeSize },
+ };
+ return false;
+ });
+ if (!found) return;
+ const { from, to, block } = found;
+ editor
+ .chain()
+ .setTextSelection({ from, to })
+ .scrollIntoView()
+ .focus(undefined, { scrollIntoView: false })
+ .run();
+ editor.view.dispatch(editor.state.tr.setMeta(flashKey, block));
+ setTimeout(() => {
+ if (!editor.isDestroyed) editor.view.dispatch(editor.state.tr.setMeta(flashKey, null));
+ }, 1200);
+ };
+
/**
* Quality's Show: the block of the page holding the passage (never a
* suggestion's card), scrolled to and marked for a moment.
@@ -979,7 +1052,7 @@ export function DraftEditor({
if (to === 'accepted') {
toast.success(t('rewrite.acceptedToast'));
// The rewrite is the whole batch: as Accept all.
- nudgeAt('acceptAll');
+ nudgeAfterRead();
} else if (to === 'rejected') toast(t('rewrite.rejectedToast'));
else toast(t('rewrite.undoneToast'));
} catch (err) {
@@ -1761,6 +1834,7 @@ export function DraftEditor({
<NextNudge
shown={nudge.shown}
quality={quality}
+ onShowPlaceholder={showFirstPlaceholder}
onPickAuthor={() => setAuthorMenuOpen(true)}
onLater={nudge.later}
onAct={nudge.close}
@@ -1791,6 +1865,7 @@ export function DraftEditor({
quality={quality}
qualityScore={qualityScore}
onShowInPage={showInPage}
+ onShowPlaceholder={showFirstPlaceholder}
onPickAuthor={() => setAuthorMenuOpen(true)}
/>
) : (
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.test.tsx
index 971d8b51e..5ea0127c2 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.test.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.test.tsx
@@ -42,6 +42,7 @@ const profile: QualityTodo = { id: 'authorProfile', done: false, gain: 40, actio
let container: HTMLDivElement;
let root: Root;
const onPickAuthor = vi.fn();
+const onShowPlaceholder = vi.fn();
const MOMENTS: NudgeMoment[] = ['agent', 'acceptAll', 'markReady'];
/** The editor's part: the hook, a button per moment, and the nudge while it shows. */
@@ -55,6 +56,7 @@ function Harness({ todos, author }: { todos: QualityTodo[]; author: ContentAutho
<NextNudge
shown={nudge.shown}
quality={{ author, brandName: 'Acme', canEdit: true }}
+ onShowPlaceholder={onShowPlaceholder}
onPickAuthor={onPickAuthor}
onLater={nudge.later}
onAct={nudge.close}
@@ -82,6 +84,7 @@ const button = (name: string) =>
beforeEach(() => {
sessionStorage.clear();
onPickAuthor.mockReset();
+ onShowPlaceholder.mockReset();
container = document.createElement('div');
root = createRoot(container);
});
@@ -103,6 +106,22 @@ describe('NextNudge', () => {
expect(status()).toBe('');
});
+ it('shows the first placeholder the agent left (CE-044)', async () => {
+ const fill: QualityTodo = {
+ id: 'placeholders',
+ done: false,
+ gain: 0,
+ action: 'showPlaceholder',
+ count: 2,
+ };
+ await render([fill, pick]);
+ await act(async () => nudgeAt('agent'));
+ expect(nudge()!.textContent).toBe('Next for you: fill 2 placeholders · 1 of 2Show nowLater');
+ await act(async () => button('Show now').click());
+ expect(onShowPlaceholder).toHaveBeenCalled();
+ expect(nudge()).toBeNull();
+ });
+
it('counts the open ones and skips the done', async () => {
await render([{ ...pick, done: true }, profile], ada);
await act(async () => nudgeAt('markReady'));
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.tsx
index 1a89d0a03..ac48ffc7c 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_next-nudge.tsx
@@ -87,12 +87,15 @@ export function useNextNudge(draftId: string, todos: QualityTodo[]) {
export function NextNudge({
shown,
quality,
+ onShowPlaceholder,
onPickAuthor,
onLater,
onAct,
}: {
shown: { todo: QualityTodo; count: number } | null;
quality: Pick<QualityRead, 'author' | 'brandName' | 'canEdit'>;
+ /** Selects the page's first placeholder, to type over. */
+ onShowPlaceholder: () => void;
onPickAuthor: () => void;
onLater: () => void;
/** It was acted on: it goes. */
@@ -125,7 +128,18 @@ export function NextNudge({
<span aria-hidden className="min-w-0 flex-1 [overflow-wrap:anywhere]">
{text}
</span>
- {action === 'pickAuthor' ? (
+ {action === 'showPlaceholder' ? (
+ <button
+ type="button"
+ className={actClass}
+ onClick={() => {
+ onAct();
+ onShowPlaceholder();
+ }}
+ >
+ {t('act.showPlaceholder')}
+ </button>
+ ) : action === 'pickAuthor' ? (
<button
type="button"
className={actClass}
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
index a80ce06fa..38ed4cb48 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
@@ -85,13 +85,19 @@ let container: HTMLDivElement;
let root: Root;
const onShow = vi.fn();
const onPickAuthor = vi.fn();
+const onShowPlaceholder = vi.fn();
async function render(quality: QualityRead | Readability | null) {
const q = quality && 'eeat' in quality ? quality : read(quality as Readability | null);
await act(async () => {
root.render(
<NextIntlClientProvider locale="en" messages={messages}>
- <QualityTab quality={q} onShow={onShow} onPickAuthor={onPickAuthor} />
+ <QualityTab
+ quality={q}
+ onShow={onShow}
+ onShowPlaceholder={onShowPlaceholder}
+ onPickAuthor={onPickAuthor}
+ />
</NextIntlClientProvider>,
);
});
@@ -194,6 +200,44 @@ describe('QualityTab', () => {
expect(profile.querySelector('a')!.getAttribute('href')).toBe('/dashboard/settings/authors');
});
+ it('lists the placeholders to fill first, with Show (CE-044)', async () => {
+ const author = ada;
+ const score = eeat({ author });
+ await render({
+ ...read(result),
+ todos: qualityTodos({
+ eeat: score,
+ author,
+ hasAuthors: true,
+ placeholders: { count: 1, had: true },
+ }),
+ });
+ const todos = container.querySelector('[aria-label="Your to-dos"]')!;
+ expect(todos.querySelector('h4')!.textContent).toBe(
+ 'Your to-dos 1 left · only you can do these',
+ );
+ const row = todos.querySelector('li')!;
+ expect(row.textContent).toBe(
+ 'Fill 1 placeholder · To doWords in [brackets] stand where a real name, quote or number goes. Put in the real one, or take the sentence outShow',
+ );
+ await act(async () => row.querySelector('button')!.click());
+ expect(onShowPlaceholder).toHaveBeenCalled();
+
+ // Filled: checked, and it stays.
+ await render({
+ ...read(result),
+ todos: qualityTodos({
+ eeat: score,
+ author,
+ hasAuthors: true,
+ placeholders: { count: 0, had: true },
+ }),
+ });
+ const done = container.querySelector('[aria-label="Your to-dos"] li')!;
+ expect(done.textContent).toBe('Fill the placeholders · DoneAll filled in');
+ expect(done.querySelector('button')).toBeNull();
+ });
+
it("says who can complete the profile when the reader can't edit the author", async () => {
await render(read(result, { ...ada, bio: null }, true, false));
const row = [...container.querySelectorAll('li')].find((li) =>
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
index ac5931127..cd66ea2b6 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
@@ -70,11 +70,14 @@ export interface Suggestion {
export function QualityTab({
quality,
onShow,
+ onShowPlaceholder,
onPickAuthor,
}: {
quality: QualityRead;
/** Scrolls the draft to a passage and marks it. */
onShow: (text: string) => void;
+ /** Selects the page's first placeholder, to type over. */
+ onShowPlaceholder: () => void;
/** Opens the header's author menu. */
onPickAuthor: () => void;
}) {
@@ -138,7 +141,13 @@ export function QualityTab({
</h4>
<ul className="space-y-2">
{todos.map((todo) => (
- <TodoRow key={todo.id} todo={todo} quality={quality} onPickAuthor={onPickAuthor} />
+ <TodoRow
+ key={todo.id}
+ todo={todo}
+ quality={quality}
+ onShowPlaceholder={onShowPlaceholder}
+ onPickAuthor={onPickAuthor}
+ />
))}
</ul>
</section>
@@ -215,6 +224,14 @@ export function useTodoCopy() {
todo: QualityTodo,
{ author, brandName, canEdit }: Pick<QualityRead, 'author' | 'brandName' | 'canEdit'>,
) => {
+ if (todo.id === 'placeholders') {
+ const count = todo.count ?? 0;
+ return {
+ title: t('placeholders.title', { count }),
+ next: t('placeholders.next', { count }),
+ detail: todo.done ? t('placeholders.done') : t('placeholders.detail'),
+ };
+ }
if (todo.id === 'byline') {
const action = todo.action === 'addAuthor' ? 'addAuthor' : 'pickAuthor';
return {
@@ -262,10 +279,12 @@ export function useTodoCopy() {
function TodoRow({
todo,
quality,
+ onShowPlaceholder,
onPickAuthor,
}: {
todo: QualityTodo;
quality: QualityRead;
+ onShowPlaceholder: () => void;
onPickAuthor: () => void;
}) {
const t = useTranslations('contentEditor.editor.quality');
@@ -320,7 +339,11 @@ function TodoRow({
</div>
{!todo.done &&
todo.action &&
- (todo.action === 'pickAuthor' ? (
+ (todo.action === 'showPlaceholder' ? (
+ <Button variant="outline" size="sm" className="h-7 shrink-0" onClick={onShowPlaceholder}>
+ {t('show')}
+ </Button>
+ ) : todo.action === 'pickAuthor' ? (
<Button variant="outline" size="sm" className="h-7 shrink-0" onClick={onPickAuthor}>
{t('pickAuthor')}
</Button>
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 1861fb178..4e655a576 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
@@ -121,6 +121,7 @@ export function EditorSidePanel({
quality = null,
qualityScore = null,
onShowInPage,
+ onShowPlaceholder,
onPickAuthor,
}: {
draft: ContentDraft;
@@ -161,6 +162,8 @@ export function EditorSidePanel({
qualityScore?: number | null;
/** Scrolls the draft to a passage and marks it: Quality's Show. */
onShowInPage?: (text: string) => void;
+ /** Selects the page's first placeholder (Quality's to-do, CE-044). */
+ onShowPlaceholder?: () => void;
/** Opens the header's author menu: Quality's Pick author. */
onPickAuthor?: () => void;
}) {
@@ -364,6 +367,7 @@ export function EditorSidePanel({
<QualityTab
quality={quality}
onShow={(text) => onShowInPage?.(text)}
+ onShowPlaceholder={() => onShowPlaceholder?.()}
onPickAuthor={() => onPickAuthor?.()}
/>
</div>
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 5c3b175ea..71a68d1b3 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
@@ -2467,6 +2467,75 @@ describe('the side panel', () => {
expect(document.querySelectorAll('[role="menuitemradio"]').length).toBe(2);
});
+ it("lists the agent's placeholders first in Quality, and Show selects the first (CE-044)", async () => {
+ getContentDraft.mockResolvedValue(
+ draft({
+ authorId: 'a1',
+ bodyHtml:
+ '<h1>Pipeline forecasting</h1><p>Ask [name of a real person] how.</p>' +
+ '<p>Then ask [name of a real person] again.</p>',
+ }),
+ );
+ window.innerWidth = 1440;
+ await renderPage();
+ await act(async () =>
+ [...container.querySelectorAll<HTMLButtonElement>('header button')]
+ .find((b) => b.textContent?.startsWith('Quality'))!
+ .click(),
+ );
+ const todos = panel()!.querySelector('[aria-label="Your to-dos"]')!;
+ const first = todos.querySelector('li')!;
+ expect(first.textContent).toContain('Fill 2 placeholders');
+ await act(async () => first.querySelector('button')!.click());
+ const editor = (container.querySelector('.ProseMirror') as HTMLElement & { editor: Editor })
+ .editor;
+ const { from, to } = editor.state.selection;
+ // The first one, selected to type over.
+ expect(editor.state.doc.textBetween(from, to)).toBe('[name of a real person]');
+ expect(editor.state.doc.textBetween(0, from)).toContain('Ask ');
+ expect(editor.state.doc.textBetween(0, from)).not.toContain('Then');
+ });
+
+ it('names the placeholders Accept all brought in, once the page is read again', async () => {
+ getContentDraft.mockResolvedValue(
+ draft({
+ authorId: 'a1',
+ bodyHtml: '<h1>Pipeline forecasting</h1><p>We delve into how teams forecast.</p>',
+ }),
+ );
+ getContentAuthors.mockResolvedValue({
+ authors: [{ ...ada, bio: 'Writes about forecasting.', sameAs: ['https://x.com/ada'] }],
+ brands: [{ id: 'b1', name: 'Acme' }],
+ me: { id: 'u1', role: 'analyst' },
+ });
+ getDraftSuggestions.mockResolvedValue([
+ {
+ id: 'n1',
+ batchId: 'b2',
+ actionId: null,
+ actionNo: null,
+ kind: 'replace',
+ blockText: 'We delve into how teams forecast.',
+ beforeText: 'delve into',
+ afterText: 'asked [name of a real person] about',
+ reason: 'remove an AI trace (rule)',
+ ruleKeys: ['aiTraces'],
+ status: 'open',
+ },
+ ]);
+ await renderPage();
+ await act(async () =>
+ [...container.querySelectorAll<HTMLButtonElement>('button')]
+ .find((b) => b.textContent === 'Accept all')!
+ .click(),
+ );
+ await act(async () => {});
+ // Not before the page is read again.
+ expect(nudge()).toBeNull();
+ await act(async () => new Promise((resolve) => setTimeout(resolve, 600)));
+ expect(nudge()!.textContent).toBe('Next for you: fill 1 placeholder · 1 of 1Show nowLater');
+ });
+
it('stays away when the agent was stopped from the wait screen', async () => {
getContentDraft.mockResolvedValue(
draft({ status: 'draft', agentState: 'writing', agentSince: new Date().toISOString() }),
@@ -2630,6 +2699,8 @@ describe('the side panel', () => {
)!;
await act(async () => accept.click());
await act(async () => {});
+ // Once the page is read again after the accept (CE-044).
+ await act(async () => new Promise((resolve) => setTimeout(resolve, 600)));
expect(nudge()!.textContent).toContain(
"Next for you: complete Ada Lovelace's profile · 1 of 1",
);
diff --git a/web/src/lib/content/page-schema.ts b/web/src/lib/content/page-schema.ts
index 9245cb44c..7fe0f8b8b 100644
--- a/web/src/lib/content/page-schema.ts
+++ b/web/src/lib/content/page-schema.ts
@@ -1,5 +1,6 @@
import type { ContentAuthor } from './authors';
import type { PageType } from './drafts';
+import { PLACEHOLDER } from './placeholders';
/**
* The page's JSON-LD for Before you publish (Content Editor Quality spec §7,
@@ -29,16 +30,11 @@ export const ARTICLE_PAGE_TYPES: readonly PageType[] = [
export const isArticlePage = (type: string | null) =>
type === null || (ARTICLE_PAGE_TYPES as readonly string[]).includes(type);
-/**
- * Words in square brackets where a real name, quote or number goes ("[figure,
- * source]"): a placeholder the Content Agent left for the person to fill, as
- * the editor's placeholder to-do reads it (CE-044). Not a footnote ("[1]"),
- * a checkbox ("[x]"), "[sic]" or a Markdown link's text.
- */
-const PLACEHOLDER = /\[(?!sic\])(?=[^[\]\n]*\p{L})[^[\]\n]{2,}\](?!\()/iu;
+/** One placeholder (placeholders.ts's, without its global flag: a test keeps no state). */
+const ONE_PLACEHOLDER = new RegExp(PLACEHOLDER.source, 'iu');
/** Whether the title still has a placeholder: it would ship as the headline. */
-export const titleHasPlaceholder = (title: string) => PLACEHOLDER.test(title);
+export const titleHasPlaceholder = (title: string) => ONE_PLACEHOLDER.test(title);
/** The page's first image with a full https address, as JSON-LD's image. */
export function firstImage(html: string): string | null {
diff --git a/web/src/lib/content/placeholders.test.ts b/web/src/lib/content/placeholders.test.ts
new file mode 100644
index 000000000..89d01f0b5
--- /dev/null
+++ b/web/src/lib/content/placeholders.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { pagePlaceholders } from './placeholders';
+
+/** Placeholders in a page (Quality spec §4, CE-044): counted for the person to fill. */
+
+describe('pagePlaceholders', () => {
+ it('counts each placeholder once, in the lines the editor keeps text in', () => {
+ expect(
+ pagePlaceholders(
+ '<h1>Pour-over</h1>' +
+ '<h2>What [name of a real person] uses</h2>' +
+ '<p>Use [figure, source] g of coffee and [figure, source] of water.</p>' +
+ '<ul><li><p>Ask [name of a real person]</p><ul><li><p>Then [time]</p></li></ul></li></ul>' +
+ '<ul><li><blockquote><p>[quote from a real person, with its source]</p></blockquote></li></ul>' +
+ '<table><tbody><tr><td><ul><li><p>[price]</p></li></ul></td></tr></tbody></table>',
+ ),
+ ).toEqual({ count: 7 });
+ });
+
+ it('reads none in footnotes, checkboxes, [sic], Markdown links or a page without them', () => {
+ expect(
+ pagePlaceholders(
+ '<p>See note [1] and [2].</p><p>[x] Done, [ ] to do.</p>' +
+ '<p>He wrote "teh" [sic].</p><p>Read [the docs](https://acme.com/docs).</p>',
+ ),
+ ).toEqual({ count: 0 });
+ expect(pagePlaceholders('')).toEqual({ count: 0 });
+ });
+});
diff --git a/web/src/lib/content/placeholders.ts b/web/src/lib/content/placeholders.ts
new file mode 100644
index 000000000..60bd9cd31
--- /dev/null
+++ b/web/src/lib/content/placeholders.ts
@@ -0,0 +1,32 @@
+/**
+ * Placeholders in a page (Content Editor Quality spec §4, §9, CE-044): words
+ * in square brackets where a real name, quote or number goes — what the
+ * Content Agent leaves when it had none ("[figure, source]", "[name of a
+ * real person]") — for the person to fill. Only they can: a to-do in
+ * Quality. An export never ships one (CE-057).
+ */
+
+/**
+ * Words in square brackets with a letter and more than one character in
+ * them; not a footnote ("[1]"), a checkbox ("[x]"), "[sic]", or a Markdown
+ * link's text ("[docs](https://…)").
+ */
+export const PLACEHOLDER = /\[(?!sic\])(?=[^[\]\n]*\p{L})[^[\]\n]{2,}\](?!\()/giu;
+
+export interface PagePlaceholders {
+ count: number;
+}
+
+/**
+ * The page's placeholders. The editor keeps every line of text in a
+ * paragraph or a heading (in lists, quotes and tables too), so each is read
+ * once there.
+ */
+export function pagePlaceholders(html: string): PagePlaceholders {
+ const doc = new DOMParser().parseFromString(html, 'text/html');
+ let count = 0;
+ for (const el of doc.body.querySelectorAll('p, h1, h2, h3, h4, h5, h6')) {
+ count += (el.textContent ?? '').match(PLACEHOLDER)?.length ?? 0;
+ }
+ return { count };
+}
diff --git a/web/src/lib/content/quality-todos.test.ts b/web/src/lib/content/quality-todos.test.ts
index 683240855..51aca5c67 100644
--- a/web/src/lib/content/quality-todos.test.ts
+++ b/web/src/lib/content/quality-todos.test.ts
@@ -68,4 +68,52 @@ describe('qualityTodos', () => {
it('has none before E-E-A-T is read', () => {
expect(qualityTodos({ eeat: null, author: null, hasAuthors: true })).toEqual([]);
});
+
+ it('asks to fill the placeholders first, and keeps it checked once filled (CE-044)', () => {
+ const fill = (count: number) => ({
+ id: 'placeholders',
+ done: count === 0,
+ gain: 0,
+ action: 'showPlaceholder',
+ count,
+ });
+ expect(
+ qualityTodos({
+ eeat: eeat({ author: null }),
+ author: null,
+ hasAuthors: true,
+ placeholders: { count: 2, had: true },
+ }),
+ ).toEqual([
+ fill(2),
+ expect.objectContaining({ id: 'byline' }),
+ expect.objectContaining({ id: 'authorProfile' }),
+ ]);
+ // Before the authors are read, the placeholders still are.
+ expect(
+ qualityTodos({
+ eeat: null,
+ author: null,
+ hasAuthors: true,
+ placeholders: { count: 2, had: true },
+ }),
+ ).toEqual([fill(2)]);
+ expect(
+ qualityTodos({
+ eeat: null,
+ author: null,
+ hasAuthors: true,
+ placeholders: { count: 0, had: true },
+ }),
+ ).toEqual([fill(0)]);
+ // A page that never had any: no row.
+ expect(
+ qualityTodos({
+ eeat: null,
+ author: null,
+ hasAuthors: true,
+ placeholders: { count: 0, had: false },
+ }),
+ ).toEqual([]);
+ });
});
diff --git a/web/src/lib/content/quality-todos.ts b/web/src/lib/content/quality-todos.ts
index 0785db07b..a207711cf 100644
--- a/web/src/lib/content/quality-todos.ts
+++ b/web/src/lib/content/quality-todos.ts
@@ -5,38 +5,49 @@ import { authorProfile, scoreGain, type EeatCheckId, type Score } from './qualit
* Your to-dos (Content Editor Quality spec §4, CE-040): what only the person
* can do for the page, read from the check results (nothing entered by
* hand). Everything else is a suggestion the agent can fix. Phase 1's are
- * the author's: the Content Agent can't add, pick or edit authors.
+ * the placeholders the agent left where it had no real name, quote or
+ * number (CE-044), and the author's: the Content Agent can't add, pick or
+ * edit authors.
*/
-export type QualityTodoId = 'byline' | 'authorProfile';
+export type QualityTodoId = 'placeholders' | 'byline' | 'authorProfile';
-/** A to-do's one button: the header's author menu, or Settings › Authors. */
-export type QualityTodoAction = 'pickAuthor' | 'addAuthor' | 'editAuthor';
+/**
+ * A to-do's one button: Show (the first placeholder, selected to type over),
+ * the header's author menu, or Settings › Authors.
+ */
+export type QualityTodoAction = 'showPlaceholder' | 'pickAuthor' | 'addAuthor' | 'editAuthor';
export interface QualityTodo {
id: QualityTodoId;
done: boolean;
- /** What E-E-A-T gains once it is done; 0 when done. */
+ /** What E-E-A-T gains once it is done; 0 when done, or when no score counts it. */
gain: number;
/** None while it waits on the one before it. */
action: QualityTodoAction | null;
+ /** How many it is about (placeholders). */
+ count?: number;
}
/**
- * The page's to-dos, in the order to do them: pick its author (or add one
- * when the workspace has none), then complete their profile, listed from the
- * start so the count holds. Done ones stay on the list, checked. None until
- * E-E-A-T is read.
+ * The page's to-dos, in the order to do them: fill the placeholders (an
+ * export never ships one), pick its author (or add one when the workspace
+ * has none), then complete their profile, listed from the start so the
+ * count holds. Done ones stay on the list, checked; placeholders are listed
+ * once the page has had some (`had`, this session). The author's wait for
+ * E-E-A-T to be read.
*/
export function qualityTodos({
eeat,
author,
hasAuthors,
+ placeholders = { count: 0, had: false },
canEdit = false,
}: {
eeat: Score<EeatCheckId> | null;
author: ContentAuthor | null;
hasAuthors: boolean;
+ placeholders?: { count: number; had: boolean };
/**
* Whether the member may edit the page's author (whoever added them, the
* author themself or an admin): only they get Edit author; anyone else is
@@ -44,7 +55,19 @@ export function qualityTodos({
*/
canEdit?: boolean;
}): QualityTodo[] {
- if (!eeat || eeat.score === null) return [];
+ const fill: QualityTodo[] =
+ placeholders.count || placeholders.had
+ ? [
+ {
+ id: 'placeholders',
+ done: placeholders.count === 0,
+ gain: 0,
+ action: 'showPlaceholder',
+ count: placeholders.count,
+ },
+ ]
+ : [];
+ if (!eeat || eeat.score === null) return fill;
const byline: QualityTodo = {
id: 'byline',
done: !!author,
@@ -53,6 +76,7 @@ export function qualityTodos({
};
const { bio, links } = authorProfile(author);
return [
+ ...fill,
byline,
{
id: 'authorProfile',