diff --git a/.gitignore b/.gitignore
index 8b2407367295..7d76b708a0d9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,6 +39,7 @@ legacy.d.ts
 # Bundle analysis artifacts
 bundleAnalysis
 bundleAnalyzerJson
+compareBundlesOutput
 
 # Misc pipeline artifacts
 artifacts
diff --git a/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md b/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md
new file mode 100644
index 000000000000..d72956dacf5d
--- /dev/null
+++ b/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md
@@ -0,0 +1,164 @@
+# Further information about the bundle-analysis commands
+
+The bundle-analysis commands measure how a change affects a package's webpack
+bundle by building the bundle on two different revisions and diffing the
+per-asset and per-package sizes, so regressions (or wins) are easy to spot
+before pushing.
+
+See [generate.md](./generate.md) and [check.md](./check.md) for the generated
+command reference. This document explains how the commands fit together and how
+to read the comparison report.
+
+## The commands
+
+| Command                                           | Responsibility                                                   |
+| ------------------------------------------------- | ---------------------------------------------------------------- |
+| `flub generate bundleAnalysisRepo`                | Build one bundle and save its stats under a label.               |
+| `flub check bundleAnalysisReposComparison`        | Diff two already-collected bundles and write the report.         |
+| `flub generate bundleAnalysisReposWithComparison` | Orchestrate both collect steps plus the compare step end-to-end. |
+
+Each collected bundle is identified by a **label** — the name of the subdirectory
+under `compareBundlesOutput/analysis/` where that bundle's `analyzer.json` is written.
+`flub generate bundleAnalysisRepo` assigns the label automatically: the sanitized
+revision it built in revision mode, or a timestamped `current_<epoch>` for the
+local working tree. `flub check bundleAnalysisReposComparison` then selects which
+two saved bundles to diff by their labels (`--base-label` and `--current-label`).
+
+Each command self-describes its flags via `--help`:
+
+```sh
+flub generate bundleAnalysisRepo --help
+flub check bundleAnalysisReposComparison --help
+flub generate bundleAnalysisReposWithComparison --help
+```
+
+## Typical workflow
+
+In almost every case you just want the one-shot orchestrator:
+
+```sh
+flub generate bundleAnalysisReposWithComparison
+```
+
+This compares your working tree against the merge-base of `HEAD` and `main` —
+i.e. the point your branch forked from — so the diff reflects only your own
+changes, not unrelated commits that have since landed on `main`. Use
+`--base-revision` to compare against a different branch, tag, or commit; the
+merge-base of that revision and `HEAD` is what actually gets built.
+
+Reach for the lower-level commands when the orchestrator's flow doesn't fit:
+
+- **`flub check bundleAnalysisReposComparison` on its own** — when both bundles are
+  already collected and you only want to re-run the diff (e.g. tweaking the
+  report, or comparing two labels the orchestrator wouldn't pair automatically).
+  It reads each side's previously saved `analyzer.json` and writes a fresh report
+  without rebuilding anything.
+- **`flub generate bundleAnalysisRepo` on its own** — when you want to capture a
+  single bundle without immediately diffing it, or to pre-populate a label for a
+  later comparison.
+
+## How collection works
+
+`flub generate bundleAnalysisRepo` runs in one of two modes:
+
+- **local** — builds the bundle from the outer enlistment (your working tree,
+  including staged changes). The staged diff is captured alongside the report so
+  the measurement is reproducible. The outer repo's git state (working tree,
+  branch, revision) is never modified.
+- **revision** — builds the bundle from a _separate_ inner clone of the repo
+  checked out at a specific commit. The inner clone is created on first use by
+  cloning directly from the outer enlistment on disk — no remote or network
+  access is involved, and every object the outer repo already has (including
+  merge-base commits that aren't branch tips) is available without a fetch. The
+  requested commit must therefore already exist locally in the outer repo. The
+  outer repo's working tree, branch, and stash are never touched.
+
+Each build runs webpack, which emits `bundleAnalyzerJson/analyzer.json`
+(webpack-bundle-analyzer's JSON report). That single file carries per-asset
+parsed/gzip sizes and per-module breakdowns — everything the comparison needs —
+so it is the only artifact saved per label; the larger webpack stats and `build/`
+outputs are not retained.
+
+The orchestrator runs `flub generate bundleAnalysisRepo` once in each mode: local
+for the current side, revision for the base side. The base-side report is cached
+and keyed by the resolved SHA, so a re-run against the same merge-base skips the
+rebuild.
+
+## Outputs
+
+- Each label's `analyzer.json` is saved under `compareBundlesOutput/analysis/<label>/`. This is
+  also where the cached base report and the inner repo clone live.
+- Comparison reports (`.txt` and `.json`) are written to `compareBundlesOutput/`.
+
+## Understanding the report
+
+The comparison report is emitted in two forms with identical data: a
+human-readable `.txt` table dump and a structured `.json` file. Every table is a
+list of rows, and each row reports the same three numbers for one named thing — a
+`Base` size, a `Current` size, and their `Diff` (`Current - Base`, so negative
+means smaller). Some tables add a base-relative `% Change` column.
+
+Two different size _measurements_ appear in the report, both read straight from
+webpack-bundle-analyzer's `analyzer.json` (no separate gzipping or stats
+decompression is done):
+
+- **Parsed size** — the minified bytes of the code as it ships, before transport
+  compression. This is the default unit for every table except the gzip one.
+- **Gzip size** — the gzipped bytes, i.e. what actually goes over the wire.
+
+The report measures the bundle at three different _granularities_, each answering a
+different question:
+
+| Table                                        | Granularity | Unit   | What it answers                                                       |
+| -------------------------------------------- | ----------- | ------ | -------------------------------------------------------------------- |
+| All assets                                   | Asset       | Parsed | How did each emitted `.js` file change?                              |
+| Gzip sizes for changed assets                | Asset       | Gzip   | For the assets whose gzip size moved, what is the over-the-wire delta?|
+| Bundle composition by category               | Package set | Parsed | How is a bundle split between Fluid Framework and third-party code?  |
+| Per-package parsed-size comparison           | Package     | Parsed | Which individual package contributed each chunk of bytes?           |
+
+### Asset tables
+
+An **asset** is a single file webpack emits (e.g. `sharedTree.js`). The _All
+assets_ table lists every emitted `.js` asset (source maps excluded) whether it
+changed or not, marking changed rows with a trailing `*`; it is the canonical
+"here is everything that ships" inventory.
+
+The _Gzip sizes for changed assets_ table is a focused supplement: it lists only
+the assets whose **gzip** size actually changed, so it stays short and signal-only.
+Note its filter is on the gzip delta itself — an asset can move in parsed size but
+not gzip (compression absorbs the change), or vice versa, so this table is not
+simply the changed rows of the parsed table re-expressed in gzip bytes.
+
+### Package-level tables
+
+The last two tables attribute bytes to the npm package that owns each module.
+This attribution is deliberately careful:
+
+- **Module -> package.** Each module's path is mapped to its owning package:
+  third-party packages by the name after the last `node_modules/`, Fluid source
+  packages by their `packages/<group>/<name>` workspace path (reported as
+  `@fluidframework/<name>`), and the synthetic entrypoint's own modules as `(app/entry)`.
+- **Scope-hoisting is undone.** When webpack concatenates (scope-hoists) modules
+  it prefixes each module's path with the concatenating barrel. That prefix is
+  stripped before attribution so hoisted modules are credited to their _real_
+  owning package rather than collapsing onto the barrel.
+- **Deduplicated per bundle.** Within a given entrypoint, a module reached more
+  than once is counted exactly once.
+
+Because shared modules can't be split across entrypoints without double-counting,
+each package-level measurement is **pinned to a single real entrypoint** rather
+than summed across the whole report. Every package-level table is measured from
+SharedTree's own `sharedTree` bundle.
+
+The _Bundle composition by category_ table rolls those per-package sizes up into
+headline buckets. For the pinned `sharedTree` entrypoint it reports the bundle's
+total Fluid Framework bytes, and a companion `+ 3rd-party deps` row that also
+folds in every third-party package in that same bundle. (Third-party bytes can't
+be split between the Fluid libraries that pull them in, because the flat
+per-package data carries no dependency graph; synthetic entrypoint code is always
+excluded.)
+
+The _Per-package parsed-size comparison_ table is the full breakdown for the
+`sharedTree` bundle: one row per owning package, sorted by current size
+descending, so the biggest contributors — and the biggest movers — are easy to
+find.
diff --git a/build-tools/packages/build-cli/docs/check.md b/build-tools/packages/build-cli/docs/check.md
index 53dcdfb5bcfb..cc089378e106 100644
--- a/build-tools/packages/build-cli/docs/check.md
+++ b/build-tools/packages/build-cli/docs/check.md
@@ -4,6 +4,7 @@
 Check commands are used to verify repo state, apply policy, etc.
 
 * [`flub check buildVersion`](#flub-check-buildversion)
+* [`flub check bundleAnalysisReposComparison`](#flub-check-bundleanalysisreposcomparison)
 * [`flub check bundleSize`](#flub-check-bundlesize)
 * [`flub check changeset`](#flub-check-changeset)
 * [`flub check latestVersions VERSION PACKAGE_OR_RELEASE_GROUP`](#flub-check-latestversions-version-package_or_release_group)
@@ -67,6 +68,41 @@ DESCRIPTION
 
 _See code: [src/commands/check/buildVersion.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/check/buildVersion.ts)_
 
+## `flub check bundleAnalysisReposComparison`
+
+Compare the two bundles previously collected by 'flub generate bundleAnalysisRepo' (base = --base-label, current = --current-label).
+
+```
+USAGE
+  $ flub check bundleAnalysisReposComparison [-v | --quiet] [--base-label <value>] [--current-label <value>]
+
+FLAGS
+  --base-label=<value>     [default: main] Label subdirectory under compareBundlesOutput/analysis holding the base-side
+                           bundle stats. Matches the label 'flub generate bundleAnalysisRepo' saves in revision mode
+                           (the sanitized revision).
+  --current-label=<value>  [default: current] Label subdirectory under compareBundlesOutput/analysis holding the
+                           current-side bundle stats. Matches the label 'flub generate bundleAnalysisRepo' saves in
+                           local mode (a timestamped 'current_<epoch>').
+
+LOGGING FLAGS
+  -v, --verbose  Enable verbose logging.
+      --quiet    Disable all logging.
+
+DESCRIPTION
+  Compare the two bundles previously collected by 'flub generate bundleAnalysisRepo' (base = --base-label, current =
+  --current-label).
+
+  To learn more see the detailed documentation at
+  https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md
+
+EXAMPLES
+  $ flub check bundleAnalysisReposComparison
+
+  $ flub check bundleAnalysisReposComparison --base-label some-revision
+```
+
+_See code: [src/commands/check/bundleAnalysisReposComparison.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/check/bundleAnalysisReposComparison.ts)_
+
 ## `flub check bundleSize`
 
 Compare the locally-collected bundle reports against the CI build of the merge-base commit (between HEAD and a target ref) and print the diff. By default, the target is auto-detected as `<canonical-remote>/main` where `<canonical-remote>` is whichever remote points at `microsoft/FluidFramework`; pass `--target` to override. Prints a human-readable summary by default; pass --json for the structured result.
diff --git a/build-tools/packages/build-cli/docs/generate.md b/build-tools/packages/build-cli/docs/generate.md
index 1c82ee5ff667..a37f72b78b71 100644
--- a/build-tools/packages/build-cli/docs/generate.md
+++ b/build-tools/packages/build-cli/docs/generate.md
@@ -5,6 +5,8 @@ Generate commands are used to create/update code, docs, readmes, etc.
 
 * [`flub generate assertTags`](#flub-generate-asserttags)
 * [`flub generate buildVersion`](#flub-generate-buildversion)
+* [`flub generate bundleAnalysisRepo`](#flub-generate-bundleanalysisrepo)
+* [`flub generate bundleAnalysisReposWithComparison`](#flub-generate-bundleanalysisreposwithcomparison)
 * [`flub generate bundleStats`](#flub-generate-bundlestats)
 * [`flub generate changelog`](#flub-generate-changelog)
 * [`flub generate changeset`](#flub-generate-changeset)
@@ -118,6 +120,101 @@ EXAMPLES
 
 _See code: [src/commands/generate/buildVersion.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/generate/buildVersion.ts)_
 
+## `flub generate bundleAnalysisRepo`
+
+Build and collect a bundle, either from the outer enlistment (local mode) or from a separate inner enlistment checked out to a specific revision (revision mode). The outer repo's working tree, branch, and stash are never modified.
+
+```
+USAGE
+  $ flub generate bundleAnalysisRepo [-v | --quiet] [--revision <value> | --merge-base <value>] [--package-dir <value>]
+
+FLAGS
+  --merge-base=<value>   Collect a bundle for the merge-base of HEAD and this committish (the fork point). Selects
+                         revision mode and is mutually exclusive with --revision. Also used as the label (the
+                         subdirectory name the bundle's stats are saved under).
+  --package-dir=<value>  [default: .] Package root whose webpack bundles are built and whose analyzer.json is collected.
+  --revision=<value>     Collect a bundle for this committish (branch, tag, commit SHA, or any committish like HEAD~2),
+                         resolved as-is via 'git rev-parse'. Selects revision mode and is mutually exclusive with
+                         --merge-base; omit both to collect the local working tree. Also used as the label (the
+                         subdirectory name the bundle's stats are saved under).
+
+LOGGING FLAGS
+  -v, --verbose  Enable verbose logging.
+      --quiet    Disable all logging.
+
+DESCRIPTION
+  Build and collect a bundle, either from the outer enlistment (local mode) or from a separate inner enlistment checked
+  out to a specific revision (revision mode). The outer repo's working tree, branch, and stash are never modified.
+
+  To learn more see the detailed documentation at
+  https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md
+
+EXAMPLES
+  $ flub generate bundleAnalysisRepo
+
+  $ flub generate bundleAnalysisRepo --revision main
+
+  $ flub generate bundleAnalysisRepo --merge-base main
+
+  $ flub generate bundleAnalysisRepo --revision client_v2.100.0
+```
+
+_See code: [src/commands/generate/bundleAnalysisRepo.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisRepo.ts)_
+
+## `flub generate bundleAnalysisReposWithComparison`
+
+Collect the local bundle and the base-revision (merge-base) bundle, then compare them. The outer repo's working tree, branch, and stash are never modified.
+
+```
+USAGE
+  $ flub generate bundleAnalysisReposWithComparison [-v | --quiet] [--base-revision <value>] [--exact-base] [--package-dir <value>]
+    [--keep-base-repo]
+
+FLAGS
+  --base-revision=<value>
+      Revision to use as the comparison baseline (branch, tag, or commit SHA). The actual base used is the merge-base of
+      HEAD and this revision (the fork point), so worktree-based setups where 'main' is in an unusual location still
+      produce the expected comparison. When omitted, the baseline is auto-detected as the freshest 'main' of a remote
+      pointing at microsoft/FluidFramework — the local 'main' is not used, since it may be stale. An explicit value
+      (including 'main') is always honored as given. Pass --exact-base to use the revision as-is instead.
+
+  --exact-base
+      Use --base-revision exactly as given (resolved via 'git rev-parse') instead of taking the merge-base with HEAD.
+      Useful for comparing the working tree against a specific commit, e.g. the current commit's parent.
+
+  --keep-base-repo
+      For debugging only: keep the inner base-repo clone after collecting the base bundle. By default the inner repo is
+      deleted once stats are saved, since it can be re-created cheaply via shallow clone on the next run. Pass this flag
+      to inspect the inner repo's working tree or build output (e.g. when a build is failing inside the inner repo).
+
+  --package-dir=<value>
+      [default: .] Package root whose webpack bundles are built and compared.
+
+LOGGING FLAGS
+  -v, --verbose  Enable verbose logging.
+      --quiet    Disable all logging.
+
+DESCRIPTION
+  Collect the local bundle and the base-revision (merge-base) bundle, then compare them. The outer repo's working tree,
+  branch, and stash are never modified.
+
+  To learn more see the detailed documentation at
+  https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md
+
+EXAMPLES
+  $ flub generate bundleAnalysisReposWithComparison
+
+  $ flub generate bundleAnalysisReposWithComparison --base-revision main
+
+  $ flub generate bundleAnalysisReposWithComparison --base-revision client_v2.100.0
+
+  $ flub generate bundleAnalysisReposWithComparison --base-revision 18062854f25 --exact-base
+
+  $ flub generate bundleAnalysisReposWithComparison --keep-base-repo
+```
+
+_See code: [src/commands/generate/bundleAnalysisReposWithComparison.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisReposWithComparison.ts)_
+
 ## `flub generate bundleStats`
 
 Find all bundle analysis artifacts and copy them into a central location to upload as build artifacts for later consumption
diff --git a/build-tools/packages/build-cli/src/commands/check/bundleAnalysisReposComparison.ts b/build-tools/packages/build-cli/src/commands/check/bundleAnalysisReposComparison.ts
new file mode 100644
index 000000000000..25147a00c981
--- /dev/null
+++ b/build-tools/packages/build-cli/src/commands/check/bundleAnalysisReposComparison.ts
@@ -0,0 +1,57 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { resolve } from "node:path";
+import { Flags } from "@oclif/core";
+
+import { compareBundles } from "../../library/bundleSize/index.js";
+import { BaseCommand } from "../../library/commands/base.js";
+
+/**
+ * Compares the two bundles previously collected by `flub generate bundleAnalysisRepo`
+ * (base = --base-label, current = --current-label) and writes human-readable `.txt` and
+ * structured `.json` comparison reports.
+ */
+export default class CheckBundleAnalysisReposComparison extends BaseCommand<
+	typeof CheckBundleAnalysisReposComparison
+> {
+	public static readonly description =
+		"Compare the two bundles previously collected by 'flub generate bundleAnalysisRepo' " +
+		"(base = --base-label, current = --current-label).\n\n" +
+		"To learn more see the detailed documentation at https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md";
+
+	public static readonly examples = [
+		"<%= config.bin %> <%= command.id %>",
+		"<%= config.bin %> <%= command.id %> --base-label some-revision",
+	];
+
+	public static readonly flags = {
+		"base-label": Flags.string({
+			description:
+				"Label subdirectory under compareBundlesOutput/analysis holding the base-side bundle stats. " +
+				"Matches the label 'flub generate bundleAnalysisRepo' saves in revision mode (the sanitized revision).",
+			default: "main",
+		}),
+		"current-label": Flags.string({
+			description:
+				"Label subdirectory under compareBundlesOutput/analysis holding the current-side bundle stats. " +
+				"Matches the label 'flub generate bundleAnalysisRepo' saves in local mode (a timestamped " +
+				"'current_<epoch>').",
+			default: "current",
+		}),
+		...BaseCommand.flags,
+	} as const;
+
+	public async run(): Promise<void> {
+		const { flags } = this;
+		const outputDir = resolve("compareBundlesOutput");
+		compareBundles({
+			analysisDirectory: resolve(outputDir, "analysis"),
+			outputDirectory: outputDir,
+			baseLabel: flags["base-label"],
+			currentLabel: flags["current-label"],
+		});
+	}
+}
diff --git a/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisRepo.ts b/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisRepo.ts
new file mode 100644
index 000000000000..33e1a895ded8
--- /dev/null
+++ b/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisRepo.ts
@@ -0,0 +1,83 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { resolve } from "node:path";
+import { Flags } from "@oclif/core";
+
+import { collectBundle } from "../../library/bundleSize/index.js";
+import { BaseCommand } from "../../library/commands/base.js";
+
+/**
+ * Builds and collects a single bundle, either from the outer enlistment (local mode) or from a
+ * separate inner enlistment checked out to a specific revision (revision mode). The collected
+ * webpack-bundle-analyzer report is saved under
+ * `<package-dir>/compareBundlesOutput/analysis/<label>/analyzer.json` for later
+ * comparison by `flub check bundleAnalysisReposComparison`.
+ */
+export default class GenerateBundleAnalysisRepo extends BaseCommand<
+	typeof GenerateBundleAnalysisRepo
+> {
+	public static readonly description =
+		"Build and collect a bundle, either from the outer enlistment (local mode) or from a " +
+		"separate inner enlistment checked out to a specific revision (revision mode). The outer " +
+		"repo's working tree, branch, and stash are never modified.\n\n" +
+		"To learn more see the detailed documentation at https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md";
+
+	public static readonly examples = [
+		"<%= config.bin %> <%= command.id %>",
+		"<%= config.bin %> <%= command.id %> --revision main",
+		"<%= config.bin %> <%= command.id %> --merge-base main",
+		"<%= config.bin %> <%= command.id %> --revision client_v2.100.0",
+	];
+
+	public static readonly flags = {
+		revision: Flags.string({
+			description:
+				"Collect a bundle for this committish (branch, tag, commit SHA, or any committish " +
+				"like HEAD~2), resolved as-is via 'git rev-parse'. Selects revision mode and is " +
+				"mutually exclusive with --merge-base; omit both to collect the local working tree. " +
+				"Also used as the label (the subdirectory name the bundle's stats are saved under).",
+			exclusive: ["merge-base"],
+		}),
+		"merge-base": Flags.string({
+			description:
+				"Collect a bundle for the merge-base of HEAD and this committish (the fork point). " +
+				"Selects revision mode and is mutually exclusive with --revision. Also used as the " +
+				"label (the subdirectory name the bundle's stats are saved under).",
+			exclusive: ["revision"],
+		}),
+		"package-dir": Flags.string({
+			description:
+				"Package root whose webpack bundles are built and whose analyzer.json is collected.",
+			default: ".",
+		}),
+		...BaseCommand.flags,
+	} as const;
+
+	public async run(): Promise<void> {
+		const { flags } = this;
+
+		const packageDir = resolve(flags["package-dir"]);
+		const analysisDir = resolve(packageDir, "compareBundlesOutput", "analysis");
+
+		const common = {
+			forceCleanBuild: false,
+			packageDir,
+			analysisDir,
+		};
+
+		// The presence of --revision/--merge-base (mutually exclusive) selects revision
+		// mode and how the committish is resolved; with neither, collect the local working tree.
+		const exactRevision = flags.revision;
+		const mergeBaseRevision = flags["merge-base"];
+		if (exactRevision !== undefined) {
+			await collectBundle({ ...common, mode: "revision", revision: exactRevision });
+		} else if (mergeBaseRevision !== undefined) {
+			await collectBundle({ ...common, mode: "revision", mergeBaseOf: mergeBaseRevision });
+		} else {
+			await collectBundle({ ...common, mode: "local" });
+		}
+	}
+}
diff --git a/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisReposWithComparison.ts b/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisReposWithComparison.ts
new file mode 100644
index 000000000000..77bda21328d8
--- /dev/null
+++ b/build-tools/packages/build-cli/src/commands/generate/bundleAnalysisReposWithComparison.ts
@@ -0,0 +1,84 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { resolve } from "node:path";
+import { Flags } from "@oclif/core";
+
+import { collectAndCompareBundles } from "../../library/bundleSize/index.js";
+import { BaseCommand } from "../../library/commands/base.js";
+
+/**
+ * Orchestrates a local bundle collection, a base-revision (merge-base) bundle collection, and a
+ * comparison between them. The outer repo's working tree, branch, and stash are never modified.
+ */
+export default class GenerateBundleAnalysisReposWithComparison extends BaseCommand<
+	typeof GenerateBundleAnalysisReposWithComparison
+> {
+	public static readonly description =
+		"Collect the local bundle and the base-revision (merge-base) bundle, then compare them. " +
+		"The outer repo's working tree, branch, and stash are never modified.\n\n" +
+		"To learn more see the detailed documentation at https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md";
+
+	public static readonly examples = [
+		"<%= config.bin %> <%= command.id %>",
+		"<%= config.bin %> <%= command.id %> --base-revision main",
+		"<%= config.bin %> <%= command.id %> --base-revision client_v2.100.0",
+		"<%= config.bin %> <%= command.id %> --base-revision 18062854f25 --exact-base",
+		"<%= config.bin %> <%= command.id %> --keep-base-repo",
+	];
+
+	public static readonly flags = {
+		"base-revision": Flags.string({
+			description:
+				"Revision to use as the comparison baseline (branch, tag, or commit SHA). The " +
+				"actual base used is the merge-base of HEAD and this revision (the fork point), so " +
+				"worktree-based setups where 'main' is in an unusual location still produce the " +
+				"expected comparison. When omitted, the baseline is auto-detected as the freshest " +
+				"'main' of a remote pointing at microsoft/FluidFramework — the local 'main' is not " +
+				"used, since it may be stale. An explicit value (including 'main') is always honored " +
+				"as given. Pass --exact-base to use the revision as-is instead.",
+			// No default: an omitted base-revision triggers freshest-remote 'main' auto-detection.
+		}),
+		"exact-base": Flags.boolean({
+			description:
+				"Use --base-revision exactly as given (resolved via 'git rev-parse') instead of taking " +
+				"the merge-base with HEAD. Useful for comparing the working tree against a specific " +
+				"commit, e.g. the current commit's parent.",
+			default: false,
+		}),
+		"package-dir": Flags.string({
+			description: "Package root whose webpack bundles are built and compared.",
+			default: ".",
+		}),
+		"keep-base-repo": Flags.boolean({
+			description:
+				"For debugging only: keep the inner base-repo clone after collecting the base " +
+				"bundle. By default the inner repo is deleted once stats are saved, since it can be " +
+				"re-created cheaply via shallow clone on the next run. Pass this flag to inspect the " +
+				"inner repo's working tree or build output (e.g. when a build is failing inside the " +
+				"inner repo).",
+			default: false,
+		}),
+		...BaseCommand.flags,
+	} as const;
+
+	public async run(): Promise<void> {
+		const { flags } = this;
+
+		const packageDir = resolve(flags["package-dir"]);
+		const outputDir = resolve(packageDir, "compareBundlesOutput");
+		const analysisDir = resolve(outputDir, "analysis");
+
+		await collectAndCompareBundles({
+			baseRevision: flags["base-revision"],
+			exactBase: flags["exact-base"],
+			forceCleanBuild: false,
+			keepBaseRepo: flags["keep-base-repo"],
+			packageDir,
+			analysisDir,
+			outputDir,
+		});
+	}
+}
diff --git a/build-tools/packages/build-cli/src/library/bundleSize/collectAndCompareBundles.ts b/build-tools/packages/build-cli/src/library/bundleSize/collectAndCompareBundles.ts
new file mode 100644
index 000000000000..da6c7740c6f3
--- /dev/null
+++ b/build-tools/packages/build-cli/src/library/bundleSize/collectAndCompareBundles.ts
@@ -0,0 +1,118 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { collectBundle } from "./collectBundle.js";
+import { compareBundles } from "./compareBundles.js";
+
+/**
+ * Options for {@link collectAndCompareBundles}.
+ */
+export interface CollectAndCompareBundlesOptions {
+	/**
+	 * Revision to use as the comparison baseline (branch, tag, or commit SHA). By default the
+	 * actual base used is the merge-base of HEAD and this revision (the fork point). When
+	 * {@link CollectAndCompareBundlesOptions.exactBase} is set, this revision is used as-is
+	 * (no merge-base). When omitted, {@link collectBundle} auto-detects the freshest "main" of a
+	 * remote pointing at microsoft/FluidFramework and uses its merge-base with HEAD.
+	 */
+	readonly baseRevision?: string;
+	/**
+	 * Use {@link CollectAndCompareBundlesOptions.baseRevision} as-is (resolved via `rev-parse`)
+	 * instead of taking the merge-base with HEAD. Useful for comparing the working tree against an
+	 * exact commit (e.g. "current vs. its parent") rather than the fork point.
+	 */
+	readonly exactBase?: boolean;
+	/** Run the full workspace clean before each build. */
+	readonly forceCleanBuild: boolean;
+	/** For debugging only: keep the inner base-repo clone after collecting the base bundle. */
+	readonly keepBaseRepo: boolean;
+	/** Package root whose webpack bundles are built and compared. */
+	readonly packageDir: string;
+	/** Directory under which per-label analyzer stats are saved. */
+	readonly analysisDir: string;
+	/** Directory where the comparison reports are written. */
+	readonly outputDir: string;
+}
+
+/**
+ * Orchestrates {@link collectBundle} (local working tree) and {@link collectBundle} (base
+ * revision), then {@link compareBundles}. The base is the merge-base of HEAD and `baseRevision`,
+ * or the revision as-is when `exactBase` is set; when `baseRevision` is omitted, the base defaults
+ * to the freshest canonical "main" at its merge-base with HEAD. Labels are automatic: the local
+ * bundle under a timestamped `current_<epoch>` label and the base under `main`. The scratch inner
+ * repo used to build the base is deleted afterward unless
+ * {@link CollectAndCompareBundlesOptions.keepBaseRepo} is set; the outer repo is never modified.
+ */
+export async function collectAndCompareBundles(
+	options: CollectAndCompareBundlesOptions,
+): Promise<void> {
+	const {
+		baseRevision,
+		exactBase = false,
+		forceCleanBuild,
+		keepBaseRepo,
+		packageDir,
+		analysisDir,
+		outputDir,
+	} = options;
+
+	const innerRepoRoot = resolve(outputDir, "base-repo");
+	const baseLabel = "main";
+
+	try {
+		console.log(`\n${"=".repeat(80)}`);
+		console.log("Collecting local bundle...");
+		console.log("=".repeat(80));
+		const currentLabel = await collectBundle({
+			mode: "local",
+			forceCleanBuild,
+			packageDir,
+			analysisDir,
+		});
+
+		console.log(`\n${"=".repeat(80)}`);
+		console.log(
+			`Collecting base bundle (revision: ${baseRevision ?? "auto-detect freshest main"}, label: ${baseLabel})...`,
+		);
+		console.log("=".repeat(80));
+		await collectBundle({
+			mode: "revision",
+			...(exactBase ? { revision: baseRevision } : { mergeBaseOf: baseRevision }),
+			label: baseLabel,
+			forceCleanBuild,
+			packageDir,
+			analysisDir,
+			baseRepoDir: innerRepoRoot,
+		});
+
+		console.log(`\n${"=".repeat(80)}`);
+		console.log("Running bundle comparison...");
+		console.log("=".repeat(80));
+		compareBundles({
+			analysisDirectory: analysisDir,
+			outputDirectory: outputDir,
+			baseLabel,
+			currentLabel,
+		});
+
+		console.log(`\n${"=".repeat(80)}`);
+		console.log("✓ Bundle collection and comparison complete!");
+		console.log("=".repeat(80));
+
+		// Delete the inner repo last, after the report is written and the completion banner is
+		// shown, so the user has the results before this slow cleanup runs. (Re-created cheaply on
+		// the next run; pass keepBaseRepo to retain it for debugging.)
+		if (!keepBaseRepo && existsSync(innerRepoRoot)) {
+			console.log(`\nDeleting inner base-repo at ${innerRepoRoot}...`);
+			rmSync(innerRepoRoot, { recursive: true, force: true });
+		}
+	} catch (error) {
+		console.error("\n✖ Error:", error instanceof Error ? error.message : String(error));
+		throw error;
+	}
+}
diff --git a/build-tools/packages/build-cli/src/library/bundleSize/collectBundle.ts b/build-tools/packages/build-cli/src/library/bundleSize/collectBundle.ts
new file mode 100644
index 000000000000..7b195eff69a0
--- /dev/null
+++ b/build-tools/packages/build-cli/src/library/bundleSize/collectBundle.ts
@@ -0,0 +1,447 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { execSync } from "node:child_process";
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+
+import { findGitRootSync } from "@fluid-tools/build-infrastructure";
+import { simpleGit } from "simple-git";
+
+import { pickFreshestRemote } from "../git/pickFreshestRemote.js";
+
+/** Filename of the per-label analyzer report. */
+const analyzerFileName = "analyzer.json";
+
+/** Filename of the sidecar recording the SHA a revision-mode report was built from. */
+const revisionMarkerFileName = "revision.txt";
+
+/**
+ * Options for {@link collectBundle}.
+ */
+export interface CollectBundleOptions {
+	/**
+	 * `local`: collect from the outer enlistment that contains {@link CollectBundleOptions.packageDir}.
+	 * `revision`: collect from a separate inner enlistment checked out at the commit resolved from
+	 * {@link CollectBundleOptions.revision} or {@link CollectBundleOptions.mergeBaseOf}.
+	 *
+	 * In `local` mode the outer enlistment is built exactly as it sits on disk: its git state
+	 * (working tree, branch, and revision) is never modified. All checkout/fetch happens only in
+	 * the inner repo used by `revision` mode.
+	 */
+	readonly mode: "local" | "revision";
+	/**
+	 * (revision mode only) Committish (branch, tag, commit SHA, or any committish like `HEAD~2`)
+	 * to build as-is, resolved via `git rev-parse`. Mutually exclusive with
+	 * {@link CollectBundleOptions.mergeBaseOf}. Resolved against the outer repo. Also used as the
+	 * default label.
+	 */
+	readonly revision?: string;
+	/**
+	 * (revision mode only) Committish whose merge-base with HEAD (the fork point) is built instead
+	 * of the committish itself. Mutually exclusive with {@link CollectBundleOptions.revision}.
+	 * Resolved against the outer repo. Also used as the default label.
+	 *
+	 * When neither this nor {@link CollectBundleOptions.revision} is set in revision mode, the base
+	 * defaults to the freshest canonical "main" (see {@link resolveDefaultBaseCommittish}) at its
+	 * merge-base with HEAD.
+	 */
+	readonly mergeBaseOf?: string;
+	/**
+	 * Directory name (under {@link CollectBundleOptions.analysisDir}) to save the collected bundle
+	 * stats into. Sanitized for filesystem use before being applied. Defaults to the sanitized
+	 * revision in revision mode, or a timestamped `current_<epoch>` in local mode.
+	 */
+	readonly label?: string;
+	/**
+	 * Run the full workspace clean (`npm run clean` at the repo root) before building.
+	 */
+	readonly forceCleanBuild: boolean;
+	/**
+	 * Package root whose webpack bundles are built and whose `analyzer.json` is collected.
+	 */
+	readonly packageDir: string;
+	/**
+	 * Directory under which per-label analyzer stats are saved.
+	 */
+	readonly analysisDir: string;
+	/**
+	 * (revision mode only) Directory where the inner enlistment is cloned and built. Defaults to
+	 * `<analysisDir>/base-repo` when not specified.
+	 */
+	readonly baseRepoDir?: string;
+}
+
+// --- Utilities ---
+
+/**
+ * Sanitizes a string for use as a filename.
+ */
+function sanitizeForFileName(value: string): string {
+	return value.replaceAll(/[^\w.-]/g, "_");
+}
+
+/**
+ * Runs a command inheriting stdio, throwing on failure.
+ */
+function run(command: string, cwd: string): void {
+	execSync(command, { cwd, stdio: "inherit" });
+}
+
+// --- Git revision resolution ---
+
+/**
+ * Resolves `rev` to its full commit SHA via `git rev-parse <rev>^{commit}`, or
+ * throws if it cannot be resolved locally. See
+ * {@link https://git-scm.com/docs/git-rev-parse}.
+ */
+async function resolveSha(repoRoot: string, rev: string): Promise<string> {
+	try {
+		const output = await simpleGit(repoRoot).raw(["rev-parse", `${rev}^{commit}`]);
+		const sha = output.trim();
+		if (sha.length > 0) return sha;
+	} catch {
+		// Fall through to the shared error below.
+	}
+	throw new Error(
+		`Could not resolve revision "${rev}" to a commit. ` +
+			`Ensure it exists locally (e.g. "git fetch origin ${rev}").`,
+	);
+}
+
+/**
+ * Resolves the merge-base of `rev` and `otherRev` (default `HEAD`) to a commit SHA via
+ * `git merge-base`, or throws if none can be found locally. See
+ * {@link https://git-scm.com/docs/git-merge-base}.
+ */
+async function resolveMergeBase(
+	repoRoot: string,
+	rev: string,
+	otherRev = "HEAD",
+): Promise<string> {
+	try {
+		const output = await simpleGit(repoRoot).raw(["merge-base", rev, otherRev]);
+		const sha = output.trim();
+		if (sha.length > 0) return sha;
+	} catch {
+		// Fall through to the shared error below.
+	}
+	throw new Error(
+		`Could not find merge-base of "${rev}" and "${otherRev}". ` +
+			`Ensure the revision exists locally (e.g. "git fetch origin ${rev}").`,
+	);
+}
+
+/**
+ * Resolves a committish to a concrete SHA in `outerRepoRoot` — the committish as-is, or (when
+ * `useMergeBase`) its merge-base with HEAD (the fork point).
+ */
+async function resolveBuildRevision(
+	outerRepoRoot: string,
+	committish: string,
+	useMergeBase: boolean,
+): Promise<string> {
+	const resolved = useMergeBase
+		? await resolveMergeBase(outerRepoRoot, committish)
+		: await resolveSha(outerRepoRoot, committish);
+	if (resolved !== committish) {
+		console.log(
+			`Resolved revision "${committish}" to ${useMergeBase ? "merge-base " : ""}${resolved}.`,
+		);
+	}
+	return resolved;
+}
+
+/** Matches a remote URL that points at the canonical microsoft/FluidFramework repo. */
+const canonicalFluidRemoteUrl = /(^|[/:])microsoft\/fluidframework(\.git)?$/i;
+
+/**
+ * Resolves the default base committish used when revision mode is requested without an explicit
+ * `revision`/`mergeBaseOf`: the `main` branch of the freshest remote pointing at
+ * microsoft/FluidFramework (preferred over the local `main`, which may be stale or absent in
+ * worktree setups). Falls back to the local `main` with a warning when no such remote is
+ * configured or fetched.
+ */
+function resolveDefaultBaseCommittish(): string {
+	const remote = pickFreshestRemote("main", (url) => canonicalFluidRemoteUrl.test(url));
+	if (remote === undefined) {
+		console.warn(
+			'Could not auto-detect a remote pointing at microsoft/FluidFramework; using local "main" ' +
+				"as the base, which may be stale.",
+		);
+		return "main";
+	}
+	const ref = `${remote}/main`;
+	console.log(`Auto-detected base revision "${ref}" (freshest "main").`);
+	return ref;
+}
+
+// --- Build steps ---
+
+/**
+ * Enables corepack and installs dependencies in the given repo.
+ */
+function installDependencies(repoRoot: string): void {
+	console.log(`Enabling corepack and installing dependencies in ${repoRoot}...`);
+	run("corepack enable", repoRoot);
+	run("pnpm install", repoRoot);
+}
+
+/**
+ * Runs the repo-root `clean` script, which invokes `fluid-build --task clean` across
+ * the entire client release group. This is the only reliable way to clear stale
+ * build artifacts for every transitive dependency of bundle-size-tests:
+ *
+ * - `fluid-build . --task clean` (scoped to this package) does NOT cascade into dependencies, because the `clean` task in fluidBuild.config.cjs has no `^clean`.
+ * - The per-package `clean` npm scripts only remove outputs in their own package.
+ */
+function cleanWorkspace(repoRoot: string): void {
+	console.log(`\nCleaning workspace build artifacts in ${repoRoot}...`);
+	run("npm run clean", repoRoot);
+}
+
+/**
+ * Compiles this package and its dependencies, then builds its webpack bundles. Uses
+ * `build:compile` (not the full `build`) to skip the lint / docs / api-report tasks, which are
+ * unnecessary here and prone to unrelated failures across revisions.
+ */
+function buildPackage(packageRoot: string): void {
+	console.log(`\nCompiling bundle-size-tests and its dependencies in ${packageRoot}...`);
+	run("npm run build:compile", packageRoot);
+	console.log(`\nBuilding bundles with webpack in ${packageRoot}...`);
+	run("npm run webpack", packageRoot);
+}
+
+// --- Environment prep ---
+
+/**
+ * Records the outer repo's staged diff as `staged-changes.patch` in the per-label
+ * directory so the analysis is reproducible. The patch is never applied; unstaged
+ * changes are excluded, with a warning if any are present.
+ */
+async function captureLocalPatch(repoRoot: string, labelDirectory: string): Promise<void> {
+	const git = simpleGit(repoRoot);
+	const stagedDiff = await git.diff(["--cached"]);
+	const unstagedDiff = await git.diff();
+	if (unstagedDiff.length > 0) {
+		console.warn(
+			`Warning: unstaged changes detected in ${repoRoot}. They will NOT be ` +
+				`captured in the patch alongside this analysis. Stage all changes you ` +
+				`want recorded (e.g. "git add -u") before collecting so the ` +
+				`patch faithfully describes what was bundled.`,
+		);
+	}
+	mkdirSync(labelDirectory, { recursive: true });
+	const patchPath = resolve(labelDirectory, "staged-changes.patch");
+	writeFileSync(patchPath, stagedDiff);
+	console.log(`Saved staged-changes patch to: ${patchPath}`);
+}
+
+/**
+ * Ensures the inner FluidFramework enlistment exists under `innerRepoRoot` and is
+ * checked out (detached) at `sha`.
+ *
+ * @remarks
+ * On first call, clones from the outer enlistment on disk (`--no-tags --no-checkout`),
+ * so no network is involved and every commit in the outer repo — including merge-base
+ * SHAs that aren't branch tips — is already available. Callers pass an already-resolved
+ * SHA, so any committish is handled uniformly. Never touches the outer repo's git state.
+ */
+async function ensureInnerRepoAtRevision(
+	sha: string,
+	outerRepoRoot: string,
+	innerRepoRoot: string,
+): Promise<void> {
+	if (!existsSync(resolve(innerRepoRoot, ".git"))) {
+		mkdirSync(dirname(innerRepoRoot), { recursive: true });
+		console.log(`\nCloning inner repo from ${outerRepoRoot} into ${innerRepoRoot}...`);
+		await simpleGit(dirname(innerRepoRoot)).clone(outerRepoRoot, innerRepoRoot, [
+			"--no-tags",
+			"--no-checkout",
+		]);
+	}
+
+	console.log(`Checking out ${sha} in inner repo...`);
+	await simpleGit(innerRepoRoot).raw(["checkout", "--detach", sha]);
+}
+
+/**
+ * Prepares a revision-mode build: checks out the inner repo at `sha`, installs deps, and returns
+ * the inner repo + package roots. Throws if the package doesn't exist at that revision.
+ */
+async function prepareRevisionBuild(
+	sha: string,
+	outerRepoRoot: string,
+	packageDir: string,
+	innerRepoRoot: string,
+): Promise<{ repoRoot: string; packageRoot: string }> {
+	await ensureInnerRepoAtRevision(sha, outerRepoRoot, innerRepoRoot);
+	// Same package inside the inner repo, via its path relative to the repo root.
+	const packageRoot = resolve(innerRepoRoot, relative(outerRepoRoot, packageDir));
+	if (!existsSync(packageRoot)) {
+		throw new Error(
+			`Expected package not found in inner repo at ${packageRoot}. ` +
+				`The revision "${sha}" may predate this package.`,
+		);
+	}
+	installDependencies(innerRepoRoot);
+	return { repoRoot: innerRepoRoot, packageRoot };
+}
+
+// --- Output ---
+
+/**
+ * Saves webpack-bundle-analyzer's `analyzer.json` report into the per-label directory under
+ * the persistent analysis root. This report is sufficient for the comparison, so the (large)
+ * webpack stats and `build/` outputs do not need to be retained.
+ *
+ * @remarks
+ * Uses copy + unlink instead of `renameSync` because the source and destination
+ * may live on different drives (e.g. `D:` to `C:\Users\<user>\AppData\Local\Temp`),
+ * which causes `renameSync` to fail with `EXDEV` on Windows.
+ *
+ * @param label - Sanitized label for this build (e.g., "main", "client_v2.100.0").
+ * @param sourcePackageRoot - Package root that produced the webpack output.
+ * @param analysisDir - Directory under which per-label stats are saved.
+ */
+function saveStats(label: string, sourcePackageRoot: string, analysisDir: string): void {
+	const analyzerJsonOutputPath = resolve(
+		sourcePackageRoot,
+		"bundleAnalyzerJson",
+		analyzerFileName,
+	);
+
+	const labelDirectory = resolve(analysisDir, label);
+	const destAnalyzerPath = resolve(labelDirectory, analyzerFileName);
+
+	if (!existsSync(analyzerJsonOutputPath)) {
+		throw new Error(
+			`Analyzer report not found at ${analyzerJsonOutputPath}. ` +
+				`Check that webpack ran successfully.`,
+		);
+	}
+
+	mkdirSync(labelDirectory, { recursive: true });
+	copyFileSync(analyzerJsonOutputPath, destAnalyzerPath);
+	unlinkSync(analyzerJsonOutputPath);
+	console.log(`Saved analyzer report to: ${destAnalyzerPath}`);
+}
+
+/**
+ * Logs the standard "collection complete" banner.
+ */
+function logCollectionComplete(mode: string, label: string, labelDirectory: string): void {
+	console.log(`\n${"=".repeat(80)}`);
+	console.log(`✓ Bundle collection complete (mode: ${mode}, label: ${label}).`);
+	console.log(`  Stats directory: ${labelDirectory}`);
+	console.log("=".repeat(80));
+}
+
+// --- Orchestrator ---
+
+/**
+ * Collects a single bundle from either the outer enlistment (local mode) or a
+ * separate inner enlistment checked out to a specific revision (revision mode),
+ * and returns the (sanitized) label its stats were saved under.
+ *
+ * @remarks
+ * In revision mode, {@link CollectBundleOptions.revision} is built as-is and
+ * {@link CollectBundleOptions.mergeBaseOf} at its merge-base with HEAD (the fork point); when
+ * neither is given, the base defaults to the freshest canonical "main" at its merge-base with
+ * HEAD (see {@link resolveDefaultBaseCommittish}). The resolved SHA is recorded in a sidecar
+ * `revision.txt`, letting a later run with the same SHA reuse the cached report (unless
+ * {@link CollectBundleOptions.forceCleanBuild} is set). Builds happen in the inner repo (see
+ * {@link ensureInnerRepoAtRevision}).
+ *
+ * In local mode the working tree is built exactly as it sits on disk; the only side effect is the
+ * up-front staged-patch record (see {@link captureLocalPatch}). The outer repo's git state is
+ * never modified.
+ */
+export async function collectBundle(options: CollectBundleOptions): Promise<string> {
+	const { mode, revision, mergeBaseOf, forceCleanBuild, packageDir, analysisDir } = options;
+
+	const outerRepoRoot = findGitRootSync(packageDir);
+	const innerRepoRoot = options.baseRepoDir ?? resolve(analysisDir, "base-repo");
+
+	// In revision mode, decide what to build, how to resolve it, and resolve it to a SHA:
+	//   - revision    → build that committish as-is (rev-parse).
+	//   - mergeBaseOf → build its merge-base with HEAD (the fork point).
+	//   - neither     → default to the freshest canonical "main" at its merge-base with HEAD. This
+	//     is the orchestrator's pass-through of an omitted base: the local "main" may be stale, so
+	//     "<remote>/main" is auto-detected, and an unspecified base means "where this branch forked
+	//     from upstream main".
+	let committish: string | undefined;
+	let resolvedRevision: string | undefined;
+	if (mode === "revision") {
+		let useMergeBase: boolean;
+		if (revision !== undefined) {
+			committish = revision;
+			useMergeBase = false;
+		} else if (mergeBaseOf !== undefined) {
+			committish = mergeBaseOf;
+			useMergeBase = true;
+		} else {
+			committish = resolveDefaultBaseCommittish();
+			useMergeBase = true;
+		}
+		resolvedRevision = await resolveBuildRevision(outerRepoRoot, committish, useMergeBase);
+	}
+
+	const label = sanitizeForFileName(
+		options.label ?? committish ?? `current_${Math.floor(Date.now() / 1000)}`,
+	);
+	const labelDirectory = resolve(analysisDir, label);
+
+	// Reuse the cached report when the resolved SHA matches a previous revision-mode run.
+	if (resolvedRevision !== undefined && !forceCleanBuild) {
+		const analyzerPath = resolve(labelDirectory, analyzerFileName);
+		const markerPath = resolve(labelDirectory, revisionMarkerFileName);
+		const cachedRevision = existsSync(markerPath)
+			? readFileSync(markerPath, "utf8").trim()
+			: undefined;
+		if (existsSync(analyzerPath) && cachedRevision === resolvedRevision) {
+			console.log(`Reusing cached bundle (revision: ${resolvedRevision}, label: ${label}).`);
+			console.log(`  Report: ${analyzerPath}`);
+			logCollectionComplete(mode, label, labelDirectory);
+			return label;
+		}
+	}
+
+	// Prepare the build environment: the local working tree, or the inner repo at the revision.
+	let repoRoot = outerRepoRoot;
+	let packageRoot = packageDir;
+	if (mode === "local") {
+		await captureLocalPatch(outerRepoRoot, labelDirectory);
+	} else {
+		({ repoRoot, packageRoot } = await prepareRevisionBuild(
+			resolvedRevision as string,
+			outerRepoRoot,
+			packageDir,
+			innerRepoRoot,
+		));
+	}
+
+	// Clean (if needed) and build the bundles.
+	if (forceCleanBuild) {
+		cleanWorkspace(repoRoot);
+	}
+	buildPackage(packageRoot);
+
+	// Save stats, recording the SHA so a later run against the same revision can skip the rebuild.
+	saveStats(label, packageRoot, analysisDir);
+	if (resolvedRevision !== undefined) {
+		writeFileSync(resolve(labelDirectory, revisionMarkerFileName), `${resolvedRevision}\n`);
+	}
+
+	logCollectionComplete(mode, label, labelDirectory);
+	return label;
+}
diff --git a/build-tools/packages/build-cli/src/library/bundleSize/compareBundles.ts b/build-tools/packages/build-cli/src/library/bundleSize/compareBundles.ts
new file mode 100644
index 000000000000..de814ac8b761
--- /dev/null
+++ b/build-tools/packages/build-cli/src/library/bundleSize/compareBundles.ts
@@ -0,0 +1,576 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import type { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
+
+import { compareJsonReports } from "./compareJsonReports.js";
+import type { BundlesComparison } from "./types.js";
+
+/**
+ * A single node from webpack-bundle-analyzer's JSON report
+ * (`analyzerMode: "json"`). Each top-level node is an emitted asset;
+ * `parsedSize`/`gzipSize` are the minified and gzipped sizes of the asset as it
+ * ships, and `isInitialByEntrypoint` maps each entrypoint the asset is an
+ * initial chunk of to `true`.
+ */
+type AnalyzerNode = BundleAnalyzerPlugin.JsonReportItem;
+
+/**
+ * Options for {@link compareBundles}.
+ */
+export interface CompareBundlesOptions {
+	/** Parent directory containing analyzer.json files at `{label}/analyzer.json`. */
+	readonly analysisDirectory: string;
+	/** Directory where the `.txt` and `.json` comparison reports are written. */
+	readonly outputDirectory: string;
+	/** Label subdirectory under {@link CompareBundlesOptions.analysisDirectory} holding the base-side bundle stats. */
+	readonly baseLabel: string;
+	/** Label subdirectory under {@link CompareBundlesOptions.analysisDirectory} holding the current-side bundle stats. */
+	readonly currentLabel: string;
+}
+
+/**
+ * One comparison row: a named measurement — an asset, owning package, or
+ * synthetic composition bucket — sized on both the base and current
+ * side, with `diff = current - base`. Every output set in the report is a list
+ * of these, so they share one factory ({@link makeRow}) and one renderer
+ * ({@link renderTable}). The unit of `base`/`current` depends on which list the
+ * row lives in: parsed bytes for most, gzip bytes for `gzipChangedAssets`.
+ */
+interface ComparisonRow {
+	name: string;
+	base: number;
+	current: number;
+	diff: number;
+}
+
+/** Builds a {@link ComparisonRow}, deriving `diff` from the two sides. */
+function makeRow(name: string, base: number, current: number): ComparisonRow {
+	return { name, base, current, diff: current - base };
+}
+
+/** Structured comparison report written to the JSON output file. */
+interface ComparisonReport {
+	/** ISO timestamp of when the comparison was generated. */
+	comparedAt: string;
+	/** Label subdirectory holding the base-side bundle stats. */
+	baseLabel: string;
+	/** Label subdirectory holding the current-side bundle stats. */
+	currentLabel: string;
+	/** Parent directory containing the per-label bundle stats. */
+	analysisDirectory: string;
+	/** Parsed-size rows for every emitted JS asset (changed or not). */
+	assets: ComparisonRow[];
+	/** Gzip-size rows, limited to assets whose gzip size changed. */
+	gzipChangedAssets: ComparisonRow[];
+	/**
+	 * Headline composition buckets, each pinned to a real entrypoint (never
+	 * summed across entrypoints); see {@link bucketDefinitions}.
+	 */
+	packageBuckets: ComparisonRow[];
+	/**
+	 * Full per-package breakdown. Format: one row per owning package, sorted by current
+	 * size descending.
+	 */
+	packages: ComparisonRow[];
+}
+
+// --- Loading analyzer reports & asset helpers ---
+
+/**
+ * Loads webpack-bundle-analyzer's JSON report for a label. If the file does not
+ * exist, returns an empty array and logs a warning.
+ */
+function loadAnalyzer(analysisDirectory: string, label: string): AnalyzerNode[] {
+	const analyzerFilePath = resolve(analysisDirectory, label, "analyzer.json");
+	if (!existsSync(analyzerFilePath)) {
+		console.warn(
+			`Warning: Analyzer report not found at "${analyzerFilePath}". ` +
+				`Returning empty stats (all assets will be treated as size 0).`,
+		);
+		return [];
+	}
+	return JSON.parse(readFileSync(analyzerFilePath, "utf8")) as AnalyzerNode[];
+}
+
+/** Whether an asset name is an emitted `.js` asset (excluding source maps). */
+function isJsAssetName(name: string): boolean {
+	return name.endsWith(".js") && !name.endsWith(".map");
+}
+
+// --- Module -> owning-package attribution ---
+
+/**
+ * Strips webpack's module-concatenation (scope-hoisting) wrapper prefix from a
+ * module `path`, returning the path of the *real* module.
+ *
+ * When webpack concatenates modules, every concatenated leaf's `path` is
+ * prefixed with the concatenation root, e.g.:
+ *
+ * ```
+ * ./../../packages/framework/fluid-framework/lib/index.js + 268 modules (concatenated)/../../packages/dds/tree/lib/treeFactory.js
+ * ```
+ *
+ * The text before the last `(concatenated)/` is the wrapper (the barrel that
+ * pulled the module in); the text after it is the real module. Naively reading
+ * the package from such a path picks up the wrapper (here `fluid-framework`)
+ * instead of the true owner (`tree`), so all hoisted modules collapse onto the
+ * barrel package. Anchoring on the last `(concatenated)/` recovers the real
+ * module path. Paths without the marker are returned unchanged.
+ */
+function stripConcatenationWrapper(modulePath: string): string {
+	const normalized = modulePath.replace(/\\/g, "/");
+	const marker = "(concatenated)/";
+	const markerIndex = normalized.lastIndexOf(marker);
+	return markerIndex >= 0 ? normalized.slice(markerIndex + marker.length) : normalized;
+}
+
+/**
+ * Locates the path segment that identifies a module's owning package: the
+ * *last* `node_modules/` (so a package's own nested dependencies are attributed
+ * to themselves), or failing that the *first* `packages/` (the workspace source
+ * layout). Returns the matched marker and its index, or `undefined` for paths
+ * belonging to neither (e.g. the synthetic entrypoint's own modules). Both
+ * {@link packageFromModulePath} and {@link canonicalModuleKey} anchor here.
+ */
+function moduleAnchor(
+	modulePath: string,
+): { marker: "node_modules/" | "packages/"; index: number } | undefined {
+	const nodeModulesIndex = modulePath.lastIndexOf("node_modules/");
+	if (nodeModulesIndex >= 0) return { marker: "node_modules/", index: nodeModulesIndex };
+	const packagesIndex = modulePath.indexOf("packages/");
+	if (packagesIndex >= 0) return { marker: "packages/", index: packagesIndex };
+	return undefined;
+}
+
+/**
+ * Extracts the owning npm package name from a webpack-bundle-analyzer module
+ * `path`. Handles the three shapes that appear in this repo's bundles:
+ *
+ * - **Third-party (pnpm):** `.../node_modules/.pnpm/<key>/node_modules/<pkg>/...` —
+ * the name after the *last* `node_modules/` is used, so a package's own nested
+ * dependencies are attributed to themselves. Scoped packages keep their `@scope/name`.
+ * - **Workspace packages:** `.../packages/<group>/<name>/...` — these are the
+ * Fluid Framework source packages, published as `@fluidframework/<name>`.
+ * - **App/entry code:** anything else (e.g. the bundle-size-tests synthetic
+ * entrypoint's own `./src/*.ts` modules) is grouped under `(app/entry)`.
+ *
+ * Concatenated-module wrapper prefixes are stripped first (see
+ * {@link stripConcatenationWrapper}) so scope-hoisted modules are attributed to
+ * their true owning package rather than the concatenating barrel.
+ */
+function packageFromModulePath(modulePath: string): string {
+	const normalized = stripConcatenationWrapper(modulePath);
+	const anchor = moduleAnchor(normalized);
+	if (anchor === undefined) return "(app/entry)";
+	const parts = normalized.slice(anchor.index + anchor.marker.length).split("/");
+	if (anchor.marker === "node_modules/") {
+		return parts[0].startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0];
+	}
+	// Workspace layout: packages/<group>/<name>/lib/...
+	return parts.length >= 2 ? `@fluidframework/${parts[1]}` : "(app/entry)";
+}
+
+/**
+ * Produces a stable identity for a module so the same source module reached via
+ * different entrypoints (webpack prefixes the path with the concatenating
+ * entry, e.g. `./src/sharedTree.ts + 384 modules (concatenated)/...`) collapses
+ * to a single key. The concatenation wrapper prefix is stripped first (see
+ * {@link stripConcatenationWrapper}), then anchoring at the owning-package
+ * segment (see {@link moduleAnchor}) removes any remaining per-entry prefix,
+ * giving "unique module" dedupe semantics.
+ */
+function canonicalModuleKey(modulePath: string): string {
+	const normalized = stripConcatenationWrapper(modulePath);
+	const anchor = moduleAnchor(normalized);
+	return anchor === undefined ? normalized : normalized.slice(anchor.index);
+}
+
+/**
+ * Walks a set of asset nodes' `groups` module trees and sums parsed sizes per
+ * owning package. Modules are deduplicated by {@link canonicalModuleKey} using
+ * a single shared `seen` set, so a module reached more than once within this
+ * asset set is counted exactly once.
+ *
+ * @remarks
+ * A node with children is an aggregate (asset, directory, or concatenated
+ * wrapper) whose `parsedSize` is just the sum of its descendants. The walk
+ * recurses into the children and skips the parent so those bytes are not
+ * double-counted; only childless leaf modules carry a real path and standalone
+ * size.
+ */
+function accumulatePackageSizes(assets: AnalyzerNode[]): Map<string, number> {
+	const perPackage = new Map<string, number>();
+	const seen = new Set<string>();
+
+	const visit = (node: AnalyzerNode): void => {
+		if (node.groups !== undefined && node.groups.length > 0) {
+			for (const child of node.groups) visit(child);
+			return;
+		}
+		// Leaf module node.
+		if (node.path === undefined) return;
+		const key = canonicalModuleKey(node.path);
+		if (seen.has(key)) return;
+		seen.add(key);
+		const packageName = packageFromModulePath(node.path);
+		perPackage.set(packageName, (perPackage.get(packageName) ?? 0) + (node.parsedSize ?? 0));
+	};
+
+	for (const node of assets) {
+		visit(node);
+	}
+	return perPackage;
+}
+
+// --- Composition buckets ---
+
+/** Named entrypoint assets the buckets and per-package breakdown are measured from. */
+const entrypointAssets = {
+	/** Entrypoint asset for SharedTree's own bundle (`bundle-size-tests/src/sharedTree.ts`). */
+	sharedTree: "sharedTree.js",
+} as const;
+
+/**
+ * Per-package parsed sizes for a single named entrypoint asset. Walks only that
+ * one asset's module tree, deduping shared modules within it, so every package
+ * is counted exactly once as it actually appears in that real bundle. Returns an
+ * empty map (and warns) if the asset is missing, rather than falling back to a
+ * misleading whole-bundle total.
+ */
+function packageSizesForAsset(nodes: AnalyzerNode[], assetLabel: string): Map<string, number> {
+	const asset = nodes.find((node) => node.label === assetLabel);
+	if (asset === undefined) {
+		console.warn(
+			`Warning: entrypoint asset "${assetLabel}" not found; reporting it as size 0.`,
+		);
+		return new Map();
+	}
+	return accumulatePackageSizes([asset]);
+}
+
+/** Diffs two per-package size maps into {@link ComparisonRow}s, sorted by current size descending (ties broken by name). */
+function diffPackageSizes(
+	base: Map<string, number>,
+	current: Map<string, number>,
+): ComparisonRow[] {
+	// Missing on a side is treated as size 0 (added/removed package).
+	return [...new Set([...base.keys(), ...current.keys()])]
+		.map((name) => makeRow(name, base.get(name) ?? 0, current.get(name) ?? 0))
+		.sort((a, b) => b.current - a.current || a.name.localeCompare(b.name));
+}
+
+/** Whether a package name belongs to Fluid Framework (any `@fluidframework/*` or `@fluid-*`). */
+function isFluidPackage(name: string): boolean {
+	return name.startsWith("@fluidframework/") || name.startsWith("@fluid-");
+}
+
+/** Whether a package's bytes are third-party (not a Fluid library, and not the entry file's own `(app/entry)` code). */
+function isThirdPartyPackage(name: string): boolean {
+	return !isFluidPackage(name) && name !== "(app/entry)";
+}
+
+/**
+ * One headline bucket: which entrypoint to measure, and whether to fold in that
+ * bundle's third-party deps on top of its Fluid Framework bytes. Add a row to
+ * {@link bucketDefinitions} to add a bucket — the rendering is fully
+ * data-driven.
+ */
+interface BucketDefinition {
+	label: string;
+	/** Entrypoint asset whose deduplicated module tree this bucket is measured from. */
+	asset: string;
+	/** Whether to also include every third-party package in the same bundle. */
+	withThirdParty: boolean;
+}
+
+/**
+ * Headline buckets, each pinned to a real entrypoint — never summed across
+ * entrypoints, which would double-count shared modules. Each bucket sums every
+ * Fluid Framework package in its bundle (the entrypoint's full Fluid footprint,
+ * not just one package); the companion `+ 3rd-party deps` bucket additionally
+ * folds in every third-party package in that same bundle.
+ *
+ * @remarks
+ * Third-party bytes can't be split between the libraries that pull them in as the flat
+ * per-package data has no dependency graph. The entry file's own code — the small
+ * `bundle-size-tests` module that imports the package being measured, reported
+ * as `(app/entry)` — is never counted, since it isn't shipped library code (see
+ * {@link isThirdPartyPackage}).
+ */
+const bucketDefinitions: readonly BucketDefinition[] = [
+	{
+		label: "SharedTree + 3rd-party deps",
+		asset: entrypointAssets.sharedTree,
+		withThirdParty: true,
+	},
+	{
+		label: "SharedTree",
+		asset: entrypointAssets.sharedTree,
+		withThirdParty: false,
+	},
+];
+
+/**
+ * Computes the per-package outputs from the raw nodes: the headline composition
+ * buckets ({@link bucketDefinitions}) and the full per-package breakdown for the
+ * `sharedTree` entrypoint. Both derive from the same
+ * entrypoint-scoped, diffed per-package rows, so each asset's rows are computed
+ * once (memoized) and reused across every bucket that references it and the full
+ * breakdown. Each bucket sums its bundle's Fluid packages (plus third-party deps
+ * when asked).
+ */
+function comparePackages(
+	baseNodes: AnalyzerNode[],
+	currentNodes: AnalyzerNode[],
+): { packageBuckets: ComparisonRow[]; packages: ComparisonRow[] } {
+	const rowsByAsset = new Map<string, ComparisonRow[]>();
+	const rowsForAsset = (asset: string): ComparisonRow[] => {
+		let rows = rowsByAsset.get(asset);
+		if (rows === undefined) {
+			rows = diffPackageSizes(
+				packageSizesForAsset(baseNodes, asset),
+				packageSizesForAsset(currentNodes, asset),
+			);
+			rowsByAsset.set(asset, rows);
+		}
+		return rows;
+	};
+
+	const packageBuckets = bucketDefinitions.map((def) => {
+		let base = 0;
+		let current = 0;
+		for (const row of rowsForAsset(def.asset)) {
+			if (isFluidPackage(row.name) || (def.withThirdParty && isThirdPartyPackage(row.name))) {
+				base += row.base;
+				current += row.current;
+			}
+		}
+		return makeRow(def.label, base, current);
+	});
+
+	return {
+		packageBuckets,
+		packages: rowsForAsset(entrypointAssets.sharedTree),
+	};
+}
+
+// --- Comparison computation ---
+
+/**
+ * Per-asset rows for one size field of every emitted JS asset (source maps
+ * excluded), sorted by name. Sizes come straight from the shared
+ * {@link compareJsonReports} primitive; an asset present on only one side is
+ * treated as size 0 on the other. Drives both the parsed-size and gzip-size
+ * asset tables.
+ */
+function compareAssetField(
+	bundleComparison: BundlesComparison,
+	field: "parsedSize" | "gzipSize",
+): ComparisonRow[] {
+	return Object.keys(bundleComparison)
+		.filter(isJsAssetName)
+		.sort()
+		.map((name) => {
+			const { base, compare } = bundleComparison[name];
+			return makeRow(name, base?.[field] ?? 0, compare?.[field] ?? 0);
+		});
+}
+
+/**
+ * Computes a structured comparison between the base and current bundles.
+ * Pure data: reads each side's `analyzer.json` (webpack-bundle-analyzer's JSON
+ * report) and does no other I/O. Parsed and gzip sizes come straight from that
+ * report, so no webpack stats decompression or on-disk gzipping is needed. Each
+ * output set is produced by its own focused helper:
+ *
+ * - {@link compareAssetField} — per-asset (parsed and gzip).
+ * - {@link comparePackages} — the headline buckets and full per-package
+ * breakdown, sharing one memoized per-asset row computation.
+ */
+function computeBundleComparison(options: CompareBundlesOptions): ComparisonReport {
+	const { baseLabel, currentLabel, analysisDirectory } = options;
+
+	const baseNodes = loadAnalyzer(analysisDirectory, baseLabel);
+	const currentNodes = loadAnalyzer(analysisDirectory, currentLabel);
+
+	// Shared primitive: per-asset { base?, compare? } size data keyed by asset
+	// label, restricted to JS assets (excluding source maps) by the helpers below.
+	const bundleComparison = compareJsonReports(baseNodes, currentNodes);
+	const assets = compareAssetField(bundleComparison, "parsedSize");
+
+	// The gzip table reports only the assets whose gzip size actually changed.
+	const gzipChangedAssets = compareAssetField(bundleComparison, "gzipSize").filter(
+		(row) => row.diff !== 0,
+	);
+
+	const { packageBuckets, packages } = comparePackages(baseNodes, currentNodes);
+
+	return {
+		comparedAt: new Date().toISOString(),
+		baseLabel,
+		currentLabel,
+		analysisDirectory,
+		assets,
+		gzipChangedAssets,
+		packageBuckets,
+		packages,
+	};
+}
+
+// --- Text rendering ---
+
+/** Formats a signed diff as "-", "+N", or "-N". */
+function formatDiff(diff: number): string {
+	if (diff === 0) return "-";
+	return diff > 0 ? `+${diff}` : `${diff}`;
+}
+
+/** Column widths shared by every comparison table. */
+const nameColumnWidth = 40;
+const valueColumnWidth = 12;
+const percentColumnWidth = 10;
+
+/** One rendered section: a banner heading over a {@link ComparisonRow} table. */
+interface TableSpec {
+	/** Banner text (rendered inside `=== ... ===`). */
+	heading: string;
+	/** Header for the name column (e.g. "Asset" or "Package"). */
+	nameHeader: string;
+	/** Rows to render. */
+	rows: ComparisonRow[];
+	/** Append a base-relative "% Change" column. */
+	showPercent?: boolean;
+	/** Flag changed rows with a trailing " *". */
+	markChanged?: boolean;
+}
+
+/** Renders one {@link TableSpec} (banner, header, separator, rows) via `emit`. */
+function renderTable(emit: (line?: string) => void, spec: TableSpec): void {
+	const { heading, nameHeader, rows, showPercent = false, markChanged = false } = spec;
+	const cell = (value: string): string => value.padStart(valueColumnWidth);
+
+	let header =
+		nameHeader.padEnd(nameColumnWidth) + cell("Base") + cell("Current") + cell("Diff");
+	if (showPercent) header += "% Change".padStart(percentColumnWidth);
+
+	emit();
+	emit(`=== ${heading} ===`);
+	emit(header);
+	emit("-".repeat(header.length));
+	for (const row of rows) {
+		const name = row.name + (markChanged && row.diff !== 0 ? " *" : "");
+		let line =
+			name.padEnd(nameColumnWidth) +
+			cell(String(row.base)) +
+			cell(String(row.current)) +
+			cell(formatDiff(row.diff));
+		if (showPercent) {
+			const percent =
+				row.base > 0 && row.diff !== 0 ? `${((row.diff / row.base) * 100).toFixed(1)}%` : "";
+			line += percent.padStart(percentColumnWidth);
+		}
+		emit(line);
+	}
+}
+
+/**
+ * Renders a {@link ComparisonReport} as a human-readable text report.
+ * Also echoes each line to the console.
+ *
+ * @remarks
+ * Sections are emitted in order: asset-level (per-emitted-file sizes) then
+ * package-level (composition buckets followed by the full breakdown). The
+ * package-level sections are each scoped to a single real entrypoint asset
+ * (see {@link bucketDefinitions} / {@link ComparisonReport}).
+ */
+function renderAsText(report: ComparisonReport): string {
+	const lines: string[] = [];
+	const emit = (line = ""): void => {
+		console.log(line);
+		lines.push(line);
+	};
+
+	emit();
+	emit(`=== Bundle Size Comparison: ${report.baseLabel} -> ${report.currentLabel} ===`);
+
+	// Asset-level sections: per-emitted-file sizes, independent of entrypoints.
+	renderTable(emit, {
+		heading: "All assets (parsed size in bytes)",
+		nameHeader: "Asset",
+		rows: report.assets,
+		showPercent: true,
+		markChanged: true,
+	});
+	if (report.gzipChangedAssets.length > 0) {
+		renderTable(emit, {
+			heading: "Gzip sizes for changed assets",
+			nameHeader: "Asset",
+			rows: report.gzipChangedAssets,
+		});
+	}
+
+	// Package-level sections: composition buckets, then the full breakdown.
+	renderTable(emit, {
+		heading: "Bundle composition by category (parsed size in bytes)",
+		nameHeader: "Package",
+		rows: report.packageBuckets,
+		showPercent: true,
+	});
+	renderTable(emit, {
+		heading: "Per-package parsed-size comparison",
+		nameHeader: "Package",
+		rows: report.packages,
+		showPercent: true,
+	});
+
+	return `${lines.join("\n")}\n`;
+}
+
+// --- File output ---
+
+function sanitizeForFileName(value: string): string {
+	return value.replaceAll(/[^\w.-]/g, "_");
+}
+
+/**
+ * Writes the text and JSON report files. File names are derived from sanitized
+ * branch names (e.g. "compare-main-to-client_v2.100.0.txt" and ".json").
+ */
+function writeOutputFiles(
+	outputDirectory: string,
+	report: ComparisonReport,
+	textContent: string,
+): void {
+	mkdirSync(outputDirectory, { recursive: true });
+
+	const baseSuffix = sanitizeForFileName(report.baseLabel);
+	const currentSuffix = sanitizeForFileName(report.currentLabel);
+	const outputBaseName = `compare-${baseSuffix}-to-${currentSuffix}`;
+	const textOutputPath = resolve(outputDirectory, `${outputBaseName}.txt`);
+	const jsonOutputPath = resolve(outputDirectory, `${outputBaseName}.json`);
+
+	writeFileSync(textOutputPath, textContent);
+	writeFileSync(jsonOutputPath, `${JSON.stringify(report, undefined, 2)}\n`);
+
+	console.log("\nWrote comparison outputs:");
+	console.log(`  ${textOutputPath}`);
+	console.log(`  ${jsonOutputPath}`);
+}
+
+/**
+ * Compares the two bundles previously collected into
+ * `{analysisDirectory}/{baseLabel}/analyzer.json` and
+ * `{analysisDirectory}/{currentLabel}/analyzer.json`, then writes human-readable
+ * `.txt` and structured `.json` comparison reports to `outputDirectory`.
+ */
+export function compareBundles(options: CompareBundlesOptions): void {
+	const report = computeBundleComparison(options);
+	const textContent = renderAsText(report);
+	writeOutputFiles(options.outputDirectory, report, textContent);
+}
diff --git a/build-tools/packages/build-cli/src/library/bundleSize/compareJsonReports.ts b/build-tools/packages/build-cli/src/library/bundleSize/compareJsonReports.ts
index e2fd37e387f1..96941c831f45 100644
--- a/build-tools/packages/build-cli/src/library/bundleSize/compareJsonReports.ts
+++ b/build-tools/packages/build-cli/src/library/bundleSize/compareJsonReports.ts
@@ -40,7 +40,7 @@ function jsonReportToBundleSizes(
  * Bundles present only in one side encode added/removed via field presence
  * (see {@link BundlesComparison}).
  */
-function compareJsonReports(
+export function compareJsonReports(
 	base: BundleAnalyzerPlugin.JsonReport | undefined,
 	compare: BundleAnalyzerPlugin.JsonReport | undefined,
 ): BundlesComparison {
diff --git a/build-tools/packages/build-cli/src/library/bundleSize/index.ts b/build-tools/packages/build-cli/src/library/bundleSize/index.ts
index 6eefef9358dd..ff3377f7db99 100644
--- a/build-tools/packages/build-cli/src/library/bundleSize/index.ts
+++ b/build-tools/packages/build-cli/src/library/bundleSize/index.ts
@@ -3,6 +3,12 @@
  * Licensed under the MIT License.
  */
 
+export {
+	type CollectAndCompareBundlesOptions,
+	collectAndCompareBundles,
+} from "./collectAndCompareBundles.js";
+export { type CollectBundleOptions, collectBundle } from "./collectBundle.js";
+export { type CompareBundlesOptions, compareBundles } from "./compareBundles.js";
 export { compareJsonReportsByPackage } from "./compareJsonReports.js";
 export { extractAnalyzerJsonsFromArtifact } from "./extractAnalyzerJsonsFromArtifact.js";
 export {
@@ -14,7 +20,7 @@ export {
 	readAnalyzerJsonsFromFileSystem,
 } from "./readAnalyzerJsonsFromFileSystem.js";
 export { sourcePackageFromAnalyzerPath } from "./sourcePackageFromAnalyzerPath.js";
-export {
+export type {
 	AnalyzerJsonByPackage,
 	BundleData,
 	BundlesComparison,
diff --git a/examples/utils/bundle-size-tests/README.md b/examples/utils/bundle-size-tests/README.md
index 195341201f95..88f7f7d6b787 100644
--- a/examples/utils/bundle-size-tests/README.md
+++ b/examples/utils/bundle-size-tests/README.md
@@ -2,6 +2,51 @@
 
 This package bundles some commonly used Fluid packages. The webpack output of this package is used for bundle analysis in our ongoing effort to make Fluid fast!
 
+## Comparing bundle sizes
+
+This package can measure how a change affects its webpack bundle by building the
+bundle on two different revisions and diffing the per-asset and per-entrypoint
+sizes, so regressions (or wins) are easy to spot before pushing.
+
+The workflow is implemented as the bundle-analysis commands (`flub generate
+bundleAnalysisRepo`, `flub check bundleAnalysisReposComparison`, and the
+`flub generate bundleAnalysisReposWithComparison` orchestrator) in
+[`@fluid-tools/build-cli`](../../../build-tools/packages/build-cli); this package
+just invokes it with the appropriate context. See
+[bundleAnalysisRepoDetails.md](../../../build-tools/packages/build-cli/docs/bundleAnalysisRepoDetails.md)
+for how the commands fit together and how to read the comparison report.
+
+### Running
+
+The orchestrator is exposed as the `compare:bundles` npm script:
+
+```sh
+npm run compare:bundles
+```
+
+To pass flags, forward them after `--`:
+
+```sh
+npm run compare:bundles -- --base-revision client_v2.100.0
+```
+
+This compares your working tree against the merge-base of `HEAD` and `main` —
+i.e. the point your branch forked from — so the diff reflects only your own
+changes, not unrelated commits that have since landed on `main`.
+
+### Outputs
+
+Everything is written under `compareBundlesOutput/` (gitignored):
+
+- Each label's `analyzer.json` is saved under `compareBundlesOutput/analysis/<label>/`.
+- Comparison reports (`.txt` and `.json`) are written to the root of
+  `compareBundlesOutput/`.
+- The base revision is built in a scratch clone under
+  `compareBundlesOutput/base-repo/`, which is deleted automatically unless
+  `--keep-base-repo` is passed.
+
+The whole `compareBundlesOutput/` directory is removed by `npm run clean`.
+
 <!-- AUTO-GENERATED-CONTENT:START (README_FOOTER) -->
 
 <!-- prettier-ignore-start -->
diff --git a/examples/utils/bundle-size-tests/package.json b/examples/utils/bundle-size-tests/package.json
index d92ca9647e76..18ec112567f9 100644
--- a/examples/utils/bundle-size-tests/package.json
+++ b/examples/utils/bundle-size-tests/package.json
@@ -20,7 +20,8 @@
 		"build:test:esm": "tsc --project ./src/test/tsconfig.json",
 		"check:biome": "biome check .",
 		"check:format": "npm run check:biome",
-		"clean": "rimraf --glob build dist lib bundleAnalysis bundleAnalyzerJson \"**/*.tsbuildinfo\" \"**/*.build.log\" nyc",
+		"clean": "rimraf --glob build dist lib bundleAnalysis bundleAnalyzerJson compareBundlesOutput \"**/*.tsbuildinfo\" \"**/*.build.log\" nyc",
+		"compare:bundles": "flub generate bundleAnalysisReposWithComparison",
 		"eslint": "eslint --quiet --format stylish src",
 		"eslint:fix": "eslint --quiet --format stylish src --fix --fix-type problem,suggestion,layout",
 		"explore:tree": "fluid-build . --task webpack && source-map-explorer ./build/sharedTree.js --html bundleAnalysis/reportTree.html",
@@ -54,6 +55,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "~2.4.5",
 		"@cerner/duplicate-package-checker-webpack-plugin": "~2.3.0",
+		"@fluid-tools/build-cli": "catalog:buildTools",
 		"@fluid-tools/version-tools": "catalog:buildTools",
 		"@fluidframework/build-common": "^2.0.3",
 		"@fluidframework/build-tools": "catalog:buildTools",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d8ae6337157c..d9446bfec2b7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4840,6 +4840,9 @@ importers:
       '@cerner/duplicate-package-checker-webpack-plugin':
         specifier: ~2.3.0
         version: 2.3.0(webpack@5.103.0)
+      '@fluid-tools/build-cli':
+        specifier: catalog:buildTools
+        version: 0.65.0(@types/node@22.19.17)(webpack-cli@5.1.4)
       '@fluid-tools/version-tools':
         specifier: catalog:buildTools
         version: 0.65.0(@types/node@22.19.17)
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 86fcfd9e3909..07c78714bfb0 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -154,6 +154,15 @@ packages:
   - "packages/**"
   - "tools/markdown-magic"
 
+  # exclude bundle-analysis output directories, which can contain package.json files from
+  # webpack bundle stats (e.g. examples/utils/bundle-size-tests).
+  - "!**/bundleAnalysis/**"
+
+  # exclude the inner FluidFramework enlistment used by examples/utils/bundle-size-tests for
+  # cross-revision bundle comparison (see `flub generate bundleAnalysisReposWithComparison`, which clones
+  # the inner repo into <outputDir>/base-repo).
+  - "!**/compareBundlesOutput/**"
+
   # exclude any package.json files that are inside src or output directories
   - "!**/dist/**"
   - "!**/lib/**"