@d-zero/page-cluster 0.3.0 → 0.4.0

package/README.md

@@ -1,12 +1,8 @@
 # `@d-zero/page-cluster`
 
-大量クロール HTML の重複・類似ページを構造トークンで検出するパッケージ。CLI が主、ライブラリ関数群がオマケ。
+大量クロール HTML の重複・類似ページを構造トークンで検出するパッケージ。HTML ページ集合を受け取って、**同一テンプレートと判定できるページ**に同じクラスタキーを振る。テキストは無視して DOM 構造だけを見るので、本文が違っても同じテンプレートを使うページ群は 1 つのクラスタにまとまる。単一サイトで数万〜十数万ページ規模のクロール成果物を、テンプレート単位に畳んで概観したいときに使う。CLI が主、ライブラリ関数群がオマケ。
 
-## What this does
-
-`page-cluster` は HTML ページ集合を受け取って、**同一テンプレートと判定できるページ**に同じキーを振る。テキストは無視して DOM 構造だけを見るので、記事本文が違うが同じテンプレートを使うページ群は 1 つのクラスタにまとまる。単一サイトで数万〜十数万ページ規模のクロール成果物を、テンプレート単位に畳んで概観したいときに使う。
-
-## Install
+## Installation
 
 ```sh
 yarn add @d-zero/page-cluster
@@ -14,7 +10,13 @@ yarn add @d-zero/page-cluster
 
 インストールすると `page-cluster` コマンドが `node_modules/.bin/` 配下に入る。
 
-## Quickstart (CLI)
+## Usage
+
+### CLI
+
+```sh
+page-cluster [--content-block-attribute <name>] [--include-landmark-positions] < pages.jsonl > clusters.jsonl
+```
 
 **入力**: JSONL 1 行 1 ページ。フィールドは以下。`html` 以外はすべて任意（`paths` / `stylesheetHrefs` がないと粗い分類になる）。
 
@@ -34,33 +36,69 @@ yarn add @d-zero/page-cluster
 { "id": "任意の識別子", "clusterKey": "..." }
 ```
 
-### クローラ出力（JSON 配列）を JSONL に変換して食わせる
+`--include-landmark-positions` を指定すると、各行に `landmarks` フィールドが追加される。header / footer / nav / aside / form / search / main のインスタンスごとに、HTML 内の位置（1-based の line/column と文字列オフセットの両方）を返す。header 〜 search の 6 種は追加で、そのページが属する最終クラスタ内での頻度分析（`shellQuorum`）に基づく `isChrome`（サイト/セクション共通の chrome か、ページ固有のコンテンツか）を持つ。`main` は常にコンテンツなので `isChrome` を持たない。
 
-`jq` のワンライナーで配列を line-delimited にする典型例:
-
-```sh
-jq -c '.[]' crawl-output.json | page-cluster > clusters.jsonl
+```json
+{
+	"id": "任意の識別子",
+	"clusterKey": "...",
+	"landmarks": {
+		"header": [
+			{
+				"startLine": 1,
+				"startColumn": 7,
+				"endLine": 1,
+				"endColumn": 30,
+				"startOffset": 6,
+				"endOffset": 29,
+				"isChrome": true
+			}
+		],
+		"footer": [],
+		"nav": [],
+		"aside": [],
+		"form": [],
+		"search": [],
+		"main": [
+			{
+				"startLine": 2,
+				"startColumn": 1,
+				"endLine": 10,
+				"endColumn": 8,
+				"startOffset": 40,
+				"endOffset": 120
+			}
+		]
+	}
+}
 ```
 
-### `--content-block-attribute`
+20,000 ページを超えるコーパス（ストリーミング経路）では `--include-landmark-positions` は使えない（エラーで終了する）。ストリーミング経路はリザーバサンプリングと近似割当を使うため、ページ単位の chrome 判定に必要な「そのページが属する最終クラスタの shell トークン」という概念を持たないため。
 
-CMS が自由編集コンテンツブロックに付与している属性名（例: `data-bgb`）が分かっている場合に指定する。指定すると比較前にその属性を持つ要素配下を無視するので、同じテンプレートで本文構成だけ違うページを混同しなくなる。
+クローラ出力が JSON 配列の場合は `jq` で line-delimited に変換して食わせる:
 
 ```sh
-page-cluster --content-block-attribute data-bgb < pages.jsonl > clusters.jsonl
+jq -c '.[]' crawl-output.json | page-cluster > clusters.jsonl
 ```
 
-### 進捗
+#### オプション
+
+- `--content-block-attribute <name>` — CMS が自由編集コンテンツブロックに付与している属性名（例: `data-bgb`）が分かっている場合に指定する。指定すると比較前にその属性を持つ要素配下を無視するので、同じテンプレートで本文構成だけ違うページを混同しなくなる。唯一の site-specific なオプションで、未指定でも `<main>` / `role="main"` を起点にした自動深さキャップが常時働く（詳細は `resolve-page-cluster-keys.ts` の JSDoc を参照）
+- `--include-landmark-positions` — 出力の各行に上記の `landmarks` フィールドを追加する。20,000 ページ超のコーパスでは使えない。指定すると進捗表示（後述）は出なくなる（進捗を出さない非ストリーミング経路に常に振り分けられるため）
+- `--help` / `-h` — ヘルプを表示する
+- `--version` / `-v` — バージョンを表示する
+
+#### 進捗表示
 
 処理中は stderr に進捗を出す。stdout の JSONL 出力は影響を受けない。
 
-**対話端末 (TTY)**: `%earth%` アニメ付きの単一ヘッダー行が in-place に書き換わり、現在のフェーズ・進捗・経過時間を表示する。
+**対話端末（TTY）**: アニメーション付きの単一ヘッダー行が in-place に書き換わり、現在のフェーズ・進捗・経過時間を表示する。
 
 ```
 🌏 page-cluster — clustering 12/47 blocks (elapsed 23s)
 ```
 
-**非TTY (パイプ・ファイルリダイレクト・CI)**: `[page-cluster] ...` 形式の行を追記する。`pass0:` / `pass1:` / `pass1b:` / `stage-b:` の phase トークンを含むので `grep` / `awk` 互換。
+**非 TTY（パイプ・ファイルリダイレクト・CI）**: `[page-cluster] ...` 形式の行を追記する。`pass0:` / `pass1:` / `pass1b:` / `stage-b:` の phase トークンを含むので `grep` / `awk` 互換。
 
 ```
 [page-cluster] reading input pages...
@@ -74,49 +112,89 @@ page-cluster --content-block-attribute data-bgb < pages.jsonl > clusters.jsonl
 
 silence したい場合は `2>/dev/null`。ログに残したい場合は `2> progress.log`。
 
-## API (brief)
+### Library
+
+サブパスエクスポート構成。import パスと提供関数の対応は以下。
+
+| import パス                                          | 提供関数                                                                                                                                                                                                                                                                                                                          |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@d-zero/page-cluster`                               | `tokenize` — `<body>` 配下を構造トークン列に変換する低レベルプリミティブ                                                                                                                                                                                                                                                          |
+| `@d-zero/page-cluster/resolve-page-cluster-keys`     | `resolvePageClusterKeys`（非同期・ファクトリ入力・メモリ有界のメインエントリー）、`resolvePageClusterKeysFromArray`（array 入力ラッパー）、`resolvePageClusterKeysInMemory`（同期・array 入力）。いずれも `includeLandmarkPositions: true` を渡すと `clusterKey` に加えて位置情報つきの `landmarks`（`PageLandmarkReport`）を返す |
+| `@d-zero/page-cluster/extract-landmarks`             | `extractLandmarks` — header / footer / nav / aside / form / search / main の 7 種を抽出し、インスタンスごとの生 HTML と HTML 内の位置（line/column・文字列オフセット）を返す                                                                                                                                                      |
+| `@d-zero/page-cluster/resolve-landmark-variant-keys` | `resolveLandmarkVariantKeys` — 特定ランドマークのデザインバリアントでページを分類                                                                                                                                                                                                                                                 |
+
+```ts
+import { resolvePageClusterKeysFromArray } from '@d-zero/page-cluster/resolve-page-cluster-keys';
+
+const keys = await resolvePageClusterKeysFromArray([
+	{
+		paths: ['news', '1'],
+		stylesheetHrefs: ['/a.css'],
+		html: '<body><article>one</article></body>',
+	},
+	{
+		paths: ['news', '2'],
+		stylesheetHrefs: ['/a.css'],
+		html: '<body><article>two</article></body>',
+	},
+	{
+		paths: ['about'],
+		stylesheetHrefs: ['/a.css'],
+		html: '<body><section>about</section></body>',
+	},
+]);
+// keys[0] === keys[1]（同一テンプレート）、keys[2] は別クラスタ
+```
 
-すべての詳細は各関数の JSDoc にある。CLI 経由で十分な場合は読み飛ばして OK。
+オプション・型・設計判断の WHY はすべて各関数の JSDoc に記載している。CLI 経由で十分な場合は読み飛ばして OK。
 
-- **`tokenize(html, options?)`** — `<body>` 配下の HTML を構造トークン列に変換する低レベルプリミティブ
-- **`resolvePageClusterKeys(pagesFactory, options?)`** — ページ集合からクラスタキーを返すメインエントリー。ファクトリ関数入力で大規模コーパスに対応
-- **`resolvePageClusterKeysFromArray(pages, options?)`** — メモリに全ページ載る前提の array 入力ラッパー
-- **`resolveLandmarkVariantKeys(htmlList, landmarkType, options?)`** — `header` / `footer` / `nav` / `aside` などのランドマークバリアント分類
-- **`extractLandmarks(html)`** — 1 ページから 6 種の HTML5 ランドマーク（header / footer / nav / aside / form / search）を抽出
+## アルゴリズム概観
 
-## Algorithm
+`clusterKey` がどう決まるかを知っておくと、出力の解釈（なぜこの 2 ページが同じキーなのか）とオプションの選択がしやすくなる。実装詳細の WHY は各ソースファイルの JSDoc が正。
 
-```
-              ┌────────────────────────────────────────┐
-              │  Blocking (paths / stylesheet 集合)    │
-              └──────────────────┬─────────────────────┘
-                                 │  同じテンプレートを共有する候補群
-                                 ▼
-              ┌────────────────────────────────────────┐
-              │  Stage A: complete-linkage クラスタリング │
-              │     (ブロック内、Jaccard 距離)          │
-              └──────────────────┬─────────────────────┘
-                                 │  各ブロックのクラスタ代表
-                                 ▼
-              ┌────────────────────────────────────────┐
-              │  Stage B: quorum-core cross-block merge │
-              │  (ブロック境界を越えた再統合)            │
-              └────────────────────────────────────────┘
-```
+### 全体パイプライン
 
-- **Blocking** — URL パスと stylesheet 集合を安価なブロッキング信号として粗く分割。同一ブロック内でだけ高価な構造比較を行うので、コーパス全体に対する比較コストを O(n²) から劇的に減らす
-- **Stage A** — ブロック内で `<main>` 配下のトークン列に対して complete-linkage 階層的クラスタリングを実行し、max-gap detection でカット高を選ぶ
-- **Stage B** — 各クラスタの quorum-core（80% クォーラム）を代表としてブロック境界をまたぐ再統合を反復。complete-linkage、包含、shape-Jaccard、L2 signature の 4 経路で融合を試みて不動点まで回す
-- **大規模自動切替** — 20,000 ページ超で自動的に**ストリーミング経路**に切り替わる。ブロックごとにリザーバサンプルで代表を学ばせ、非サンプルページを Jaccard で最寄りクラスタに割当。メモリ使用量が最大ブロックのサイズに比例するようになる
+```mermaid
+flowchart TD
+    IN[入力ページ集合] --> P0["Pass 0: ブロッキング<br>URL パス + first-party CSS 集合 → blockKey<br>（orphan ページの再割当を含む）"]
+    P0 --> GATE{"ページ数 ≤ 20,000?"}
 
-### Self-tuning
+    GATE -- "yes（in-memory）" --> CHROME_ALL["chrome discovery（コーパス全体）<br>ランドマーク署名の度数分布に auto-cut<br>→ グローバル chrome 除外 / ローカル chrome 再注入"]
+    CHROME_ALL --> SA_ALL["Stage A × 全ブロック<br>深さキャップ → tokenize →<br>complete-linkage + auto-cut → 包含割当"]
+
+    GATE -- "no（ストリーミング）" --> RES["ブロックごとにリザーバサンプリング<br>（各ブロック最大 100 ページ、決定的シード）"]
+    RES --> SA_SAMPLE["chrome discovery + Stage A<br>（サンプルのみ、ブロック単位で逐次 flush）"]
+    SA_SAMPLE --> P1B["Pass 1b: 非サンプルページを<br>max-Jaccard で最寄りクラスタへ割当"]
 
-閾値はすべて **max-gap auto-cut**（度数分布の最大ギャップの中点を境界とする）でデータから自己発見される。Stage A のマージ高さカット、Stage B のシェル判定、コーパス全体の共通クローム判定など、3 階層でこの同一プリミティブを再帰使用しているので、サイトごとにハイパーパラメータをチューニングする必要はない。詳細は `autoCutThreshold` の JSDoc を参照。
+    SA_ALL --> SB["Stage B: ブロック越えマージ<br>（不動点ループ、下図）"]
+    P1B --> SB
+    SB --> OUT["clusterKey を入力順に出力"]
+```
 
-## Notes
+- **Pass 0（ブロッキング）** — HTML を読まず、URL パスと first-party stylesheet 集合だけで粗く分割する。高価な構造比較を同一ブロック内に閉じ込め、コーパス全体の比較コストを O(n²) から劇的に減らす。stylesheet を持たない orphan ページは同一セクションの CSS ブロックへ再割当される
+- **chrome discovery** — 全ページのランドマーク署名の度数分布に auto-cut を当て、閾値以上を「グローバル chrome」（サイト共通のヘッダー等）として比較から除外し、閾値未満かつ 2 ページ以上に出現するものを「ローカル chrome」（セクション固有のナビ等）としてトークン再注入する
+- **Stage A（ブロック内クラスタリング）** — ブロックごとに直線的な処理。`<main>` の深さキャップ（候補深度を全走査して knee を探す自動選択）→ tokenize → complete-linkage 階層クラスタリング → max-gap auto-cut でカット高を決定 → 最後に包含関係にあるクラスタを吸収する包含割当（割当チェーンを辿り、循環はメンバー最大のクラスタをルートに選んで解決）
+- **Pass 1b（ストリーミング時のみ）** — 20,000 ページ超では各ブロックをリザーバサンプリング（最大 100 ページ、ブロックキーをシードにした決定的乱数）で代表させ、サンプル外のページは Stage A 完了後に max-Jaccard で最寄りクラスタへ一括割当する。メモリ使用量はコーパス全体ではなくサンプルサイズに比例する
+- **Stage B（ブロック越えマージ）** — ブロック分割はあくまで比較コスト削減のためなので、最後に同一テンプレートがブロックを跨いで分かれていないか再統合する。これが唯一の反復処理（次節）
+
+### Stage B: ブロック越え統合の不動点ループ
+
+```mermaid
+flowchart TD
+    START["ラウンド開始（最大 10 ラウンド）"] --> CORE["現在のプール済みメンバーから再計算:<br>文書頻度 → distinctive tokens → quorum core（80%）"]
+    CORE --> FINE["fine stage（単一 union-find 上で 3 経路）:<br>① complete-linkage（固定 0.8）<br>② 包含割当（0.9、チェーン走査 + サイクル解決）<br>③ shape-Jaccard（0.9、複数ページユニットのみ）"]
+    FINE --> Q1{"fine でマージ発生?"}
+    Q1 -- yes --> APPLY1["マージ適用（メンバー統合）"]
+    APPLY1 --> START
+    Q1 -- no --> L2["L2 stage:<br>L2 signature 包含 + shell 相互裏付け<br>（shell は auto-cut で自己発見）"]
+    L2 --> Q2{"L2 でマージ発生?"}
+    Q2 -- yes --> APPLY2["マージ適用"]
+    APPLY2 --> START
+    Q2 -- no --> DONE["収束 — 全ユニットのキーが不動点に到達"]
+```
 
-### `contentBlockAttribute` の存在意義
+マージが起きるとユニットのメンバー構成が変わり、文書頻度も quorum core も変わる。そのため毎ラウンド、統合後のプールから全指標を**再計算**してマージを再試行する。fine stage・L2 stage の両方でマージが 1 件も出なくなった時点で不動点に到達したとみなして収束する（安全弁として最大 10 ラウンド。実データでは 7 ラウンド以内に収束）。L2 stage は fine stage が空振りしたラウンドでしか実行されない最後の粗い経路で、誤マージ防止のために shell（ランドマーク由来トークン）の相互裏付けを要求する。
 
-このパッケージが持つ唯一の site-specific なオプション。CMS の自由編集ブロックに付与される属性名（例: `data-bgb`）は HTML から自動検知できないので外部知識として受け取る形にしている。指定された属性を持つ要素の配下は比較対象から除外され、同じテンプレート上で本文構成だけ違うページの誤分割を防ぐ。
+### Self-tuning
 
-未指定でも大半のケースで動くよう、`<main>` / `role="main"` を起点にした自動深さキャップが常時有効になっている。
+閾値の多くは **max-gap auto-cut**（度数分布の隣接ギャップ最大の中点を境界とする）でデータから自己発見される。① Stage A のカット高、② Stage B の shell 判定、③ chrome discovery のグローバル/ローカル判定、④ Pass 0 の URL パス深さ選択、の 4 箇所で同一プリミティブを再利用しているので、サイトごとにハイパーパラメータをチューニングする必要はない。詳細は `autoCutThreshold` の JSDoc を参照。例外的に Stage B fine stage の complete-linkage だけは固定閾値 0.8 を使う（理由は `merge-cross-block-clusters.ts` の JSDoc を参照）。

package/dist/build-page-landmark-report.d.ts

@@ -0,0 +1,50 @@
+import type { ExtractLandmarksResult, LandmarkPosition } from './extract-landmarks.js';
+import type { TokenizeOptions } from './types.js';
+/**
+ * A landmark instance's position plus whether
+ * {@link ./is-chrome-landmark-instance.js | isChromeLandmarkInstance} judged
+ * it shared site/section chrome (`true`) or page-specific content (`false`),
+ * against the unit's {@link ./shell-quorum.js | shellQuorum} shell tokens.
+ */
+export type ReportedLandmarkInstance = LandmarkPosition & {
+    readonly isChrome: boolean;
+};
+/**
+ * Per-page landmark position report built by
+ * {@link ./build-page-landmark-report.js | buildPageLandmarkReport}. `main`
+ * carries no `isChrome` verdict — it never participates in chrome/shell
+ * discovery (see `extractLandmarks`'s "main handling" note) and is always
+ * content.
+ */
+export type PageLandmarkReport = {
+    header: ReportedLandmarkInstance[];
+    footer: ReportedLandmarkInstance[];
+    nav: ReportedLandmarkInstance[];
+    aside: ReportedLandmarkInstance[];
+    form: ReportedLandmarkInstance[];
+    search: ReportedLandmarkInstance[];
+    main: LandmarkPosition[];
+};
+/**
+ * Builds a page's landmark position report: every landmark instance's
+ * location, with `header`/`footer`/`nav`/`aside`/`form`/`search` instances
+ * additionally classified as chrome or content against `shellTokens`.
+ *
+ * Reads `landmarks` directly — the full, non-deduplicated instance list
+ * `extractLandmarks` produced — rather than going through
+ * {@link ./per-page-landmark-signatures.js | computePerPageLandmarkInstances}'s
+ * per-page-deduplicated `PerPageLandmarkInstance[]`: that dedupe collapses
+ * same-signature instances to one entry, which would silently drop the
+ * position of every duplicate instance a position report needs to include.
+ * @param landmarks
+ * @param shellTokens The unit-level shell token set from
+ * {@link ./shell-quorum.js | shellQuorum}, computed once per final cluster
+ * and shared across every member page's report.
+ * @param tokenizeOptions
+ * @example
+ * ```ts
+ * const shellTokens = shellQuorum(clusterPerPageInstances);
+ * const report = buildPageLandmarkReport(extractLandmarks(page.html), shellTokens);
+ * ```
+ */
+export declare function buildPageLandmarkReport(landmarks: ExtractLandmarksResult, shellTokens: ReadonlySet<string>, tokenizeOptions?: TokenizeOptions): PageLandmarkReport;

package/dist/build-page-landmark-report.js

@@ -0,0 +1,67 @@
+import { isChromeLandmarkInstance } from './is-chrome-landmark-instance.js';
+import { ALL_LANDMARK_TYPES } from './per-page-landmark-signatures.js';
+import { tokenize } from './tokenize.js';
+/**
+ * Strips `html` off a {@link LandmarkInstance}, keeping only its position.
+ * `buildPageLandmarkReport`'s output is meant to be serialized per page
+ * across a whole corpus (the CLI's JSONL output), so the report
+ * deliberately excludes each instance's raw HTML to keep that payload from
+ * scaling with markup size — callers who also need the HTML already have
+ * `ExtractLandmarksResult` in hand.
+ * @param instance
+ */
+function toPosition(instance) {
+    return {
+        startOffset: instance.startOffset,
+        endOffset: instance.endOffset,
+        startLine: instance.startLine,
+        startColumn: instance.startColumn,
+        endLine: instance.endLine,
+        endColumn: instance.endColumn,
+    };
+}
+/**
+ * Builds a page's landmark position report: every landmark instance's
+ * location, with `header`/`footer`/`nav`/`aside`/`form`/`search` instances
+ * additionally classified as chrome or content against `shellTokens`.
+ *
+ * Reads `landmarks` directly — the full, non-deduplicated instance list
+ * `extractLandmarks` produced — rather than going through
+ * {@link ./per-page-landmark-signatures.js | computePerPageLandmarkInstances}'s
+ * per-page-deduplicated `PerPageLandmarkInstance[]`: that dedupe collapses
+ * same-signature instances to one entry, which would silently drop the
+ * position of every duplicate instance a position report needs to include.
+ * @param landmarks
+ * @param shellTokens The unit-level shell token set from
+ * {@link ./shell-quorum.js | shellQuorum}, computed once per final cluster
+ * and shared across every member page's report.
+ * @param tokenizeOptions
+ * @example
+ * ```ts
+ * const shellTokens = shellQuorum(clusterPerPageInstances);
+ * const report = buildPageLandmarkReport(extractLandmarks(page.html), shellTokens);
+ * ```
+ */
+export function buildPageLandmarkReport(landmarks, shellTokens, tokenizeOptions) {
+    const report = {
+        header: [],
+        footer: [],
+        nav: [],
+        aside: [],
+        form: [],
+        search: [],
+        main: landmarks.main.map(toPosition),
+    };
+    for (const type of ALL_LANDMARK_TYPES) {
+        for (const instance of landmarks[type]) {
+            const tokens = instance.html
+                ? new Set(tokenize(`<body>${instance.html}</body>`, tokenizeOptions).tokens)
+                : new Set();
+            report[type].push({
+                ...toPosition(instance),
+                isChrome: isChromeLandmarkInstance(tokens, shellTokens),
+            });
+        }
+    }
+    return report;
+}

package/dist/cli.d.ts

@@ -5,6 +5,7 @@
  */
 type CliArgs = {
     readonly contentBlockAttribute?: string;
+    readonly includeLandmarkPositions?: boolean;
     readonly help?: boolean;
     readonly version?: boolean;
     readonly unknownFlag?: string;

package/dist/cli.js

@@ -8,7 +8,7 @@ import process from 'node:process';
 import { Lanes } from '@d-zero/dealer';
 import { resolvePageClusterKeys } from './resolve-page-cluster-keys.js';
 const HELP_TEXT = `Usage:
-  page-cluster [--content-block-attribute <name>] < pages.jsonl > clusters.jsonl
+  page-cluster [--content-block-attribute <name>] [--include-landmark-positions] < pages.jsonl > clusters.jsonl
 
 Input (JSONL, one page per line):
   {
@@ -22,10 +22,35 @@ Input (JSONL, one page per line):
 Output (JSONL, one line per input page, in input order):
   { "id": "...", "clusterKey": "..." }
 
+  With --include-landmark-positions, each line additionally carries a
+  \`landmarks\` field: every header/footer/nav/aside/form/search/main
+  instance's position (1-based line/column plus string offsets), with the
+  six excisable types (all but main) also carrying an \`isChrome\` verdict
+  against that page's final cluster:
+  {
+    "id": "...", "clusterKey": "...",
+    "landmarks": {
+      "header": [{ "startLine": 1, "startColumn": 7, "endLine": 1,
+                    "endColumn": 30, "startOffset": 6, "endOffset": 29,
+                    "isChrome": true }],
+      "footer": [...], "nav": [...], "aside": [...], "form": [...], "search": [...],
+      "main": [{ "startLine": 2, "startColumn": 1, "endLine": 10,
+                  "endColumn": 8, "startOffset": 40, "endOffset": 120 }]
+    }
+  }
+
 Options:
   --content-block-attribute <name>   CMS-provided attribute marking freeform
                                      content blocks that should be stripped
                                      before comparison (e.g. \`data-bgb\`).
+  --include-landmark-positions       Add the \`landmarks\` field described
+                                     above to every output line. Not
+                                     supported for corpora over 20,000 pages
+                                     (throws instead of streaming). Disables
+                                     progress output on stderr — this option
+                                     always routes through the same
+                                     non-progress-emitting code path as a
+                                     run without progress.
   --help                             Print this help and exit.
   --version                          Print the package version and exit.
 
@@ -82,6 +107,10 @@ export function parseArgs(argv) {
                 i++;
                 break;
             }
+            case '--include-landmark-positions': {
+                out.includeLandmarkPositions = true;
+                break;
+            }
             default: {
                 out.unknownFlag = arg;
                 return out;
@@ -331,18 +360,39 @@ export async function runCli(options) {
                 renderProgress(lanes, useTty, formatProgressLine(event, elapsed()));
             },
         };
-        let keys;
+        // `includeLandmarkPositions` always routes resolvePageClusterKeys
+        // through its non-progress-emitting sync path (see that option's own
+        // JSDoc), so the onProgress callback above is set but never invoked
+        // in this branch — no separate "quiet" resolveOptions variant needed.
+        let clusterKeys;
+        let landmarksByIndex;
         try {
-            keys = await resolvePageClusterKeys(() => pages, resolveOptions);
+            if (args.includeLandmarkPositions) {
+                const results = await resolvePageClusterKeys(() => pages, {
+                    ...resolveOptions,
+                    includeLandmarkPositions: true,
+                });
+                clusterKeys = results.map((r) => r.clusterKey);
+                landmarksByIndex = results.map((r) => r.landmarks);
+            }
+            else {
+                clusterKeys = await resolvePageClusterKeys(() => pages, resolveOptions);
+            }
         }
         catch (error) {
             renderProgress(lanes, useTty, errorLine(error.message));
             return 1;
         }
-        const clusterCount = new Set(keys).size;
+        const clusterCount = new Set(clusterKeys).size;
         renderProgress(lanes, useTty, doneLine(pages.length, clusterCount, elapsed()));
-        for (const [index, key] of keys.entries()) {
-            options.stdout.write(`${JSON.stringify({ id: ids[index] ?? index, clusterKey: key })}\n`);
+        for (const [index, key] of clusterKeys.entries()) {
+            const row = {
+                id: ids[index] ?? index,
+                clusterKey: key,
+            };
+            if (landmarksByIndex)
+                row.landmarks = landmarksByIndex[index];
+            options.stdout.write(`${JSON.stringify(row)}\n`);
         }
         return 0;
     }

package/dist/extract-landmarks.d.ts

@@ -11,16 +11,50 @@
  * 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"`.
+ *
+ * `main` is deliberately not a member of this union even though
+ * {@link ./extract-landmarks.js | extractLandmarks} reports it: this type is
+ * also the parameter type of `resolveLandmarkVariantKeys` and the vocabulary
+ * that chrome discovery (`computePerPageLandmarkInstances`'s
+ * `ALL_LANDMARK_TYPES`) iterates over. Admitting `'main'` here would let
+ * `resolveLandmarkVariantKeys(pages, 'main')` type-check while silently
+ * returning nothing (chrome discovery never looks at `main` instances) —
+ * exactly the kind of type-level lie this module avoids elsewhere. `main` is
+ * content, not chrome: it never participates in frequency-based chrome
+ * discovery, only in position reporting.
  */
 export type LandmarkType = 'header' | 'footer' | 'nav' | 'aside' | 'form' | 'search';
+/**
+ * An instance's location within the HTML string it was extracted from, in
+ * both string-index and 1-based line/column form. Computed once per page by
+ * {@link ./extract-landmarks.js | extractLandmarks} via
+ * {@link ./offset-to-line-column.js | buildLineColumnIndex}/`offsetToLineColumn`
+ * and carried downstream as plain numbers — nothing recomputes it.
+ */
+export type LandmarkPosition = {
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly startLine: number;
+    readonly startColumn: number;
+    readonly endLine: number;
+    readonly endColumn: number;
+};
+/**
+ * One landmark instance: its raw HTML plus its {@link LandmarkPosition}
+ * within the page it was extracted from.
+ */
+export type LandmarkInstance = LandmarkPosition & {
+    readonly html: string;
+};
 /**
  * Result of {@link ./extract-landmarks.js | extractLandmarks}. Each landmark
- * 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
+ * field holds an array 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 `header`/`footer`/`nav`/`aside`/
+ * `form`/`search` span excised (`main` is never excised — see
+ * `extractLandmarks`'s "main handling" note), 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
@@ -33,12 +67,13 @@ export type LandmarkType = 'header' | 'footer' | 'nav' | 'aside' | 'form' | 'sea
  * depth or ordering rule.
  */
 export type ExtractLandmarksResult = {
-    header: string[];
-    footer: string[];
-    nav: string[];
-    aside: string[];
-    form: string[];
-    search: string[];
+    header: LandmarkInstance[];
+    footer: LandmarkInstance[];
+    nav: LandmarkInstance[];
+    aside: LandmarkInstance[];
+    form: LandmarkInstance[];
+    search: LandmarkInstance[];
+    main: LandmarkInstance[];
     remainderHtml: string;
 };
 /**
@@ -113,14 +148,40 @@ export type ExtractLandmarksResult = {
  * 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>',
  * // }
  * ```