npm - @d-zero/page-cluster - Versions diffs - 0.3.0 → 0.4.0 - Mend

@d-zero/page-cluster 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +131 -53
package/dist/build-page-landmark-report.d.ts +50 -0
package/dist/build-page-landmark-report.js +67 -0
package/dist/cli.d.ts +1 -0
package/dist/cli.js +56 -6
package/dist/extract-landmarks.d.ts +75 -14
package/dist/extract-landmarks.js +64 -4
package/dist/is-chrome-landmark-instance.d.ts +41 -0
package/dist/is-chrome-landmark-instance.js +50 -0
package/dist/merge-cross-block-clusters.js +5 -97
package/dist/offset-to-line-column.d.ts +38 -0
package/dist/offset-to-line-column.js +49 -0
package/dist/per-page-landmark-signatures.d.ts +10 -1
package/dist/per-page-landmark-signatures.js +16 -4
package/dist/resolve-page-cluster-keys.d.ts +62 -1
package/dist/resolve-page-cluster-keys.js +77 -84
package/dist/shell-quorum.d.ts +70 -0
package/dist/shell-quorum.js +110 -0
package/package.json +4 -4

package/dist/extract-landmarks.js CHANGED Viewed

@@ -1,11 +1,13 @@
 import { excise } from './excise.js';
 import { findMatchingElements, } from './find-shallowest-elements.js';
+import { buildLineColumnIndex, offsetToLineColumn } from './offset-to-line-column.js';
 const TAG_TO_TYPE = {
     header: 'header',
     footer: 'footer',
     nav: 'nav',
     aside: 'aside',
     search: 'search',
+    main: 'main',
 };
 const ROLE_TO_TYPE = {
     banner: 'header',
@@ -14,6 +16,7 @@ const ROLE_TO_TYPE = {
     complementary: 'aside',
     form: 'form',
     search: 'search',
+    main: 'main',
 };
 /**
  * Determines which landmark type(s) an element matches by tag name or
@@ -40,6 +43,16 @@ function matchLandmarkTypes(tagName, role) {
     }
     return types;
 }
+/**
+ * Type guard splitting `findMatchingElements`' combined match list into the
+ * excisable six landmark types vs `main`. `main` is content, not chrome, and
+ * must never be mixed into the same `keepOutermost` sweep as the other six
+ * — see `extractLandmarks`'s "main handling" note for why.
+ * @param match
+ */
+function isMainMatch(match) {
+    return match.type === 'main';
+}
 /**
  * Filters out any match whose whole-element span is strictly contained by
  * another match's span, keeping only outermost instances. Runs across all
@@ -151,21 +164,50 @@ function keepOutermost(matches) {
  * 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.
+ *
+ * ## Main handling
+ *
+ * `main` (the `<main>` tag or `role="main"`) is collected the same way as
+ * the other six types — one entry per genuinely-closed instance, in
+ * document order — but is kept out of every mechanism the other six feed:
+ *
+ * - It is **never excised**: its span is never added to `remainderHtml`'s
+ *   excise list, because `main` is the page's actual content, not chrome.
+ *   Removing it would gut `remainderHtml` down to whatever sits outside
+ *   `<main>` (nothing, on most real pages).
+ * - Its `keepOutermost` nesting sweep runs **separately** from the other six
+ *   types'. If it shared the sweep, a `<main>` that wraps most of the page
+ *   (as it typically does) would make every `header`/`nav`/`aside` nested
+ *   inside it look "contained by main" and get dropped — destroying the
+ *   section-local chrome detection this module exists to enable (see "Why
+ *   collect every instance" above). Only nested `<main>`s (an edge case —
+ *   HTML discourages more than one) are deduplicated against each other.
+ * - It never contributes to chrome/shell-frequency analysis (`main` is
+ *   absent from `computePerPageLandmarkInstances`'s `ALL_LANDMARK_TYPES`):
+ *   its instances are reported for position purposes only, never treated as
+ *   candidate chrome.
  * @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: [{ html: '<header>H</header>', startOffset: 6, endOffset: 24,
+ * //              startLine: 1, startColumn: 7, endLine: 1, endColumn: 25 }],
+ * //   footer: [{ html: '<footer>F</footer>', startOffset: 38, endOffset: 56,
+ * //              startLine: 1, startColumn: 39, endLine: 1, endColumn: 57 }],
  * //   nav: [], aside: [], form: [], search: [],
+ * //   main: [{ html: '<main>M</main>', startOffset: 24, endOffset: 38,
+ * //            startLine: 1, startColumn: 25, endLine: 1, endColumn: 39 }],
  * //   remainderHtml: '<body><main>M</main></body>',
  * // }
  * ```
  */
 export function extractLandmarks(html) {
     const allMatches = findMatchingElements(html, matchLandmarkTypes);
-    const outermost = keepOutermost(allMatches);
+    const mainMatches = allMatches.filter(isMainMatch);
+    const excisableMatches = allMatches.filter((match) => !isMainMatch(match));
+    const outermost = keepOutermost(excisableMatches);
+    const outermostMain = keepOutermost(mainMatches);
     const result = {
         header: [],
         footer: [],
@@ -173,13 +215,31 @@ export function extractLandmarks(html) {
         aside: [],
         form: [],
         search: [],
+        main: [],
         remainderHtml: html,
     };
     const spans = [];
+    const lineColumnIndex = buildLineColumnIndex(html);
+    const toInstance = (match) => {
+        const start = offsetToLineColumn(lineColumnIndex, match.startOffset);
+        const end = offsetToLineColumn(lineColumnIndex, match.endOffset);
+        return {
+            html: html.slice(match.startOffset, match.endOffset),
+            startOffset: match.startOffset,
+            endOffset: match.endOffset,
+            startLine: start.line,
+            startColumn: start.column,
+            endLine: end.line,
+            endColumn: end.column,
+        };
+    };
     for (const match of outermost) {
-        result[match.type].push(html.slice(match.startOffset, match.endOffset));
+        result[match.type].push(toInstance(match));
         spans.push({ start: match.startOffset, end: match.endOffset });
     }
+    for (const match of outermostMain) {
+        result.main.push(toInstance(match));
+    }
     result.remainderHtml = excise(html, spans);
     return result;
 }

package/dist/is-chrome-landmark-instance.d.ts ADDED Viewed

@@ -0,0 +1,41 @@
+/**
+ * Default containment threshold for {@link ./is-chrome-landmark-instance.js | isChromeLandmarkInstance}.
+ * Chosen to match the quorum/shell fractions used elsewhere in this pipeline
+ * ({@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s
+ * `QUORUM_FRACTION`, {@link ./shell-quorum.js | SHELL_QUORUM_FALLBACK_FRACTION}) —
+ * unlike those, this exact value has not been validated against real crawl
+ * data; it is a starting point carried over by convention, adjustable via
+ * this function's `threshold` parameter.
+ */
+export declare const DEFAULT_CHROME_OVERLAP_THRESHOLD = 0.8;
+/**
+ * Classifies a single landmark instance as chrome (shared site/section
+ * furniture) or content, given the instance's own tokens and the shell
+ * token set {@link ./shell-quorum.js | shellQuorum} discovered for its unit.
+ *
+ * ## Why containment (`|instance ∩ shell| / |instance|`) and not Jaccard
+ *
+ * `shellTokens` is the union of chrome tokens across an entire unit's
+ * landmark instances (header + nav + footer + …, corpus-wide), so it is
+ * usually far larger than any single instance's own token set. Jaccard's
+ * denominator is the *union* of both sets, which stays shell-sized even when
+ * the instance is 100% shell tokens — driving the score down regardless of
+ * how purely "shell" the instance is. Containment instead asks "of this
+ * instance's own tokens, how many are shell tokens", which is the question
+ * that actually matters for classifying one instance.
+ *
+ * An instance with zero tokens is never chrome (there is nothing to
+ * corroborate) — matches {@link ./per-page-landmark-signatures.js | computePerPageLandmarkInstances}'s
+ * own choice to drop zero-token instances before they ever reach a
+ * `PerPageLandmarkInstance`, kept here as a defensive default rather than an
+ * assumption about every caller.
+ * @param instanceTokens
+ * @param shellTokens
+ * @param threshold
+ * @example
+ * ```ts
+ * const shellTokens = shellQuorum(unitPerPageInstances);
+ * const isChrome = isChromeLandmarkInstance(instance.tokens, shellTokens);
+ * ```
+ */
+export declare function isChromeLandmarkInstance(instanceTokens: ReadonlySet<string>, shellTokens: ReadonlySet<string>, threshold?: number): boolean;

package/dist/is-chrome-landmark-instance.js ADDED Viewed

@@ -0,0 +1,50 @@
+/**
+ * Default containment threshold for {@link ./is-chrome-landmark-instance.js | isChromeLandmarkInstance}.
+ * Chosen to match the quorum/shell fractions used elsewhere in this pipeline
+ * ({@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s
+ * `QUORUM_FRACTION`, {@link ./shell-quorum.js | SHELL_QUORUM_FALLBACK_FRACTION}) —
+ * unlike those, this exact value has not been validated against real crawl
+ * data; it is a starting point carried over by convention, adjustable via
+ * this function's `threshold` parameter.
+ */
+export const DEFAULT_CHROME_OVERLAP_THRESHOLD = 0.8;
+/**
+ * Classifies a single landmark instance as chrome (shared site/section
+ * furniture) or content, given the instance's own tokens and the shell
+ * token set {@link ./shell-quorum.js | shellQuorum} discovered for its unit.
+ *
+ * ## Why containment (`|instance ∩ shell| / |instance|`) and not Jaccard
+ *
+ * `shellTokens` is the union of chrome tokens across an entire unit's
+ * landmark instances (header + nav + footer + …, corpus-wide), so it is
+ * usually far larger than any single instance's own token set. Jaccard's
+ * denominator is the *union* of both sets, which stays shell-sized even when
+ * the instance is 100% shell tokens — driving the score down regardless of
+ * how purely "shell" the instance is. Containment instead asks "of this
+ * instance's own tokens, how many are shell tokens", which is the question
+ * that actually matters for classifying one instance.
+ *
+ * An instance with zero tokens is never chrome (there is nothing to
+ * corroborate) — matches {@link ./per-page-landmark-signatures.js | computePerPageLandmarkInstances}'s
+ * own choice to drop zero-token instances before they ever reach a
+ * `PerPageLandmarkInstance`, kept here as a defensive default rather than an
+ * assumption about every caller.
+ * @param instanceTokens
+ * @param shellTokens
+ * @param threshold
+ * @example
+ * ```ts
+ * const shellTokens = shellQuorum(unitPerPageInstances);
+ * const isChrome = isChromeLandmarkInstance(instance.tokens, shellTokens);
+ * ```
+ */
+export function isChromeLandmarkInstance(instanceTokens, shellTokens, threshold = DEFAULT_CHROME_OVERLAP_THRESHOLD) {
+    if (instanceTokens.size === 0)
+        return false;
+    let hit = 0;
+    for (const token of instanceTokens) {
+        if (shellTokens.has(token))
+            hit++;
+    }
+    return hit / instanceTokens.size >= threshold;
+}

package/dist/merge-cross-block-clusters.js CHANGED Viewed

@@ -1,11 +1,11 @@
 import { assignContainedClusters } from './assign-contained-clusters.js';
-import { autoCutThreshold } from './auto-cut-threshold.js';
 import { collapseAnonymousDivs } from './collapse-anonymous-divs.js';
 import { completeLinkageDendrogram, labelsAtThreshold, } from './complete-linkage-dendrogram.js';
 import { computeDocumentFrequency } from './compute-document-frequency.js';
 import { jaccardSimilarity } from './jaccard-similarity.js';
 import { reservoirSample } from './reservoir-sample.js';
 import { shapeToken } from './shape-token.js';
+import { shellQuorum } from './shell-quorum.js';
 import { splitTokensByFrequency } from './split-tokens-by-frequency.js';
 /**
  * Fixed complete-linkage threshold for the cross-block fine stage.
@@ -26,11 +26,10 @@ const CROSS_BLOCK_THRESHOLD = 0.8;
  * on real crawl data. Full union is shell-dominated: 298 pages collapsed into
  * 4 clusters — also confirmed. 80% quorum avoids both failure modes.
  *
- * Also reused as the fallback clamp for {@link ./auto-cut-threshold.js |
- * autoCutThreshold} when running on the per-landmark-instance frequency
- * distribution in {@link ./merge-cross-block-clusters.js | shellQuorum}. The
- * clamp only ever *loosens* the cut relative to this floor (never tightens),
- * and only fires in the degenerate cases the JSDoc there describes.
+ * Not shared with {@link ./shell-quorum.js | shellQuorum}'s own fallback
+ * clamp (`SHELL_QUORUM_FALLBACK_FRACTION`) — the two happen to be the same
+ * value today because both were validated against the same real crawl
+ * corpora, but they are independently tunable.
  */
 const QUORUM_FRACTION = 0.8;
 /**
@@ -159,97 +158,6 @@ function l2Contained(xSig, ySig) {
     }
     return true;
 }
-/**
- * Discovers a unit's shell tokens by auto-cutting the per-*token* page-
- * frequency histogram of every landmark instance's tokens. This is the same
- * max-gap primitive used for Stage A merge-height cutoffs, applied
- * recursively at the landmark-token layer.
- *
- * ## Why per-token and not per-signature
- *
- * An earlier iteration ran the histogram at the level of full landmark-
- * instance signatures (canonicalized token sets). That failed on a real,
- * common pattern: a shared site chrome whose markup carries a per-page
- * distinguishing element (a breadcrumb, a page-title element with a page-
- * specific class, a "current" state). All pages have most of the same
- * tokens, but every page's full signature is distinct because tokens embed
- * class names. Per-signature counting saw 5 signatures at freq 0.2 each,
- * autoCutThreshold on the flat distribution returned the clamp, and the
- * shell collapsed to empty even though every page shared the core header
- * skeleton. Per-token counting handles the same case correctly — the shared
- * skeleton tokens each hit freq 1.0.
- *
- * ## The histogram
- *
- * For every member page, all its landmark instances are tokenized and
- * unioned into a single per-page token set (order-agnostic, deduped: a
- * token appearing in two of the page's landmarks still counts once for
- * that page). The corpus histogram is then "how many pages contain each
- * token". Tokens that appear on nearly every page are the unit's chrome;
- * tokens that appear on only a handful are page-specific content that
- * happens to be tagged as a landmark.
- *
- * ## Why auto-cut instead of a hard-coded quorum
- *
- * A fixed 80% quorum (this file's earlier implementation) baked one
- * threshold in for every unit. Real corpora don't obey a universal cutoff:
- * a section-local landmark token that appears on 60% of a unit's pages is
- * the section's chrome under any reasonable reading, but 80% quorum
- * discards it. Auto-cut looks at the *shape* of the frequency distribution
- * and picks the widest gap between adjacent frequencies — if the
- * distribution is `{1.00, 1.00, 0.65, 0.03, 0.02}`, the gap between 0.65
- * and 0.03 (0.62) dwarfs everything else and the cut lands mid-gap around
- * 0.34, correctly grouping the 0.65 tokens with the site-wide 1.00 ones as
- * "chrome for this unit". If instead the distribution is flat, the clamp
- * to {@link QUORUM_FRACTION} keeps the threshold from being tighter than
- * the fallback default.
- *
- * ## Fallbacks
- *
- * A single distinct token (`heights.length < 2`) or a perfectly flat
- * distribution (`maxGap === 0`) returns the {@link QUORUM_FRACTION} clamp
- * verbatim — exactly the same 80%-quorum behavior as before. So degenerate
- * cases degrade to the old contract; only richer distributions get the
- * auto-cut benefit.
- *
- * A page with no landmarks contributes an empty set, deliberately, so the
- * shell-corroboration jaccard between two landmark-less pages is 0 rather
- * than 1 (which it would be if we handed back a `<body></body>`-derived
- * `{body}` fallback set to both sides).
- * @param perPageInstances
- */
-function shellQuorum(perPageInstances) {
-    const pageCount = perPageInstances.length;
-    if (pageCount === 0)
-        return new Set();
-    // Union all instance token sets per page (dedupe within page: a token
-    // present on both header and footer of the same page still counts once
-    // for that page's contribution).
-    const tokenPageCount = new Map();
-    for (const instances of perPageInstances) {
-        const perPageUnion = new Set();
-        for (const inst of instances) {
-            for (const token of inst.tokens)
-                perPageUnion.add(token);
-        }
-        for (const token of perPageUnion) {
-            tokenPageCount.set(token, (tokenPageCount.get(token) ?? 0) + 1);
-        }
-    }
-    if (tokenPageCount.size === 0)
-        return new Set();
-    const frequencies = [];
-    for (const count of tokenPageCount.values()) {
-        frequencies.push(count / pageCount);
-    }
-    const cut = autoCutThreshold(frequencies, QUORUM_FRACTION);
-    const shell = new Set();
-    for (const [token, count] of tokenPageCount) {
-        if (count / pageCount >= cut)
-            shell.add(token);
-    }
-    return shell;
-}
 // ---------------------------------------------------------------------------
 // Main function
 // ---------------------------------------------------------------------------

package/dist/offset-to-line-column.d.ts ADDED Viewed

@@ -0,0 +1,38 @@
+/**
+ * A 1-based line/column position within an HTML string.
+ */
+export type LineColumn = {
+    readonly line: number;
+    readonly column: number;
+};
+/**
+ * Precomputed lookup structure for {@link ./offset-to-line-column.js | offsetToLineColumn}:
+ * every newline's string-index offset, ascending.
+ */
+export type LineColumnIndex = {
+    readonly newlineOffsets: readonly number[];
+};
+/**
+ * Scans `html` once and records every `\n` offset, so repeated
+ * {@link ./offset-to-line-column.js | offsetToLineColumn} calls against the
+ * same HTML string can binary-search instead of re-scanning from the start
+ * each time. Built once per page and reused across every landmark instance's
+ * start/end offset — a page with dozens of landmark instances would
+ * otherwise pay for a fresh O(n) scan per offset instead of one O(n) scan
+ * total.
+ * @param html
+ */
+export declare function buildLineColumnIndex(html: string): LineColumnIndex;
+/**
+ * Converts a string-index `offset` (the same unit as `htmlparser2`'s
+ * `startIndex`/`endIndex`, i.e. UTF-16 code units) into a 1-based
+ * `{line, column}` position, using an index built by
+ * {@link ./offset-to-line-column.js | buildLineColumnIndex}.
+ *
+ * `\r\n` line endings are handled without special-casing: the `\r` is
+ * counted as the last column of its own line, matching how most editors
+ * report position for CRLF files.
+ * @param index
+ * @param offset
+ */
+export declare function offsetToLineColumn(index: LineColumnIndex, offset: number): LineColumn;

package/dist/offset-to-line-column.js ADDED Viewed

@@ -0,0 +1,49 @@
+/**
+ * Scans `html` once and records every `\n` offset, so repeated
+ * {@link ./offset-to-line-column.js | offsetToLineColumn} calls against the
+ * same HTML string can binary-search instead of re-scanning from the start
+ * each time. Built once per page and reused across every landmark instance's
+ * start/end offset — a page with dozens of landmark instances would
+ * otherwise pay for a fresh O(n) scan per offset instead of one O(n) scan
+ * total.
+ * @param html
+ */
+export function buildLineColumnIndex(html) {
+    const newlineOffsets = [];
+    for (let i = 0; i < html.length; i++) {
+        if (html.codePointAt(i) === 10)
+            newlineOffsets.push(i);
+    }
+    return { newlineOffsets };
+}
+/**
+ * Converts a string-index `offset` (the same unit as `htmlparser2`'s
+ * `startIndex`/`endIndex`, i.e. UTF-16 code units) into a 1-based
+ * `{line, column}` position, using an index built by
+ * {@link ./offset-to-line-column.js | buildLineColumnIndex}.
+ *
+ * `\r\n` line endings are handled without special-casing: the `\r` is
+ * counted as the last column of its own line, matching how most editors
+ * report position for CRLF files.
+ * @param index
+ * @param offset
+ */
+export function offsetToLineColumn(index, offset) {
+    const { newlineOffsets } = index;
+    let low = 0;
+    let high = newlineOffsets.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        if (newlineOffsets[mid] < offset) {
+            low = mid + 1;
+        }
+        else {
+            high = mid;
+        }
+    }
+    // `low` is the count of newlines strictly before `offset`, i.e. the
+    // number of completed lines — so `low` newlines completed means we're on
+    // line `low + 1`.
+    const lineStart = low === 0 ? 0 : newlineOffsets[low - 1] + 1;
+    return { line: low + 1, column: offset - lineStart + 1 };
+}

package/dist/per-page-landmark-signatures.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { ExtractLandmarksResult, LandmarkType } from './extract-landmarks.js';
+import type { ExtractLandmarksResult, LandmarkPosition, LandmarkType } from './extract-landmarks.js';
 import type { TokenizeOptions } from './types.js';
 /**
  * Every landmark type extractLandmarks may populate, iterated in a fixed
@@ -13,11 +13,20 @@ export declare const ALL_LANDMARK_TYPES: readonly LandmarkType[];
  * {@link ./canonicalize-token-set.js | canonicalizeTokenSet}). Signatures
  * are reused across consumers so two callers see the same "same instance"
  * verdict without independently re-canonicalizing.
+ *
+ * `position` is the instance's location in the page it came from, computed
+ * once by {@link ./extract-landmarks.js | extractLandmarks} and carried here
+ * unchanged — a back-reference for callers (e.g.
+ * {@link ./build-page-landmark-report.js | buildPageLandmarkReport}) that
+ * need to report where a chrome-classified instance actually sits, not just
+ * that it exists. It plays no part in `tokens`/`signature` computation or in
+ * the corpus-frequency logic that consumes this type.
  */
 export type PerPageLandmarkInstance = {
     readonly type: LandmarkType;
     readonly tokens: ReadonlySet<string>;
     readonly signature: string;
+    readonly position: LandmarkPosition;
 };
 /**
  * Tokenizes every landmark instance across every page once, keyed by page

package/dist/per-page-landmark-signatures.js CHANGED Viewed

@@ -44,17 +44,29 @@ export function computePerPageLandmarkInstances(landmarks, tokenizeOptions) {
         const seenSignatures = new Set();
         const out = [];
         for (const type of ALL_LANDMARK_TYPES) {
-            for (const instanceHtml of entry[type]) {
-                if (!instanceHtml)
+            for (const instance of entry[type]) {
+                if (!instance.html)
                     continue;
-                const tokens = new Set(tokenize(`<body>${instanceHtml}</body>`, tokenizeOptions).tokens);
+                const tokens = new Set(tokenize(`<body>${instance.html}</body>`, tokenizeOptions).tokens);
                 if (tokens.size === 0)
                     continue;
                 const signature = canonicalizeTokenSet(tokens);
                 if (seenSignatures.has(signature))
                     continue;
                 seenSignatures.add(signature);
-                out.push({ type, tokens, signature });
+                out.push({
+                    type,
+                    tokens,
+                    signature,
+                    position: {
+                        startOffset: instance.startOffset,
+                        endOffset: instance.endOffset,
+                        startLine: instance.startLine,
+                        startColumn: instance.startColumn,
+                        endLine: instance.endLine,
+                        endColumn: instance.endColumn,
+                    },
+                });
             }
         }
         return out;

package/dist/resolve-page-cluster-keys.d.ts CHANGED Viewed

@@ -1,7 +1,9 @@
 import type { ExtractLandmarksResult } from './extract-landmarks.js';
+import type { PerPageLandmarkInstance } from './per-page-landmark-signatures.js';
 import type { ResolveBlockingGroupKeysOptions } from './resolve-blocking-group-keys.js';
 import type { ResolveStructuralClusterKeysOptions } from './resolve-structural-cluster-keys.js';
 import type { TokenizeOptions } from './types.js';
+import { type PageLandmarkReport } from './build-page-landmark-report.js';
 /**
  * Reinjects each page's *local* (non-corpus-wide) landmark-instance tokens
  * into its block token set for Stage A clustering, restoring exactly the
@@ -65,6 +67,7 @@ import type { TokenizeOptions } from './types.js';
 export declare function computeLocalChromeArtifacts(landmarks: readonly ExtractLandmarksResult[], tokenizeOptions: TokenizeOptions | undefined): {
     readonly localSignatures: ReadonlySet<string>;
     readonly localTokensByPage: readonly ReadonlySet<string>[];
+    readonly perPageInstances: readonly (readonly PerPageLandmarkInstance[])[];
 };
 /**
  * Reinjects each page's *local* (non-corpus-wide) landmark-instance tokens
@@ -162,9 +165,47 @@ export type ResolvePageClusterKeysOptions = TokenizeOptions & ResolveBlockingGro
      * sync helper to running a per-block async loop that emits
      * `pass1-block-complete` and `stage-b-start`. Omitting `onProgress`
      * keeps the small-corpus branch on the pre-refactor sync path with
-     * zero yield overhead.
+     * zero yield overhead. Ignored when `includeLandmarkPositions` is
+     * `true` — that option always routes the small-corpus branch through
+     * the sync helper (see `includeLandmarkPositions`'s own JSDoc), so no
+     * progress events fire in that combination.
      */
     onProgress?: (event: ProgressEvent) => void;
+    /**
+     * When `true`, every result entry additionally carries a
+     * {@link PageLandmarkReport} — each landmark instance's position, plus
+     * a chrome/content verdict for the six excisable types (see
+     * {@link ./build-page-landmark-report.js | buildPageLandmarkReport}).
+     * Changes the return shape from `string[]` to
+     * `{@link PageClusterKeyResult}[]` (see the overloads on
+     * `resolvePageClusterKeysInMemory`/`resolvePageClusterKeys`/
+     * `resolvePageClusterKeysFromArray`). Defaults to `false`, in which
+     * case every existing caller's behavior and return type are
+     * unchanged.
+     *
+     * Not supported on the streaming path
+     * (`pageCount > {@link CORPUS_INLINE_THRESHOLD}`): reservoir sampling
+     * and Jaccard-based non-sample assignment there have no notion of
+     * "this page's shell tokens" to classify chrome against, and
+     * retrofitting one is out of scope. `resolvePageClusterKeys` throws a
+     * `RangeError` up front if both apply to the same call, rather than
+     * silently degrading semantics.
+     *
+     * On the async factory-based `resolvePageClusterKeys`, this option
+     * forces the small-corpus branch through the sync
+     * `resolvePageClusterKeysInMemory` helper regardless of `onProgress`
+     * — see `onProgress`'s own JSDoc.
+     */
+    includeLandmarkPositions?: boolean;
+};
+/**
+ * One page's clustering result when `includeLandmarkPositions` is `true`:
+ * the same `clusterKey` every caller already gets, plus that page's
+ * {@link PageLandmarkReport}.
+ */
+export type PageClusterKeyResult = {
+    readonly clusterKey: string;
+    readonly landmarks: PageLandmarkReport;
 };
 /**
  * Corpus size at or below which the async factory-based
@@ -188,6 +229,17 @@ export type ResolvePageClusterKeysOptions = TokenizeOptions & ResolveBlockingGro
  * anything above 20,000 is routed to streaming.
  */
 export declare const CORPUS_INLINE_THRESHOLD = 20000;
+/**
+ * Throws when `includeLandmarkPositions` is combined with a corpus over
+ * `threshold` pages (the streaming path — see `includeLandmarkPositions`'s
+ * own JSDoc for why it has no sample-based equivalent there). Split out from
+ * its call site so tests can exercise the boundary with a small injected
+ * `threshold` instead of constructing a 20,001-page fixture to cross the
+ * real {@link CORPUS_INLINE_THRESHOLD}.
+ * @param pageCount
+ * @param threshold
+ */
+export declare function assertLandmarkPositionsSupportedForPageCount(pageCount: number, threshold: number): void;
 /**
  * Reservoir-sample size per block on the streaming path. Blocks larger than
  * this have Stage A run on a random sample of `BLOCK_SAMPLE_SIZE` pages,
@@ -240,6 +292,9 @@ export declare const BLOCK_SAMPLE_SIZE = 100;
  * @param pages
  * @param options
  */
+export declare function resolvePageClusterKeysInMemory(pages: readonly PageClusterSignals[], options: ResolvePageClusterKeysOptions & {
+    includeLandmarkPositions: true;
+}): PageClusterKeyResult[];
 export declare function resolvePageClusterKeysInMemory(pages: readonly PageClusterSignals[], options?: ResolvePageClusterKeysOptions): string[];
 /**
  * Factory function returning an iterator over pages. Called once per streaming
@@ -303,6 +358,9 @@ export type PageFactory = () => Iterable<PageClusterSignals> | AsyncIterable<Pag
  * });
  * ```
  */
+export declare function resolvePageClusterKeys(pages: PageFactory, options: ResolvePageClusterKeysOptions & {
+    includeLandmarkPositions: true;
+}): Promise<PageClusterKeyResult[]>;
 export declare function resolvePageClusterKeys(pages: PageFactory, options?: ResolvePageClusterKeysOptions): Promise<string[]>;
 /**
  * Convenience wrapper that runs {@link ./resolve-page-cluster-keys.js | resolvePageClusterKeys}
@@ -320,4 +378,7 @@ export declare function resolvePageClusterKeys(pages: PageFactory, options?: Res
  * ]);
  * ```
  */
+export declare function resolvePageClusterKeysFromArray(pages: readonly PageClusterSignals[], options: ResolvePageClusterKeysOptions & {
+    includeLandmarkPositions: true;
+}): Promise<PageClusterKeyResult[]>;
 export declare function resolvePageClusterKeysFromArray(pages: readonly PageClusterSignals[], options?: ResolvePageClusterKeysOptions): Promise<string[]>;