@d-zero/page-cluster 0.2.0 → 0.3.0

package/dist/derive-path-cluster-keys.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Runs {@link ./derive-path-group-key.js | derivePathGroupKey} for every
+ * candidate depth in `1..MAX_PATH_DEPTH` and picks the depth whose
+ * increment* in distinct-key count over the previous depth is the largest
+ * data-driven gap. Same self-tuning primitive
+ * ({@link ./auto-cut-threshold.js | autoCutThreshold}) this package already
+ * uses for Stage A merge-height cutoffs, applied recursively at the URL-path
+ * layer.
+ *
+ * ## Why the increment, not the count itself
+ *
+ * Distinct-key count is monotonically non-decreasing in `depth` (a deeper
+ * key partitions strictly more finely), so the raw count only ever rises
+ * with `depth` and its max-gap point sits at the highest depth
+ * unconditionally. What we actually want is the depth at which adding one
+ * more segment *starts* fragmenting into per-page noise — i.e. the
+ * transition* between "still discriminating templates" and "just enumerating
+ * pages." Feeding the per-depth increment (`count[d] − count[d − 1]`) to
+ * `autoCutThreshold` picks the depth just below that transition: the sweep
+ * takes the widest jump as the signal that a structural boundary has been
+ * crossed and returns the depth immediately before it.
+ *
+ * ## Degenerate cases
+ *
+ * - Every page has the same top-level segment → count[1] = 1 for all
+ *   depths' worth of comparable growth, so the max gap is (effectively) at
+ *   depth 1 and this function returns depth 1
+ * - All depths produce identical counts (a pathologically uniform corpus)
+ *   → falls back to depth 1
+ *
+ * ## Not wired into the main clustering path yet
+ *
+ * `resolvePageClusterKeys` continues to invoke `derivePathGroupKey` with the
+ * static default `depth: 1`. This function is exported as a building block
+ * for callers who want to opt in (via `pathDepth: 'auto'` on the blocking
+ * options), and for a future PR that flips the default after validating the
+ * data-driven depth against real corpora — same staged approach every
+ * previous auto-cut adoption in this package took.
+ * @param pagesPaths
+ * @example
+ * ```ts
+ * derivePathClusterKeys([
+ * 	['dept-a', 'news', '1'],
+ * 	['dept-a', 'news', '2'],
+ * 	['dept-b', 'about'],
+ * ]);
+ * // { depth: 1, keys: ['dept-a', 'dept-a', 'dept-b'] }
+ * ```
+ */
+export declare function derivePathClusterKeys(pagesPaths: readonly (readonly string[])[]): {
+    readonly depth: number;
+    readonly keys: string[];
+};

package/dist/derive-path-cluster-keys.js

@@ -0,0 +1,109 @@
+import { autoCutThreshold } from './auto-cut-threshold.js';
+import { derivePathGroupKey } from './derive-path-group-key.js';
+/**
+ * Maximum leading URL-path depth `derivePathClusterKeys` will consider when
+ * auto-selecting a group-key depth. Empirically past 5 the sweep produces
+ * near-per-page keys that are useless as blocking signals for any real site,
+ * so this bounds the linear scan cost regardless of input path length.
+ */
+const MAX_PATH_DEPTH = 5;
+/**
+ * Below this page count `derivePathClusterKeys` falls back to depth 1
+ * unconditionally: the auto-cut needs at least a handful of pages to see a
+ * meaningful gap in the depth-vs-key-count curve, and every real
+ * "blocking-signal" use case for this function is over corpora larger than
+ * this. Chosen conservatively so that small-corpus regression tests stay
+ * on the shallowest-depth path they already validated.
+ */
+const AUTO_CUT_MIN_PAGES = 20;
+/**
+ * Runs {@link ./derive-path-group-key.js | derivePathGroupKey} for every
+ * candidate depth in `1..MAX_PATH_DEPTH` and picks the depth whose
+ * increment* in distinct-key count over the previous depth is the largest
+ * data-driven gap. Same self-tuning primitive
+ * ({@link ./auto-cut-threshold.js | autoCutThreshold}) this package already
+ * uses for Stage A merge-height cutoffs, applied recursively at the URL-path
+ * layer.
+ *
+ * ## Why the increment, not the count itself
+ *
+ * Distinct-key count is monotonically non-decreasing in `depth` (a deeper
+ * key partitions strictly more finely), so the raw count only ever rises
+ * with `depth` and its max-gap point sits at the highest depth
+ * unconditionally. What we actually want is the depth at which adding one
+ * more segment *starts* fragmenting into per-page noise — i.e. the
+ * transition* between "still discriminating templates" and "just enumerating
+ * pages." Feeding the per-depth increment (`count[d] − count[d − 1]`) to
+ * `autoCutThreshold` picks the depth just below that transition: the sweep
+ * takes the widest jump as the signal that a structural boundary has been
+ * crossed and returns the depth immediately before it.
+ *
+ * ## Degenerate cases
+ *
+ * - Every page has the same top-level segment → count[1] = 1 for all
+ *   depths' worth of comparable growth, so the max gap is (effectively) at
+ *   depth 1 and this function returns depth 1
+ * - All depths produce identical counts (a pathologically uniform corpus)
+ *   → falls back to depth 1
+ *
+ * ## Not wired into the main clustering path yet
+ *
+ * `resolvePageClusterKeys` continues to invoke `derivePathGroupKey` with the
+ * static default `depth: 1`. This function is exported as a building block
+ * for callers who want to opt in (via `pathDepth: 'auto'` on the blocking
+ * options), and for a future PR that flips the default after validating the
+ * data-driven depth against real corpora — same staged approach every
+ * previous auto-cut adoption in this package took.
+ * @param pagesPaths
+ * @example
+ * ```ts
+ * derivePathClusterKeys([
+ * 	['dept-a', 'news', '1'],
+ * 	['dept-a', 'news', '2'],
+ * 	['dept-b', 'about'],
+ * ]);
+ * // { depth: 1, keys: ['dept-a', 'dept-a', 'dept-b'] }
+ * ```
+ */
+export function derivePathClusterKeys(pagesPaths) {
+    if (pagesPaths.length === 0)
+        return { depth: 1, keys: [] };
+    // Depth-1 keys are needed unconditionally — either as the return value
+    // itself (short-circuit / fallback) or as the count[1] entry for the
+    // auto-cut sweep.
+    const depth1Keys = pagesPaths.map((paths) => derivePathGroupKey(paths, 1));
+    if (pagesPaths.length < AUTO_CUT_MIN_PAGES) {
+        return { depth: 1, keys: depth1Keys };
+    }
+    // Distinct-key count at each candidate depth. Increments per depth:
+    // count[d] − count[d − 1] — the marginal fragmentation added by going
+    // one segment deeper.
+    const countsPerDepth = [new Set(depth1Keys).size];
+    const keysPerDepth = [depth1Keys];
+    for (let depth = 2; depth <= MAX_PATH_DEPTH; depth++) {
+        const keys = pagesPaths.map((paths) => derivePathGroupKey(paths, depth));
+        keysPerDepth.push(keys);
+        countsPerDepth.push(new Set(keys).size);
+    }
+    const incrementsFromDepth2 = [];
+    for (let i = 1; i < countsPerDepth.length; i++) {
+        incrementsFromDepth2.push((countsPerDepth[i] ?? 0) - (countsPerDepth[i - 1] ?? 0));
+    }
+    // autoCutThreshold picks the largest max-gap in the increments; the
+    // clamp fires only in the fully-degenerate "no gap" case, in which we
+    // stay at depth 1. When it finds a real gap, we pick the deepest depth
+    // whose increment is still below the cut (i.e. one step before the
+    // point where marginal fragmentation crosses into per-page noise).
+    const cut = autoCutThreshold(incrementsFromDepth2, 1);
+    if (!Number.isFinite(cut) || cut <= 0) {
+        return { depth: 1, keys: depth1Keys };
+    }
+    let chosen = 1;
+    for (const [i, element] of incrementsFromDepth2.entries()) {
+        const inc = element ?? 0;
+        if (inc >= cut)
+            break;
+        chosen = i + 2; // depth-2 for i=0, depth-3 for i=1, ...
+    }
+    return { depth: chosen, keys: keysPerDepth[chosen - 1] ?? depth1Keys };
+}

package/dist/extract-landmarks.d.ts

@@ -1,80 +1,126 @@
 /**
- * The four structural regions this module knows how to carve out of a page.
+ * The six structural regions this module knows how to carve out of a page.
  * Chosen to match both the HTML5 sectioning-element vocabulary and the
  * corresponding ARIA landmark roles, since real sites use either or both
  * (confirmed on two real crawl archives, ~9,200 pages combined: `<header>`/
  * `<footer>`/`<nav>` present on 99%+ of pages; ARIA roles present on ~53% of
  * one of the two sites, layered on top of the tags rather than replacing
  * them).
+ *
+ * `form` is matched only via `role="form"` (not bare `<form>` tags, which
+ * have no implicit landmark role under HTML-AAM unless given an accessible
+ * name). `search` is matched via both the `<search>` element (WHATWG
+ * landmark shorthand) and `role="search"`.
  */
-export type LandmarkType = 'header' | 'footer' | 'nav' | 'aside';
+export type LandmarkType = 'header' | 'footer' | 'nav' | 'aside' | 'form' | 'search';
 /**
  * Result of {@link ./extract-landmarks.js | extractLandmarks}. Each landmark
- * field holds the raw HTML of the single chosen instance of that region (see
- * `extractLandmarks`'s JSDoc for the "shallowest wins" selection rule);
- * absent if the page has none — or if the only candidate(s) found were
- * malformed markup `extractLandmarks` declined to trust (see its JSDoc's
- * note on discarded candidates). `remainderHtml` is the original HTML
- * with every chosen region's markup excised, meant to be fed straight into
+ * field holds an array of the raw HTML of every genuinely-closed instance
+ * of that region on the page, in document order. Empty array if the page
+ * has none — or if every candidate found was malformed markup
+ * `extractLandmarks` declined to trust (see its JSDoc's note on discarded
+ * candidates). `remainderHtml` is the original HTML with every extracted
+ * span excised, meant to be fed straight into
  * {@link ./tokenize.js | tokenize} as the page's content-only signal.
+ *
+ * Multiple instances per type are the norm, not the exception: real crawl
+ * data commonly has 2–3 `<nav>`s per page (site nav + local nav + related-
+ * articles nav), and one production page in the tuning corpora had 11
+ * `<header>` elements. Downstream is responsible for deciding which
+ * instances are chrome vs content via corpus/unit frequency analysis (see
+ * {@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s
+ * `shellQuorum`) rather than this module baking that judgment in with a
+ * depth or ordering rule.
  */
 export type ExtractLandmarksResult = {
-    header?: string;
-    footer?: string;
-    nav?: string;
-    aside?: string;
+    header: string[];
+    footer: string[];
+    nav: string[];
+    aside: string[];
+    form: string[];
+    search: string[];
     remainderHtml: string;
 };
 /**
- * Finds, for each of the four landmark types, the single best-matching
- * region in `html` (by tag name or ARIA role — see `matchLandmarkTypes`),
- * and returns both that region's own HTML and the rest of the page with all
- * chosen regions removed.
+ * Collects every genuinely-closed landmark instance on the page — one entry
+ * per type per instance, in document order — and returns them alongside
+ * `remainderHtml`, the original HTML with every extracted span excised.
+ *
+ * ## Why collect every instance rather than a single "primary" one
+ *
+ * Earlier iterations of this function returned the shallowest match per
+ * type on the theory that the outermost `<nav>`/`<header>`/… was the "real"
+ * site-wide chrome and anything deeper was page-specific content. Real
+ * crawl data breaks that model on the third category: **section-local
+ * chrome**. On a real mid-sized crawl corpus, one URL section carried a
+ * section-local `<nav>` inside `<main>` that other sections didn't; with
+ * shallowest-wins that nav gets classified as content and left in
+ * `remainderHtml`, at which point the corpus-wide 90% frequency filter
+ * leaves it there (it's not frequent enough), and the section-local
+ * template variant disappears into the same cluster as the section without
+ * the local nav.
+ *
+ * Delegating chrome-vs-content judgment to downstream frequency analysis
+ * (see {@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s
+ * `shellQuorum`, which runs auto-cut over the per-landmark-token page-
+ * frequency histogram) lets the same primitive already used for merge-
+ * height cutoffs discover chrome across whatever scope it's applied at —
+ * corpus-wide, block-wide, unit-wide — without a hard-coded rule up here
+ * forcing the call one way.
  *
- * When a type has more than one candidate (confirmed on real crawl data: one
- * page had 11 `<header>` elements, most pages have 2-3 `<nav>` elements —
- * typically a site-wide nav plus in-content ones like a "related articles"
- * block), the shallowest one wins (fewest ancestors since `<body>`; ties
- * broken by document order). The rationale: the site-wide chrome instance is
- * structurally the outermost one — anything nested deeper inside `<main>`/
- * `<article>` content is, definitionally, part of the page's own content
- * rather than shared site chrome, even if it happens to reuse the same tag
- * or role.
+ * ## Why single-string concatenation was rejected
+ *
+ * A weaker variant of "collect every instance" concatenates all matches of
+ * the same type into one string and keeps the old single-string result
+ * shape. That was evaluated and rejected: it breaks
+ * `computeLandmarkStatus`'s `canonicalizeTokenSet` bucketing (article-
+ * specific `<header>`s vary per page, exploding buckets toward page count
+ * and killing the O(n²) → O(bucket²) speedup), pollutes `shellQuorum` with
+ * in-content nav tokens (dismantling the L2 microsite guard), and still
+ * conflates site-wide vs local nav instances within the same type token set (the
+ * common-vocabulary tokens of a global nav bury the distinctive tokens of
+ * a section-local nav in any frequency filter downstream). Array shape
+ * with instance-level downstream handling avoids all three.
+ *
+ * ## Nested landmark handling
+ *
+ * `<nav>` nested inside a `<header>` is genuinely two landmarks by the
+ * HTML/ARIA vocabulary, but for the frequency-analysis use case they're
+ * one region of markup and must not be counted twice. `keepOutermost`
+ * drops the inner match on those grounds. An identical-span element that
+ * matches two types via tag+role (e.g. `<header role="navigation">`) is
+ * preserved under both types since neither strictly contains the other.
+ *
+ * ## Scoping and robustness
  *
  * Only the first `<body>` is in scope, matching `tokenize()`'s own contract
  * (`<head>` and anything outside body is ignored; a duplicated top-level
- * `<body>` from broken SSR/templating is ignored, same as
- * `run-tokenizer.ts`).
+ * `<body>` from broken SSR/templating is ignored). Nothing inside an opaque
+ * tag (`script`/`style`/`noscript`/`svg`) is searched. A candidate whose
+ * closing tag can't be confirmed as genuine (an unclosed or self-closed-
+ * with-`/>` landmark tag — see `isGenuineClose`) is discarded rather than
+ * trusted: safety against corrupting `remainderHtml` outweighs completeness.
  *
- * `remainderHtml` is built by excising the chosen regions' raw markup
+ * `remainderHtml` is built by excising the extracted spans' raw markup
  * outright — no placeholder is left in their place, since a placeholder
  * string would itself become a token once `remainderHtml` is tokenized,
  * reintroducing exactly the kind of synthetic chrome signal this function
- * exists to remove. One known, accepted side effect of this: if a chosen
+ * exists to remove. One known, accepted side effect: if an extracted
  * landmark and the remaining content share a class-less/role-less `<div>`/
  * `<span>` wrapper as siblings, removing the landmark can change that
  * wrapper's child count and flip it from "not fold-eligible" to
- * "fold-eligible" once `remainderHtml` is tokenized (see
- * `resolveClosedFrame`'s fold rule) — the wrapper's own segment then
- * disappears from the surviving paths, shortening them by one level. This
- * is inherent to "delete the matched span, use whatever's left" and is not
- * treated as a bug.
- *
- * A candidate whose closing tag can't be confirmed as genuine (an unclosed
- * or self-closed-with-`/>` landmark tag — see `isGenuineClose`) is discarded
- * rather than trusted: safety against corrupting `remainderHtml` outweighs
- * completeness of landmark detection for malformed markup. That type then
- * falls back to another well-formed candidate of the same type if one
- * exists (regardless of its depth relative to the discarded one), or is
- * left absent if none do — instead of the page's real content being
- * silently deleted.
+ * "fold-eligible" once `remainderHtml` is tokenized. The wrapper's own
+ * segment then disappears from the surviving paths, shortening them by one
+ * level. This is inherent to "delete the matched span, use whatever's
+ * left" and is not treated as a bug.
  * @param html
  * @example
  * ```ts
  * extractLandmarks('<body><header>H</header><main>M</main><footer>F</footer></body>');
  * // {
- * //   header: '<header>H</header>',
- * //   footer: '<footer>F</footer>',
+ * //   header: ['<header>H</header>'],
+ * //   footer: ['<footer>F</footer>'],
+ * //   nav: [], aside: [], form: [], search: [],
  * //   remainderHtml: '<body><main>M</main></body>',
  * // }
  * ```

package/dist/extract-landmarks.js

@@ -1,16 +1,19 @@
 import { excise } from './excise.js';
-import { findShallowestElements } from './find-shallowest-elements.js';
+import { findMatchingElements, } from './find-shallowest-elements.js';
 const TAG_TO_TYPE = {
     header: 'header',
     footer: 'footer',
     nav: 'nav',
     aside: 'aside',
+    search: 'search',
 };
 const ROLE_TO_TYPE = {
     banner: 'header',
     contentinfo: 'footer',
     navigation: 'nav',
     complementary: 'aside',
+    form: 'form',
+    search: 'search',
 };
 /**
  * Determines which landmark type(s) an element matches by tag name or
@@ -38,67 +41,145 @@ function matchLandmarkTypes(tagName, role) {
     return types;
 }
 /**
- * Finds, for each of the four landmark types, the single best-matching
- * region in `html` (by tag name or ARIA role — see `matchLandmarkTypes`),
- * and returns both that region's own HTML and the rest of the page with all
- * chosen regions removed.
+ * Filters out any match whose whole-element span is strictly contained by
+ * another match's span, keeping only outermost instances. Runs across all
+ * landmark types together — a `<nav>` nested inside a `<header>` gets
+ * dropped, since keeping both would let shell-token computations count the
+ * nav's markup twice (once as the header's inner HTML and once as the nav
+ * itself), skewing the frequency histograms that downstream chrome
+ * detection depends on. Ties (identical spans, e.g. `<header
+ * role="navigation">` matching both types) are preserved: neither strictly
+ * contains the other.
  *
- * When a type has more than one candidate (confirmed on real crawl data: one
- * page had 11 `<header>` elements, most pages have 2-3 `<nav>` elements —
- * typically a site-wide nav plus in-content ones like a "related articles"
- * block), the shallowest one wins (fewest ancestors since `<body>`; ties
- * broken by document order). The rationale: the site-wide chrome instance is
- * structurally the outermost one — anything nested deeper inside `<main>`/
- * `<article>` content is, definitionally, part of the page's own content
- * rather than shared site chrome, even if it happens to reuse the same tag
- * or role.
+ * Input is expected pre-sorted by `startOffset` ascending, which is what
+ * `findMatchingElements` guarantees. In the worst case the inner scan over
+ * already-kept outers is O(n²) — real crawl data has fewer than ~30
+ * landmark candidates per page so this is comfortably faster than the
+ * alternative approaches (interval tree, span sweep with an active-set
+ * stack) at page-scale sizes. If a real corpus with hundreds of landmarks
+ * per page ever appears, revisit.
+ * @param matches
+ */
+function keepOutermost(matches) {
+    const result = [];
+    for (const match of matches) {
+        let contained = false;
+        for (const outer of result) {
+            if (outer.startOffset <= match.startOffset &&
+                match.endOffset <= outer.endOffset &&
+                // A strict containment; identical spans (same element matching
+                // two types via tag+role) are not dropped.
+                (outer.startOffset < match.startOffset || match.endOffset < outer.endOffset)) {
+                contained = true;
+                break;
+            }
+        }
+        if (!contained)
+            result.push(match);
+    }
+    return result;
+}
+/**
+ * Collects every genuinely-closed landmark instance on the page — one entry
+ * per type per instance, in document order — and returns them alongside
+ * `remainderHtml`, the original HTML with every extracted span excised.
+ *
+ * ## Why collect every instance rather than a single "primary" one
+ *
+ * Earlier iterations of this function returned the shallowest match per
+ * type on the theory that the outermost `<nav>`/`<header>`/… was the "real"
+ * site-wide chrome and anything deeper was page-specific content. Real
+ * crawl data breaks that model on the third category: **section-local
+ * chrome**. On a real mid-sized crawl corpus, one URL section carried a
+ * section-local `<nav>` inside `<main>` that other sections didn't; with
+ * shallowest-wins that nav gets classified as content and left in
+ * `remainderHtml`, at which point the corpus-wide 90% frequency filter
+ * leaves it there (it's not frequent enough), and the section-local
+ * template variant disappears into the same cluster as the section without
+ * the local nav.
+ *
+ * Delegating chrome-vs-content judgment to downstream frequency analysis
+ * (see {@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s
+ * `shellQuorum`, which runs auto-cut over the per-landmark-token page-
+ * frequency histogram) lets the same primitive already used for merge-
+ * height cutoffs discover chrome across whatever scope it's applied at —
+ * corpus-wide, block-wide, unit-wide — without a hard-coded rule up here
+ * forcing the call one way.
+ *
+ * ## Why single-string concatenation was rejected
+ *
+ * A weaker variant of "collect every instance" concatenates all matches of
+ * the same type into one string and keeps the old single-string result
+ * shape. That was evaluated and rejected: it breaks
+ * `computeLandmarkStatus`'s `canonicalizeTokenSet` bucketing (article-
+ * specific `<header>`s vary per page, exploding buckets toward page count
+ * and killing the O(n²) → O(bucket²) speedup), pollutes `shellQuorum` with
+ * in-content nav tokens (dismantling the L2 microsite guard), and still
+ * conflates site-wide vs local nav instances within the same type token set (the
+ * common-vocabulary tokens of a global nav bury the distinctive tokens of
+ * a section-local nav in any frequency filter downstream). Array shape
+ * with instance-level downstream handling avoids all three.
+ *
+ * ## Nested landmark handling
+ *
+ * `<nav>` nested inside a `<header>` is genuinely two landmarks by the
+ * HTML/ARIA vocabulary, but for the frequency-analysis use case they're
+ * one region of markup and must not be counted twice. `keepOutermost`
+ * drops the inner match on those grounds. An identical-span element that
+ * matches two types via tag+role (e.g. `<header role="navigation">`) is
+ * preserved under both types since neither strictly contains the other.
+ *
+ * ## Scoping and robustness
  *
  * Only the first `<body>` is in scope, matching `tokenize()`'s own contract
  * (`<head>` and anything outside body is ignored; a duplicated top-level
- * `<body>` from broken SSR/templating is ignored, same as
- * `run-tokenizer.ts`).
+ * `<body>` from broken SSR/templating is ignored). Nothing inside an opaque
+ * tag (`script`/`style`/`noscript`/`svg`) is searched. A candidate whose
+ * closing tag can't be confirmed as genuine (an unclosed or self-closed-
+ * with-`/>` landmark tag — see `isGenuineClose`) is discarded rather than
+ * trusted: safety against corrupting `remainderHtml` outweighs completeness.
  *
- * `remainderHtml` is built by excising the chosen regions' raw markup
+ * `remainderHtml` is built by excising the extracted spans' raw markup
  * outright — no placeholder is left in their place, since a placeholder
  * string would itself become a token once `remainderHtml` is tokenized,
  * reintroducing exactly the kind of synthetic chrome signal this function
- * exists to remove. One known, accepted side effect of this: if a chosen
+ * exists to remove. One known, accepted side effect: if an extracted
  * landmark and the remaining content share a class-less/role-less `<div>`/
  * `<span>` wrapper as siblings, removing the landmark can change that
  * wrapper's child count and flip it from "not fold-eligible" to
- * "fold-eligible" once `remainderHtml` is tokenized (see
- * `resolveClosedFrame`'s fold rule) — the wrapper's own segment then
- * disappears from the surviving paths, shortening them by one level. This
- * is inherent to "delete the matched span, use whatever's left" and is not
- * treated as a bug.
- *
- * A candidate whose closing tag can't be confirmed as genuine (an unclosed
- * or self-closed-with-`/>` landmark tag — see `isGenuineClose`) is discarded
- * rather than trusted: safety against corrupting `remainderHtml` outweighs
- * completeness of landmark detection for malformed markup. That type then
- * falls back to another well-formed candidate of the same type if one
- * exists (regardless of its depth relative to the discarded one), or is
- * left absent if none do — instead of the page's real content being
- * silently deleted.
+ * "fold-eligible" once `remainderHtml` is tokenized. The wrapper's own
+ * segment then disappears from the surviving paths, shortening them by one
+ * level. This is inherent to "delete the matched span, use whatever's
+ * left" and is not treated as a bug.
  * @param html
  * @example
  * ```ts
  * extractLandmarks('<body><header>H</header><main>M</main><footer>F</footer></body>');
  * // {
- * //   header: '<header>H</header>',
- * //   footer: '<footer>F</footer>',
+ * //   header: ['<header>H</header>'],
+ * //   footer: ['<footer>F</footer>'],
+ * //   nav: [], aside: [], form: [], search: [],
  * //   remainderHtml: '<body><main>M</main></body>',
  * // }
  * ```
  */
 export function extractLandmarks(html) {
-    const matches = findShallowestElements(html, matchLandmarkTypes);
-    const result = { remainderHtml: html };
-    const winnerSpans = [];
-    for (const match of matches) {
-        result[match.type] = html.slice(match.startOffset, match.endOffset);
-        winnerSpans.push({ start: match.startOffset, end: match.endOffset });
+    const allMatches = findMatchingElements(html, matchLandmarkTypes);
+    const outermost = keepOutermost(allMatches);
+    const result = {
+        header: [],
+        footer: [],
+        nav: [],
+        aside: [],
+        form: [],
+        search: [],
+        remainderHtml: html,
+    };
+    const spans = [];
+    for (const match of outermost) {
+        result[match.type].push(html.slice(match.startOffset, match.endOffset));
+        spans.push({ start: match.startOffset, end: match.endOffset });
     }
-    result.remainderHtml = excise(html, winnerSpans);
+    result.remainderHtml = excise(html, spans);
     return result;
 }