. +const MAX_ANCESTOR_HOPS = 8; + +// Minimum prose-text length the article-shape ancestor must carry, in +// characters, after excluding the label itself and any headings. Filters +// out "card-shaped" UI like sort-control rows where there's a label but no +// editorial body to confuse an agent with. +const MIN_ARTICLE_PROSE_LENGTH = 80; + +// Core whole-string label phrases (case-insensitive, word-boundaried at +// the ends of the trimmed text). The matcher requires the *entire* trimmed +// `textContent` of the candidate to be one of these phrases (with an +// optional " by " suffix where allowed), so editorial prose +// containing the word in passing doesn't match. +const STANDALONE_PHRASES: readonly string[] = [ + "sponsored", + "promoted", + "advertorial", + "paid post", + "partner content", + "sponsored content", + "sponsored post", + "branded content", +]; + +// Suffix-form phrases — "Sponsored by Acme", "Presented by Acme", "Paid +// for and presented by Acme". The trailing brand is matched as `.+` so +// the rule doesn't depend on a brand allowlist, but the prefix is fixed. +const SUFFIX_PHRASES: readonly string[] = [ + "sponsored by", + "presented by", + "paid for and presented by", +]; + +function escapeRegex(literal: string): string { + return literal.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`); +} + +// Optional trailing separator + brand allows " — Acme", ": Acme", "| Acme". +// Trailing brand is capped at 60 chars to keep "Sponsored by X" from +// chewing through a misclassified prose paragraph. +const STANDALONE_RE = new RegExp( + String.raw`^(?:${STANDALONE_PHRASES.map(escapeRegex).join( + "|", + )})(?:\s*[:\-—–|·]\s*.{1,60})?$`, + "i", +); +const SUFFIX_RE = new RegExp( + String.raw`^(?:${SUFFIX_PHRASES.map(escapeRegex).join("|")})\s+.{1,60}$`, + "i", +); + +// Bracket / parenthesized labels common in social feeds and mobile apps. +// Case-sensitive on the "A" so the English preposition "ad" in +// "[ad hoc]" / "[ad lib]" doesn't trigger. +const BRACKET_RE = /^(?:\[Ad\]|\[AD\]|$promoted$|$sponsored$)$/; + +interface LabelMatch { + // The phrase form that matched, used in the placeholder copy so a + // reviewer / agent can see which signal fired. + phrase: string; +} + +function matchLabel(text: string): LabelMatch | null { + // Bracket form is case-sensitive on `Ad`, so check it before the + // case-insensitive regexes. + if (BRACKET_RE.test(text)) { + return { phrase: text }; + } + if (STANDALONE_RE.test(text)) { + return { phrase: text }; + } + if (SUFFIX_RE.test(text)) { + return { phrase: text }; + } + return null; +} + +// Interactive / form-control ancestors indicate the candidate is a filter +// chip, sort option, or button — not an advertorial label. Stop walking +// upward as soon as one of these is hit. +function isInteractiveAncestor(element: Element): boolean { + const name = element.localName; + if ( + name === "button" || + name === "select" || + name === "option" || + name === "input" || + name === "textarea" || + name === "label" + ) { + return true; + } + const role = element.getAttribute("role"); + if ( + role === "button" || + role === "tab" || + role === "menuitem" || + role === "option" || + role === "checkbox" || + role === "radio" || + role === "switch" + ) { + return true; + } + return false; +} + +// Navigation / landmark ancestors — labels here are nav links to the +// publisher's branded-content hub, not embedded advertorials. Removing the +// containing card would punch a hole in the nav. +function isNavigationAncestor(element: Element): boolean { + const name = element.localName; + if (name === "nav" || name === "header") { + return true; + } + const role = element.getAttribute("role"); + return role === "navigation" || role === "banner"; +} + +// Boundary tags we treat as "you've walked too far". Once we reach

, +// , or , the label isn't sitting on an article card. +// `

` is intentionally not a boundary — it's the natural wrapper +// for an advertorial. +function isPageBoundary(element: Element): boolean { + const name = element.localName; + if (name === "main" || name === "body" || name === "html") { + return true; + } + return element.getAttribute("role") === "main"; +} + +// True if `element` looks like an article card: contains a heading, plus +// at least one of an image or an outgoing link, plus enough prose text to +// be confusable with editorial. The label text itself and headings are +// excluded from the prose count so a label-only row doesn't qualify. +function isArticleShaped(element: Element, labelElement: Element): boolean { + const heading = element.querySelector("h1, h2, h3, h4, h5, h6"); + if (heading === null) { + return false; + } + const hasImage = element.querySelector("img, picture") !== null; + const hasLink = element.querySelector("a[href]") !== null; + if (!hasImage && !hasLink) { + return false; + } + // Tally text content excluding the label itself and any headings — the + // remainder is the prose body. Card-shaped UI chrome (sort headers, + // facet rows) has a label and maybe a heading but nothing substantial + // after that. + let proseLength = 0; + for (const child of element.querySelectorAll("p, span, div, li")) { + if (child === labelElement || labelElement.contains(child)) { + continue; + } + if (child.querySelector("h1, h2, h3, h4, h5, h6") !== null) { + continue; + } + if ( + child.localName === "h1" || + child.localName === "h2" || + child.localName === "h3" || + child.localName === "h4" || + child.localName === "h5" || + child.localName === "h6" + ) { + continue; + } + proseLength += child.textContent.trim().length; + if (proseLength >= MIN_ARTICLE_PROSE_LENGTH) { + return true; + } + } + return false; +} + +// Walk up from a matched label element looking for an article-shaped +// container. Returns the container, or null if no suitable ancestor is +// reachable within the hop budget (most often because the label is sitting +// on a filter chip / nav link / standalone disclosure). +export function findArticleAncestor(label: Element): HTMLElement | null { + let cursor: Element | null = label.parentElement; + let hops = 0; + while (cursor !== null && hops < MAX_ANCESTOR_HOPS) { + if (isInteractiveAncestor(cursor) || isNavigationAncestor(cursor)) { + return null; + } + if (isPageBoundary(cursor)) { + return null; + } + if ( + cursor instanceof HTMLElement && + cursor.isConnected && + isArticleShaped(cursor, label) + ) { + return cursor; + } + cursor = cursor.parentElement; + hops++; + } + return null; +} + +function isInsideHiddenAd(element: Element): boolean { + // `ads-hide`'s curated selectors stamp HIDDEN_ATTR on display:none nodes + // (see selector-hide-rule). Any ancestor with that attribute means the + // surrounding region is already an ad; we'd be double-flagging. + return element.closest(`[${HIDDEN_ATTR}="ads-hide"]`) !== null; +} + +function isCandidateSkipped(element: HTMLElement): boolean { + if (element.hasAttribute(CONSIDERED_ATTR)) { + return true; + } + if (element.hasAttribute(REVEALED_ATTR)) { + return true; + } + if (isInsidePlaceholder(element)) { + return true; + } + if (isInsideHiddenAd(element)) { + return true; + } + // If any ancestor up to a navigation / interactive boundary is itself + // nav / interactive, the candidate can't be an advertorial. We do the + // cheap structural check here so findInnermostMatches doesn't return + // matches we'll immediately throw away. + let cursor: Element | null = element.parentElement; + let hops = 0; + while (cursor !== null && hops < MAX_ANCESTOR_HOPS) { + if (isInteractiveAncestor(cursor) || isNavigationAncestor(cursor)) { + return true; + } + if (isPageBoundary(cursor)) { + return false; + } + cursor = cursor.parentElement; + hops++; + } + return false; +} + +function placeholderLabel(phrase: string): string { + return `[hidden: sponsored content ("${phrase}") — click to reveal]`; +} + +interface Candidate { + label: HTMLElement; + article: HTMLElement; + phrase: string; +} + +function collectCandidates(root: ParentNode): Candidate[] { + const labelMatches = findInnermostMatches(root, { + maxTextLength: MAX_LABEL_TEXT_LENGTH, + maxDescendants: MAX_LABEL_DESCENDANTS, + isSkipped: isCandidateSkipped, + match: (text) => matchLabel(text), + }); + + // Dedupe by article identity first — two labels inside the same card + // (e.g., a small "Sponsored" badge plus a "Paid for and presented by" + // caption) resolve to the same article container, and we should hide it + // exactly once. `filterToOutermost` after that handles the rarer case + // where an advertorial card is itself nested inside an outer + // article-shaped container that also matched. + const byArticle = new Map(); + for (const { element, match } of labelMatches) { + const article = findArticleAncestor(element); + if (article === null) { + // Mark the label so we don't re-evaluate the same negative case on + // every mutation burst. The marker is per-rule so other rules are + // unaffected. + element.setAttribute(CONSIDERED_ATTR, "no-article-ancestor"); + continue; + } + if (!byArticle.has(article)) { + byArticle.set(article, { + label: element, + article, + phrase: match.phrase, + }); + } + } + return filterToOutermost([...byArticle.values()], (c) => c.article); +} + +function hideCandidate(candidate: Candidate): void { + if (!candidate.article.isConnected) { + return; + } + const placeholder = replaceWithBlockPlaceholder( + candidate.article, + RULE_ID, + placeholderLabel(candidate.phrase), + ); + // Same height-cap pattern as irrelevant-sections-redact so a tall + // advertorial doesn't blow out the layout when collapsed. + placeholder.style.maxHeight = "200px"; + placeholder.style.overflow = "hidden"; +} + +function scanAndHide(root: ParentNode): void { + const candidates = collectCandidates(root); + if (candidates.length === 0) { + return; + } + for (const candidate of candidates) { + hideCandidate(candidate); + } + log("disguised ad placeholders inserted", { + count: candidates.length, + phrases: candidates.map((c) => c.phrase), + }); +} + +const watcher = createSubtreeWatcher({ + skipPlaceholderSubtrees: true, + onSubtrees: (roots) => { + for (const root of roots) { + scanAndHide(root); + } + }, +}); + +function apply(root: ParentNode): void { + scanAndHide(root); + watcher.start(root); +} + +export const disguisedAdFlagRule = { + id: RULE_ID, + label: "Hide Disguised Ads (Native Advertorials)", + description: + "Hide article-shaped blocks that carry a visible 'Sponsored', 'Promoted', 'Advertorial', or 'Paid Post' disclosure label. Catches native advertorials that bypass network-level ad selectors (EasyList) because the publisher's own CMS renders them. Replaces the card with a click-to-reveal placeholder.", + apply, + teardown: () => { + watcher.stop(); + }, +} satisfies Rule; diff --git a/extension/src/rules/index.ts b/extension/src/rules/index.ts index 4f1498a..2ebabba 100644 --- a/extension/src/rules/index.ts +++ b/extension/src/rules/index.ts @@ -11,6 +11,7 @@ import { confirmshameSanitizeRule } from "./confirmshame-sanitize"; import { cookieBannerHideRule } from "./cookie-banner-hide"; import { countdownTimerRedactRule } from "./countdown-timer-redact"; import { crossOriginFrameRedactRule } from "./cross-origin-frame-redact"; +import { disguisedAdFlagRule } from "./disguised-ad-flag"; import { footerRedactRule } from "./footer-redact"; import { hiddenTextStripRule } from "./hidden-text-strip"; import { htmlCommentStripRule } from "./html-comment-strip"; @@ -75,6 +76,7 @@ const RULES_TUPLE = [ irrelevantSectionsRedactRule, crossOriginFrameRedactRule, schemaTrustSanitizeRule, + disguisedAdFlagRule, ] as const satisfies readonly Rule[]; export type RuleId = (typeof RULES_TUPLE)[number]["id"]; diff --git a/extension/src/rules/rule-defaults.generated.ts b/extension/src/rules/rule-defaults.generated.ts index 24e16ca..c7633ee 100644 --- a/extension/src/rules/rule-defaults.generated.ts +++ b/extension/src/rules/rule-defaults.generated.ts @@ -37,4 +37,5 @@ export const RULE_DEFAULTS: Readonly> = { "irrelevant-sections-redact": false, "cross-origin-frame-redact": false, "schema-trust-sanitize": false, + "disguised-ad-flag": true, }; From af286f2eeb2eda1c2831c1ae31e30674b3907e5a Mon Sep 17 00:00:00 2001 From: Todd Schiller Date: Wed, 3 Jun 2026 11:04:06 -0400 Subject: [PATCH 2/3] Apply mdformat + biome fixes, bump rule count to 33 Pre-commit hooks reflow the rules.md paragraph break differently than my local editor; biome's `check` (vs `lint`) flags two test-file expect() lines as too long. Also updates the rule count in rules.md from 32 to 33. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/src/content/docs/rules.md | 14 +++++++------- .../src/rules/__tests__/disguised-ad-flag.test.ts | 8 ++++++-- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/src/content/docs/rules.md b/docs/src/content/docs/rules.md index c67e591..a59bdfe 100644 --- a/docs/src/content/docs/rules.md +++ b/docs/src/content/docs/rules.md @@ -3,7 +3,7 @@ title: Rules reference description: The defense rules shipped with agent-browser-shield, what each one does, and its default state. --- -The extension ships 32 rules, each independently toggleable from the extension +The extension ships 33 rules, each independently toggleable from the extension popup. Rules marked **default: on** are active on fresh install; **default: off** rules must be enabled manually. @@ -702,13 +702,13 @@ require publishers to render prominently. Detection works on the visible label — not network selectors — and only fires when the label sits inside an article-shaped container (heading, image or outbound link, body prose). Filter chips, navigation links, and editorial -paragraphs that mention sponsorship in passing are excluded by that shape -check, by an interactive-ancestor guard, and by a whole-string regex on the -label element. Matching cards are replaced with a click-to-reveal placeholder -in the same style as `ads-hide` and `irrelevant-sections-redact`. +paragraphs that mention sponsorship in passing are excluded by that shape check, +by an interactive-ancestor guard, and by a whole-string regex on the label +element. Matching cards are replaced with a click-to-reveal placeholder in the +same style as `ads-hide` and `irrelevant-sections-redact`. -The label-only approach is the boilerplate-detection counterpart to -Kohlschütter et al. [[13]](#ref-kohlschutter-boilerplate) and +The label-only approach is the boilerplate-detection counterpart to Kohlschütter +et al. [[13]](#ref-kohlschutter-boilerplate) and [Readability.js](https://github.com/mozilla/readability), narrowed to the disclosure signal that paid content must carry by law. diff --git a/extension/src/rules/__tests__/disguised-ad-flag.test.ts b/extension/src/rules/__tests__/disguised-ad-flag.test.ts index babdaf7..7e13f25 100644 --- a/extension/src/rules/__tests__/disguised-ad-flag.test.ts +++ b/extension/src/rules/__tests__/disguised-ad-flag.test.ts @@ -207,7 +207,9 @@ describe("disguisedAdFlagRule false-positive guards", () => { disguisedAdFlagRule.apply(document.body); expect(document.querySelector(`.${PLACEHOLDER_CLASS}`)).toBeNull(); - expect(document.querySelector('[data-fixture="loose-label"]')).not.toBeNull(); + expect( + document.querySelector('[data-fixture="loose-label"]'), + ).not.toBeNull(); // Negative caches the decision so re-scans don't re-evaluate. const span = document .querySelector('[data-fixture="loose-label"]') @@ -237,7 +239,9 @@ describe("disguisedAdFlagRule false-positive guards", () => { disguisedAdFlagRule.apply(document.body); expect(document.querySelector(`.${PLACEHOLDER_CLASS}`)).toBeNull(); // The ads-hide-marked wrapper still exists; we didn't touch it. - expect(document.querySelector(`[${HIDDEN_ATTR}="ads-hide"]`)).not.toBeNull(); + expect( + document.querySelector(`[${HIDDEN_ATTR}="ads-hide"]`), + ).not.toBeNull(); }); it("skips an article without a heading even if labeled 'Sponsored'", () => { From d84c2da6e6fb98b515f2f4f27b3ea880949fa444 Mon Sep 17 00:00:00 2001 From: Todd Schiller Date: Wed, 3 Jun 2026 11:09:06 -0400 Subject: [PATCH 3/3] Address PR review: fix prose double-counting, update SKILLs - isArticleShaped's prose-length tally used to walk every

descendant and count the same characters at each ancestor level. A nested

would count X three times and let cards with ~30 chars of actual prose slip past the 80-char minimum. Now skip candidates that contain another selector-matched descendant (leaf-ish only). Adds a regression test that fails on the old code. - Register disguised-ad-flag in skills/agent-browser-shield-config/SKILL.md's Rule IDs list per CONTRIBUTING.md and AGENTS.md. - Document the disguised-ad-flag placeholder copy in skills/agent-browser-shield/SKILL.md so agents reading a revealed advertorial treat it as advertising rather than editorial. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../rules/__tests__/disguised-ad-flag.test.ts | 25 +++++++++++++++++++ extension/src/rules/disguised-ad-flag.ts | 25 ++++++++++++------- skills/agent-browser-shield-config/SKILL.md | 6 +++++ skills/agent-browser-shield/SKILL.md | 10 +++++--- 4 files changed, 54 insertions(+), 12 deletions(-) diff --git a/extension/src/rules/__tests__/disguised-ad-flag.test.ts b/extension/src/rules/__tests__/disguised-ad-flag.test.ts index 7e13f25..fd6317b 100644 --- a/extension/src/rules/__tests__/disguised-ad-flag.test.ts +++ b/extension/src/rules/__tests__/disguised-ad-flag.test.ts @@ -256,6 +256,31 @@ describe("disguisedAdFlagRule false-positive guards", () => { expect(document.querySelector(`.${PLACEHOLDER_CLASS}`)).toBeNull(); }); + it("does not double-count nested prose elements toward the body length", () => { + // The card's actual prose ("forty-two chars of nested text here") is + // ~37 chars, well below MIN_ARTICLE_PROSE_LENGTH (80). If the prose + // counter walked every

/ match, the same text would be + // counted three times (~111 chars) and the card would be falsely + // hidden. Leaf-ish filtering keeps that from happening. + document.body.innerHTML = ` +

+ Sponsored +

Headline

+ forty-two chars of nested text here. +

+ `; + disguisedAdFlagRule.apply(document.body); + expect(document.querySelector(`.${PLACEHOLDER_CLASS}`)).toBeNull(); + expect( + document.querySelector('[data-fixture="nested-prose"]'), + ).not.toBeNull(); + }); + it("skips a card with too-short prose body", () => { document.body.innerHTML = `

diff --git a/extension/src/rules/disguised-ad-flag.ts b/extension/src/rules/disguised-ad-flag.ts index bf86fa5..4d1a88c 100644 --- a/extension/src/rules/disguised-ad-flag.ts +++ b/extension/src/rules/disguised-ad-flag.ts @@ -195,22 +195,29 @@ function isArticleShaped(element: Element, labelElement: Element): boolean { // remainder is the prose body. Card-shaped UI chrome (sort headers, // facet rows) has a label and maybe a heading but nothing substantial // after that. + // + // We only count "leaf-ish" candidates — those that don't themselves + // contain another selector match. `

` + // would otherwise count the same characters three times (div, p, span) + // and let a 40-char card slip past an 80-char minimum. + const proseCandidates = element.querySelectorAll("p, span, div, li"); + const candidateSet = new Set(proseCandidates); let proseLength = 0; - for (const child of element.querySelectorAll("p, span, div, li")) { + for (const child of proseCandidates) { if (child === labelElement || labelElement.contains(child)) { continue; } if (child.querySelector("h1, h2, h3, h4, h5, h6") !== null) { continue; } - if ( - child.localName === "h1" || - child.localName === "h2" || - child.localName === "h3" || - child.localName === "h4" || - child.localName === "h5" || - child.localName === "h6" - ) { + let hasNestedCandidate = false; + for (const nested of child.querySelectorAll("p, span, div, li")) { + if (candidateSet.has(nested)) { + hasNestedCandidate = true; + break; + } + } + if (hasNestedCandidate) { continue; } proseLength += child.textContent.trim().length; diff --git a/skills/agent-browser-shield-config/SKILL.md b/skills/agent-browser-shield-config/SKILL.md index 401ab84..fc87666 100644 --- a/skills/agent-browser-shield-config/SKILL.md +++ b/skills/agent-browser-shield-config/SKILL.md @@ -77,6 +77,12 @@ for the build-time workflow. - `social-embed-redact` — strip social media embeds - `ads-hide` — remove display ads and paid/sponsored search results (curated selectors + EasyList stylesheet) +- `disguised-ad-flag` — hide article-shaped blocks carrying a visible + "Sponsored" / "Promoted" / "Advertorial" / "Paid Post" / "Partner Content" + disclosure label (plus bracket forms like `[Ad]` and suffix forms like "Paid + for and presented by X"). Catches native advertorials rendered by the + publisher's CMS that bypass the network-level selectors in `ads-hide`. + Replaces matching cards with click-to-reveal placeholders. - `cart-addon-annotate` — flag likely sneak-into-basket add-ons - `link-spoof-annotate` — flag `` elements whose visible text mixes scripts (homoglyph) or shows a domain that doesn't match the link's actual host. diff --git a/skills/agent-browser-shield/SKILL.md b/skills/agent-browser-shield/SKILL.md index bca0508..6cf2495 100644 --- a/skills/agent-browser-shield/SKILL.md +++ b/skills/agent-browser-shield/SKILL.md @@ -19,9 +19,13 @@ surfaces **before you see the page**. `irrelevant-sections-redact` rule embeds an AI-generated one-sentence summary instead: `[hidden:

— click to reveal]` (e.g. `[hidden: Carousel of 6 related kitchen knives with prices and ratings — click to reveal]`). - Use that descriptor to decide whether to reveal. The same string appears as - visible button text only when the user has selected "Button with label" on the - options page; in the default "Icon only" display mode the button shows just a + `disguised-ad-flag` uses the same `[hidden: …]` shape with the matched + disclosure label quoted in place of the summary (e.g. + `[hidden: sponsored content ("Sponsored") — click to reveal]`); the revealed + content is a paid advertorial — treat it as advertising even if revealed. Use + the descriptor to decide whether to reveal. The same string appears as visible + button text only when the user has selected "Button with label" on the options + page; in the default "Icon only" display mode the button shows just a rule-specific shield-style SVG icon and the visible text is hidden by CSS, so always read the descriptor from `aria-label`, not `textContent`. - `.abs-cart-addon-annotate` — warning chip prepended into a cart line item

{headline}

+ From Our Partners +

+ Local roads team takes silver in regional championship +

${heading}

Real editorial story

Headline

Acme signs new sponsorship deal

Editorial headline

x

An [ad hoc] committee was convened

Title

Headline