From f62f461dbf16b1e03223f8a144370e4b098a75b4 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 12:36:41 -0700
Subject: [PATCH 01/10] feat(migration): convert shortcodes to blocks or static
 HTML, with preview, batches, rollback and an assets companion

Every supported shortcode now has a tested destination (docs/migration.md):
grid -> Columns, standalone buttons -> Buttons, lead -> Paragraph, wells
and alerts -> Custom HTML (self-contained) or Group (classes), collapse
and tabs -> Details sections (name-grouped), labels/tooltips/inline
buttons -> inline HTML, icons -> inline SVG extracted from the bundled
Glyphicons font. Output is block markup (round-trips losslessly through
core's parser so the editor never flags it) or plain HTML for classic
posts; styling is self-contained by default or Bootstrap-classes-only.
Unbalanced tags, escaped [[bs_x]] and unknown bs_ tags are left in place
and listed; dropped behaviour (alert dismiss, tooltip placement, grid
offsets, tabs -> sections) is reported as notes stored with the post.

Tools page gains: per-post preview with a wp_text_diff() diff and a
stale-check on apply; migrate one / selected / in AJAX batches (no-JS
fallback); originals kept in _bs_migration_original (never overwritten)
plus the usual revision; roll back selected; a migrated-posts list.

Companion: companion/bootstrap-legacy-assets is a minimal separate
plugin (CSS, JS, Glyphicons, tooltip init; three switches; no
shortcodes) that stays idle while this plugin loads assets and skips
files a theme already registers. The migration page builds its zip from
this plugin's files and installs it through core's Plugin_Upgrader only
after an explicit consent checkbox, or offers the zip for manual upload
where PHP cannot write to the plugins directory.

Verified end to end in specs/migration.spec.js: scan, preview, migrate,
roll back (byte-identical), batch, re-scan clean, companion install,
deactivate Bootstrap Shortcodes, then columns/buttons/wells/labels/svg
icons/lead/details (click + keyboard, exclusive group)/tab sections/
native tooltips on desktop and a 390px viewport, with and without the
companion. release-it now also bumps BS_SHORTCODES_VERSION.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .release-it.json                              |   3 +-
 ROADMAP.md                                    |  14 +-
 bootstrap-shortcodes.php                      |   6 +-
 .../bootstrap-legacy-assets.php               | 138 ++++
 companion/bootstrap-legacy-assets/readme.txt  |  24 +
 docs/compatibility.md                         |   4 +-
 docs/migration.md                             | 122 +++
 docs/privacy.md                               |  11 +-
 inc/class-bs-admin-migration.php              | 437 +++++++++++
 inc/class-bs-admin-tools.php                  |  14 +-
 inc/class-bs-companion.php                    | 126 ++++
 inc/class-bs-migration.php                    | 149 ++++
 inc/class-bs-migrator.php                     | 695 ++++++++++++++++++
 js/admin-tools.js                             | 103 +++
 readme.txt                                    |   6 +
 specs/migration.spec.js                       | 222 ++++++
 tests/phpunit/AdminMigrationTest.php          |  52 ++
 tests/phpunit/CompanionTest.php               |  97 +++
 tests/phpunit/MigrationApplyTest.php          | 145 ++++
 tests/phpunit/MigratorConvertTest.php         | 283 +++++++
 20 files changed, 2634 insertions(+), 17 deletions(-)
 create mode 100644 companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php
 create mode 100644 companion/bootstrap-legacy-assets/readme.txt
 create mode 100644 docs/migration.md
 create mode 100644 inc/class-bs-admin-migration.php
 create mode 100644 inc/class-bs-companion.php
 create mode 100644 inc/class-bs-migration.php
 create mode 100644 inc/class-bs-migrator.php
 create mode 100644 specs/migration.spec.js
 create mode 100644 tests/phpunit/AdminMigrationTest.php
 create mode 100644 tests/phpunit/CompanionTest.php
 create mode 100644 tests/phpunit/MigrationApplyTest.php
 create mode 100644 tests/phpunit/MigratorConvertTest.php

diff --git a/.release-it.json b/.release-it.json
index 527929b..dd5b888 100644
--- a/.release-it.json
+++ b/.release-it.json
@@ -20,8 +20,9 @@
         "after:bump": [
             "sed -i.bak -e \"s/Stable tag: .*/Stable tag: ${version}/\" readme.txt",
             "sed -i.bak -e \"s/Version: .*/Version: ${version}/\" bootstrap-shortcodes.php",
+            "sed -i.bak -e \"s/define( 'BS_SHORTCODES_VERSION', '[^']*' )/define( 'BS_SHORTCODES_VERSION', '${version}' )/\" bootstrap-shortcodes.php",
             "rm -f readme.txt.bak bootstrap-shortcodes.php.bak",
             "git add readme.txt bootstrap-shortcodes.php"
         ]
     }
-}
\ No newline at end of file
+}
diff --git a/ROADMAP.md b/ROADMAP.md
index b43133f..2670e61 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,6 +1,6 @@
 # Roadmap: a safe landing for Bootstrap Shortcodes
 
-Status: living document. Last updated 2026-10-31.
+Status: living document. Last updated 2026-10-31 (all three phases implemented locally; PRs pending push approval).
 
 This plugin is in **maintenance mode**. It is kept safe and working for the sites
 that already depend on it; it is not being grown into a page builder or a Bootstrap
@@ -89,12 +89,12 @@ string search, never unserialize-and-rewrite).
 
 Branch `feat/migration`. Acceptance criteria:
 
-- [ ] Component-by-component matrix in `docs/migration.md` (destination, WP version, preserved content/interaction, visual differences, retained dependency, fallback, limitations).
-- [ ] Converter: shortcode text to block markup or reviewed static HTML, preserving unrelated markup and third-party shortcodes; unknown/malformed/ambiguous occurrences are left in place and listed for manual review.
-- [ ] Preview, migrate selected, migrate in batches, review outstanding; explicit confirmation, nonces, capability checks.
-- [ ] Originals stored in post meta (not only revisions) with a tested rollback; stale-content protection via `post_modified_gmt` check; bounded, resumable, safe to retry.
-- [ ] Legacy assets handoff: a separate, minimal companion plugin ("Bootstrap 3 Legacy Assets") shipped in this repo, installable from the migration page only with explicit consent; works with this plugin deactivated and deleted; avoids double-loading with theme Bootstrap; documents what retaining Bootstrap 3 means.
-- [ ] Verified by deactivating this plugin in wp-env after migration: desktop/mobile layouts, keyboard, tabs, collapse, icons, tooltips.
+- [x] Component-by-component matrix in `docs/migration.md` (destination, WP version, preserved content/interaction, visual differences, retained dependency, fallback, limitations).
+- [x] Converter: shortcode text to block markup or reviewed static HTML, preserving unrelated markup and third-party shortcodes; unknown/malformed/ambiguous occurrences are left in place and listed for manual review.
+- [x] Preview, migrate selected, migrate in batches, review outstanding; explicit confirmation, nonces, capability checks.
+- [x] Originals stored in post meta (not only revisions) with a tested rollback; stale-content protection via `post_modified_gmt` check; bounded, resumable, safe to retry.
+- [x] Legacy assets handoff: a separate, minimal companion plugin ("Bootstrap 3 Legacy Assets") shipped in this repo, installable from the migration page only with explicit consent; works with this plugin deactivated and deleted; avoids double-loading with theme Bootstrap; documents what retaining Bootstrap 3 means.
+- [x] Verified by deactivating this plugin in wp-env after migration: desktop/mobile layouts, keyboard, tabs, collapse, icons, tooltips.
 
 ## Decisions
 
diff --git a/bootstrap-shortcodes.php b/bootstrap-shortcodes.php
index 5c5512d..8a218c9 100644
--- a/bootstrap-shortcodes.php
+++ b/bootstrap-shortcodes.php
@@ -26,7 +26,11 @@
 require_once( 'inc/bs_lead.php' );
 require_once( 'inc/bs_tooltip.php' );
 require_once( 'inc/class-bs-scanner.php' );
+require_once( 'inc/class-bs-migrator.php' );
+require_once( 'inc/class-bs-migration.php' );
+require_once( 'inc/class-bs-companion.php' );
 require_once( 'inc/class-bs-admin-tools.php' );
+require_once( 'inc/class-bs-admin-migration.php' );
 require_once( 'inc/class-bs-cli.php' );
 
 class BootstrapShortcodes{
@@ -302,5 +306,5 @@ function dw_render_form() {
 
 $bscodes = new BootstrapShortcodes();
 if ( is_admin() ) {
-    $bs_admin_tools = new BS_Admin_Tools();
+    $bs_admin_tools = new BS_Admin_Tools( new BS_Admin_Migration() );
 }
diff --git a/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php b/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php
new file mode 100644
index 0000000..94f05e3
--- /dev/null
+++ b/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php
@@ -0,0 +1,138 @@
+<?php
+/*
+Plugin Name: Bootstrap 3 Legacy Assets
+Plugin URI: https://github.com/TheWebShop/bootstrap-shortcodes/blob/master/docs/migration.md
+Description: Keeps loading the Bootstrap 3.4.1 CSS, JavaScript and Glyphicons font that the Bootstrap Shortcodes plugin used to load, for sites that still have markup relying on them. No shortcodes, no settings beyond three switches. Bootstrap 3 is end-of-life: this is a compatibility bridge, not a supported framework.
+Version: 1.0.0
+Author: Kevin Attfield
+Requires at least: 5.0
+Requires PHP: 7.4
+License: GPLv2 or later
+*/
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+if ( ! class_exists( 'BS_Legacy_Assets' ) ) :
+
+class BS_Legacy_Assets {
+
+	const OPTION  = 'bs_legacy_assets';
+	const VERSION = '1.0.0';
+
+	public static function defaults() {
+		return array( 'css' => '1', 'js' => '1', 'tooltips' => '1' );
+	}
+
+	public static function options() {
+		$o = get_option( self::OPTION );
+		return is_array( $o ) ? $o : self::defaults();
+	}
+
+	public function __construct() {
+		register_activation_hook( __FILE__, array( __CLASS__, 'activate' ) );
+		add_action( 'wp_enqueue_scripts', array( $this, 'enqueue' ), 20 );
+		add_action( 'admin_init', array( $this, 'register_settings' ) );
+		add_action( 'admin_menu', array( $this, 'menu' ) );
+		add_action( 'admin_notices', array( $this, 'notices' ) );
+	}
+
+	public static function activate() {
+		if ( false === get_option( self::OPTION ) ) {
+			add_option( self::OPTION, self::defaults() );
+		}
+	}
+
+	/** True when Bootstrap Shortcodes is active and still loading its own copy. */
+	public static function original_plugin_loads_assets() {
+		if ( ! class_exists( 'BootstrapShortcodes' ) ) {
+			return false;
+		}
+		$o = get_option( 'bs_options' );
+		return is_array( $o ) && ( ! empty( $o['chk_default_options_css'] ) || ! empty( $o['chk_default_options_js'] ) );
+	}
+
+	/** A theme or another plugin already registered a Bootstrap file of this kind. */
+	public static function other_bootstrap( $kind ) {
+		$deps = 'css' === $kind ? wp_styles() : wp_scripts();
+		foreach ( $deps->registered as $handle => $dep ) {
+			if ( 0 === strpos( $handle, 'bs-legacy' ) || empty( $dep->src ) ) {
+				continue;
+			}
+			if ( preg_match( '#bootstrap(\.bundle)?(\.min)?\.(css|js)(\?|$)#i', $dep->src ) ) {
+				return $handle;
+			}
+		}
+		return '';
+	}
+
+	public function enqueue() {
+		if ( self::original_plugin_loads_assets() ) {
+			return; // avoid double loading while the original is still active
+		}
+		$o    = self::options();
+		$base = plugins_url( '', __FILE__ );
+		if ( ! empty( $o['css'] ) && ! self::other_bootstrap( 'css' ) ) {
+			wp_enqueue_style( 'bs-legacy-bootstrap', $base . '/css/bootstrap.css', array(), '3.4.1' );
+		}
+		if ( ! empty( $o['js'] ) && ! self::other_bootstrap( 'js' ) ) {
+			wp_enqueue_script( 'bs-legacy-bootstrap', $base . '/js/bootstrap.js', array( 'jquery' ), '3.4.1' );
+		}
+		if ( ! empty( $o['tooltips'] ) ) {
+			wp_enqueue_script( 'bs-legacy-init', $base . '/js/init.js', array( 'jquery' ), self::VERSION );
+		}
+	}
+
+	public function register_settings() {
+		register_setting( 'bs_legacy_assets', self::OPTION, array( 'sanitize_callback' => array( __CLASS__, 'sanitize' ) ) );
+	}
+
+	public static function sanitize( $input ) {
+		$clean = array();
+		foreach ( array_keys( self::defaults() ) as $key ) {
+			if ( is_array( $input ) && ! empty( $input[ $key ] ) ) {
+				$clean[ $key ] = '1';
+			}
+		}
+		return $clean;
+	}
+
+	public function menu() {
+		add_options_page( 'Legacy Bootstrap', 'Legacy Bootstrap', 'manage_options', 'bs-legacy-assets', array( $this, 'page' ) );
+	}
+
+	public function notices() {
+		if ( ! current_user_can( 'manage_options' ) ) {
+			return;
+		}
+		if ( self::original_plugin_loads_assets() ) {
+			echo '<div class="notice notice-warning"><p>' . esc_html__( 'Bootstrap 3 Legacy Assets is waiting: the Bootstrap Shortcodes plugin is still loading its own Bootstrap files. Deactivate Bootstrap Shortcodes (or turn off its two asset settings) and this plugin takes over.', 'bs-legacy-assets' ) . '</p></div>';
+		}
+	}
+
+	public function page() {
+		$o = self::options();
+		?>
+		<div class="wrap">
+			<h1>Bootstrap 3 Legacy Assets</h1>
+			<p><?php esc_html_e( 'This plugin exists so a site can remove Bootstrap Shortcodes without losing the Bootstrap 3 styling its remaining markup depends on. It loads the same files that plugin loaded (Bootstrap 3.4.1 CSS and JavaScript, the Glyphicons font, and a small tooltip initialiser). It registers no shortcodes.', 'bs-legacy-assets' ); ?></p>
+			<div class="notice notice-warning inline"><p><strong><?php esc_html_e( 'Bootstrap 3 is end-of-life.', 'bs-legacy-assets' ); ?></strong> <?php esc_html_e( 'Version 3.4.1 (2019) is the last release; the Bootstrap project publishes no fixes for it. Keeping it is a deliberate compatibility choice. Treat this plugin as temporary: migrate the remaining markup to your theme or to blocks, then deactivate it.', 'bs-legacy-assets' ); ?></p></div>
+			<form method="post" action="options.php">
+				<?php settings_fields( 'bs_legacy_assets' ); ?>
+				<table class="form-table">
+					<tr><th scope="row"><?php esc_html_e( 'Bootstrap CSS', 'bs-legacy-assets' ); ?></th><td><label><input type="checkbox" name="<?php echo esc_attr( self::OPTION ); ?>[css]" value="1" <?php checked( ! empty( $o['css'] ) ); ?> /> <?php esc_html_e( 'Load bootstrap.css (grid, buttons, wells, labels, alerts, panels, Glyphicons)', 'bs-legacy-assets' ); ?></label></td></tr>
+					<tr><th scope="row"><?php esc_html_e( 'Bootstrap JavaScript', 'bs-legacy-assets' ); ?></th><td><label><input type="checkbox" name="<?php echo esc_attr( self::OPTION ); ?>[js]" value="1" <?php checked( ! empty( $o['js'] ) ); ?> /> <?php esc_html_e( 'Load bootstrap.js (tabs, collapse, dropdowns, modals, tooltips; needs jQuery)', 'bs-legacy-assets' ); ?></label></td></tr>
+					<tr><th scope="row"><?php esc_html_e( 'Tooltips', 'bs-legacy-assets' ); ?></th><td><label><input type="checkbox" name="<?php echo esc_attr( self::OPTION ); ?>[tooltips]" value="1" <?php checked( ! empty( $o['tooltips'] ) ); ?> /> <?php esc_html_e( 'Initialise [data-toggle="tooltip"] elements, as Bootstrap Shortcodes did', 'bs-legacy-assets' ); ?></label></td></tr>
+				</table>
+				<p class="description"><?php esc_html_e( 'If your theme registers its own Bootstrap CSS or JavaScript, the matching file here is skipped automatically to avoid loading it twice.', 'bs-legacy-assets' ); ?></p>
+				<?php submit_button(); ?>
+			</form>
+		</div>
+		<?php
+	}
+}
+
+endif;
+
+new BS_Legacy_Assets();
diff --git a/companion/bootstrap-legacy-assets/readme.txt b/companion/bootstrap-legacy-assets/readme.txt
new file mode 100644
index 0000000..6eb6ec0
--- /dev/null
+++ b/companion/bootstrap-legacy-assets/readme.txt
@@ -0,0 +1,24 @@
+=== Bootstrap 3 Legacy Assets ===
+Contributors: sinetheta
+Tags: bootstrap, compatibility
+Requires at least: 5.0
+Tested up to: 7.1
+Requires PHP: 7.4
+Stable tag: 1.0.0
+License: GPLv2 or later
+License URI: http://www.gnu.org/licenses/gpl-2.0.html
+
+Keeps loading Bootstrap 3.4.1 (CSS, JavaScript, Glyphicons) after the Bootstrap Shortcodes plugin is removed.
+
+== Description ==
+
+A compatibility bridge, generated by the Bootstrap Shortcodes plugin's migration page. It loads exactly the frontend files that plugin loaded, and nothing else: no shortcodes, no editor buttons, no admin tooling. Three switches under Settings > Legacy Bootstrap turn the CSS, the JavaScript and the tooltip initialiser on or off.
+
+**Bootstrap 3 is end-of-life.** 3.4.1 (February 2019) is its last release. Keeping it running is a deliberate choice made for content that still depends on it; the plan should be to migrate that content and deactivate this plugin.
+
+It avoids double loading: while Bootstrap Shortcodes is active with its asset settings on, this plugin does nothing; if the theme registers its own bootstrap.css or bootstrap.js, the matching file here is skipped.
+
+== Changelog ==
+
+= 1.0.0 =
+* First release, built from Bootstrap Shortcodes' bundled assets.
diff --git a/docs/compatibility.md b/docs/compatibility.md
index d69f939..ca78305 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -20,8 +20,8 @@ itself still supports.
 
 | WordPress | PHP | What ran | Result |
 | --- | --- | --- | --- |
-| 7.1.4 | 8.3 | PHPUnit (81 tests), Playwright (17 tests: Classic Editor dialogs, frontend rendering and interaction under plugin-/theme-/no-Bootstrap-JS setups, conditional loading, block-editor Shortcode block) | green, 2026-10-31 |
-| 6.4.7 | 7.4 | PHPUnit (81 tests); every component rendered on the frontend with assets present; deactivate/reactivate keeps settings | green, 2026-10-31 |
+| 7.1.4 | 8.3 | PHPUnit (151 tests), Playwright (20 tests: Classic Editor dialogs; frontend rendering and interaction under plugin-/theme-/no-Bootstrap-JS setups; conditional loading; block-editor Shortcode block; the Tools report; the full migration run ending with the plugin deactivated and the migrated pages checked on desktop and phone viewports) | green, 2026-10-31 |
+| 6.4.7 | 7.4 | PHPUnit (151 tests, including converter, scanner and migration); every component rendered on the frontend with assets present; deactivate/reactivate keeps settings | green, 2026-10-31 |
 | latest (wp-env default) | 8.2 | PHPUnit + Playwright in GitHub Actions on every PR | see CI |
 
 Not tested: multisite, PHP 8.4 specifically (nothing in the plugin is version
diff --git a/docs/migration.md b/docs/migration.md
new file mode 100644
index 0000000..749d8ce
--- /dev/null
+++ b/docs/migration.md
@@ -0,0 +1,122 @@
+# Migrating off Bootstrap Shortcodes
+
+The goal is a site that renders the same content with this plugin deactivated and
+deleted. There are three steps, all on **Tools > Bootstrap Shortcodes**:
+
+1. **Scan** to learn what depends on the plugin (see the report's "If you deactivated
+   this plugin today" and "Not scanned" sections; a clean post scan is not proof).
+2. **Migrate** post content: preview one post with a diff, migrate it, or select
+   posts and migrate in batches. Originals are kept for rollback.
+3. **Decide about Bootstrap itself**: either nothing else needs it (self-contained
+   styling, theme has its own), or install the legacy-assets companion.
+
+Then deactivate the plugin, check the pages the report listed, and delete it.
+
+## What the migration does and does not touch
+
+- Rewrites **post content** only (every post type and status the scan covers).
+  Widgets, options, custom fields, term descriptions and theme files are reported,
+  not rewritten: edit those by hand using the same mappings below.
+- Reads each post fresh at migration time, so a post edited after the scan is
+  converted from its current content. A single-post preview is refused if the post
+  changed after the preview was made.
+- Stores the original content in the custom field `_bs_migration_original` (first
+  migration only; later migrations of the same post never overwrite it), and
+  `wp_update_post()` records a revision as usual. **Roll back** restores the stored
+  original and removes the custom field. Rollback does not depend on revisions.
+- Leaves in place, and lists: occurrences whose opening and closing tags do not match
+  (an unclosed `[bs_well]`), escaped `[[bs_x]]` examples, and `bs_` tags the plugin
+  never registered (typos, other plugins). Nothing in a post is dropped silently;
+  every approximation is reported as a note in the preview and stored with the post.
+- Never runs on activation, update or a schedule. Needs `manage_options`, a nonce
+  and a button press (or `edit_post` for each post).
+
+## Output options
+
+| Option | Values | Meaning |
+| --- | --- | --- |
+| Output | auto / blocks / HTML | `blocks` writes core block markup (Columns, Buttons, Details, Paragraph, Group, Custom HTML, Classic). `HTML` writes plain markup with no block comments, for classic-editor sites. `auto` picks blocks for posts that already contain blocks, otherwise HTML. |
+| Styling | self-contained / Bootstrap classes | `self-contained` adds inline styles (wells, alerts, labels, lead, tooltips) and inline SVG icons so nothing needs Bootstrap CSS. `Bootstrap classes` keeps only the original class names, for sites that keep Bootstrap 3 via the theme or the companion. |
+
+Block output is checked to round-trip through core's block parser/serializer
+losslessly (`MigratorConvertTest::test_block_mode_output_is_what_the_editor_would_save`),
+so the editor opens migrated posts without "invalid block" prompts.
+
+## Component matrix
+
+WP = minimum WordPress version for the block destination; the HTML destination works
+everywhere. "Keeps" lists what is preserved; "Changes" what is visibly or
+behaviourally different; "Needs" what the output still depends on.
+
+| Shortcode | Blocks destination | HTML destination | WP | Keeps | Changes | Needs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `bs_row` + `bs_col` | Columns > Column, width from the first `col-*-N` class (N/12 as %) | `<div class="row"><div class="col-sm-6">` unchanged | 5.0 | content, nesting, column proportions, extra classes (as block className) | responsive breakpoints become the Columns block's own (stack on mobile); `offset`/`push`/`pull` dropped and noted; theme spacing | HTML output needs Bootstrap CSS |
+| `bs_button` standalone | Buttons > Button with url/text/target (`rel="noopener noreferrer"` for `_blank`) | `<a class="btn btn-primary">` identical to today | 5.4 | text, link, target | theme button style instead of Bootstrap colours/sizes | HTML output needs Bootstrap CSS |
+| `bs_button` inline in a sentence | stays an inline `<a class="btn ...">` (noted) | same | – | everything | – | Bootstrap CSS |
+| `bs_well` | self-contained: Custom HTML block with inline well styling; classes: Group block with `well` class | `<div class="well" style="...">` or `<div class="well">` | 5.0 | content (paragraphs baked in for the HTML block) | editable as HTML rather than blocks (self-contained); small sizing differences | classes variant needs Bootstrap CSS |
+| `bs_notification` | same shape as wells with alert colours and `role="alert"` | same | 5.0 | message, type colour | **dismiss (×) button removed** (needs Bootstrap JS), noted | classes variant needs Bootstrap CSS |
+| `bs_lead` | Paragraph with `lead` class and the theme's `large` font size | `<p class="lead" style="font-size:1.3em;font-weight:300">` | 5.0 | text | exact size follows the theme | classes variant needs Bootstrap CSS |
+| `bs_label` | inline `<span class="label label-x">` with inline colours | same | – | text, type colour | – | classes variant needs Bootstrap CSS |
+| `bs_icon` | inline SVG built from the bundled Glyphicons font (`<svg class="bs-icon bs-icon-star">`, `currentColor`, 1em) | same | – | the glyph, size relative to text, extra classes | none visible; unknown glyph names keep `<i class="glyphicon ...">` and are noted | classes variant, or unknown glyphs, need the Glyphicons font (Bootstrap CSS) |
+| `bs_tooltip` | `<span class="bs-tooltip" title="...">` (dotted underline when self-contained) | same | – | the text and the tooltip text (they were always identical) | native browser tooltip: no placement/trigger, none on touch devices; noted | – |
+| `bs_collapse` + `bs_citem` | one Details block per item, `name` = group id so one opens at a time (WP 6.6+; ignored earlier), `open` for `open="true"`, element `id` kept so `#anchor` links work | `<div class="bs-collapse"><details name><summary>` | 6.3 (Details block); HTML works everywhere | titles, content, initial open state, one-at-a-time behaviour, anchor ids | Bootstrap panel chrome gone (theme styles the Details block); keyboard: native `<summary>` | – |
+| `bs_tabs` + `bs_thead` + `bs_tab` + `bs_dropdown` + `bs_tcontents` + `bs_tcontent` | one Details block per pane, titled by the matching tab (`href="#id"` ↔ `id`), active pane open; dropdown tabs flattened as "Dropdown: Tab" | `<div class="bs-tabs"><details>` per pane | 6.3 / any | every pane's content, titles, order, initial pane, anchor ids | **tabs become stacked collapsible sections** (semantic alternative, noted). On WordPress 7.1+ the editor's Tabs block can be built from them by hand if tabs are wanted back | – |
+
+Attributes the plugin never used (anything not in the table above, such as a
+`color=` on a well) are dropped with a note; they never rendered anything.
+
+Why not the core Accordion (6.9) and Tabs (7.1) blocks directly? Both are
+Interactivity-API blocks whose saved markup must match the editor's exactly; hand
+written markup that drifts makes the editor flag every migrated post as invalid.
+Details is a static block with a stable save format and a `name` attribute, so it is
+the reliable automatic destination. Converting Details to Accordion or Tabs is a
+manual, per-post editor action.
+
+## Keeping Bootstrap 3 after removal: the companion
+
+If the report shows "Still needs: Bootstrap 3 CSS" on migrated posts, or your theme or
+hand-written HTML uses Bootstrap 3 classes, or you use `[bs_icon]` names that are not
+in the bundled set, the site still needs Bootstrap 3 after this plugin is gone.
+
+**Bootstrap 3 Legacy Assets** is a separate, minimal plugin (`companion/` in this
+repository; the migration page builds its zip from this plugin's own files). It:
+
+- loads the same Bootstrap 3.4.1 CSS, JS, Glyphicons font and tooltip initialiser
+  this plugin loads, with three on/off switches (Settings > Legacy Bootstrap);
+- registers **no** shortcodes and has no other behaviour;
+- stays idle while Bootstrap Shortcodes is active with its asset settings on, and
+  skips its CSS or JS when the theme registers its own `bootstrap.css` / `bootstrap.js`,
+  so nothing loads twice;
+- is installed only from the migration page after ticking an explicit statement, or
+  by uploading the downloaded zip yourself. Its settings start as copies of this
+  plugin's CSS/JS settings.
+
+Be honest with yourself about what that means: the site no longer depends on
+Bootstrap Shortcodes, but it still depends on **end-of-life Bootstrap 3** (see
+`docs/security.md`). Treat the companion as a bridge to be removed once the remaining
+markup is migrated.
+
+## Verifying before you delete
+
+The repository's Playwright suite (`specs/migration.spec.js`) does this end to end
+in a test site: scan, preview, migrate, roll back, migrate again in a batch, install
+the companion, **deactivate Bootstrap Shortcodes**, and then check on the frontend
+that columns, buttons, wells, labels, icons, lead text, collapse sections (open,
+close, keyboard), tab sections and tooltips still render and work, on a desktop and
+a phone-sized viewport. Do the same on your site with the pages the report listed.
+
+Checklist:
+
+- [ ] Scan shows no remaining post content, or only occurrences you have reviewed.
+- [ ] "Other surfaces" and "Not scanned" items reviewed by hand.
+- [ ] Decided about Bootstrap 3: theme-provided, not needed, or companion installed.
+- [ ] Plugin deactivated; listed pages checked on desktop and mobile.
+- [ ] Plugin deleted. The custom fields `_bs_migration_original` / `_bs_migration_result`
+      stay with the posts; delete them when you no longer want rollback.
+
+## Manual mappings for non-post content
+
+For widgets, options, custom fields and theme files, use the HTML destinations above
+(the plugin's output for each shortcode is in `inc/bs_*.php`). A theme calling
+`do_shortcode()` on a custom field will render whatever that field holds; migrate
+the field's text with the same rules, or replace the call with the markup directly.
diff --git a/docs/privacy.md b/docs/privacy.md
index 0695d45..979b4ce 100644
--- a/docs/privacy.md
+++ b/docs/privacy.md
@@ -76,9 +76,10 @@ shared summaries answer well enough. If that changes, it will be a separate,
 documented decision, with the same "off by default, inspect before sending" rules,
 and never enabled by an update.
 
-## Migration (planned, phase 3)
+## Migration
 
-Not part of this release. When it ships, migrating content will rewrite your own
-posts in your own database after explicit confirmation, keep the original in post
-meta (`_bs_migration_original`) for rollback, and send nothing anywhere. Its
-documentation (`docs/migration.md`) arrives with it.
+Migrating content rewrites your own posts in your own database after explicit
+confirmation, and keeps the original in post meta (`_bs_migration_original`, plus a
+`_bs_migration_result` summary) for rollback. Nothing is sent anywhere. Those two
+custom fields stay with the posts after uninstall so rollback remains possible; delete
+them when you no longer want it. See `docs/migration.md`.
diff --git a/inc/class-bs-admin-migration.php b/inc/class-bs-admin-migration.php
new file mode 100644
index 0000000..65f6e2c
--- /dev/null
+++ b/inc/class-bs-admin-migration.php
@@ -0,0 +1,437 @@
+<?php
+/**
+ * The migration half of Tools > Bootstrap Shortcodes: options, per-post
+ * preview with a diff, migrate one / selected / in batches, roll back, and
+ * the legacy-assets companion hand-off. Every write needs manage_options, a
+ * nonce, and a click; nothing runs on activation, update or cron.
+ */
+class BS_Admin_Migration {
+
+	const ACTION_PREVIEW  = 'bs_migrate_preview';
+	const ACTION_APPLY    = 'bs_migrate_apply';
+	const ACTION_BATCH    = 'bs_migrate_batch';
+	const ACTION_ROLLBACK = 'bs_migrate_rollback';
+	const ACTION_COMPANION = 'bs_companion_install';
+	const ACTION_COMPANION_ZIP = 'bs_companion_zip';
+	const BATCH = 10;
+
+	public function __construct() {
+		add_action( 'admin_post_' . self::ACTION_APPLY, array( $this, 'handle_apply' ) );
+		add_action( 'admin_post_' . self::ACTION_BATCH, array( $this, 'handle_batch_form' ) );
+		add_action( 'admin_post_' . self::ACTION_ROLLBACK, array( $this, 'handle_rollback' ) );
+		add_action( 'admin_post_' . self::ACTION_COMPANION, array( $this, 'handle_companion' ) );
+		add_action( 'admin_post_' . self::ACTION_COMPANION_ZIP, array( $this, 'handle_companion_zip' ) );
+		add_action( 'wp_ajax_' . self::ACTION_BATCH, array( $this, 'handle_batch_ajax' ) );
+	}
+
+	private function authorise( $action ) {
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_die( esc_html__( 'You do not have permission to do that.', 'bsshortcodes' ), '', array( 'response' => 403 ) );
+		}
+		check_admin_referer( $action );
+	}
+
+	private function back( $args = array() ) {
+		wp_safe_redirect( BS_Admin_Tools::url( $args ) );
+		exit;
+	}
+
+	private function options_from_request() {
+		return BS_Migration::options_from( array(
+			'mode'  => isset( $_REQUEST['mode'] ) ? sanitize_key( $_REQUEST['mode'] ) : 'auto',
+			'style' => isset( $_REQUEST['style'] ) ? sanitize_key( $_REQUEST['style'] ) : 'inline',
+		) );
+	}
+
+	/* ---------------------------------------------------------------- */
+	/* Handlers                                                          */
+	/* ---------------------------------------------------------------- */
+
+	public function handle_apply() {
+		$this->authorise( self::ACTION_APPLY );
+		$post_id  = isset( $_POST['post_id'] ) ? (int) $_POST['post_id'] : 0;
+		$expected = isset( $_POST['modified_gmt'] ) ? sanitize_text_field( wp_unslash( $_POST['modified_gmt'] ) ) : null;
+		$r        = BS_Migration::apply( $post_id, $this->options_from_request(), $expected );
+		if ( is_wp_error( $r ) ) {
+			$this->back( array( 'bs_msg' => 'error', 'bs_text' => rawurlencode( $r->get_error_message() ), 'bs_preview' => $post_id, 'mode' => $this->options_from_request()['mode'], 'style' => $this->options_from_request()['style'] ) );
+		}
+		$this->back( array( 'bs_msg' => 'migrated', 'bs_count' => 1, 'bs_post' => $post_id ) );
+	}
+
+	/** No-JS batch: up to MAX_BATCH posts in one request. */
+	public function handle_batch_form() {
+		$this->authorise( self::ACTION_BATCH );
+		$ids = isset( $_POST['post_ids'] ) ? array_map( 'intval', (array) $_POST['post_ids'] ) : array();
+		$out = BS_Migration::batch( $ids, $this->options_from_request() );
+		$ok  = count( array_filter( $out, function ( $r ) { return $r['ok']; } ) );
+		$this->back( array( 'bs_msg' => 'migrated', 'bs_count' => $ok, 'bs_failed' => count( $out ) - $ok ) );
+	}
+
+	public function handle_batch_ajax() {
+		list( $status, $data ) = $this->batch_response();
+		if ( 200 === $status ) {
+			wp_send_json_success( $data );
+		}
+		wp_send_json_error( $data, $status );
+	}
+
+	public function batch_response() {
+		if ( ! current_user_can( 'manage_options' ) ) {
+			return array( 403, array( 'message' => 'forbidden' ) );
+		}
+		if ( ! check_ajax_referer( self::ACTION_BATCH, false, false ) ) {
+			return array( 403, array( 'message' => 'bad nonce' ) );
+		}
+		$ids = isset( $_POST['post_ids'] ) ? array_map( 'intval', (array) $_POST['post_ids'] ) : array();
+		$ids = array_slice( $ids, 0, self::BATCH );
+		return array( 200, array( 'results' => BS_Migration::batch( $ids, $this->options_from_request() ) ) );
+	}
+
+	public function handle_rollback() {
+		$this->authorise( self::ACTION_ROLLBACK );
+		$ids = isset( $_POST['post_ids'] ) ? array_map( 'intval', (array) $_POST['post_ids'] ) : array();
+		if ( isset( $_POST['post_id'] ) ) {
+			$ids[] = (int) $_POST['post_id'];
+		}
+		$ok = 0;
+		foreach ( array_slice( array_unique( $ids ), 0, BS_Migration::MAX_BATCH ) as $id ) {
+			if ( true === BS_Migration::rollback( $id ) ) {
+				$ok++;
+			}
+		}
+		$this->back( array( 'bs_msg' => 'rolled_back', 'bs_count' => $ok ) );
+	}
+
+	public function handle_companion() {
+		$this->authorise( self::ACTION_COMPANION );
+		if ( empty( $_POST['bs_companion_consent'] ) ) {
+			$this->back( array( 'bs_msg' => 'error', 'bs_text' => rawurlencode( __( 'Tick the confirmation box to install the companion.', 'bsshortcodes' ) ) ) );
+		}
+		$r = BS_Companion::install_and_activate();
+		if ( is_wp_error( $r ) ) {
+			$this->back( array( 'bs_msg' => 'error', 'bs_text' => rawurlencode( $r->get_error_message() ) ) );
+		}
+		$this->back( array( 'bs_msg' => 'companion' ) );
+	}
+
+	public function handle_companion_zip() {
+		$this->authorise( self::ACTION_COMPANION_ZIP );
+		$zip = BS_Companion::build_zip();
+		if ( is_wp_error( $zip ) ) {
+			wp_die( esc_html( $zip->get_error_message() ) );
+		}
+		nocache_headers();
+		header( 'Content-Type: application/zip' );
+		header( 'Content-Disposition: attachment; filename="' . BS_Companion::SLUG . '.zip"' );
+		header( 'Content-Length: ' . filesize( $zip ) );
+		readfile( $zip );
+		@unlink( $zip );
+		exit;
+	}
+
+	/* ---------------------------------------------------------------- */
+	/* Rendering (called from BS_Admin_Tools::render)                    */
+	/* ---------------------------------------------------------------- */
+
+	public function render_notices() {
+		if ( empty( $_GET['bs_msg'] ) ) {
+			return;
+		}
+		$msg   = sanitize_key( $_GET['bs_msg'] );
+		$count = isset( $_GET['bs_count'] ) ? (int) $_GET['bs_count'] : 0;
+		$class = 'notice-success';
+		switch ( $msg ) {
+			case 'migrated':
+				$failed = isset( $_GET['bs_failed'] ) ? (int) $_GET['bs_failed'] : 0;
+				/* translators: %d: count */
+				$text = sprintf( _n( '%d post migrated.', '%d posts migrated.', $count, 'bsshortcodes' ), $count );
+				if ( $failed ) {
+					/* translators: %d: count */
+					$text .= ' ' . sprintf( __( '%d could not be migrated (nothing convertible, or skipped occurrences); see the list.', 'bsshortcodes' ), $failed );
+					$class = 'notice-warning';
+				}
+				$text .= ' ' . __( 'Re-run the scan to refresh the report.', 'bsshortcodes' );
+				break;
+			case 'rolled_back':
+				/* translators: %d: count */
+				$text = sprintf( _n( '%d post rolled back to its original content.', '%d posts rolled back to their original content.', $count, 'bsshortcodes' ), $count );
+				break;
+			case 'companion':
+				$text = __( 'Bootstrap 3 Legacy Assets is installed and active. It stays idle until Bootstrap Shortcodes stops loading its own files.', 'bsshortcodes' );
+				break;
+			case 'error':
+				$class = 'notice-error';
+				$text  = isset( $_GET['bs_text'] ) ? sanitize_text_field( rawurldecode( wp_unslash( $_GET['bs_text'] ) ) ) : __( 'Something went wrong.', 'bsshortcodes' );
+				break;
+			default:
+				return;
+		}
+		echo '<div class="notice ' . esc_attr( $class ) . ' is-dismissible"><p>' . esc_html( $text ) . '</p></div>';
+	}
+
+	public function current_options() {
+		return $this->options_from_request();
+	}
+
+	/** The per-post preview page (diff + migrate button). Returns true if it rendered. */
+	public function render_preview() {
+		if ( empty( $_GET['bs_preview'] ) ) {
+			return false;
+		}
+		$post_id = (int) $_GET['bs_preview'];
+		$options = $this->options_from_request();
+		$preview = BS_Migration::preview( $post_id, $options );
+		echo '<p><a href="' . esc_url( BS_Admin_Tools::url() ) . '">&larr; ' . esc_html__( 'Back to the report', 'bsshortcodes' ) . '</a></p>';
+		if ( is_wp_error( $preview ) ) {
+			echo '<div class="notice notice-error"><p>' . esc_html( $preview->get_error_message() ) . '</p></div>';
+			return true;
+		}
+		$r = $preview['result'];
+		?>
+		<h2><?php printf( esc_html__( 'Preview: %s', 'bsshortcodes' ), esc_html( $preview['title'] ? $preview['title'] : '#' . $post_id ) ); ?></h2>
+		<p>
+			<?php
+			printf(
+				/* translators: 1: mode, 2: style */
+				esc_html__( 'Output: %1$s, styling: %2$s.', 'bsshortcodes' ),
+				esc_html( 'blocks' === $r['mode'] ? __( 'block markup', 'bsshortcodes' ) : __( 'static HTML', 'bsshortcodes' ) ),
+				esc_html( 'inline' === $r['style'] ? __( 'self-contained (inline styles, inline SVG icons)', 'bsshortcodes' ) : __( 'Bootstrap classes only', 'bsshortcodes' ) )
+			);
+			?>
+			<?php echo $this->options_switcher( $options, array( 'bs_preview' => $post_id ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>
+		</p>
+		<?php if ( $preview['already'] ) : ?>
+			<div class="notice notice-info inline"><p><?php esc_html_e( 'This post was migrated before; its stored original is kept and will not be replaced by migrating again.', 'bsshortcodes' ); ?></p></div>
+		<?php endif; ?>
+		<?php $this->render_result_lists( $r ); ?>
+		<?php if ( 0 === $r['converted'] ) : ?>
+			<p><strong><?php esc_html_e( 'Nothing can be converted automatically in this post.', 'bsshortcodes' ); ?></strong></p>
+		<?php else : ?>
+			<?php
+			$diff = wp_text_diff( $preview['original'], $preview['converted'], array( 'title_left' => __( 'Current content', 'bsshortcodes' ), 'title_right' => __( 'After migration', 'bsshortcodes' ) ) );
+			echo $diff ? $diff : '<p>' . esc_html__( 'No visible difference.', 'bsshortcodes' ) . '</p>'; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- wp_text_diff escapes.
+			?>
+			<details>
+				<summary><?php esc_html_e( 'Full converted source', 'bsshortcodes' ); ?></summary>
+				<textarea readonly rows="16" style="width:100%;font-family:monospace"><?php echo esc_textarea( $preview['converted'] ); ?></textarea>
+			</details>
+			<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="bs-migrate-one">
+				<?php wp_nonce_field( self::ACTION_APPLY ); ?>
+				<input type="hidden" name="action" value="<?php echo esc_attr( self::ACTION_APPLY ); ?>" />
+				<input type="hidden" name="post_id" value="<?php echo (int) $post_id; ?>" />
+				<input type="hidden" name="modified_gmt" value="<?php echo esc_attr( $preview['modified_gmt'] ); ?>" />
+				<input type="hidden" name="mode" value="<?php echo esc_attr( $options['mode'] ); ?>" />
+				<input type="hidden" name="style" value="<?php echo esc_attr( $options['style'] ); ?>" />
+				<p>
+					<button class="button button-primary"><?php esc_html_e( 'Migrate this post', 'bsshortcodes' ); ?></button>
+					<span class="description"><?php esc_html_e( 'Writes the converted content, keeps the original for rollback, and adds a revision. Refuses if the post changed since this preview.', 'bsshortcodes' ); ?></span>
+				</p>
+			</form>
+		<?php endif; ?>
+		<?php
+		return true;
+	}
+
+	private function render_result_lists( $r ) {
+		if ( $r['skipped'] ) :
+			?>
+			<div class="notice notice-warning inline"><p><strong><?php esc_html_e( 'Left in place for manual review:', 'bsshortcodes' ); ?></strong>
+			<?php
+			$parts = array();
+			foreach ( $r['skipped'] as $s ) {
+				$parts[] = sprintf( '[%s] (%s)', $s['tag'], 'unbalanced' === $s['reason'] ? __( 'opening/closing tags do not match', 'bsshortcodes' ) : $s['reason'] );
+			}
+			echo esc_html( implode( ', ', $parts ) );
+			?>
+			</p></div>
+		<?php endif; ?>
+		<?php if ( $r['notes'] ) : ?>
+			<ul class="bs-notes">
+				<?php foreach ( $r['notes'] as $note ) : ?>
+					<li><?php echo esc_html( $note ); ?></li>
+				<?php endforeach; ?>
+			</ul>
+		<?php endif; ?>
+		<?php if ( $r['dependencies'] ) : ?>
+			<p><strong><?php esc_html_e( 'Still needs:', 'bsshortcodes' ); ?></strong>
+				<?php echo esc_html( implode( ', ', array_map( array( $this, 'dependency_label' ), $r['dependencies'] ) ) ); ?>
+				<?php esc_html_e( '(keep the theme\'s Bootstrap 3, or install the legacy-assets companion below).', 'bsshortcodes' ); ?>
+			</p>
+		<?php endif;
+	}
+
+	public function dependency_label( $dep ) {
+		$labels = array(
+			'bootstrap-css' => __( 'Bootstrap 3 CSS', 'bsshortcodes' ),
+			'glyphicons'    => __( 'Glyphicons font (part of Bootstrap 3 CSS)', 'bsshortcodes' ),
+		);
+		return isset( $labels[ $dep ] ) ? $labels[ $dep ] : $dep;
+	}
+
+	private function options_switcher( $options, $extra_args ) {
+		$links = array();
+		foreach ( array( 'auto' => __( 'auto', 'bsshortcodes' ), 'blocks' => __( 'blocks', 'bsshortcodes' ), 'html' => __( 'HTML', 'bsshortcodes' ) ) as $mode => $label ) {
+			$links[] = $mode === $options['mode'] ? '<strong>' . esc_html( $label ) . '</strong>' : '<a href="' . esc_url( BS_Admin_Tools::url( array_merge( $extra_args, array( 'mode' => $mode, 'style' => $options['style'] ) ) ) ) . '">' . esc_html( $label ) . '</a>';
+		}
+		$out = esc_html__( 'Output:', 'bsshortcodes' ) . ' ' . implode( ' | ', $links );
+		$links = array();
+		foreach ( array( 'inline' => __( 'self-contained', 'bsshortcodes' ), 'classes' => __( 'Bootstrap classes', 'bsshortcodes' ) ) as $style => $label ) {
+			$links[] = $style === $options['style'] ? '<strong>' . esc_html( $label ) . '</strong>' : '<a href="' . esc_url( BS_Admin_Tools::url( array_merge( $extra_args, array( 'mode' => $options['mode'], 'style' => $style ) ) ) ) . '">' . esc_html( $label ) . '</a>';
+		}
+		return '<span class="bs-switcher">' . $out . ' &nbsp; ' . esc_html__( 'Styling:', 'bsshortcodes' ) . ' ' . implode( ' | ', $links ) . '</span>';
+	}
+
+	/** Migration controls shown under the report's affected-content table. */
+	public function render_migration_section( $results ) {
+		$options  = $this->options_from_request();
+		$migrated = BS_Migration::migrated_posts();
+		$pending  = array();
+		foreach ( $results['posts'] as $p ) {
+			if ( ! in_array( 'malformed', $p['flags'], true ) || $p['counts'] ) {
+				$pending[] = $p['id'];
+			}
+		}
+		?>
+		<h2 id="migration"><?php esc_html_e( 'Migrate', 'bsshortcodes' ); ?></h2>
+		<p><?php esc_html_e( 'Rewrites the shortcodes in a post as blocks or plain HTML so the post no longer needs this plugin. Every migrated post keeps its original in a custom field and gets a revision; you can roll back any time from this page. Occurrences the converter is unsure about (mismatched open/close tags, unrecognised tags) are left exactly as they are and listed for you.', 'bsshortcodes' ); ?>
+			<a href="https://github.com/TheWebShop/bootstrap-shortcodes/blob/master/docs/migration.md" target="_blank" rel="noopener noreferrer"><?php esc_html_e( 'What each component becomes', 'bsshortcodes' ); ?></a>
+		</p>
+		<p><?php echo $this->options_switcher( $options, array() ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?></p>
+		<ul class="description" style="list-style:disc;margin-left:1.5em">
+			<li><?php esc_html_e( 'Output "auto": block markup for posts that already use blocks, static HTML for classic posts.', 'bsshortcodes' ); ?></li>
+			<li><?php esc_html_e( 'Styling "self-contained": wells, alerts, labels, lead text and tooltips carry inline styles and icons become inline SVG, so nothing needs Bootstrap CSS. "Bootstrap classes" keeps the original class names only, for sites that keep Bootstrap 3 (theme or companion).', 'bsshortcodes' ); ?></li>
+			<li><?php esc_html_e( 'Grid rows become Columns blocks (or keep row/col classes in HTML output), standalone buttons become Buttons blocks, collapse items and tabs become collapsible Details sections. Tabs change interaction (sections instead of tabs); alerts lose the dismiss button; tooltips become native title tooltips.', 'bsshortcodes' ); ?></li>
+		</ul>
+
+		<?php if ( $pending ) : ?>
+			<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="bs-migrate-batch" data-nonce="<?php echo esc_attr( wp_create_nonce( self::ACTION_BATCH ) ); ?>" data-action="<?php echo esc_attr( self::ACTION_BATCH ); ?>" data-batch="<?php echo (int) self::BATCH; ?>">
+				<?php wp_nonce_field( self::ACTION_BATCH ); ?>
+				<input type="hidden" name="action" value="<?php echo esc_attr( self::ACTION_BATCH ); ?>" />
+				<input type="hidden" name="mode" value="<?php echo esc_attr( $options['mode'] ); ?>" />
+				<input type="hidden" name="style" value="<?php echo esc_attr( $options['style'] ); ?>" />
+				<table class="widefat striped bs-migrate-table">
+					<thead><tr>
+						<td class="check-column"><input type="checkbox" class="bs-check-all" aria-label="<?php esc_attr_e( 'Select all', 'bsshortcodes' ); ?>" /></td>
+						<th><?php esc_html_e( 'Post', 'bsshortcodes' ); ?></th>
+						<th><?php esc_html_e( 'Status', 'bsshortcodes' ); ?></th>
+						<th><?php esc_html_e( 'Components', 'bsshortcodes' ); ?></th>
+						<th><?php esc_html_e( 'Complications', 'bsshortcodes' ); ?></th>
+						<th><?php esc_html_e( 'Migration', 'bsshortcodes' ); ?></th>
+					</tr></thead>
+					<tbody>
+					<?php
+					$labels = BS_Admin_Tools::flag_labels();
+					foreach ( $results['posts'] as $p ) :
+						$is_migrated = in_array( $p['id'], $migrated, true );
+						$preview_url = BS_Admin_Tools::url( array( 'bs_preview' => $p['id'], 'mode' => $options['mode'], 'style' => $options['style'] ) );
+						?>
+						<tr data-post-id="<?php echo (int) $p['id']; ?>">
+							<th scope="row" class="check-column"><input type="checkbox" name="post_ids[]" value="<?php echo (int) $p['id']; ?>" /></th>
+							<td><a href="<?php echo esc_url( get_edit_post_link( $p['id'] ) ); ?>"><?php echo esc_html( '' !== $p['title'] ? $p['title'] : '#' . $p['id'] ); ?></a></td>
+							<td><?php echo esc_html( $p['status'] ); ?></td>
+							<td><?php
+								$parts = array();
+								foreach ( $p['counts'] as $tag => $n ) {
+									$parts[] = $tag . ' ×' . (int) $n;
+								}
+								echo esc_html( implode( ', ', $parts ) );
+							?></td>
+							<td><?php
+								$parts = array();
+								foreach ( $p['flags'] as $flag ) {
+									$parts[] = isset( $labels[ $flag ] ) ? $labels[ $flag ] : $flag;
+								}
+								echo esc_html( implode( '; ', $parts ) );
+							?></td>
+							<td class="bs-migrate-status">
+								<a href="<?php echo esc_url( $preview_url ); ?>"><?php esc_html_e( 'Preview', 'bsshortcodes' ); ?></a>
+								<?php if ( $is_migrated ) : ?>
+									<em><?php esc_html_e( '(migrated before; shortcodes remain)', 'bsshortcodes' ); ?></em>
+								<?php endif; ?>
+							</td>
+						</tr>
+					<?php endforeach; ?>
+					</tbody>
+				</table>
+				<p>
+					<button class="button button-primary bs-migrate-selected" disabled><?php esc_html_e( 'Migrate selected', 'bsshortcodes' ); ?></button>
+					<span class="description"><?php printf( esc_html__( 'Each post is read fresh and converted from its current content, %d at a time. Posts with mismatched tags are converted where possible and the rest is left for you.', 'bsshortcodes' ), (int) self::BATCH ); ?></span>
+					<span class="bs-migrate-progress"></span>
+				</p>
+			</form>
+		<?php else : ?>
+			<p><?php esc_html_e( 'The last scan found no post content to migrate.', 'bsshortcodes' ); ?></p>
+		<?php endif; ?>
+
+		<h3><?php esc_html_e( 'Migrated posts (roll back)', 'bsshortcodes' ); ?></h3>
+		<?php if ( ! $migrated ) : ?>
+			<p><?php esc_html_e( 'None yet.', 'bsshortcodes' ); ?></p>
+		<?php else : ?>
+			<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="bs-rollback" onsubmit="return window.confirm('<?php echo esc_js( __( 'Restore the original shortcode content of the selected posts?', 'bsshortcodes' ) ); ?>');">
+				<?php wp_nonce_field( self::ACTION_ROLLBACK ); ?>
+				<input type="hidden" name="action" value="<?php echo esc_attr( self::ACTION_ROLLBACK ); ?>" />
+				<table class="widefat striped bs-rollback-table">
+					<thead><tr><td class="check-column"><input type="checkbox" class="bs-check-all" aria-label="<?php esc_attr_e( 'Select all', 'bsshortcodes' ); ?>" /></td><th><?php esc_html_e( 'Post', 'bsshortcodes' ); ?></th><th><?php esc_html_e( 'Migrated', 'bsshortcodes' ); ?></th><th><?php esc_html_e( 'Result', 'bsshortcodes' ); ?></th></tr></thead>
+					<tbody>
+					<?php foreach ( $migrated as $id ) :
+						$meta = get_post_meta( $id, BS_Migration::META_RESULT, true );
+						$meta = is_array( $meta ) ? $meta : array();
+						?>
+						<tr>
+							<th scope="row" class="check-column"><input type="checkbox" name="post_ids[]" value="<?php echo (int) $id; ?>" /></th>
+							<td><a href="<?php echo esc_url( get_edit_post_link( $id ) ); ?>"><?php echo esc_html( get_the_title( $id ) ? get_the_title( $id ) : '#' . $id ); ?></a> <a href="<?php echo esc_url( get_permalink( $id ) ); ?>"><?php esc_html_e( 'view', 'bsshortcodes' ); ?></a></td>
+							<td><?php echo isset( $meta['migrated_at'] ) ? esc_html( wp_date( get_option( 'date_format' ) . ' ' . get_option( 'time_format' ), $meta['migrated_at'] ) ) : ''; ?></td>
+							<td><?php
+								if ( $meta ) {
+									printf( esc_html__( '%1$d converted, %2$d left in place; %3$s', 'bsshortcodes' ), (int) $meta['converted'], (int) $meta['skipped'], esc_html( $meta['dependencies'] ? __( 'still needs: ', 'bsshortcodes' ) . implode( ', ', array_map( array( $this, 'dependency_label' ), $meta['dependencies'] ) ) : __( 'no legacy CSS needed', 'bsshortcodes' ) ) );
+								}
+							?></td>
+						</tr>
+					<?php endforeach; ?>
+					</tbody>
+				</table>
+				<p><button class="button"><?php esc_html_e( 'Roll back selected', 'bsshortcodes' ); ?></button></p>
+			</form>
+		<?php endif; ?>
+
+		<?php $this->render_companion_section( $results ); ?>
+		<?php
+	}
+
+	private function render_companion_section( $results ) {
+		$env       = $results['environment'];
+		$installed = BS_Companion::is_installed();
+		$active    = BS_Companion::is_active();
+		?>
+		<h3 id="legacy-assets"><?php esc_html_e( 'Keeping Bootstrap 3 after removing this plugin', 'bsshortcodes' ); ?></h3>
+		<p><?php esc_html_e( 'Removing this plugin removes two things: the shortcodes, and (unless your theme provides Bootstrap) the Bootstrap 3 CSS/JavaScript it loads on every page. Migration handles the first. If anything else on the site still relies on Bootstrap 3 (theme markup, hand-written HTML with btn/row/col classes, posts migrated with "Bootstrap classes" styling, Glyphicons), you need the second too.', 'bsshortcodes' ); ?></p>
+		<ul style="list-style:disc;margin-left:1.5em">
+			<li><?php esc_html_e( 'Best: your theme loads its own Bootstrap, or you migrate everything with "self-contained" styling and need nothing.', 'bsshortcodes' ); ?></li>
+			<li><?php esc_html_e( 'Otherwise: install the "Bootstrap 3 Legacy Assets" companion. It is a separate, tiny plugin built from this plugin\'s files that loads the same CSS/JS/font and nothing else. It registers no shortcodes, so the site is independent of Bootstrap Shortcodes but still carries a documented Bootstrap 3 dependency.', 'bsshortcodes' ); ?></li>
+		</ul>
+		<p><strong><?php esc_html_e( 'Bootstrap 3 is end-of-life (last release 3.4.1, 2019).', 'bsshortcodes' ); ?></strong> <?php esc_html_e( 'No upstream security fixes will come; what is known is documented in docs/security.md. Keeping it is a deliberate, temporary choice.', 'bsshortcodes' ); ?></p>
+		<?php if ( $active ) : ?>
+			<p class="notice notice-success inline" style="padding:8px"><?php esc_html_e( 'The companion is installed and active. It takes over the moment this plugin stops loading its files (deactivate this plugin, or turn off its asset settings).', 'bsshortcodes' ); ?> <a href="<?php echo esc_url( admin_url( 'options-general.php?page=bs-legacy-assets' ) ); ?>"><?php esc_html_e( 'Companion settings', 'bsshortcodes' ); ?></a></p>
+		<?php elseif ( $installed ) : ?>
+			<p class="notice notice-info inline" style="padding:8px"><?php esc_html_e( 'The companion is installed but not active.', 'bsshortcodes' ); ?> <a href="<?php echo esc_url( admin_url( 'plugins.php' ) ); ?>"><?php esc_html_e( 'Plugins', 'bsshortcodes' ); ?></a></p>
+		<?php else : ?>
+			<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="bs-companion">
+				<?php wp_nonce_field( self::ACTION_COMPANION ); ?>
+				<input type="hidden" name="action" value="<?php echo esc_attr( self::ACTION_COMPANION ); ?>" />
+				<p><label><input type="checkbox" name="bs_companion_consent" value="1" /> <?php esc_html_e( 'I understand this installs and activates a separate plugin that keeps loading end-of-life Bootstrap 3.4.1 on my site, and that ownership of those assets moves from Bootstrap Shortcodes to it.', 'bsshortcodes' ); ?></label></p>
+				<p>
+					<button class="button"><?php esc_html_e( 'Install and activate the companion', 'bsshortcodes' ); ?></button>
+					<a class="button" href="<?php echo esc_url( wp_nonce_url( admin_url( 'admin-post.php?action=' . self::ACTION_COMPANION_ZIP ), self::ACTION_COMPANION_ZIP ) ); ?>"><?php esc_html_e( 'Download the companion zip instead', 'bsshortcodes' ); ?></a>
+					<span class="description"><?php esc_html_e( 'Its settings start as copies of this plugin\'s CSS/JS settings.', 'bsshortcodes' ); ?></span>
+				</p>
+			</form>
+		<?php endif; ?>
+		<p class="description">
+			<?php
+			esc_html_e( 'Current settings: ', 'bsshortcodes' );
+			echo esc_html( sprintf( 'CSS %s, JS %s.', $env['settings']['css'] ? __( 'on', 'bsshortcodes' ) : __( 'off', 'bsshortcodes' ), $env['settings']['js'] ? __( 'on', 'bsshortcodes' ) : __( 'off', 'bsshortcodes' ) ) );
+			?>
+		</p>
+		<?php
+	}
+}
diff --git a/inc/class-bs-admin-tools.php b/inc/class-bs-admin-tools.php
index 3339570..2ae50a1 100644
--- a/inc/class-bs-admin-tools.php
+++ b/inc/class-bs-admin-tools.php
@@ -12,7 +12,11 @@ class BS_Admin_Tools {
 	const ACTION = 'bs_scan_step';
 	const BATCH  = 100;
 
-	public function __construct() {
+	/** @var BS_Admin_Migration|null */
+	private $migration;
+
+	public function __construct( $migration = null ) {
+		$this->migration = $migration;
 		add_action( 'admin_menu', array( $this, 'register_page' ) );
 		add_action( 'admin_post_' . self::ACTION, array( $this, 'handle_form_step' ) );
 		add_action( 'admin_post_bs_scan_reset', array( $this, 'handle_reset' ) );
@@ -46,6 +50,11 @@ public function enqueue( $hook ) {
 			'nonce'   => wp_create_nonce( self::ACTION ),
 			'batch'   => self::BATCH,
 			'reload'  => self::url(),
+			'i18n'    => array(
+				'migrated' => __( 'migrated', 'bsshortcodes' ),
+				'failed'   => __( 'not migrated', 'bsshortcodes' ),
+				'confirm'  => __( 'Migrate the selected posts now? Originals are kept for rollback.', 'bsshortcodes' ),
+			),
 		) );
 	}
 
@@ -146,6 +155,8 @@ public function render() {
 		?>
 		<div class="wrap bs-tools">
 			<h1><?php esc_html_e( 'Bootstrap Shortcodes: dependency report', 'bsshortcodes' ); ?></h1>
+			<?php if ( $this->migration ) { $this->migration->render_notices(); } ?>
+			<?php if ( $this->migration && $this->migration->render_preview() ) { echo '</div>'; return; } ?>
 			<p><?php esc_html_e( 'What on this site depends on this plugin, and what would happen if you removed it. The scan reads content; it changes nothing and sends nothing anywhere.', 'bsshortcodes' ); ?></p>
 
 			<?php $this->render_controls( $state, $done ); ?>
@@ -156,6 +167,7 @@ public function render() {
 				<?php $this->render_posts( $results ); ?>
 				<?php $this->render_surfaces( $results ); ?>
 				<?php $this->render_not_scanned( $results ); ?>
+				<?php if ( $this->migration ) { $this->migration->render_migration_section( $results ); } ?>
 				<?php $this->render_share( $results ); ?>
 			<?php endif; ?>
 		</div>
diff --git a/inc/class-bs-companion.php b/inc/class-bs-companion.php
new file mode 100644
index 0000000..cccba1c
--- /dev/null
+++ b/inc/class-bs-companion.php
@@ -0,0 +1,126 @@
+<?php
+/**
+ * Builds and installs the "Bootstrap 3 Legacy Assets" companion plugin from
+ * this plugin's own files. Install only happens from an explicit, nonced,
+ * consented admin action; a zip download is always offered as the manual path.
+ */
+class BS_Companion {
+
+	const SLUG = 'bootstrap-legacy-assets';
+	const FILE = 'bootstrap-legacy-assets/bootstrap-legacy-assets.php';
+
+	public static function source_dir() {
+		return dirname( BS_SHORTCODES_FILE ) . '/companion/' . self::SLUG;
+	}
+
+	/** Files that go into the zip: [path inside zip => absolute source]. */
+	public static function manifest() {
+		$plugin = dirname( BS_SHORTCODES_FILE );
+		$files  = array(
+			self::SLUG . '/bootstrap-legacy-assets.php' => self::source_dir() . '/bootstrap-legacy-assets.php',
+			self::SLUG . '/readme.txt'                  => self::source_dir() . '/readme.txt',
+			self::SLUG . '/css/bootstrap.css'           => $plugin . '/css/bootstrap.css',
+			self::SLUG . '/js/bootstrap.js'             => $plugin . '/js/bootstrap.js',
+			self::SLUG . '/js/init.js'                  => $plugin . '/js/init.js',
+		);
+		foreach ( glob( $plugin . '/fonts/glyphicons-halflings-regular.*' ) as $font ) {
+			$files[ self::SLUG . '/fonts/' . basename( $font ) ] = $font;
+		}
+		return $files;
+	}
+
+	/**
+	 * Write the zip into the uploads dir (private name) and return its path.
+	 */
+	public static function build_zip() {
+		$upload = wp_upload_dir();
+		if ( ! empty( $upload['error'] ) ) {
+			return new WP_Error( 'bs_zip', $upload['error'] );
+		}
+		$path = trailingslashit( $upload['basedir'] ) . self::SLUG . '-' . wp_generate_password( 8, false ) . '.zip';
+		$files = self::manifest();
+		foreach ( $files as $src ) {
+			if ( ! is_readable( $src ) ) {
+				return new WP_Error( 'bs_zip', sprintf( 'Missing source file %s', basename( $src ) ) );
+			}
+		}
+		if ( class_exists( 'ZipArchive' ) ) {
+			$zip = new ZipArchive();
+			if ( true !== $zip->open( $path, ZipArchive::CREATE | ZipArchive::OVERWRITE ) ) {
+				return new WP_Error( 'bs_zip', 'Could not create the zip file.' );
+			}
+			foreach ( $files as $inside => $src ) {
+				$zip->addFile( $src, $inside );
+			}
+			$zip->close();
+		} else {
+			require_once ABSPATH . 'wp-admin/includes/class-pclzip.php';
+			$zip = new PclZip( $path );
+			foreach ( $files as $inside => $src ) {
+				$res = $zip->add( $src, PCLZIP_OPT_REMOVE_ALL_PATH, PCLZIP_OPT_ADD_PATH, dirname( $inside ) );
+				if ( 0 === $res ) {
+					return new WP_Error( 'bs_zip', $zip->errorInfo( true ) );
+				}
+			}
+		}
+		return $path;
+	}
+
+	public static function is_installed() {
+		return file_exists( WP_PLUGIN_DIR . '/' . self::FILE );
+	}
+
+	public static function is_active() {
+		return function_exists( 'is_plugin_active' ) ? is_plugin_active( self::FILE ) : in_array( self::FILE, (array) get_option( 'active_plugins', array() ), true );
+	}
+
+	/**
+	 * Install (if needed) and activate through core's upgrader. Only works when
+	 * WordPress can write to the plugins directory itself; otherwise the caller
+	 * should offer the zip for manual upload.
+	 */
+	public static function install_and_activate() {
+		if ( ! current_user_can( 'install_plugins' ) || ! current_user_can( 'activate_plugins' ) ) {
+			return new WP_Error( 'bs_forbidden', __( 'You cannot install plugins on this site.', 'bsshortcodes' ) );
+		}
+		require_once ABSPATH . 'wp-admin/includes/file.php';
+		require_once ABSPATH . 'wp-admin/includes/plugin.php';
+		if ( ! self::is_installed() ) {
+			if ( 'direct' !== get_filesystem_method() || ! wp_is_writable( WP_PLUGIN_DIR ) ) {
+				return new WP_Error( 'bs_filesystem', __( 'WordPress cannot write to the plugins directory on this host. Download the zip and install it through Plugins > Add New > Upload Plugin.', 'bsshortcodes' ) );
+			}
+			$zip = self::build_zip();
+			if ( is_wp_error( $zip ) ) {
+				return $zip;
+			}
+			require_once ABSPATH . 'wp-admin/includes/class-wp-upgrader.php';
+			$skin     = new WP_Ajax_Upgrader_Skin();
+			$upgrader = new Plugin_Upgrader( $skin );
+			$result   = $upgrader->install( $zip );
+			@unlink( $zip );
+			if ( is_wp_error( $result ) ) {
+				return $result;
+			}
+			if ( ! $result ) {
+				$errors = $skin->get_errors();
+				return new WP_Error( 'bs_install', $errors && $errors->has_errors() ? $errors->get_error_message() : __( 'Install failed.', 'bsshortcodes' ) );
+			}
+			if ( ! self::is_installed() ) {
+				return new WP_Error( 'bs_install', __( 'The companion did not land in the plugins directory.', 'bsshortcodes' ) );
+			}
+		}
+		// Mirror the original plugin's asset choices so the site looks the same.
+		$o = get_option( 'bs_options' );
+		$o = is_array( $o ) ? $o : array();
+		update_option( 'bs_legacy_assets', array_filter( array(
+			'css'      => empty( $o['chk_default_options_css'] ) ? '' : '1',
+			'js'       => empty( $o['chk_default_options_js'] ) ? '' : '1',
+			'tooltips' => empty( $o['chk_default_options_js'] ) ? '' : '1',
+		) ) );
+		$activated = activate_plugin( self::FILE );
+		if ( is_wp_error( $activated ) ) {
+			return $activated;
+		}
+		return true;
+	}
+}
diff --git a/inc/class-bs-migration.php b/inc/class-bs-migration.php
new file mode 100644
index 0000000..0497dee
--- /dev/null
+++ b/inc/class-bs-migration.php
@@ -0,0 +1,149 @@
+<?php
+/**
+ * Applying conversions to posts: preview, apply with a recoverable original,
+ * roll back, and bounded batches. Nothing here runs automatically; every write
+ * comes from an explicit admin action with a nonce and a capability check.
+ */
+class BS_Migration {
+
+	const META_ORIGINAL = '_bs_migration_original';
+	const META_RESULT   = '_bs_migration_result';
+	const MAX_BATCH     = 25;
+
+	public static function options_from( $input ) {
+		$mode  = isset( $input['mode'] ) && in_array( $input['mode'], array( 'auto', 'blocks', 'html' ), true ) ? $input['mode'] : 'auto';
+		$style = isset( $input['style'] ) && in_array( $input['style'], array( 'inline', 'classes' ), true ) ? $input['style'] : 'inline';
+		return array( 'mode' => $mode, 'style' => $style );
+	}
+
+	/**
+	 * Convert without writing. Includes what the apply step will check against.
+	 */
+	public static function preview( $post_id, $options ) {
+		$post = get_post( $post_id );
+		if ( ! $post ) {
+			return new WP_Error( 'bs_not_found', __( 'Post not found.', 'bsshortcodes' ) );
+		}
+		if ( ! current_user_can( 'edit_post', $post->ID ) ) {
+			return new WP_Error( 'bs_forbidden', __( 'You cannot edit this post.', 'bsshortcodes' ) );
+		}
+		$result = BS_Migrator::convert( $post->post_content, $options );
+		return array(
+			'post_id'      => $post->ID,
+			'title'        => $post->post_title,
+			'status'       => $post->post_status,
+			'modified_gmt' => $post->post_modified_gmt,
+			'original'     => $post->post_content,
+			'converted'    => $result['content'],
+			'result'       => $result,
+			'already'      => (bool) get_post_meta( $post->ID, self::META_ORIGINAL, true ),
+		);
+	}
+
+	/**
+	 * Write the conversion. Refuses if the post changed since $expected_modified_gmt
+	 * (when given), keeps the original in post meta on first migration, and lets
+	 * wp_update_post() add a revision as usual.
+	 */
+	public static function apply( $post_id, $options, $expected_modified_gmt = null ) {
+		$preview = self::preview( $post_id, $options );
+		if ( is_wp_error( $preview ) ) {
+			return $preview;
+		}
+		if ( null !== $expected_modified_gmt && $expected_modified_gmt !== $preview['modified_gmt'] ) {
+			return new WP_Error( 'bs_stale', __( 'This post was edited after the preview was made. Preview it again before migrating.', 'bsshortcodes' ) );
+		}
+		$result = $preview['result'];
+		if ( 0 === $result['converted'] ) {
+			return new WP_Error( 'bs_nothing', $result['skipped'] ? __( 'Nothing could be converted automatically; see the skipped list.', 'bsshortcodes' ) : __( 'No shortcodes to convert in this post.', 'bsshortcodes' ) );
+		}
+		if ( ! $preview['already'] ) {
+			$kept = add_post_meta( $post_id, self::META_ORIGINAL, array(
+				'content'      => $preview['original'],
+				'modified_gmt' => $preview['modified_gmt'],
+				'migrated_at'  => time(),
+				'version'      => BS_Migrator::VERSION,
+			), true );
+			if ( ! $kept ) {
+				return new WP_Error( 'bs_backup', __( 'Could not store the original content; nothing was changed.', 'bsshortcodes' ) );
+			}
+		}
+		$updated = wp_update_post( array( 'ID' => $post_id, 'post_content' => $preview['converted'] ), true );
+		if ( is_wp_error( $updated ) ) {
+			return $updated;
+		}
+		update_post_meta( $post_id, self::META_RESULT, array(
+			'converted'    => $result['converted'],
+			'skipped'      => count( $result['skipped'] ),
+			'notes'        => $result['notes'],
+			'dependencies' => $result['dependencies'],
+			'mode'         => $result['mode'],
+			'style'        => $result['style'],
+			'migrated_at'  => time(),
+		) );
+		return array(
+			'post_id'      => $post_id,
+			'converted'    => $result['converted'],
+			'skipped'      => $result['skipped'],
+			'notes'        => $result['notes'],
+			'dependencies' => $result['dependencies'],
+		);
+	}
+
+	/** Put the stored original back. The migrated version stays in revisions. */
+	public static function rollback( $post_id ) {
+		$post = get_post( $post_id );
+		if ( ! $post ) {
+			return new WP_Error( 'bs_not_found', __( 'Post not found.', 'bsshortcodes' ) );
+		}
+		if ( ! current_user_can( 'edit_post', $post->ID ) ) {
+			return new WP_Error( 'bs_forbidden', __( 'You cannot edit this post.', 'bsshortcodes' ) );
+		}
+		$backup = get_post_meta( $post->ID, self::META_ORIGINAL, true );
+		if ( ! is_array( $backup ) || ! isset( $backup['content'] ) ) {
+			return new WP_Error( 'bs_no_backup', __( 'No stored original for this post.', 'bsshortcodes' ) );
+		}
+		$updated = wp_update_post( array( 'ID' => $post->ID, 'post_content' => $backup['content'] ), true );
+		if ( is_wp_error( $updated ) ) {
+			return $updated;
+		}
+		delete_post_meta( $post->ID, self::META_ORIGINAL );
+		delete_post_meta( $post->ID, self::META_RESULT );
+		return true;
+	}
+
+	/**
+	 * Apply to several posts. Each post is read fresh and converted from its
+	 * current content, so a post edited after the scan is converted as it is
+	 * now, never from a stale copy. Bounded to MAX_BATCH per call.
+	 */
+	public static function batch( $post_ids, $options ) {
+		$post_ids = array_slice( array_values( array_unique( array_map( 'intval', (array) $post_ids ) ) ), 0, self::MAX_BATCH );
+		$out      = array();
+		foreach ( $post_ids as $id ) {
+			$r = self::apply( $id, $options );
+			$out[ $id ] = is_wp_error( $r )
+				? array( 'ok' => false, 'code' => $r->get_error_code(), 'message' => $r->get_error_message() )
+				: array( 'ok' => true, 'converted' => $r['converted'], 'skipped' => count( $r['skipped'] ), 'dependencies' => $r['dependencies'] );
+		}
+		return $out;
+	}
+
+	/** Posts that hold a stored original, newest first (bounded). */
+	public static function migrated_posts( $limit = 500 ) {
+		return get_posts( array(
+			'post_type'      => 'any',
+			'post_status'    => 'any',
+			'posts_per_page' => $limit,
+			'meta_key'       => self::META_ORIGINAL,
+			'orderby'        => 'modified',
+			'order'          => 'DESC',
+			'fields'         => 'ids',
+			'no_found_rows'  => true,
+		) );
+	}
+
+	public static function is_migrated( $post_id ) {
+		return (bool) get_post_meta( $post_id, self::META_ORIGINAL, true );
+	}
+}
diff --git a/inc/class-bs-migrator.php b/inc/class-bs-migrator.php
new file mode 100644
index 0000000..07e1372
--- /dev/null
+++ b/inc/class-bs-migrator.php
@@ -0,0 +1,695 @@
+<?php
+/**
+ * Converter: bs_* shortcode text into block markup or static HTML.
+ *
+ * Rules it keeps:
+ *  - everything that is not one of our shortcodes is passed through byte for byte
+ *    (HTML, other plugins' shortcodes, escaped [[bs_x]], unrecognised bs_ tags);
+ *  - an occurrence it cannot convert safely (unbalanced open/close) is left in
+ *    place and reported in `skipped`;
+ *  - anything it drops or approximates is reported in `notes`;
+ *  - the CSS/JS the output still relies on is reported in `dependencies`.
+ *
+ * Modes:  blocks (core block markup), html (static HTML), auto (blocks when the
+ *         post already has blocks, otherwise html).
+ * Styles: inline (self-contained: inline styles, inline SVG icons, wells and
+ *         alerts as Custom HTML blocks) or classes (keep Bootstrap class names
+ *         only; needs Bootstrap 3 CSS from the theme or the legacy-assets companion).
+ */
+class BS_Migrator {
+
+	const VERSION = 1;
+
+	private static $options;
+	private static $skipped;
+	private static $notes;
+	private static $deps;
+	private static $converted;
+	private static $unbalanced;
+	private static $tab_titles;
+	private static $section_counter;
+
+	public static function convert( $content, $options = array() ) {
+		$options = wp_parse_args( $options, array( 'mode' => 'auto', 'style' => 'inline' ) );
+		if ( 'auto' === $options['mode'] ) {
+			$options['mode'] = ( is_string( $content ) && has_blocks( $content ) ) ? 'blocks' : 'html';
+		}
+		self::$options    = $options;
+		self::$skipped    = array();
+		self::$notes      = array();
+		self::$deps       = array();
+		self::$converted  = 0;
+		self::$tab_titles = array();
+		self::$section_counter = 0;
+
+		$result = array(
+			'content'      => $content,
+			'converted'    => 0,
+			'skipped'      => array(),
+			'notes'        => array(),
+			'dependencies' => array(),
+			'mode'         => $options['mode'],
+			'style'        => $options['style'],
+			'version'      => self::VERSION,
+		);
+		if ( ! is_string( $content ) || false === strpos( $content, '[bs_' ) ) {
+			return $result;
+		}
+
+		$scan             = BS_Scanner::scan_text( $content );
+		self::$unbalanced = $scan['unbalanced'];
+
+		if ( 'blocks' === $options['mode'] && has_blocks( $content ) ) {
+			// A block document: convert inside the blocks that hold shortcodes
+			// (Shortcode, Classic, Paragraph, Custom HTML ...) without breaking
+			// their structure.
+			$result['content'] = serialize_blocks( self::convert_blocks( parse_blocks( $content ) ) );
+		} else {
+			$result['content'] = self::process( $content, true );
+			if ( 'blocks' === $options['mode'] ) {
+				// Loose text between blocks becomes paragraphs (or a Classic block), as the editor would.
+				$result['content'] = self::inner_blocks( $result['content'] );
+			}
+		}
+		$result['converted']    = self::$converted;
+		$result['skipped']      = self::$skipped;
+		$result['notes']        = array_values( array_unique( self::$notes ) );
+		$result['dependencies'] = array_values( array_unique( self::$deps ) );
+		return $result;
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Block documents                                                     */
+	/* ------------------------------------------------------------------ */
+
+	/**
+	 * Walk parsed blocks. Shortcode blocks and standalone-shortcode paragraphs
+	 * are replaced by the converted blocks; Classic, Custom HTML and other
+	 * blocks get their inner HTML converted as static HTML; inner blocks recurse.
+	 */
+	private static function convert_blocks( $blocks ) {
+		$out = array();
+		foreach ( $blocks as $block ) {
+			$html = isset( $block['innerHTML'] ) ? $block['innerHTML'] : '';
+			$has  = false !== strpos( $html, '[bs_' );
+			if ( null === $block['blockName'] ) {
+				if ( $has ) {
+					$block = self::raw_block( self::inner_blocks( self::process( $html, true ) ) );
+				}
+				$out[] = $block;
+				continue;
+			}
+			if ( 'core/shortcode' === $block['blockName'] && $has ) {
+				$converted = self::inner_blocks( self::process( $html, true ) );
+				$out[]     = self::raw_block( $converted );
+				continue;
+			}
+			if ( 'core/paragraph' === $block['blockName'] && $has && preg_match( '/^\s*<p[^>]*>\s*(\[bs_[\s\S]*\])\s*<\/p>\s*$/', $html, $m ) && self::is_single_shortcode( $m[1] ) ) {
+				$converted = self::inner_blocks( self::process( $m[1], true ) );
+				$out[]     = self::raw_block( $converted );
+				continue;
+			}
+			if ( $has ) {
+				// Inline components inside this block's own HTML (paragraph, heading,
+				// list, classic, custom HTML ...): static HTML keeps the block valid.
+				$saved_mode              = self::$options['mode'];
+				self::$options['mode']   = 'html';
+				$block['innerHTML']      = self::process( $html, false );
+				$counted                 = self::$converted;
+				foreach ( $block['innerContent'] as $i => $chunk ) {
+					if ( is_string( $chunk ) && false !== strpos( $chunk, '[bs_' ) ) {
+						$block['innerContent'][ $i ] = self::process( $chunk, false );
+					}
+				}
+				self::$converted       = $counted; // innerContent repeats innerHTML; count once
+				self::$options['mode'] = $saved_mode;
+			}
+			if ( ! empty( $block['innerBlocks'] ) ) {
+				$block['innerBlocks'] = self::convert_blocks( $block['innerBlocks'] );
+			}
+			$out[] = $block;
+		}
+		return $out;
+	}
+
+	/** One of our shortcodes (possibly enclosing), and nothing else. */
+	private static function is_single_shortcode( $text ) {
+		if ( ! preg_match_all( '/' . get_shortcode_regex( BS_Scanner::tags() ) . '/', $text, $m, PREG_SET_ORDER | PREG_OFFSET_CAPTURE ) ) {
+			return false;
+		}
+		return 1 === count( $m ) && 0 === $m[0][0][1] && strlen( $m[0][0][0] ) === strlen( $text );
+	}
+
+	private static function raw_block( $html ) {
+		$html = "\n" . trim( $html ) . "\n";
+		return array( 'blockName' => null, 'attrs' => array(), 'innerBlocks' => array(), 'innerHTML' => $html, 'innerContent' => array( $html ) );
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Walking                                                             */
+	/* ------------------------------------------------------------------ */
+
+	private static function process( $text, $top_level ) {
+		if ( false === strpos( $text, '[bs_' ) ) {
+			return $text;
+		}
+		$pattern = '/' . get_shortcode_regex( BS_Scanner::tags() ) . '/';
+		$out     = '';
+		$last    = 0;
+		if ( ! preg_match_all( $pattern, $text, $matches, PREG_SET_ORDER | PREG_OFFSET_CAPTURE ) ) {
+			return $text;
+		}
+		foreach ( $matches as $m ) {
+			$start = $m[0][1];
+			$whole = $m[0][0];
+			$out  .= substr( $text, $last, $start - $last );
+			$last  = $start + strlen( $whole );
+
+			if ( '[' === $m[1][0] && ']' === $m[6][0] ) {
+				$out .= $whole; // escaped: literal text by design
+				continue;
+			}
+			$tag = $m[2][0];
+			if ( in_array( $tag, self::$unbalanced, true ) ) {
+				self::$skipped[] = array( 'tag' => $tag, 'reason' => 'unbalanced', 'offset' => $start );
+				$out .= $whole;
+				continue;
+			}
+			$attrs   = shortcode_parse_atts( $m[3][0] );
+			$attrs   = is_array( $attrs ) ? $attrs : array();
+			$content = isset( $m[5][0] ) ? $m[5][0] : '';
+			// The editor's own line-break markers ("<br class="nc" />", or without the
+			// space before TinyMCE normalises it) were never meant to render.
+			$content = preg_replace( '/<br class="nc"\s*\/?>/', '', $content );
+			self::note_unknown_attrs( $tag, $attrs );
+
+			$before     = substr( $text, 0, $start );
+			$after      = substr( $text, $last );
+			$standalone = (bool) preg_match( '/(^|\n)[ \t]*$/', $before ) && (bool) preg_match( '/^[ \t]*(\n|$)/', $after );
+
+			$replacement = self::convert_one( $tag, $attrs, $content, $standalone, $top_level );
+			if ( null === $replacement ) {
+				$out .= $whole;
+				continue;
+			}
+			self::$converted++;
+			$out .= $replacement;
+		}
+		$out .= substr( $text, $last );
+		return $out;
+	}
+
+	private static function note_unknown_attrs( $tag, $attrs ) {
+		$known = BS_Scanner::$known_attrs[ $tag ];
+		foreach ( $attrs as $k => $v ) {
+			if ( is_string( $k ) && ! in_array( $k, $known, true ) ) {
+				/* translators: 1: attribute, 2: shortcode */
+				self::$notes[] = sprintf( 'Attribute "%1$s" on [%2$s] was never used by the plugin and is dropped.', $k, $tag );
+			}
+		}
+	}
+
+	private static function blocks() {
+		return 'blocks' === self::$options['mode'];
+	}
+
+	private static function inline_style() {
+		return 'inline' === self::$options['style'];
+	}
+
+	private static function attr( $value ) {
+		return esc_attr( (string) $value );
+	}
+
+	private static function convert_one( $tag, $attrs, $content, $standalone, $top_level ) {
+		switch ( $tag ) {
+			case 'bs_row':
+				return self::row( $attrs, $content );
+			case 'bs_col':
+				return self::col( $attrs, $content, $top_level );
+			case 'bs_well':
+				return self::well( $attrs, $content );
+			case 'bs_notification':
+				return self::alert( $attrs, $content );
+			case 'bs_lead':
+				return self::lead( $content );
+			case 'bs_button':
+				return self::button( $attrs, $standalone );
+			case 'bs_label':
+				return self::label( $attrs, $content );
+			case 'bs_icon':
+				return self::icon( $attrs );
+			case 'bs_tooltip':
+				return self::tooltip( $attrs, $content );
+			case 'bs_collapse':
+				return self::collapse( $attrs, $content );
+			case 'bs_citem':
+				return self::citem( $attrs, $content, '' );
+			case 'bs_tabs':
+				return self::tabs( $content );
+			case 'bs_thead':
+			case 'bs_dropdown':
+			case 'bs_tab':
+				// Only meaningful inside [bs_tabs]; stray ones have nothing to show.
+				self::$notes[] = sprintf( 'A stray [%s] outside [bs_tabs] was removed (it rendered an empty tab strip).', $tag );
+				return '';
+			case 'bs_tcontents':
+				return self::process( $content, false );
+			case 'bs_tcontent':
+				return self::tcontent( $attrs, $content );
+		}
+		return null;
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Inner content helpers                                               */
+	/* ------------------------------------------------------------------ */
+
+	/**
+	 * Turn already-processed inner content into inner blocks: existing blocks
+	 * pass through, plain text becomes paragraphs, anything else becomes a
+	 * Classic block (which keeps wpautop behaviour for mixed HTML).
+	 */
+	private static function inner_blocks( $html ) {
+		$html = trim( $html );
+		if ( '' === $html ) {
+			return '';
+		}
+		$parts = array();
+		foreach ( parse_blocks( $html ) as $block ) {
+			if ( null !== $block['blockName'] ) {
+				$parts[] = trim( serialize_block( $block ) );
+				continue;
+			}
+			$chunk = trim( $block['innerHTML'] );
+			if ( '' === $chunk ) {
+				continue;
+			}
+			if ( $chunk === wp_strip_all_tags( $chunk ) ) {
+				foreach ( preg_split( '/\n\s*\n/', $chunk ) as $para ) {
+					$para = trim( $para );
+					if ( '' !== $para ) {
+						$parts[] = "<!-- wp:paragraph -->\n<p>" . str_replace( "\n", "<br>\n", $para ) . "</p>\n<!-- /wp:paragraph -->";
+					}
+				}
+				continue;
+			}
+			if ( self::is_simple_inline_html( $chunk ) ) {
+				$parts[] = "<!-- wp:paragraph -->\n<p>" . $chunk . "</p>\n<!-- /wp:paragraph -->";
+				continue;
+			}
+			$parts[] = "<!-- wp:freeform -->\n" . $chunk . "\n<!-- /wp:freeform -->";
+		}
+		return implode( "\n\n", $parts );
+	}
+
+	/** One line of text with only inline elements (span, a, svg, i, strong ...). */
+	private static function is_simple_inline_html( $chunk ) {
+		if ( false !== strpos( $chunk, "\n" ) ) {
+			return false;
+		}
+		$stripped = preg_replace( '#<(/?)(a|abbr|b|strong|i|em|span|svg|path|code|small|sub|sup|br)\b[^>]*>#i', '', $chunk );
+		return false === strpos( $stripped, '<' );
+	}
+
+	private static function wrap_block( $name, $attrs, $html ) {
+		$json = $attrs ? ' ' . wp_json_encode( $attrs, JSON_UNESCAPED_SLASHES ) : '';
+		return "<!-- wp:{$name}{$json} -->\n{$html}\n<!-- /wp:{$name} -->";
+	}
+
+	/** Static HTML keeps classic behaviour: wpautop runs later, as it always did. */
+	private static function inner_html( $html ) {
+		return self::process( $html, false );
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Components                                                          */
+	/* ------------------------------------------------------------------ */
+
+	private static function row( $attrs, $content ) {
+		$classes = isset( $attrs['class'] ) ? preg_split( '/\s+/', trim( $attrs['class'] ) ) : array( 'row' );
+		$extra   = array_values( array_diff( array_filter( $classes ), array( 'row' ) ) );
+		if ( ! self::blocks() ) {
+			self::$deps[] = 'bootstrap-css';
+			return '<div class="' . self::attr( implode( ' ', array_merge( array( 'row' ), $extra ) ) ) . '">' . self::inner_html( $content ) . '</div>';
+		}
+		$inner = self::process( $content, false );
+		// Inner must be columns only; stray text between columns is kept as its own column.
+		$columns = array();
+		foreach ( parse_blocks( trim( $inner ) ) as $block ) {
+			if ( 'core/column' === $block['blockName'] ) {
+				$columns[] = trim( serialize_block( $block ) );
+			} elseif ( '' !== trim( $block['innerHTML'] ) || null !== $block['blockName'] ) {
+				$columns[] = self::wrap_block( 'column', array(), '<div class="wp-block-column">' . self::inner_blocks( null !== $block['blockName'] ? serialize_block( $block ) : $block['innerHTML'] ) . '</div>' );
+				self::$notes[] = 'Content inside a [bs_row] that was not in a [bs_col] was placed in its own column.';
+			}
+		}
+		$block_attrs = $extra ? array( 'className' => implode( ' ', $extra ) ) : array();
+		$class       = 'wp-block-columns' . ( $extra ? ' ' . implode( ' ', $extra ) : '' );
+		return self::wrap_block( 'columns', $block_attrs, '<div class="' . self::attr( $class ) . '">' . implode( '', $columns ) . '</div>' );
+	}
+
+	private static function col( $attrs, $content, $top_level ) {
+		$classes = isset( $attrs['class'] ) ? preg_split( '/\s+/', trim( $attrs['class'] ) ) : array( 'col-sm-1' );
+		$classes = array_values( array_filter( $classes ) );
+		if ( ! self::blocks() ) {
+			self::$deps[] = 'bootstrap-css';
+			return '<div class="' . self::attr( implode( ' ', $classes ) ) . '">' . self::inner_html( $content ) . '</div>';
+		}
+		$width = null;
+		$extra = array();
+		foreach ( $classes as $class ) {
+			if ( preg_match( '/^col-(xs|sm|md|lg)-(\d{1,2})$/', $class, $mm ) ) {
+				if ( null === $width ) {
+					$width = (int) $mm[2];
+				}
+			} elseif ( preg_match( '/^col-(xs|sm|md|lg)-(offset|push|pull)-\d{1,2}$/', $class ) ) {
+				self::$notes[] = sprintf( 'Grid %s class "%s" has no Columns-block equivalent and was dropped.', 'offset/push/pull', $class );
+			} else {
+				$extra[] = $class;
+			}
+		}
+		$block_attrs = array();
+		$style       = '';
+		if ( $width && $width < 12 ) {
+			$pct                  = rtrim( rtrim( number_format( $width / 12 * 100, 2, '.', '' ), '0' ), '.' ) . '%';
+			$block_attrs['width'] = $pct;
+			$style                = ' style="flex-basis:' . $pct . '"';
+		}
+		if ( $extra ) {
+			$block_attrs['className'] = implode( ' ', $extra );
+		}
+		$class = 'wp-block-column' . ( $extra ? ' ' . implode( ' ', $extra ) : '' );
+		$inner = self::inner_blocks( self::process( $content, false ) );
+		return self::wrap_block( 'column', $block_attrs, '<div class="' . self::attr( $class ) . '"' . $style . '>' . $inner . '</div>' );
+	}
+
+	private static function well( $attrs, $content ) {
+		$size  = isset( $attrs['size'] ) && in_array( $attrs['size'], array( 'sm', 'lg' ), true ) ? $attrs['size'] : '';
+		$class = 'well' . ( $size ? ' well-' . $size : '' );
+		$pad   = 'lg' === $size ? '24px' : ( 'sm' === $size ? '9px' : '19px' );
+		$style = 'background-color:#f5f5f5;border:1px solid #e3e3e3;border-radius:' . ( 'lg' === $size ? '6px' : ( 'sm' === $size ? '3px' : '4px' ) ) . ';padding:' . $pad . ';margin-bottom:20px';
+		return self::box( $class, $style, $content, '' );
+	}
+
+	private static function alert( $attrs, $content ) {
+		$type   = isset( $attrs['type'] ) ? sanitize_html_class( $attrs['type'], 'unknown' ) : 'unknown';
+		$colors = array(
+			'success' => array( '#dff0d8', '#d6e9c6', '#3c763d' ),
+			'info'    => array( '#d9edf7', '#bce8f1', '#31708f' ),
+			'warning' => array( '#fcf8e3', '#faebcc', '#8a6d3b' ),
+			'danger'  => array( '#f2dede', '#ebccd1', '#a94442' ),
+		);
+		$c     = isset( $colors[ $type ] ) ? $colors[ $type ] : array( '#f5f5f5', '#e3e3e3', '#333333' );
+		$style = 'background-color:' . $c[0] . ';border:1px solid ' . $c[1] . ';color:' . $c[2] . ';border-radius:4px;padding:15px;margin-bottom:20px';
+		if ( ! isset( $attrs['dismissible'] ) || 'true' === $attrs['dismissible'] ) {
+			self::$notes[] = 'Alerts lose their dismiss (×) button: it needs Bootstrap JavaScript. The message itself is kept.';
+		}
+		return self::box( 'alert alert-' . $type, $style, $content, ' role="alert"' );
+	}
+
+	/** Shared by wells and alerts: a styled container. */
+	private static function box( $class, $style, $content, $extra_attrs ) {
+		if ( self::blocks() ) {
+			if ( self::inline_style() ) {
+				$inner = self::process( $content, false );
+				$html  = '<div class="' . self::attr( $class ) . '"' . $extra_attrs . ' style="' . self::attr( $style ) . '">' . self::bake_paragraphs( $inner ) . '</div>';
+				return self::wrap_block( 'html', array(), $html );
+			}
+			self::$deps[] = 'bootstrap-css';
+			return self::wrap_block( 'group', array( 'className' => $class ), '<div class="wp-block-group ' . self::attr( $class ) . '"' . $extra_attrs . '>' . self::inner_blocks( self::process( $content, false ) ) . '</div>' );
+		}
+		$inner = self::inner_html( $content );
+		if ( self::inline_style() ) {
+			return '<div class="' . self::attr( $class ) . '"' . $extra_attrs . ' style="' . self::attr( $style ) . '">' . $inner . '</div>';
+		}
+		self::$deps[] = 'bootstrap-css';
+		return '<div class="' . self::attr( $class ) . '"' . $extra_attrs . '>' . $inner . '</div>';
+	}
+
+	/**
+	 * Inside a Custom HTML block wpautop no longer runs, so bake the paragraphs
+	 * classic content relied on. Block markup inside is rendered to HTML.
+	 */
+	private static function bake_paragraphs( $html ) {
+		$html = trim( $html );
+		if ( '' === $html ) {
+			return '';
+		}
+		if ( has_blocks( $html ) ) {
+			$html = do_blocks( $html );
+		}
+		return wpautop( $html );
+	}
+
+	private static function lead( $content ) {
+		$inner = self::process( $content, false );
+		if ( self::blocks() ) {
+			if ( trim( $inner ) === wp_strip_all_tags( trim( $inner ) ) || self::is_simple_inline_html( trim( $inner ) ) ) {
+				return self::wrap_block( 'paragraph', array( 'className' => 'lead', 'fontSize' => 'large' ), '<p class="lead has-large-font-size">' . trim( $inner ) . '</p>' );
+			}
+			return self::wrap_block( 'group', array( 'className' => 'lead', 'fontSize' => 'large' ), '<div class="wp-block-group lead has-large-font-size">' . self::inner_blocks( $inner ) . '</div>' );
+		}
+		$style = self::inline_style() ? ' style="font-size:1.3em;font-weight:300"' : '';
+		if ( ! self::inline_style() ) {
+			self::$deps[] = 'bootstrap-css';
+		}
+		$tag = ( trim( $inner ) === wp_strip_all_tags( trim( $inner ) ) || self::is_simple_inline_html( trim( $inner ) ) ) ? 'p' : 'div';
+		return '<' . $tag . ' class="lead"' . $style . '>' . trim( $inner ) . '</' . $tag . '>';
+	}
+
+	private static function button( $attrs, $standalone ) {
+		$a = shortcode_atts( array( 'size' => '', 'type' => 'default', 'value' => 'button', 'href' => '#', 'target' => '' ), $attrs );
+		$target = strtolower( trim( $a['target'] ) );
+		$target_attr = '';
+		if ( in_array( $target, array( '_blank', '_self', '_parent', '_top' ), true ) ) {
+			$target_attr = ' target="' . self::attr( $target ) . '"' . ( '_blank' === $target ? ' rel="noopener noreferrer"' : '' );
+		}
+		if ( self::blocks() && $standalone ) {
+			$link = '<a class="wp-block-button__link wp-element-button" href="' . esc_url( $a['href'] ) . '"' . $target_attr . '>' . esc_html( $a['value'] ) . '</a>';
+			$inner = self::wrap_block( 'button', array(), '<div class="wp-block-button">' . $link . '</div>' );
+			return self::wrap_block( 'buttons', array(), '<div class="wp-block-buttons">' . $inner . '</div>' );
+		}
+		// Inline (or html mode): identical to what the shortcode rendered.
+		$size_class = ( $a['size'] && $a['size'] !== $a['type'] ) ? ' btn-' . self::attr( $a['size'] ) : '';
+		if ( self::inline_style() ) {
+			self::$deps[] = 'bootstrap-css';
+			self::$notes[] = 'Inline buttons keep their Bootstrap "btn" classes: a button in the middle of a sentence has no block equivalent.';
+		} else {
+			self::$deps[] = 'bootstrap-css';
+		}
+		return '<a class="btn btn-' . self::attr( $a['type'] ) . $size_class . '" href="' . esc_url( $a['href'] ) . '"' . $target_attr . '>' . esc_html( $a['value'] ) . '</a>';
+	}
+
+	private static function label( $attrs, $content ) {
+		$type   = isset( $attrs['type'] ) ? sanitize_html_class( $attrs['type'], 'default' ) : 'default';
+		$colors = array( 'default' => '#777', 'primary' => '#337ab7', 'success' => '#5cb85c', 'info' => '#5bc0de', 'warning' => '#f0ad4e', 'danger' => '#d9534f' );
+		$bg     = isset( $colors[ $type ] ) ? $colors[ $type ] : '#777';
+		$inner  = self::process( $content, false );
+		if ( self::inline_style() ) {
+			return '<span class="label label-' . $type . '" style="display:inline-block;padding:.2em .6em .3em;font-size:75%;font-weight:700;line-height:1;color:#fff;background-color:' . $bg . ';border-radius:.25em;white-space:nowrap;vertical-align:baseline">' . $inner . '</span>';
+		}
+		self::$deps[] = 'bootstrap-css';
+		return '<span class="label label-' . $type . '">' . $inner . '</span>';
+	}
+
+	private static function icon( $attrs ) {
+		$name    = isset( $attrs['name'] ) ? trim( $attrs['name'] ) : 'default';
+		$classes = preg_split( '/\s+/', $name );
+		$glyph   = null;
+		foreach ( $classes as $class ) {
+			if ( preg_match( '/^glyphicon-([a-z0-9-]+)$/', $class, $mm ) ) {
+				$glyph = $mm[1];
+			}
+		}
+		$fallback = '<i class="' . self::attr( $name ) . '" aria-hidden="true"></i>';
+		if ( ! self::inline_style() || ! $glyph ) {
+			self::$deps[] = 'glyphicons';
+			return $fallback;
+		}
+		$path = BS_Glyphs::path( $glyph );
+		if ( ! $path ) {
+			self::$deps[] = 'glyphicons';
+			self::$notes[] = sprintf( 'Icon "%s" is not in the bundled Glyphicons set; its markup was kept and still needs the font.', $glyph );
+			return $fallback;
+		}
+		$extra = array_values( array_diff( $classes, array( 'glyphicon', 'glyphicon-' . $glyph ) ) );
+		$class = 'bs-icon bs-icon-' . $glyph . ( $extra ? ' ' . implode( ' ', $extra ) : '' );
+		return '<svg class="' . self::attr( $class ) . '" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ' . (int) $path['adv'] . ' 1200" width="1em" height="1em" aria-hidden="true" focusable="false" style="display:inline-block;vertical-align:-.15em;fill:currentColor"><path transform="translate(0,960) scale(1,-1)" d="' . self::attr( $path['d'] ) . '"/></svg>';
+	}
+
+	private static function tooltip( $attrs, $content ) {
+		$text = trim( $content );
+		self::$notes[] = 'Tooltips become native browser tooltips (title attribute): no placement or trigger control, and no tooltip on touch devices. The text is shown inline as before.';
+		$style = self::inline_style() ? ' style="text-decoration:underline dotted;cursor:help"' : '';
+		return '<span class="bs-tooltip" title="' . self::attr( $text ) . '"' . $style . '>' . esc_html( $text ) . '</span>';
+	}
+
+	private static function collapse( $attrs, $content ) {
+		$group = isset( $attrs['id'] ) ? sanitize_html_class( $attrs['id'] ) : '';
+		// Children need the group name; pass it through a static so citem() sees it.
+		$inner = self::process_with_group( $content, $group );
+		if ( self::blocks() ) {
+			return trim( $inner );
+		}
+		return '<div class="bs-collapse"' . ( $group ? ' id="' . self::attr( $group ) . '"' : '' ) . '>' . $inner . '</div>';
+	}
+
+	private static $group_stack = array();
+
+	private static function process_with_group( $content, $group ) {
+		self::$group_stack[] = $group;
+		$out = self::process( $content, false );
+		array_pop( self::$group_stack );
+		return $out;
+	}
+
+	private static function citem( $attrs, $content, $unused ) {
+		$group = self::$group_stack ? end( self::$group_stack ) : ( isset( $attrs['parent'] ) ? sanitize_html_class( $attrs['parent'] ) : '' );
+		$id    = isset( $attrs['id'] ) ? sanitize_html_class( $attrs['id'] ) : '';
+		$title = isset( $attrs['title'] ) ? $attrs['title'] : 'Collapse title';
+		$open  = isset( $attrs['open'] ) && 'true' === $attrs['open'];
+		return self::details( $title, $content, $open, $id, $group );
+	}
+
+	private static function details( $title, $content, $open, $id, $group ) {
+		$title_html = esc_html( wp_strip_all_tags( $title ) );
+		if ( self::blocks() ) {
+			$block_attrs = array();
+			if ( $open ) {
+				$block_attrs['showContent'] = true;
+			}
+			if ( $group ) {
+				$block_attrs['name'] = $group;
+			}
+			$html = '<details class="wp-block-details"' . ( $group ? ' name="' . self::attr( $group ) . '"' : '' ) . ( $id ? ' id="' . self::attr( $id ) . '"' : '' ) . ( $open ? ' open' : '' ) . '><summary>' . $title_html . '</summary>' . self::inner_blocks( self::process( $content, false ) ) . '</details>';
+			return self::wrap_block( 'details', $block_attrs, $html );
+		}
+		return '<details' . ( $group ? ' name="' . self::attr( $group ) . '"' : '' ) . ( $id ? ' id="' . self::attr( $id ) . '"' : '' ) . ( $open ? ' open' : '' ) . '><summary>' . $title_html . '</summary>' . self::inner_html( $content ) . '</details>';
+	}
+
+	/**
+	 * Tabs: collect the tab strip (titles by href) first, then render each pane
+	 * as a collapsible section titled by its tab. A disclosed semantic change.
+	 */
+	private static function tabs( $content ) {
+		self::$notes[] = 'Tabs become collapsible sections (one <details> per tab, in order). Dropdown tabs are flattened as "Dropdown: Tab". On WordPress 7.1+ you can convert them to the Tabs block in the editor afterwards.';
+		$titles = array();
+		if ( preg_match_all( '/' . get_shortcode_regex( array( 'bs_thead' ) ) . '/', $content, $heads, PREG_SET_ORDER ) ) {
+			foreach ( $heads as $head ) {
+				self::collect_tab_titles( isset( $head[5] ) ? $head[5] : '', '', $titles );
+			}
+		}
+		$previous         = self::$tab_titles;
+		self::$tab_titles = $titles;
+		self::$section_counter = 0;
+		// Strip the head: its tabs are now titles. Convert the panes.
+		$panes = preg_replace( '/' . get_shortcode_regex( array( 'bs_thead' ) ) . '/', '', $content );
+		$panes = self::process( $panes, false );
+		self::$tab_titles = $previous;
+		if ( self::blocks() ) {
+			return trim( $panes );
+		}
+		return '<div class="bs-tabs">' . trim( $panes ) . '</div>';
+	}
+
+	private static function collect_tab_titles( $head, $prefix, &$titles ) {
+		if ( ! preg_match_all( '/' . get_shortcode_regex( array( 'bs_tab', 'bs_dropdown' ) ) . '/', $head, $items, PREG_SET_ORDER ) ) {
+			return;
+		}
+		foreach ( $items as $item ) {
+			$attrs = shortcode_parse_atts( $item[3] );
+			$attrs = is_array( $attrs ) ? $attrs : array();
+			if ( 'bs_dropdown' === $item[2] ) {
+				$title = isset( $attrs['title'] ) ? $attrs['title'] : '';
+				self::collect_tab_titles( isset( $item[5] ) ? $item[5] : '', $title ? $title . ': ' : '', $titles );
+				continue;
+			}
+			$href = isset( $attrs['href'] ) ? ltrim( trim( $attrs['href'] ), '#' ) : '';
+			if ( '' !== $href && ! isset( $titles[ $href ] ) ) {
+				$titles[ $href ] = $prefix . ( isset( $attrs['title'] ) ? $attrs['title'] : $href );
+			}
+		}
+	}
+
+	private static function tcontent( $attrs, $content ) {
+		$id   = isset( $attrs['id'] ) ? sanitize_html_class( $attrs['id'] ) : '';
+		$open = isset( $attrs['class'] ) && 'active' === trim( $attrs['class'] );
+		self::$section_counter++;
+		$title = ( $id && isset( self::$tab_titles[ $id ] ) ) ? self::$tab_titles[ $id ] : sprintf( 'Section %d', self::$section_counter );
+		return self::details( $title, $content, $open, $id, '' );
+	}
+}
+
+/**
+ * Glyphicons Halflings paths, read from the SVG font this plugin already ships
+ * (the same glyphs the CSS maps to .glyphicon-* classes), so migrated icons
+ * need no font or CSS at all.
+ */
+class BS_Glyphs {
+
+	private static $map;
+
+	public static function path( $name ) {
+		self::load();
+		return isset( self::$map[ $name ] ) ? self::$map[ $name ] : null;
+	}
+
+	public static function names() {
+		self::load();
+		return array_keys( self::$map );
+	}
+
+	private static function load() {
+		if ( null !== self::$map ) {
+			return;
+		}
+		self::$map = array();
+		$dir  = dirname( BS_SHORTCODES_FILE );
+		$css  = @file_get_contents( $dir . '/css/bootstrap.css' );
+		$font = @file_get_contents( $dir . '/fonts/glyphicons-halflings-regular.svg' );
+		if ( ! $css || ! $font ) {
+			return;
+		}
+		// class -> codepoint
+		$codes = array();
+		if ( preg_match_all( '/\.glyphicon-([a-z0-9-]+):before\{content:"\\\\([0-9a-f]+)"\}/i', $css, $m, PREG_SET_ORDER ) ) {
+			foreach ( $m as $mm ) {
+				$codes[ $mm[1] ] = hexdec( $mm[2] );
+			}
+		}
+		// codepoint -> path
+		$paths = array();
+		if ( preg_match_all( '/<glyph\s+([^>]*)\/>/', $font, $g, PREG_SET_ORDER ) ) {
+			foreach ( $g as $gg ) {
+				if ( ! preg_match( '/unicode="([^"]*)"/', $gg[1], $u ) || ! preg_match( '/\sd="([^"]*)"/', $gg[1], $d ) ) {
+					continue;
+				}
+				$uni = html_entity_decode( $u[1], ENT_QUOTES | ENT_HTML5, 'UTF-8' );
+				$cp  = self::codepoint( $uni );
+				if ( null === $cp ) {
+					continue;
+				}
+				$adv = preg_match( '/horiz-adv-x="(\d+)"/', $gg[1], $a ) ? (int) $a[1] : 1200;
+				$paths[ $cp ] = array( 'd' => $d[1], 'adv' => $adv );
+			}
+		}
+		foreach ( $codes as $name => $cp ) {
+			if ( isset( $paths[ $cp ] ) ) {
+				self::$map[ $name ] = $paths[ $cp ];
+			}
+		}
+	}
+
+	private static function codepoint( $char ) {
+		if ( '' === $char ) {
+			return null;
+		}
+		$ord = function_exists( 'mb_ord' ) ? mb_ord( $char, 'UTF-8' ) : null;
+		if ( null === $ord || false === $ord ) {
+			$u = unpack( 'N', mb_convert_encoding( $char, 'UCS-4BE', 'UTF-8' ) );
+			$ord = $u ? $u[1] : null;
+		}
+		return $ord;
+	}
+}
diff --git a/js/admin-tools.js b/js/admin-tools.js
index dbf4340..d1d6efb 100644
--- a/js/admin-tools.js
+++ b/js/admin-tools.js
@@ -63,3 +63,106 @@
         run(false);
     }
 })();
+
+/* Migration: select-all boxes and batched "Migrate selected". */
+(function () {
+    if (typeof bsTools === 'undefined') {
+        return;
+    }
+    var checkAlls = document.querySelectorAll('.bs-check-all');
+    for (var i = 0; i < checkAlls.length; i++) {
+        checkAlls[i].addEventListener('change', function (e) {
+            var boxes = e.target.closest('form').querySelectorAll('input[name="post_ids[]"]');
+            for (var j = 0; j < boxes.length; j++) {
+                boxes[j].checked = e.target.checked;
+            }
+            sync();
+        });
+    }
+    var form = document.querySelector('.bs-migrate-batch');
+    var button = form ? form.querySelector('.bs-migrate-selected') : null;
+    var progress = form ? form.querySelector('.bs-migrate-progress') : null;
+
+    function selected() {
+        if (!form) {
+            return [];
+        }
+        var boxes = form.querySelectorAll('input[name="post_ids[]"]:checked');
+        var ids = [];
+        for (var i = 0; i < boxes.length; i++) {
+            ids.push(boxes[i].value);
+        }
+        return ids;
+    }
+    function sync() {
+        if (button) {
+            button.disabled = selected().length === 0;
+        }
+    }
+    if (!form) {
+        return;
+    }
+    form.addEventListener('change', sync);
+    sync();
+
+    function mark(id, text, ok) {
+        var row = form.querySelector('tr[data-post-id="' + id + '"] .bs-migrate-status');
+        if (row) {
+            var strong = document.createElement('strong');
+            strong.style.color = ok ? '#00a32a' : '#d63638';
+            strong.textContent = text;
+            row.textContent = '';
+            row.appendChild(strong);
+        }
+    }
+
+    function sendBatch(ids) {
+        var body = new FormData();
+        body.append('action', form.getAttribute('data-action'));
+        body.append('_ajax_nonce', form.getAttribute('data-nonce'));
+        body.append('mode', form.querySelector('input[name="mode"]').value);
+        body.append('style', form.querySelector('input[name="style"]').value);
+        for (var i = 0; i < ids.length; i++) {
+            body.append('post_ids[]', ids[i]);
+        }
+        return fetch(bsTools.ajaxUrl, { method: 'POST', credentials: 'same-origin', body: body })
+            .then(function (r) { return r.json(); })
+            .then(function (json) {
+                if (!json || !json.success) {
+                    throw new Error(json && json.data && json.data.message ? json.data.message : 'request failed');
+                }
+                var results = json.data.results || {};
+                Object.keys(results).forEach(function (id) {
+                    var r = results[id];
+                    mark(id, r.ok ? bsTools.i18n.migrated + ' (' + r.converted + ')' : bsTools.i18n.failed + ': ' + r.message, r.ok);
+                });
+            });
+    }
+
+    form.addEventListener('submit', function (e) {
+        e.preventDefault();
+        var ids = selected();
+        if (!ids.length || !window.confirm(bsTools.i18n.confirm)) {
+            return;
+        }
+        button.disabled = true;
+        var size = parseInt(form.getAttribute('data-batch'), 10) || 10;
+        var done = 0;
+        function next() {
+            if (!ids.length) {
+                progress.textContent = ' ' + done + ' done. Re-run the scan to refresh the report.';
+                return;
+            }
+            var chunk = ids.splice(0, size);
+            return sendBatch(chunk).then(function () {
+                done += chunk.length;
+                progress.textContent = ' ' + done + ' processed…';
+                return next();
+            });
+        }
+        next().catch(function (err) {
+            progress.textContent = ' stopped: ' + err.message;
+            button.disabled = false;
+        });
+    });
+})();
diff --git a/readme.txt b/readme.txt
index 640f0a9..7945132 100644
--- a/readme.txt
+++ b/readme.txt
@@ -70,6 +70,8 @@ Please report issues directly to our [Github repository](https://github.com/TheW
 * New Tools > Bootstrap Shortcodes page: scans the site in batches and reports which shortcodes are used where (published vs drafts, widgets, options, custom fields, term descriptions, theme files), what a text scan cannot see, and what removing the plugin would change
 * New WP-CLI command: wp bs-shortcodes scan
 * Optional, manual "share a summary with the author" export: nothing is ever sent automatically (see docs/privacy.md)
+* Migration: preview (with a diff), migrate one post or a batch, and roll back. Every component has a destination (Columns, Buttons, Details, Paragraph, Group/Custom HTML blocks, or plain HTML); originals are kept in a custom field; nothing runs automatically (see docs/migration.md)
+* "Bootstrap 3 Legacy Assets" companion plugin, built and installed from the migration page with explicit consent, for sites that must keep Bootstrap 3 after removing this plugin
 
 = 3.5.0 =
 * Add optional target attribute to the button shortcode ("_blank" also adds rel="noopener noreferrer")
@@ -146,6 +148,10 @@ Please report issues directly to our [Github repository](https://github.com/TheW
 
 No. It makes no external requests and has no tracking. The dependency report under Tools can produce a summary of shortcode usage counts that you may choose to send to the author yourself; nothing is sent by the plugin. Details: https://github.com/TheWebShop/bootstrap-shortcodes/blob/master/docs/privacy.md
 
+= How do I stop using this plugin? =
+
+Tools > Bootstrap Shortcodes: scan, preview, migrate (per post or in batches, with rollback), then decide whether anything still needs Bootstrap 3 itself. The full component-by-component guide: https://github.com/TheWebShop/bootstrap-shortcodes/blob/master/docs/migration.md
+
 = How do I find out what on my site uses these shortcodes? =
 
 Tools > Bootstrap Shortcodes scans posts, pages, custom post types, widgets, options, custom fields, term descriptions and your theme's PHP files, and lists what it found and what it could not check. On the command line: `wp bs-shortcodes scan`.
diff --git a/specs/migration.spec.js b/specs/migration.spec.js
new file mode 100644
index 0000000..e876c86
--- /dev/null
+++ b/specs/migration.spec.js
@@ -0,0 +1,222 @@
+/**
+ * The whole exit path in a browser: scan, preview, migrate one post, roll it
+ * back, migrate in a batch, install the legacy-assets companion, deactivate
+ * Bootstrap Shortcodes, and check the migrated content still renders and works
+ * on desktop and phone viewports. Finally reactivate so other specs are unaffected.
+ */
+const { test, expect } = require('@wordpress/e2e-test-utils-playwright');
+
+const CLASSIC = [
+    '[bs_row class="row"][bs_col class="col-sm-8"]Main column text[/bs_col][bs_col class="col-sm-4"]Side column text[/bs_col][/bs_row]',
+    '',
+    '[bs_button type="primary" value="Go somewhere" href="https://example.com/"]',
+    '',
+    '[bs_well size="sm"]A well of text[/bs_well]',
+    '[bs_notification type="info"]An info notice[/bs_notification]',
+    '[bs_lead]Lead text here[/bs_lead]',
+    'Inline: [bs_label type="success"]Label text[/bs_label] and [bs_icon name="glyphicon glyphicon-star"] star and [bs_tooltip]tooltip words[/bs_tooltip].',
+    '',
+    '[bs_collapse id="faq"][bs_citem id="q1" parent="faq" title="First question"]First answer[/bs_citem][bs_citem id="q2" parent="faq" title="Second question" open="true"]Second answer[/bs_citem][/bs_collapse]',
+    '',
+    '[bs_tabs][bs_thead][bs_tab class="active" href="#t1" title="Tab one"][bs_tab href="#t2" title="Tab two"][/bs_thead][bs_tcontents][bs_tcontent class="active" id="t1"]Pane one text[/bs_tcontent][bs_tcontent id="t2"]Pane two text[/bs_tcontent][/bs_tcontents][/bs_tabs]',
+].join('\n');
+
+const BLOCKS = [
+    '<!-- wp:paragraph -->',
+    '<p>Block intro</p>',
+    '<!-- /wp:paragraph -->',
+    '',
+    '<!-- wp:shortcode -->',
+    '[bs_row][bs_col class="col-sm-6"]Block left[/bs_col][bs_col class="col-sm-6"]Block right[/bs_col][/bs_row]',
+    '<!-- /wp:shortcode -->',
+].join('\n');
+
+const TOOLS = { path: 'tools.php', query: 'page=bs-shortcodes-tools' };
+
+async function scan(admin, page) {
+    await admin.visitAdminPage(TOOLS.path, TOOLS.query);
+    await page.getByRole('button', { name: /Scan this site|Scan again/ }).click();
+    await expect(page.getByRole('heading', { name: 'Migrate', exact: true })).toBeVisible({ timeout: 30000 });
+}
+
+async function expectMigratedPageWorks(page, link) {
+    await page.goto(link);
+    // Grid
+    await expect(page.locator('.row .col-sm-8')).toContainText('Main column text');
+    // Button
+    const button = page.locator('a.btn.btn-primary');
+    await expect(button).toHaveAttribute('href', 'https://example.com/');
+    await expect(button).toBeVisible();
+    // Well, alert, lead, label with self-contained styling
+    await expect(page.locator('div.well')).toHaveCSS('background-color', 'rgb(245, 245, 245)');
+    await expect(page.locator('div.alert[role="alert"]')).toContainText('An info notice');
+    await expect(page.locator('.lead')).toContainText('Lead text here');
+    await expect(page.locator('span.label-success')).toHaveCSS('background-color', 'rgb(92, 184, 92)');
+    // Icon as inline SVG, tooltip as native title
+    await expect(page.locator('svg.bs-icon-star path')).toHaveCount(1);
+    await expect(page.locator('span.bs-tooltip')).toHaveAttribute('title', 'tooltip words');
+    // Collapse: second open, first toggles by click and by keyboard
+    await expect(page.locator('details#q2')).toHaveAttribute('open', '');
+    await expect(page.locator('details#q1')).not.toHaveAttribute('open', '');
+    await page.locator('details#q1 summary').click();
+    await expect(page.locator('details#q1')).toHaveAttribute('open', '');
+    await expect(page.locator('details#q1')).toContainText('First answer');
+    // Exclusive group: opening q1 closed q2 (name attribute); keyboard toggles q1 back.
+    await expect(page.locator('details#q2')).not.toHaveAttribute('open', '');
+    await page.locator('details#q1 summary').focus();
+    await page.keyboard.press('Enter');
+    await expect(page.locator('details#q1')).not.toHaveAttribute('open', '');
+    // Tabs: sections, first open
+    await expect(page.locator('details#t1')).toHaveAttribute('open', '');
+    await expect(page.locator('details#t1 summary')).toHaveText('Tab one');
+    await page.locator('details#t2 summary').click();
+    await expect(page.locator('details#t2')).toContainText('Pane two text');
+    // No literal shortcodes anywhere
+    await expect(page.locator('body')).not.toContainText('[bs_');
+}
+
+const COMPANION = 'bootstrap-legacy-assets/bootstrap-legacy-assets';
+
+// Start and finish without the companion, whatever an earlier run left behind.
+async function removeCompanion(requestUtils) {
+    try {
+        await requestUtils.rest({ method: 'PUT', path: `/wp/v2/plugins/${COMPANION}`, data: { status: 'inactive' } });
+    } catch (e) { /* not installed */ }
+    try {
+        await requestUtils.rest({ method: 'DELETE', path: `/wp/v2/plugins/${COMPANION}` });
+    } catch (e) { /* not installed or not deletable here */ }
+}
+
+test.describe('Migration end to end', () => {
+    let classic;
+    let blocks;
+
+    test.beforeAll(async ({ requestUtils }) => {
+        await removeCompanion(requestUtils);
+        await requestUtils.deleteAllPosts();
+        classic = await requestUtils.createPost({ title: 'Classic migration', content: CLASSIC, status: 'publish' });
+        blocks = await requestUtils.createPost({ title: 'Block migration', content: BLOCKS, status: 'publish' });
+    });
+
+    test('preview, migrate, roll back, batch-migrate, hand off assets, deactivate and verify', async ({ admin, page, requestUtils }) => {
+        test.setTimeout(180000);
+
+        // Default asset settings so the pre-migration page is the normal one.
+        await admin.visitAdminPage('options-general.php', 'page=bootstrap-shortcodes/bootstrap-shortcodes.php');
+        await page.locator('input[name="bs_options[chk_default_options_css]"]').setChecked(true);
+        await page.locator('input[name="bs_options[chk_default_options_js]"]').setChecked(true);
+        await page.locator('input[name="bs_options[chk_conditional_assets]"]').setChecked(false);
+        await page.locator('input[type="submit"]').click();
+
+        await scan(admin, page);
+        const row = page.locator('table.bs-migrate-table tr', { hasText: 'Classic migration' });
+        await expect(row).toContainText('bs_row');
+
+        // Preview shows a diff, notes, and no write has happened.
+        await row.getByRole('link', { name: 'Preview' }).click();
+        await expect(page.getByRole('heading', { name: 'Preview: Classic migration' })).toBeVisible();
+        await expect(page.locator('table.diff')).toBeVisible();
+        await expect(page.locator('.bs-notes')).toContainText('Tabs become collapsible sections');
+        await expect(page.locator('.bs-notes')).toContainText('dismiss');
+        const before = await requestUtils.rest({ path: `/wp/v2/posts/${classic.id}`, params: { context: 'edit' } });
+        expect(before.content.raw).toContain('[bs_row');
+
+        // Migrate this post.
+        await page.getByRole('button', { name: 'Migrate this post' }).click();
+        await expect(page.locator('.notice.is-dismissible.notice-success')).toContainText('1 post migrated');
+        const after = await requestUtils.rest({ path: `/wp/v2/posts/${classic.id}`, params: { context: 'edit' } });
+        expect(after.content.raw).not.toContain('[bs_row');
+        expect(after.content.raw).toContain('<details');
+
+        // It renders and works with the plugin still active.
+        await expectMigratedPageWorks(page, classic.link);
+
+        // Roll back restores the exact original.
+        await admin.visitAdminPage(TOOLS.path, TOOLS.query);
+        const rollbackRow = page.locator('table.bs-rollback-table tr', { hasText: 'Classic migration' });
+        await rollbackRow.locator('input[type="checkbox"]').check();
+        page.once('dialog', (d) => d.accept());
+        await page.getByRole('button', { name: 'Roll back selected' }).click();
+        await expect(page.locator('.notice.is-dismissible.notice-success')).toContainText('1 post rolled back');
+        const restored = await requestUtils.rest({ path: `/wp/v2/posts/${classic.id}`, params: { context: 'edit' } });
+        expect(restored.content.raw).toBe(CLASSIC);
+
+        // Batch-migrate both posts through the AJAX path.
+        await scan(admin, page);
+        await page.locator('table.bs-migrate-table .bs-check-all').check();
+        page.once('dialog', (d) => d.accept());
+        await page.getByRole('button', { name: 'Migrate selected' }).click();
+        await expect(page.locator('.bs-migrate-progress')).toContainText('done', { timeout: 30000 });
+        await expect(page.locator('table.bs-migrate-table tr', { hasText: 'Classic migration' })).toContainText('migrated');
+        await expect(page.locator('table.bs-migrate-table tr', { hasText: 'Block migration' })).toContainText('migrated');
+        const migratedBlocks = await requestUtils.rest({ path: `/wp/v2/posts/${blocks.id}`, params: { context: 'edit' } });
+        expect(migratedBlocks.content.raw).toContain('<!-- wp:columns');
+        expect(migratedBlocks.content.raw).not.toContain('wp:shortcode');
+
+        // After a re-scan nothing is left in post content.
+        await scan(admin, page);
+        await expect(page.locator('.bs-impact')).toContainText('No post content uses the shortcodes');
+
+        // Hand off the assets: consent is required, then install + activate.
+        await page.getByRole('button', { name: 'Install and activate the companion' }).click();
+        await expect(page.locator('.notice.is-dismissible.notice-error')).toContainText('Tick the confirmation box');
+        await page.locator('input[name="bs_companion_consent"]').check();
+        await page.getByRole('button', { name: 'Install and activate the companion' }).click();
+        // Hosts where PHP cannot write the plugins directory get the manual path instead;
+        // the zip must still download. The PHPUnit suite covers the real install.
+        const notice = page.locator('.notice.is-dismissible').first();
+        await expect(notice).toBeVisible();
+        const companionInstalled = (await notice.textContent()).includes('Legacy Assets is installed and active');
+        if (!companionInstalled) {
+            await expect(notice).toContainText(/cannot write to the plugins directory|Could not create directory/);
+            const zipUrl = await page.getByRole('link', { name: 'Download the companion zip instead' }).getAttribute('href');
+            const zip = await page.request.get(zipUrl);
+            expect(zip.ok()).toBeTruthy();
+            expect(zip.headers()['content-type']).toContain('application/zip');
+            expect((await zip.body()).length).toBeGreaterThan(100000);
+        }
+
+        // Deactivate Bootstrap Shortcodes for real.
+        await admin.visitAdminPage('plugins.php');
+        const pluginRow = page.locator('tr[data-slug="bootstrap-shortcodes"]');
+        await pluginRow.locator('.deactivate a').click();
+        await expect(pluginRow).toHaveClass(/\binactive\b/);
+        if (companionInstalled) {
+            await expect(page.locator('tr[data-plugin="bootstrap-legacy-assets/bootstrap-legacy-assets.php"]')).toHaveClass(/\bactive\b/);
+        }
+
+        // Frontend without the plugin: desktop and phone.
+        await expectMigratedPageWorks(page, classic.link);
+        await expect(page.locator('link#bs_bootstrap-css')).toHaveCount(0);
+        await expect(page.locator('link#bs-legacy-bootstrap-css')).toHaveCount(companionInstalled ? 1 : 0);
+        await page.goto(blocks.link);
+        await expect(page.locator('.wp-block-columns .wp-block-column').first()).toContainText('Block left');
+
+        await page.setViewportSize({ width: 390, height: 844 });
+        await expectMigratedPageWorks(page, classic.link);
+        const mainBox = await page.locator('.row .col-sm-8').boundingBox();
+        expect(mainBox.width).toBeLessThanOrEqual(390);
+
+        // And with the companion gone too: self-contained styling needs nothing.
+        await page.setViewportSize({ width: 1280, height: 800 });
+        if (companionInstalled) {
+            await admin.visitAdminPage('plugins.php');
+            await page.locator('tr[data-plugin="bootstrap-legacy-assets/bootstrap-legacy-assets.php"] .deactivate a').click();
+        }
+        await page.goto(classic.link);
+        await expect(page.locator('link#bs-legacy-bootstrap-css')).toHaveCount(0);
+        await expect(page.locator('div.well')).toHaveCSS('background-color', 'rgb(245, 245, 245)');
+        await expect(page.locator('svg.bs-icon-star')).toBeVisible();
+        await expect(page.locator('details#q2')).toHaveAttribute('open', '');
+
+        // Leave the site as other specs expect it.
+        await admin.visitAdminPage('plugins.php');
+        await page.locator('tr[data-slug="bootstrap-shortcodes"] .activate a').click();
+        await expect(page.locator('tr[data-slug="bootstrap-shortcodes"]')).toHaveClass(/\bactive\b/);
+    });
+
+    test.afterAll(async ({ requestUtils }) => {
+        await requestUtils.deleteAllPosts();
+        await removeCompanion(requestUtils);
+    });
+});
diff --git a/tests/phpunit/AdminMigrationTest.php b/tests/phpunit/AdminMigrationTest.php
new file mode 100644
index 0000000..789e785
--- /dev/null
+++ b/tests/phpunit/AdminMigrationTest.php
@@ -0,0 +1,52 @@
+<?php
+/**
+ * Migration handlers: capability and nonce gates on the batch endpoint.
+ */
+class AdminMigrationTest extends WP_UnitTestCase {
+
+	private $admin;
+
+	public function set_up() {
+		parent::set_up();
+		$this->admin = new BS_Admin_Migration();
+		$_POST = array();
+		$_REQUEST = array();
+	}
+
+	public function tear_down() {
+		$_POST = array();
+		$_REQUEST = array();
+		parent::tear_down();
+	}
+
+	public function test_batch_refuses_editors_and_bad_nonces() {
+		$id = self::factory()->post->create( array( 'post_content' => '[bs_well]a[/bs_well]' ) );
+		wp_set_current_user( self::factory()->user->create( array( 'role' => 'editor' ) ) );
+		$_POST = array( '_ajax_nonce' => wp_create_nonce( BS_Admin_Migration::ACTION_BATCH ), 'post_ids' => array( $id ) );
+		$_REQUEST = $_POST;
+		list( $status ) = $this->admin->batch_response();
+		$this->assertSame( 403, $status );
+
+		wp_set_current_user( self::factory()->user->create( array( 'role' => 'administrator' ) ) );
+		$_POST['_ajax_nonce'] = 'bad';
+		$_REQUEST = $_POST;
+		list( $status ) = $this->admin->batch_response();
+		$this->assertSame( 403, $status );
+		$this->assertSame( '[bs_well]a[/bs_well]', get_post( $id )->post_content );
+	}
+
+	public function test_batch_converts_for_admins_and_reports_per_post() {
+		$id = self::factory()->post->create( array( 'post_content' => '[bs_well]a[/bs_well]' ) );
+		wp_set_current_user( self::factory()->user->create( array( 'role' => 'administrator' ) ) );
+		$_POST = array( '_ajax_nonce' => wp_create_nonce( BS_Admin_Migration::ACTION_BATCH ), 'post_ids' => array( $id, 424242 ), 'mode' => 'html', 'style' => 'classes' );
+		$_REQUEST = $_POST;
+
+		list( $status, $data ) = $this->admin->batch_response();
+
+		$this->assertSame( 200, $status );
+		$this->assertTrue( $data['results'][ $id ]['ok'] );
+		$this->assertFalse( $data['results'][424242]['ok'] );
+		$this->assertSame( '<div class="well">a</div>', get_post( $id )->post_content );
+		$this->assertContains( 'bootstrap-css', $data['results'][ $id ]['dependencies'] );
+	}
+}
diff --git a/tests/phpunit/CompanionTest.php b/tests/phpunit/CompanionTest.php
new file mode 100644
index 0000000..d1bf703
--- /dev/null
+++ b/tests/phpunit/CompanionTest.php
@@ -0,0 +1,97 @@
+<?php
+/**
+ * The legacy-assets companion: built from this plugin's own files, and its
+ * double-loading guards.
+ */
+class CompanionTest extends WP_UnitTestCase {
+
+	public function test_manifest_points_at_existing_files() {
+		$files = BS_Companion::manifest();
+		$this->assertArrayHasKey( 'bootstrap-legacy-assets/bootstrap-legacy-assets.php', $files );
+		$this->assertArrayHasKey( 'bootstrap-legacy-assets/css/bootstrap.css', $files );
+		$this->assertArrayHasKey( 'bootstrap-legacy-assets/js/bootstrap.js', $files );
+		$this->assertArrayHasKey( 'bootstrap-legacy-assets/js/init.js', $files );
+		$this->assertArrayHasKey( 'bootstrap-legacy-assets/fonts/glyphicons-halflings-regular.woff2', $files );
+		foreach ( $files as $src ) {
+			$this->assertFileExists( $src );
+		}
+	}
+
+	public function test_zip_builds_with_every_manifest_entry() {
+		$zip = BS_Companion::build_zip();
+		$this->assertNotWPError( $zip );
+		$this->assertFileExists( $zip );
+		$archive = new ZipArchive();
+		$this->assertTrue( $archive->open( $zip ) );
+		$names = array();
+		for ( $i = 0; $i < $archive->numFiles; $i++ ) {
+			$names[] = $archive->getNameIndex( $i );
+		}
+		$archive->close();
+		unlink( $zip );
+		foreach ( array_keys( BS_Companion::manifest() ) as $inside ) {
+			$this->assertContains( $inside, $names );
+		}
+	}
+
+	public function test_companion_skips_when_the_original_still_loads_assets() {
+		require_once dirname( dirname( __DIR__ ) ) . '/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php';
+		update_option( 'bs_options', BootstrapShortcodes::default_options() );
+		$this->assertTrue( BS_Legacy_Assets::original_plugin_loads_assets() );
+
+		$GLOBALS['wp_styles'] = new WP_Styles();
+		( new BS_Legacy_Assets() )->enqueue();
+		$this->assertNotContains( 'bs-legacy-bootstrap', $GLOBALS['wp_styles']->queue );
+
+		update_option( 'bs_options', array( 'chk_default_options_grid' => '1' ) );
+		$this->assertFalse( BS_Legacy_Assets::original_plugin_loads_assets() );
+		( new BS_Legacy_Assets() )->enqueue();
+		$this->assertContains( 'bs-legacy-bootstrap', $GLOBALS['wp_styles']->queue );
+		delete_option( 'bs_options' );
+	}
+
+	public function test_companion_detects_a_theme_bootstrap() {
+		require_once dirname( dirname( __DIR__ ) ) . '/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php';
+		$GLOBALS['wp_styles'] = new WP_Styles();
+		wp_register_style( 'my-theme-bootstrap', 'https://theme.test/assets/bootstrap.min.css?ver=3' );
+		$this->assertSame( 'my-theme-bootstrap', BS_Legacy_Assets::other_bootstrap( 'css' ) );
+		$GLOBALS['wp_scripts'] = new WP_Scripts();
+		$this->assertSame( '', BS_Legacy_Assets::other_bootstrap( 'js' ) );
+	}
+
+	public function test_install_is_refused_without_capability() {
+		wp_set_current_user( self::factory()->user->create( array( 'role' => 'editor' ) ) );
+		$r = BS_Companion::install_and_activate();
+		$this->assertWPError( $r );
+		$this->assertSame( 'bs_forbidden', $r->get_error_code() );
+	}
+
+	public function test_install_and_activate_puts_a_working_plugin_in_place() {
+		if ( ! wp_is_writable( WP_PLUGIN_DIR ) ) {
+			$this->markTestSkipped( 'plugins directory not writable in this environment' );
+		}
+		wp_set_current_user( self::factory()->user->create( array( 'role' => 'administrator' ) ) );
+		update_option( 'bs_options', array( 'chk_default_options_css' => '1' ) ); // JS off: companion must mirror it
+		$dir = WP_PLUGIN_DIR . '/' . BS_Companion::SLUG;
+		$this->assertDirectoryDoesNotExist( $dir );
+
+		try {
+			$r = BS_Companion::install_and_activate();
+
+			$this->assertTrue( $r, is_wp_error( $r ) ? $r->get_error_message() : '' );
+			$this->assertFileExists( $dir . '/bootstrap-legacy-assets.php' );
+			$this->assertFileExists( $dir . '/css/bootstrap.css' );
+			$this->assertFileExists( $dir . '/fonts/glyphicons-halflings-regular.woff2' );
+			$this->assertTrue( BS_Companion::is_active() );
+			$this->assertSame( array( 'css' => '1' ), get_option( 'bs_legacy_assets' ) );
+			$this->assertSame( file_get_contents( dirname( dirname( __DIR__ ) ) . '/css/bootstrap.css' ), file_get_contents( $dir . '/css/bootstrap.css' ) );
+		} finally {
+			deactivate_plugins( BS_Companion::FILE );
+			delete_option( 'bs_legacy_assets' );
+			delete_option( 'bs_options' );
+			global $wp_filesystem;
+			WP_Filesystem();
+			$wp_filesystem->delete( $dir, true );
+		}
+	}
+}
diff --git a/tests/phpunit/MigrationApplyTest.php b/tests/phpunit/MigrationApplyTest.php
new file mode 100644
index 0000000..a3a3313
--- /dev/null
+++ b/tests/phpunit/MigrationApplyTest.php
@@ -0,0 +1,145 @@
+<?php
+/**
+ * Writing migrations: originals are kept, stale previews are refused, rollback
+ * restores byte for byte, permissions are enforced, batches are bounded.
+ */
+class MigrationApplyTest extends WP_UnitTestCase {
+
+	private $admin;
+	private $opts = array( 'mode' => 'html', 'style' => 'inline' );
+
+	public function set_up() {
+		parent::set_up();
+		$this->admin = self::factory()->user->create( array( 'role' => 'administrator' ) );
+		wp_set_current_user( $this->admin );
+	}
+
+	public function test_apply_keeps_the_original_and_rewrites_the_post() {
+		$original = "Intro\n\n[bs_well]Hello[/bs_well]\n\nOutro";
+		$id       = self::factory()->post->create( array( 'post_content' => $original ) );
+
+		$r = BS_Migration::apply( $id, $this->opts );
+
+		$this->assertNotWPError( $r );
+		$this->assertSame( 1, $r['converted'] );
+		$post = get_post( $id );
+		$this->assertStringContainsString( '<div class="well" style="', $post->post_content );
+		$this->assertStringNotContainsString( '[bs_well]', $post->post_content );
+		$backup = get_post_meta( $id, BS_Migration::META_ORIGINAL, true );
+		$this->assertSame( $original, $backup['content'] );
+		$this->assertTrue( BS_Migration::is_migrated( $id ) );
+		$this->assertContains( $id, BS_Migration::migrated_posts() );
+		$this->assertNotEmpty( wp_get_post_revisions( $id ), 'wp_update_post should still record a revision' );
+	}
+
+	public function test_rollback_restores_the_original_exactly() {
+		$original = "<p>Keep</p>\n[bs_label type=\"info\"]x[/bs_label]\n";
+		$id       = self::factory()->post->create( array( 'post_content' => $original ) );
+		BS_Migration::apply( $id, $this->opts );
+		$this->assertNotSame( $original, get_post( $id )->post_content );
+
+		$this->assertTrue( BS_Migration::rollback( $id ) );
+
+		$this->assertSame( $original, get_post( $id )->post_content );
+		$this->assertFalse( BS_Migration::is_migrated( $id ) );
+		$this->assertEmpty( get_post_meta( $id, BS_Migration::META_RESULT, true ) );
+		$this->assertWPError( BS_Migration::rollback( $id ) );
+	}
+
+	public function test_a_second_migration_does_not_overwrite_the_first_backup() {
+		$original = '[bs_well]a[/bs_well] [bs_bogus]';
+		$id       = self::factory()->post->create( array( 'post_content' => $original ) );
+		BS_Migration::apply( $id, $this->opts );
+		wp_update_post( array( 'ID' => $id, 'post_content' => get_post( $id )->post_content . ' [bs_lead]later[/bs_lead]' ) );
+
+		BS_Migration::apply( $id, $this->opts );
+
+		$this->assertSame( $original, get_post_meta( $id, BS_Migration::META_ORIGINAL, true )['content'] );
+		$this->assertTrue( BS_Migration::rollback( $id ) );
+		$this->assertSame( $original, get_post( $id )->post_content );
+	}
+
+	public function test_stale_preview_is_refused() {
+		$id      = self::factory()->post->create( array( 'post_content' => '[bs_well]a[/bs_well]' ) );
+		$preview = BS_Migration::preview( $id, $this->opts );
+		// Someone edits the post after the preview was shown (wp_update_post always
+		// stamps "now", which within one second equals the preview, so write the
+		// edit straight to the table the way a later save would look).
+		global $wpdb;
+		$wpdb->update( $wpdb->posts, array( 'post_content' => '[bs_well]b[/bs_well]', 'post_modified_gmt' => '2030-01-01 00:00:00', 'post_modified' => '2030-01-01 00:00:00' ), array( 'ID' => $id ) );
+		clean_post_cache( $id );
+
+		$r = BS_Migration::apply( $id, $this->opts, $preview['modified_gmt'] );
+
+		$this->assertWPError( $r );
+		$this->assertSame( 'bs_stale', $r->get_error_code() );
+		$this->assertSame( '[bs_well]b[/bs_well]', get_post( $id )->post_content );
+		$this->assertFalse( BS_Migration::is_migrated( $id ) );
+	}
+
+	public function test_nothing_to_convert_writes_nothing() {
+		$id = self::factory()->post->create( array( 'post_content' => 'plain' ) );
+		$r  = BS_Migration::apply( $id, $this->opts );
+		$this->assertWPError( $r );
+		$this->assertSame( 'bs_nothing', $r->get_error_code() );
+		$this->assertFalse( BS_Migration::is_migrated( $id ) );
+
+		$id2 = self::factory()->post->create( array( 'post_content' => '[bs_well]unclosed' ) );
+		$r2  = BS_Migration::apply( $id2, $this->opts );
+		$this->assertWPError( $r2 );
+		$this->assertSame( '[bs_well]unclosed', get_post( $id2 )->post_content );
+	}
+
+	public function test_users_without_edit_rights_are_refused() {
+		$id = self::factory()->post->create( array( 'post_content' => '[bs_well]a[/bs_well]' ) );
+		wp_set_current_user( self::factory()->user->create( array( 'role' => 'subscriber' ) ) );
+
+		$this->assertSame( 'bs_forbidden', BS_Migration::preview( $id, $this->opts )->get_error_code() );
+		$this->assertSame( 'bs_forbidden', BS_Migration::apply( $id, $this->opts )->get_error_code() );
+		$this->assertSame( 'bs_forbidden', BS_Migration::rollback( $id )->get_error_code() );
+		$this->assertSame( '[bs_well]a[/bs_well]', get_post( $id )->post_content );
+	}
+
+	public function test_batch_is_bounded_reports_per_post_and_is_safe_to_retry() {
+		$ids = array();
+		for ( $i = 0; $i < 3; $i++ ) {
+			$ids[] = self::factory()->post->create( array( 'post_content' => "[bs_lead]{$i}[/bs_lead]" ) );
+		}
+		$plain = self::factory()->post->create( array( 'post_content' => 'plain' ) );
+		$ids[] = $plain;
+		$ids[] = 999999;
+
+		$out = BS_Migration::batch( $ids, $this->opts );
+
+		$this->assertCount( 5, $out );
+		$this->assertTrue( $out[ $ids[0] ]['ok'] );
+		$this->assertFalse( $out[ $plain ]['ok'] );
+		$this->assertSame( 'bs_nothing', $out[ $plain ]['code'] );
+		$this->assertSame( 'bs_not_found', $out[999999]['code'] );
+
+		// Retry: already-migrated posts have nothing left to convert and are untouched.
+		$again = BS_Migration::batch( $ids, $this->opts );
+		$this->assertSame( 'bs_nothing', $again[ $ids[0] ]['code'] );
+		$this->assertSame( "[bs_lead]0[/bs_lead]", get_post_meta( $ids[0], BS_Migration::META_ORIGINAL, true )['content'] );
+
+		$this->assertCount( BS_Migration::MAX_BATCH, BS_Migration::batch( range( 1, 100 ), $this->opts ) );
+	}
+
+	public function test_migrated_content_renders_without_the_shortcode_handlers() {
+		$id = self::factory()->post->create( array( 'post_content' => "[bs_collapse id=\"g\"][bs_citem id=\"a\" parent=\"g\" title=\"Q\"]A[/bs_citem][/bs_collapse]\n\n[bs_icon name=\"glyphicon glyphicon-ok\"] done" ) );
+		BS_Migration::apply( $id, array( 'mode' => 'blocks', 'style' => 'inline' ) );
+
+		// Simulate the plugin being gone: no bs_ shortcodes registered.
+		global $shortcode_tags;
+		$saved = $shortcode_tags;
+		foreach ( BS_Scanner::tags() as $tag ) {
+			remove_shortcode( $tag );
+		}
+		$rendered = apply_filters( 'the_content', get_post( $id )->post_content );
+		$shortcode_tags = $saved;
+
+		$this->assertMatchesRegularExpression( '#<details class="wp-block-details[^"]*" name="g" id="a"><summary>Q</summary>#', $rendered );
+		$this->assertStringContainsString( '<svg class="bs-icon bs-icon-ok"', $rendered );
+		$this->assertStringNotContainsString( '[bs_', $rendered );
+	}
+}
diff --git a/tests/phpunit/MigratorConvertTest.php b/tests/phpunit/MigratorConvertTest.php
new file mode 100644
index 0000000..b7ef55f
--- /dev/null
+++ b/tests/phpunit/MigratorConvertTest.php
@@ -0,0 +1,283 @@
+<?php
+/**
+ * The converter: shortcode text in, block markup or static HTML out, with
+ * everything it could not convert left exactly where it was and explained.
+ */
+class MigratorConvertTest extends WP_UnitTestCase {
+
+	private function blocks( $content, $style = 'inline' ) {
+		return BS_Migrator::convert( $content, array( 'mode' => 'blocks', 'style' => $style ) );
+	}
+
+	private function html( $content, $style = 'inline' ) {
+		return BS_Migrator::convert( $content, array( 'mode' => 'html', 'style' => $style ) );
+	}
+
+	/* ---- untouched things ------------------------------------------------ */
+
+	public function test_content_without_our_shortcodes_is_returned_byte_for_byte() {
+		$content = "<p>Hello</p>\n[gallery ids=\"1,2\"]\n<!-- wp:paragraph -->\n<p>Block</p>\n<!-- /wp:paragraph -->";
+		$r = $this->blocks( $content );
+		$this->assertSame( $content, $r['content'] );
+		$this->assertSame( 0, $r['converted'] );
+	}
+
+	public function test_escaped_shortcodes_and_unknown_bs_tags_are_left_alone() {
+		$content = 'Docs: [[bs_well]x[/bs_well]] and [bs_bogus a="1"] and [bs_well]real[/bs_well]';
+		$r = $this->html( $content );
+		$this->assertStringContainsString( '[[bs_well]x[/bs_well]]', $r['content'] );
+		$this->assertStringContainsString( '[bs_bogus a="1"]', $r['content'] );
+		$this->assertStringNotContainsString( '[bs_well]real', $r['content'] );
+		$this->assertSame( 1, $r['converted'] );
+	}
+
+	public function test_unbalanced_tags_are_skipped_and_explained() {
+		$content = '[bs_well]never closed [bs_button value="ok"]';
+		$r = $this->html( $content );
+		$this->assertStringStartsWith( '[bs_well]never closed', $r['content'] );
+		$this->assertStringNotContainsString( '[bs_button', $r['content'] );
+		$this->assertCount( 1, $r['skipped'] );
+		$this->assertSame( 'bs_well', $r['skipped'][0]['tag'] );
+		$this->assertSame( 'unbalanced', $r['skipped'][0]['reason'] );
+	}
+
+	public function test_unknown_attributes_are_dropped_with_a_note() {
+		$r = $this->html( '[bs_well size="sm" color="red"]x[/bs_well]' );
+		$this->assertStringNotContainsString( 'red', $r['content'] );
+		$this->assertStringContainsString( 'Attribute "color" on [bs_well]', implode( "\n", $r['notes'] ) );
+	}
+
+	public function test_editor_line_break_markers_are_removed_like_the_handlers_do() {
+		$r = $this->html( '[bs_well]<br class="nc" />Text<br class="nc"/>[/bs_well]' );
+		$this->assertStringNotContainsString( 'class="nc"', $r['content'] );
+		$this->assertStringContainsString( 'Text', $r['content'] );
+	}
+
+	/* ---- grid ------------------------------------------------------------- */
+
+	public function test_grid_becomes_columns_blocks_with_widths() {
+		$r = $this->blocks( '[bs_row][bs_col class="col-sm-8"]Main[/bs_col][bs_col class="col-sm-4"]Side[/bs_col][/bs_row]' );
+		$c = $r['content'];
+		$this->assertStringContainsString( '<!-- wp:columns -->', $c );
+		$this->assertStringContainsString( '<!-- wp:column {"width":"66.67%"} -->', $c );
+		$this->assertStringContainsString( '<div class="wp-block-column" style="flex-basis:66.67%">', $c );
+		$this->assertStringContainsString( '<!-- wp:column {"width":"33.33%"} -->', $c );
+		$this->assertStringContainsString( '<!-- wp:paragraph -->' . "\n" . '<p>Main</p>' . "\n" . '<!-- /wp:paragraph -->', $c );
+		$this->assertSame( 3, $r['converted'] );
+		$blocks = parse_blocks( $c );
+		$this->assertSame( 'core/columns', $blocks[0]['blockName'] );
+		$this->assertCount( 2, $blocks[0]['innerBlocks'] );
+		$this->assertSame( 'core/paragraph', $blocks[0]['innerBlocks'][0]['innerBlocks'][0]['blockName'] );
+	}
+
+	public function test_grid_custom_classes_and_offsets_are_kept_or_noted() {
+		$r = $this->blocks( '[bs_row class="row fancy"][bs_col class="col-md-6 col-md-offset-3 hero"]x[/bs_col][/bs_row]' );
+		$this->assertStringContainsString( '<!-- wp:columns {"className":"fancy"} -->', $r['content'] );
+		$this->assertStringContainsString( '<div class="wp-block-columns fancy">', $r['content'] );
+		$this->assertStringContainsString( '{"width":"50%","className":"hero"}', $r['content'] );
+		$this->assertStringContainsString( 'offset', wp_json_encode( $r['notes'] ) );
+	}
+
+	public function test_grid_in_html_mode_keeps_bootstrap_markup() {
+		$r = $this->html( '[bs_row][bs_col class="col-sm-6"]A[/bs_col][/bs_row]' );
+		$this->assertSame( '<div class="row"><div class="col-sm-6">A</div></div>', $r['content'] );
+		$this->assertContains( 'bootstrap-css', $r['dependencies'] );
+	}
+
+	/* ---- buttons ---------------------------------------------------------- */
+
+	public function test_standalone_button_becomes_a_buttons_block() {
+		$r = $this->blocks( "Before\n\n[bs_button type=\"primary\" value=\"Go\" href=\"https://x.test/\" target=\"_blank\"]\n\nAfter" );
+		$c = $r['content'];
+		$this->assertStringContainsString( '<!-- wp:buttons -->', $c );
+		$this->assertStringContainsString( '<a class="wp-block-button__link wp-element-button" href="https://x.test/" target="_blank" rel="noopener noreferrer">Go</a>', $c );
+		$blocks = array_values( array_filter( parse_blocks( $c ), function ( $b ) { return null !== $b['blockName']; } ) );
+		$this->assertSame( array( 'core/paragraph', 'core/buttons', 'core/paragraph' ), wp_list_pluck( $blocks, 'blockName' ) );
+	}
+
+	public function test_inline_button_stays_inline_html() {
+		$r = $this->blocks( 'Click [bs_button value="here" href="/x"] to continue.' );
+		$this->assertStringContainsString( '<p>Click <a class="btn btn-default" href="/x">here</a> to continue.</p>', $r['content'] );
+		$this->assertStringNotContainsString( 'wp:buttons', $r['content'] );
+	}
+
+	public function test_button_html_mode_is_identical_to_the_shortcode_output() {
+		$shortcode = '[bs_button size="lg" type="primary" value="Click Me" href="https://example.com" target="_blank"]';
+		$this->assertSame( do_shortcode( $shortcode ), $this->html( $shortcode )['content'] );
+	}
+
+	/* ---- wells, alerts, lead ---------------------------------------------- */
+
+	public function test_well_inline_style_is_self_contained() {
+		$r = $this->html( '[bs_well size="lg"]Text[/bs_well]' );
+		$this->assertStringContainsString( '<div class="well well-lg" style="', $r['content'] );
+		$this->assertStringContainsString( 'background-color:#f5f5f5', $r['content'] );
+		$this->assertStringContainsString( 'padding:24px', $r['content'] );
+		$this->assertNotContains( 'bootstrap-css', $r['dependencies'] );
+	}
+
+	public function test_well_classes_style_needs_bootstrap_css() {
+		$r = $this->html( '[bs_well]Text[/bs_well]', 'classes' );
+		$this->assertSame( '<div class="well">Text</div>', $r['content'] );
+		$this->assertContains( 'bootstrap-css', $r['dependencies'] );
+	}
+
+	public function test_well_in_blocks_mode_becomes_a_group_block_with_inner_paragraph() {
+		$r = $this->blocks( '[bs_well]One<br class="nc"/>[/bs_well]', 'classes' );
+		$this->assertStringContainsString( '<!-- wp:group {"className":"well"} -->', $r['content'] );
+		$this->assertStringContainsString( '<div class="wp-block-group well"><!-- wp:paragraph -->', $r['content'] );
+		$html = $this->blocks( '[bs_well]One[/bs_well]', 'inline' );
+		$this->assertStringContainsString( '<!-- wp:html -->', $html['content'] );
+		$this->assertStringContainsString( '<div class="well" style="', $html['content'] );
+	}
+
+	public function test_alert_loses_its_dismiss_button_and_says_so() {
+		$r = $this->html( '[bs_notification type="warning"]Careful[/bs_notification]' );
+		$this->assertStringContainsString( '<div class="alert alert-warning" role="alert" style="', $r['content'] );
+		$this->assertStringContainsString( '#fcf8e3', $r['content'] );
+		$this->assertStringNotContainsString( 'data-dismiss', $r['content'] );
+		$this->assertStringContainsString( 'dismiss', wp_json_encode( $r['notes'] ) );
+	}
+
+	public function test_lead_becomes_a_large_paragraph() {
+		$r = $this->blocks( '[bs_lead]Intro[/bs_lead]' );
+		$this->assertStringContainsString( '<!-- wp:paragraph {"className":"lead","fontSize":"large"} -->' . "\n" . '<p class="lead has-large-font-size">Intro</p>', $r['content'] );
+		$h = $this->html( '[bs_lead]Intro[/bs_lead]' );
+		$this->assertStringContainsString( '<p class="lead" style="font-size:1.3em;font-weight:300">Intro</p>', $h['content'] );
+	}
+
+	/* ---- inline components ------------------------------------------------ */
+
+	public function test_label_stays_inline_with_fallback_styling() {
+		$r = $this->html( 'Status: [bs_label type="success"]New[/bs_label]!' );
+		$this->assertStringContainsString( 'Status: <span class="label label-success" style="', $r['content'] );
+		$this->assertStringContainsString( 'background-color:#5cb85c', $r['content'] );
+		$this->assertStringEndsWith( '>New</span>!', $r['content'] );
+	}
+
+	public function test_icon_becomes_inline_svg_from_the_bundled_font() {
+		$r = $this->html( 'A [bs_icon name="glyphicon glyphicon-star"] star' );
+		$this->assertMatchesRegularExpression( '#A <svg class="bs-icon bs-icon-star" [^>]*aria-hidden="true"[^>]*><path [^>]*d="M[^"]+"/></svg> star#', $r['content'] );
+		$this->assertStringContainsString( 'viewBox="0 0 1200 1200"', $r['content'] );
+		$this->assertNotContains( 'glyphicons', $r['dependencies'] );
+	}
+
+	public function test_icon_without_a_known_glyph_keeps_the_markup_and_flags_the_font() {
+		$r = $this->html( '[bs_icon name="glyphicon glyphicon-not-a-glyph"]' );
+		$this->assertSame( '<i class="glyphicon glyphicon-not-a-glyph" aria-hidden="true"></i>', $r['content'] );
+		$this->assertContains( 'glyphicons', $r['dependencies'] );
+		$classes = $this->html( '[bs_icon name="glyphicon glyphicon-star"]', 'classes' );
+		$this->assertSame( '<i class="glyphicon glyphicon-star" aria-hidden="true"></i>', $classes['content'] );
+		$this->assertContains( 'glyphicons', $classes['dependencies'] );
+	}
+
+	public function test_tooltip_becomes_a_native_title() {
+		$r = $this->html( 'See [bs_tooltip placement="left"]the details[/bs_tooltip].' );
+		$this->assertStringContainsString( 'See <span class="bs-tooltip" title="the details" style="', $r['content'] );
+		$this->assertStringContainsString( '>the details</span>.', $r['content'] );
+		$this->assertStringContainsString( 'placement', wp_json_encode( $r['notes'] ) );
+	}
+
+	/* ---- collapse and tabs ------------------------------------------------- */
+
+	public function test_collapse_becomes_details_blocks_sharing_a_name() {
+		$r = $this->blocks( '[bs_collapse id="faq"][bs_citem id="q1" parent="faq" title="First?"]A1[/bs_citem][bs_citem id="q2" parent="faq" title="Second?" open="true"]A2[/bs_citem][/bs_collapse]' );
+		$c = $r['content'];
+		$this->assertStringContainsString( '<!-- wp:details {"name":"faq"} -->' . "\n" . '<details class="wp-block-details" name="faq" id="q1"><summary>First?</summary>', $c );
+		$this->assertStringContainsString( '<!-- wp:details {"showContent":true,"name":"faq"} -->' . "\n" . '<details class="wp-block-details" name="faq" id="q2" open><summary>Second?</summary>', $c );
+		$this->assertStringContainsString( '<p>A2</p>', $c );
+		$blocks = array_values( array_filter( parse_blocks( $c ), function ( $b ) { return null !== $b['blockName']; } ) );
+		$this->assertSame( array( 'core/details', 'core/details' ), wp_list_pluck( $blocks, 'blockName' ) );
+	}
+
+	public function test_collapse_html_mode_is_native_details() {
+		$r = $this->html( '[bs_collapse id="g"][bs_citem id="a" parent="g" title="T &amp; A"]Body[/bs_citem][/bs_collapse]' );
+		$this->assertSame( '<div class="bs-collapse" id="g"><details name="g" id="a"><summary>T &amp; A</summary>Body</details></div>', $r['content'] );
+	}
+
+	public function test_tabs_become_details_sections_with_titles_matched_by_href() {
+		$sc = '[bs_tabs][bs_thead][bs_tab class="active" href="#one" title="One"][bs_dropdown title="More"][bs_tab href="#two" title="Two"][/bs_dropdown][/bs_thead]'
+			. '[bs_tcontents][bs_tcontent class="active" id="one"]First pane[/bs_tcontent][bs_tcontent id="two"]Second pane[/bs_tcontent][/bs_tcontents][/bs_tabs]';
+		$r = $this->html( $sc );
+		$this->assertSame( '<div class="bs-tabs"><details id="one" open><summary>One</summary>First pane</details><details id="two"><summary>More: Two</summary>Second pane</details></div>', $r['content'] );
+		$this->assertStringContainsString( 'tabs', wp_json_encode( $r['notes'] ) );
+
+		$b = $this->blocks( $sc );
+		$this->assertStringContainsString( '<!-- wp:details {"showContent":true} -->' . "\n" . '<details class="wp-block-details" id="one" open><summary>One</summary>', $b['content'] );
+	}
+
+	public function test_tab_pane_without_a_matching_tab_gets_a_generic_title() {
+		$r = $this->html( '[bs_tabs][bs_thead][bs_tab href="#a" title="A"][/bs_thead][bs_tcontents][bs_tcontent id="a"]x[/bs_tcontent][bs_tcontent id="orphan"]y[/bs_tcontent][/bs_tcontents][/bs_tabs]' );
+		$this->assertStringContainsString( '<details id="orphan"><summary>Section 2</summary>y</details>', $r['content'] );
+	}
+
+	/* ---- mixed content and safety ------------------------------------------ */
+
+	public function test_mixed_html_inside_a_container_becomes_a_classic_block() {
+		$r = $this->blocks( '[bs_well]<h3>Title</h3><ul><li>a</li></ul>[/bs_well]', 'classes' );
+		$this->assertStringContainsString( '<!-- wp:freeform -->' . "\n" . '<h3>Title</h3><ul><li>a</li></ul>' . "\n" . '<!-- /wp:freeform -->', $r['content'] );
+	}
+
+	public function test_third_party_shortcodes_inside_containers_survive() {
+		$r = $this->html( '[bs_col class="col-sm-6"][contact-form-7 id="3"][/bs_col]' );
+		$this->assertSame( '<div class="col-sm-6">[contact-form-7 id="3"]</div>', $r['content'] );
+	}
+
+	public function test_attribute_values_are_escaped_in_output() {
+		$r = $this->html( '[bs_citem id=\'x" onmouseover="alert(1)\' title=\'<img src=x onerror=alert(1)>\']b[/bs_citem]' );
+		$this->assertStringNotContainsString( 'onmouseover="alert', $r['content'] );
+		$this->assertStringNotContainsString( '<img', $r['content'] );
+	}
+
+	public function test_auto_mode_picks_blocks_only_for_block_content() {
+		$classic = BS_Migrator::convert( '[bs_lead]x[/bs_lead]', array( 'mode' => 'auto' ) );
+		$this->assertStringStartsWith( '<p class="lead"', $classic['content'] );
+		$block = BS_Migrator::convert( "<!-- wp:paragraph -->\n<p>p</p>\n<!-- /wp:paragraph -->\n[bs_lead]x[/bs_lead]", array( 'mode' => 'auto' ) );
+		$this->assertStringContainsString( '<!-- wp:paragraph {"className":"lead"', $block['content'] );
+	}
+
+	public function test_block_mode_output_is_what_the_editor_would_save() {
+		$content = '[bs_row][bs_col class="col-sm-6"][bs_well]Nested [bs_label]tag[/bs_label][/bs_well][/bs_col][/bs_row]';
+		$r = $this->blocks( $content, 'classes' );
+		// Round trip through core's parser/serializer must be lossless, or the editor would flag the blocks.
+		$this->assertSame( $r['content'], serialize_blocks( parse_blocks( $r['content'] ) ) );
+	}
+
+	/* ---- block documents ---------------------------------------------------- */
+
+	public function test_shortcode_block_is_replaced_by_the_converted_blocks() {
+		$doc = "<!-- wp:paragraph -->\n<p>Intro</p>\n<!-- /wp:paragraph -->\n\n<!-- wp:shortcode -->\n[bs_row][bs_col class=\"col-sm-6\"]A[/bs_col][bs_col class=\"col-sm-6\"]B[/bs_col][/bs_row]\n<!-- /wp:shortcode -->";
+		$r   = BS_Migrator::convert( $doc, array( 'mode' => 'auto' ) );
+		$this->assertSame( 'blocks', $r['mode'] );
+		$this->assertStringNotContainsString( 'wp:shortcode', $r['content'] );
+		$names = wp_list_pluck( array_filter( parse_blocks( $r['content'] ), function ( $b ) { return null !== $b['blockName']; } ), 'blockName' );
+		$this->assertSame( array( 'core/paragraph', 'core/columns' ), array_values( $names ) );
+		$this->assertSame( $r['content'], serialize_blocks( parse_blocks( $r['content'] ) ) );
+	}
+
+	public function test_paragraph_holding_only_a_shortcode_becomes_that_block() {
+		$doc = "<!-- wp:paragraph -->\n<p>[bs_button value=\"Go\" href=\"/go\"]</p>\n<!-- /wp:paragraph -->";
+		$r   = BS_Migrator::convert( $doc, array( 'mode' => 'auto' ) );
+		$this->assertStringContainsString( '<!-- wp:buttons -->', $r['content'] );
+		$this->assertStringNotContainsString( '<p>', $r['content'] );
+	}
+
+	public function test_inline_shortcodes_inside_paragraph_and_classic_blocks_stay_in_place() {
+		$doc = "<!-- wp:paragraph -->\n<p>New: [bs_label type=\"info\"]beta[/bs_label] today</p>\n<!-- /wp:paragraph -->\n\n<!-- wp:freeform -->\n<h3>Old</h3>\n[bs_well]Classic well[/bs_well]\n<!-- /wp:freeform -->";
+		$r   = BS_Migrator::convert( $doc, array( 'mode' => 'auto' ) );
+		$blocks = array_values( array_filter( parse_blocks( $r['content'] ), function ( $b ) { return null !== $b['blockName']; } ) );
+		$this->assertSame( array( 'core/paragraph', 'core/freeform' ), wp_list_pluck( $blocks, 'blockName' ) );
+		$this->assertStringContainsString( '<p>New: <span class="label label-info" style="', $blocks[0]['innerHTML'] );
+		$this->assertStringContainsString( '<div class="well" style="', $blocks[1]['innerHTML'] );
+		$this->assertStringNotContainsString( '[bs_', $r['content'] );
+		$this->assertSame( 2, $r['converted'] );
+	}
+
+	public function test_shortcodes_inside_nested_blocks_are_reached() {
+		$doc = "<!-- wp:columns -->\n<div class=\"wp-block-columns\"><!-- wp:column -->\n<div class=\"wp-block-column\"><!-- wp:shortcode -->\n[bs_lead]Deep[/bs_lead]\n<!-- /wp:shortcode --></div>\n<!-- /wp:column --></div>\n<!-- /wp:columns -->";
+		$r   = BS_Migrator::convert( $doc, array( 'mode' => 'auto' ) );
+		$this->assertStringContainsString( '<p class="lead has-large-font-size">Deep</p>', $r['content'] );
+		$this->assertStringNotContainsString( 'wp:shortcode', $r['content'] );
+		$this->assertSame( 'core/paragraph', parse_blocks( $r['content'] )[0]['innerBlocks'][0]['innerBlocks'][0]['blockName'] );
+	}
+}

From da7f233d9d70c8c315a893d4b115b506909af911 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 12:48:12 -0700
Subject: [PATCH 02/10] docs(receiver): record the maintainer's approval, cost
 ceiling and abuse-control requirements

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/reporting-receiver.md | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/docs/reporting-receiver.md b/docs/reporting-receiver.md
index 6b1ac19..65bb14f 100644
--- a/docs/reporting-receiver.md
+++ b/docs/reporting-receiver.md
@@ -1,9 +1,21 @@
 # Follow-up: a receiver for shared usage summaries
 
-Status: **decision recorded 2026-10-31, not built, not deployed.** Today the only
-channel is the manual export on the Tools page (`docs/privacy.md`). This note is
-the smallest design that would let a user send that same payload with one click,
-so the deployment decision can be made in one sitting when it is wanted.
+Status: **approved to build 2026-10-31 as a trial; not built, not deployed.** Today
+the only channel is the manual export on the Tools page (`docs/privacy.md`). This
+note is the design for a one-click send to a Cloudflare Worker, written so the next
+session can build it without re-deriving the constraints.
+
+## Constraints from the maintainer (2026-10-31)
+
+- Hosting the tool for the community is welcome, and paying for it is fine, but it
+  must not be able to run up a bill: abuse by one party must cost nothing beyond a
+  fixed, known amount. Prefer the **Workers Free plan**, where exceeding a limit
+  fails requests instead of billing, over Workers Paid with usage billing.
+- Heavy control and monitoring: a kill switch, per-IP and global rate limits,
+  payload size and schema caps, and a view of volume per day that the maintainer
+  checks, with alerts where Cloudflare offers them for free.
+- This is a learning trial for future (possibly commercial) plugin services, so
+  keep it small, readable and fully documented rather than clever.
 
 ## What it must not change
 
@@ -45,6 +57,24 @@ Cloudflare's own request logs exist and are retained per their policy.
 - **Re-identification:** unchanged from `docs/privacy.md`: not from the data,
   possibly from unusual counts to someone who already knows the site.
 
+## Abuse and cost controls (required before deploy)
+
+| Control | Mechanism | Free-plan ceiling it relies on |
+| --- | --- | --- |
+| Global daily cap | Workers Free: 100,000 requests/day, then requests error; KV Free: 1,000 writes/day, then writes fail | the cap is the bill: there is none |
+| Per-IP rate limit | Workers Rate Limiting binding (e.g. 5 requests / 10 min per IP) and one WAF rate-limiting rule (free plan allows one) | no cost |
+| Kill switch | KV key `paused`; checked first; set from the dashboard or `wrangler kv` | one KV read per request (100,000/day free) |
+| Payload cap | reject bodies > 8 KB, non-JSON, `schema !== 1`, unknown keys, non-integer counts, counts > 10^7 | Worker CPU only |
+| Method/path allowlist | only `POST /v1/summary`; everything else 404 with no body | – |
+| No egress | the Worker calls nothing (no email, no third parties) | – |
+| Storage growth | one KV value per record, TTL 24 months, key = random id; a daily cron summarises counts into one `stats:YYYY-MM-DD` key | KV Free 1 GB |
+| Monitoring | `GET /v1/stats` behind a bearer secret (wrangler secret) returning per-day counts; Cloudflare dashboard Workers metrics; `wrangler tail` for live logs; Cloudflare Notifications for Worker error rate | no cost |
+| Upgrade path | if the trial outgrows Free, move to Workers Paid only after adding a hard spend ceiling in the dashboard and re-reviewing this table | – |
+
+Explicitly rejected: Turnstile/CAPTCHA (the client is a server, not a browser), API
+keys shipped in the plugin (public by definition), and storing IPs for abuse
+analysis (the rate limiter needs them only in memory).
+
 ## Plugin-side change when the receiver exists
 
 - A "Send this summary now" button on the same consent screen, next to

From 9e120109f7ccf0805e287bdd19922baaf87e9fac Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 15:39:50 -0700
Subject: [PATCH 03/10] fix(review): address CodeRabbit findings on the
 migration PR

- Slash content before add_post_meta() and wp_update_post(): both
  unslash their input, so backslashes (Windows paths, regexes, block
  attribute escapes such as \u002d\u002d) were lost on migration and the
  stored original could not be restored byte for byte. Test added.
- After writing, compare the saved content with the preview; if WordPress
  filtered it (no unfiltered_html: inline SVG icons, details name=...),
  restore the original, drop the backup and return bs_filtered instead of
  leaving a silently different post. Test added (author role).
- Companion install always enables the tooltip initialiser: the original
  loads init.js regardless of the JS setting since phase 1.
- Playwright: open both migrated posts in the block editor (forcing it past
  the Classic Editor plugin's per-post default) and assert no block shows
  the invalid-content warning; docs/migration.md now describes exactly
  that instead of over-claiming from the PHP round-trip test.
- docs/reporting-receiver.md: account-shared Workers Free quotas, a
  supported 60 s rate-limit period with approximate per-location counters,
  the authenticated stats route in the allowlist, a 2 KB body cap, a
  300 records/day ingestion cap and 12-month TTL so storage stays under
  the 1 GB KV Free limit.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/migration.md                    |  9 +++++---
 docs/reporting-receiver.md           | 15 +++++++------
 inc/class-bs-companion.php           |  2 +-
 inc/class-bs-migration.php           | 27 +++++++++++++++++++----
 specs/migration.spec.js              | 27 +++++++++++++++++++++++
 tests/phpunit/CompanionTest.php      |  2 +-
 tests/phpunit/MigrationApplyTest.php | 33 ++++++++++++++++++++++++++++
 7 files changed, 99 insertions(+), 16 deletions(-)

diff --git a/docs/migration.md b/docs/migration.md
index 749d8ce..3feda1f 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -38,9 +38,12 @@ Then deactivate the plugin, check the pages the report listed, and delete it.
 | Output | auto / blocks / HTML | `blocks` writes core block markup (Columns, Buttons, Details, Paragraph, Group, Custom HTML, Classic). `HTML` writes plain markup with no block comments, for classic-editor sites. `auto` picks blocks for posts that already contain blocks, otherwise HTML. |
 | Styling | self-contained / Bootstrap classes | `self-contained` adds inline styles (wells, alerts, labels, lead, tooltips) and inline SVG icons so nothing needs Bootstrap CSS. `Bootstrap classes` keeps only the original class names, for sites that keep Bootstrap 3 via the theme or the companion. |
 
-Block output is checked to round-trip through core's block parser/serializer
-losslessly (`MigratorConvertTest::test_block_mode_output_is_what_the_editor_would_save`),
-so the editor opens migrated posts without "invalid block" prompts.
+Block output is checked two ways: it round-trips through core's PHP block
+parser/serializer losslessly (`MigratorConvertTest::test_block_mode_output_is_what_the_editor_would_save`,
+which proves the delimiters and attributes are well formed), and the Playwright
+run opens migrated posts in the block editor and asserts that no block shows the
+"unexpected or invalid content" warning (`specs/migration.spec.js`), which is the
+editor's own JavaScript validation of each block's saved HTML.
 
 ## Component matrix
 
diff --git a/docs/reporting-receiver.md b/docs/reporting-receiver.md
index 65bb14f..7c6ca80 100644
--- a/docs/reporting-receiver.md
+++ b/docs/reporting-receiver.md
@@ -28,7 +28,7 @@ session can build it without re-deriving the constraints.
 ## Smallest viable receiver
 
 One HTTPS endpoint, `POST /v1/summary`, accepting `application/json` bodies up to
-8 KB with `schema === 1`, validating field names and types against an allowlist,
+2 KB with `schema === 1`, validating field names and types against an allowlist,
 and appending the record to a store with a server-generated random id. Replies
 `202` with nothing but the id, which the plugin shows so the user can quote it
 when asking for deletion.
@@ -49,7 +49,7 @@ Cloudflare's own request logs exist and are retained per their policy.
 
 - **Stored:** the payload, the server-generated id, and the received date (day).
 - **Not stored:** IP, user agent, headers, referrer.
-- **Retention:** 24 months, then deleted; or sooner on request quoting the id.
+- **Retention:** 12 months (KV TTL), then deleted; or sooner on request quoting the id.
 - **Access:** the maintainer only; used to decide which components the migration
   tools must cover; aggregate counts may be published in the repository.
 - **Deletion:** the id shown after sending is the only key; an email or GitHub
@@ -61,13 +61,14 @@ Cloudflare's own request logs exist and are retained per their policy.
 
 | Control | Mechanism | Free-plan ceiling it relies on |
 | --- | --- | --- |
-| Global daily cap | Workers Free: 100,000 requests/day, then requests error; KV Free: 1,000 writes/day, then writes fail | the cap is the bill: there is none |
-| Per-IP rate limit | Workers Rate Limiting binding (e.g. 5 requests / 10 min per IP) and one WAF rate-limiting rule (free plan allows one) | no cost |
+| Account daily cap (shared) | Workers Free: 100,000 requests/day **per account**, then requests error; KV Free: 1,000 writes/day **per account**, then writes fail. Other Workers on the same account eat into these, so the receiver gets its own Cloudflare account (free) or the shared-quota risk is accepted knowingly | the cap is the bill: there is none |
+| Per-IP rate limit | Workers Rate Limiting binding with a supported period (60 s; e.g. 3 requests / 60 s per IP). Counters are approximate and per Cloudflare location, so this is a brake, not a guarantee; one WAF rate-limiting rule (free plan allows one) backs it up at the edge | no cost |
 | Kill switch | KV key `paused`; checked first; set from the dashboard or `wrangler kv` | one KV read per request (100,000/day free) |
-| Payload cap | reject bodies > 8 KB, non-JSON, `schema !== 1`, unknown keys, non-integer counts, counts > 10^7 | Worker CPU only |
-| Method/path allowlist | only `POST /v1/summary`; everything else 404 with no body | – |
+| Payload cap | reject bodies > 2 KB (a full payload with every component is about 1 KB), non-JSON, `schema !== 1`, unknown keys, non-integer counts, counts > 10^7 | Worker CPU only |
+| Ingestion cap | at most 300 accepted records per UTC day (a KV counter `count:YYYY-MM-DD`); beyond that reply `429` without storing | KV Free writes 1,000/day |
+| Method/path allowlist | `POST /v1/summary` (public) and `GET /v1/stats` (bearer secret, see Monitoring); everything else 404 with no body | – |
 | No egress | the Worker calls nothing (no email, no third parties) | – |
-| Storage growth | one KV value per record, TTL 24 months, key = random id; a daily cron summarises counts into one `stats:YYYY-MM-DD` key | KV Free 1 GB |
+| Storage growth | one KV value per record, TTL 12 months, key = random id; a daily cron summarises counts into one `stats:YYYY-MM-DD` key. Worst case 300 × 2 KB × 365 ≈ 220 MB, inside the 1 GB KV Free limit | KV Free 1 GB |
 | Monitoring | `GET /v1/stats` behind a bearer secret (wrangler secret) returning per-day counts; Cloudflare dashboard Workers metrics; `wrangler tail` for live logs; Cloudflare Notifications for Worker error rate | no cost |
 | Upgrade path | if the trial outgrows Free, move to Workers Paid only after adding a hard spend ceiling in the dashboard and re-reviewing this table | – |
 
diff --git a/inc/class-bs-companion.php b/inc/class-bs-companion.php
index cccba1c..df347b3 100644
--- a/inc/class-bs-companion.php
+++ b/inc/class-bs-companion.php
@@ -115,7 +115,7 @@ public static function install_and_activate() {
 		update_option( 'bs_legacy_assets', array_filter( array(
 			'css'      => empty( $o['chk_default_options_css'] ) ? '' : '1',
 			'js'       => empty( $o['chk_default_options_js'] ) ? '' : '1',
-			'tooltips' => empty( $o['chk_default_options_js'] ) ? '' : '1',
+			'tooltips' => '1', // the original always loads init.js, whatever the JS setting
 		) ) );
 		$activated = activate_plugin( self::FILE );
 		if ( is_wp_error( $activated ) ) {
diff --git a/inc/class-bs-migration.php b/inc/class-bs-migration.php
index 0497dee..68d5d2b 100644
--- a/inc/class-bs-migration.php
+++ b/inc/class-bs-migration.php
@@ -57,21 +57,40 @@ public static function apply( $post_id, $options, $expected_modified_gmt = null
 		if ( 0 === $result['converted'] ) {
 			return new WP_Error( 'bs_nothing', $result['skipped'] ? __( 'Nothing could be converted automatically; see the skipped list.', 'bsshortcodes' ) : __( 'No shortcodes to convert in this post.', 'bsshortcodes' ) );
 		}
+		$backup_created = false;
 		if ( ! $preview['already'] ) {
-			$kept = add_post_meta( $post_id, self::META_ORIGINAL, array(
+			// add_post_meta() and wp_update_post() both wp_unslash() their input, so
+			// slash first or every backslash in the content is lost.
+			$kept = add_post_meta( $post_id, self::META_ORIGINAL, wp_slash( array(
 				'content'      => $preview['original'],
 				'modified_gmt' => $preview['modified_gmt'],
 				'migrated_at'  => time(),
 				'version'      => BS_Migrator::VERSION,
-			), true );
+			) ), true );
 			if ( ! $kept ) {
 				return new WP_Error( 'bs_backup', __( 'Could not store the original content; nothing was changed.', 'bsshortcodes' ) );
 			}
+			$backup_created = true;
 		}
-		$updated = wp_update_post( array( 'ID' => $post_id, 'post_content' => $preview['converted'] ), true );
+		$updated = wp_update_post( wp_slash( array( 'ID' => $post_id, 'post_content' => $preview['converted'] ) ), true );
 		if ( is_wp_error( $updated ) ) {
+			if ( $backup_created ) {
+				delete_post_meta( $post_id, self::META_ORIGINAL );
+			}
 			return $updated;
 		}
+		// Users without unfiltered_html get their content passed through kses on
+		// save, which can strip the inline SVG icons or the <details name> grouping.
+		// The preview showed the unfiltered markup, so never leave a silently
+		// different version behind: put the original back and say why.
+		$saved = get_post_field( 'post_content', $post_id, 'raw' );
+		if ( $saved !== $preview['converted'] ) {
+			wp_update_post( wp_slash( array( 'ID' => $post_id, 'post_content' => $preview['original'] ) ) );
+			if ( $backup_created ) {
+				delete_post_meta( $post_id, self::META_ORIGINAL );
+			}
+			return new WP_Error( 'bs_filtered', __( 'WordPress filtered the converted markup on save because your account cannot publish unfiltered HTML, so the post would not match the preview. Nothing was changed; ask an administrator with that capability to run the migration.', 'bsshortcodes' ) );
+		}
 		update_post_meta( $post_id, self::META_RESULT, array(
 			'converted'    => $result['converted'],
 			'skipped'      => count( $result['skipped'] ),
@@ -103,7 +122,7 @@ public static function rollback( $post_id ) {
 		if ( ! is_array( $backup ) || ! isset( $backup['content'] ) ) {
 			return new WP_Error( 'bs_no_backup', __( 'No stored original for this post.', 'bsshortcodes' ) );
 		}
-		$updated = wp_update_post( array( 'ID' => $post->ID, 'post_content' => $backup['content'] ), true );
+		$updated = wp_update_post( wp_slash( array( 'ID' => $post->ID, 'post_content' => $backup['content'] ) ), true );
 		if ( is_wp_error( $updated ) ) {
 			return $updated;
 		}
diff --git a/specs/migration.spec.js b/specs/migration.spec.js
index e876c86..12b6442 100644
--- a/specs/migration.spec.js
+++ b/specs/migration.spec.js
@@ -157,6 +157,33 @@ test.describe('Migration end to end', () => {
         await scan(admin, page);
         await expect(page.locator('.bs-impact')).toContainText('No post content uses the shortcodes');
 
+        // The block editor's own validation: open both migrated posts with the
+        // block editor and make sure no block reports invalid content.
+        await admin.visitAdminPage('options-writing.php');
+        await page.locator('input[name="classic-editor-replace"][value="block"]').check();
+        await page.locator('input[name="classic-editor-allow-users"][value="allow"]').check();
+        await page.locator('#submit').click();
+        for (const id of [blocks.id, classic.id]) {
+            // classic-editor__forget is what the plugin's own "Edit (Block editor)" link
+            // uses; without it a post with no blocks opens in TinyMCE.
+            await admin.visitAdminPage('post.php', `post=${id}&action=edit&classic-editor__forget`);
+            await expect(page.getByRole('heading', { name: 'Edit Post', level: 1 })).toBeVisible();
+            await page.locator('iframe[name="editor-canvas"], .block-editor-writing-flow').first().waitFor({ timeout: 20000 });
+            // The block list lives in an iframe only when every block supports it; a
+            // Classic block (HTML-mode output) keeps the editor inline. Look in both.
+            const iframed = (await page.locator('iframe[name="editor-canvas"]').count()) > 0;
+            const root = iframed ? page.frameLocator('iframe[name="editor-canvas"]') : page;
+            await expect(root.locator('.is-root-container')).toBeVisible();
+            await expect(root.locator('.wp-block').first()).toBeVisible();
+            await expect(root.locator('.block-editor-warning')).toHaveCount(0);
+            await expect(page.locator('.block-editor-warning')).toHaveCount(0);
+            await expect(root.locator('body')).not.toContainText('unexpected or invalid content');
+        }
+        await admin.visitAdminPage('options-writing.php');
+        await page.locator('input[name="classic-editor-replace"][value="classic"]').check();
+        await page.locator('#submit').click();
+        await admin.visitAdminPage(TOOLS.path, TOOLS.query);
+
         // Hand off the assets: consent is required, then install + activate.
         await page.getByRole('button', { name: 'Install and activate the companion' }).click();
         await expect(page.locator('.notice.is-dismissible.notice-error')).toContainText('Tick the confirmation box');
diff --git a/tests/phpunit/CompanionTest.php b/tests/phpunit/CompanionTest.php
index d1bf703..b288701 100644
--- a/tests/phpunit/CompanionTest.php
+++ b/tests/phpunit/CompanionTest.php
@@ -83,7 +83,7 @@ public function test_install_and_activate_puts_a_working_plugin_in_place() {
 			$this->assertFileExists( $dir . '/css/bootstrap.css' );
 			$this->assertFileExists( $dir . '/fonts/glyphicons-halflings-regular.woff2' );
 			$this->assertTrue( BS_Companion::is_active() );
-			$this->assertSame( array( 'css' => '1' ), get_option( 'bs_legacy_assets' ) );
+			$this->assertSame( array( 'css' => '1', 'tooltips' => '1' ), get_option( 'bs_legacy_assets' ) );
 			$this->assertSame( file_get_contents( dirname( dirname( __DIR__ ) ) . '/css/bootstrap.css' ), file_get_contents( $dir . '/css/bootstrap.css' ) );
 		} finally {
 			deactivate_plugins( BS_Companion::FILE );
diff --git a/tests/phpunit/MigrationApplyTest.php b/tests/phpunit/MigrationApplyTest.php
index a3a3313..23ba82d 100644
--- a/tests/phpunit/MigrationApplyTest.php
+++ b/tests/phpunit/MigrationApplyTest.php
@@ -142,4 +142,37 @@ public function test_migrated_content_renders_without_the_shortcode_handlers() {
 		$this->assertStringContainsString( '<svg class="bs-icon bs-icon-ok"', $rendered );
 		$this->assertStringNotContainsString( '[bs_', $rendered );
 	}
+
+	public function test_backslashes_survive_migration_and_rollback() {
+		$original = "Path C:\\Users\\kev and a regex \\d+\n\n[bs_well]keep \\ this[/bs_well]\n\n<!-- wp:paragraph {\"placeholder\":\"\\u002d\\u002d\\u003c\"} -->\n<p>p</p>\n<!-- /wp:paragraph -->";
+		// wp_insert_post() expects slashed input (the factory passes args straight through).
+		$id       = self::factory()->post->create( array( 'post_content' => wp_slash( $original ) ) );
+		$this->assertSame( $original, get_post( $id )->post_content );
+
+		$r = BS_Migration::apply( $id, array( 'mode' => 'blocks', 'style' => 'inline' ) );
+
+		$this->assertNotWPError( $r );
+		$migrated = get_post( $id )->post_content;
+		$this->assertStringContainsString( 'C:\\Users\\kev', $migrated );
+		$this->assertStringContainsString( '\\u002d\\u002d\\u003c', $migrated );
+		$this->assertStringContainsString( 'keep \\ this', $migrated );
+		$this->assertSame( $original, get_post_meta( $id, BS_Migration::META_ORIGINAL, true )['content'] );
+		$this->assertTrue( BS_Migration::rollback( $id ) );
+		$this->assertSame( $original, get_post( $id )->post_content );
+	}
+
+	public function test_users_whose_markup_would_be_filtered_are_refused_and_nothing_changes() {
+		$author   = self::factory()->user->create( array( 'role' => 'author' ) );
+		$original = '[bs_icon name="glyphicon glyphicon-ok"] done [bs_collapse id="g"][bs_citem id="a" parent="g" title="Q"]A[/bs_citem][/bs_collapse]';
+		$id       = self::factory()->post->create( array( 'post_content' => $original, 'post_author' => $author ) );
+		wp_set_current_user( $author );
+		$this->assertFalse( current_user_can( 'unfiltered_html' ) );
+
+		$r = BS_Migration::apply( $id, array( 'mode' => 'html', 'style' => 'inline' ) );
+
+		$this->assertWPError( $r );
+		$this->assertSame( 'bs_filtered', $r->get_error_code() );
+		$this->assertSame( $original, get_post( $id )->post_content );
+		$this->assertFalse( BS_Migration::is_migrated( $id ) );
+	}
 }

From 71f8673954791eb99bdec7548eabb72b96fccca5 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 15:41:32 -0700
Subject: [PATCH 04/10] test(e2e): restore the Classic Editor user-switch
 setting after the block-editor check

Leaving "allow users to switch editors" on let the admin's last-used editor
(block, forced by the validation step) win on post-new.php and broke the
TinyMCE dialog specs on the next run.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 specs/migration.spec.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/specs/migration.spec.js b/specs/migration.spec.js
index 12b6442..c3a653e 100644
--- a/specs/migration.spec.js
+++ b/specs/migration.spec.js
@@ -179,8 +179,12 @@ test.describe('Migration end to end', () => {
             await expect(page.locator('.block-editor-warning')).toHaveCount(0);
             await expect(root.locator('body')).not.toContainText('unexpected or invalid content');
         }
+        // Put the Classic Editor plugin back exactly as the editor specs expect:
+        // classic by default and no per-user switching (otherwise this user's
+        // last-used editor, now "block", would win on post-new.php).
         await admin.visitAdminPage('options-writing.php');
         await page.locator('input[name="classic-editor-replace"][value="classic"]').check();
+        await page.locator('input[name="classic-editor-allow-users"][value="disallow"]').check();
         await page.locator('#submit').click();
         await admin.visitAdminPage(TOOLS.path, TOOLS.query);
 

From 378c4994f57a69ffb4ea94a6b2bb1592892b7cd1 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 16:09:04 -0700
Subject: [PATCH 05/10] test(e2e): wait for the block editor canvas instead of
 a heading (CI boots it slowly)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 specs/migration.spec.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/specs/migration.spec.js b/specs/migration.spec.js
index c3a653e..432ad57 100644
--- a/specs/migration.spec.js
+++ b/specs/migration.spec.js
@@ -167,8 +167,8 @@ test.describe('Migration end to end', () => {
             // classic-editor__forget is what the plugin's own "Edit (Block editor)" link
             // uses; without it a post with no blocks opens in TinyMCE.
             await admin.visitAdminPage('post.php', `post=${id}&action=edit&classic-editor__forget`);
-            await expect(page.getByRole('heading', { name: 'Edit Post', level: 1 })).toBeVisible();
-            await page.locator('iframe[name="editor-canvas"], .block-editor-writing-flow').first().waitFor({ timeout: 20000 });
+            // The block editor boots slowly on CI runners; wait for its canvas, not a heading.
+            await page.locator('iframe[name="editor-canvas"], .block-editor-writing-flow').first().waitFor({ timeout: 60000 });
             // The block list lives in an iframe only when every block supports it; a
             // Classic block (HTML-mode output) keeps the editor inline. Look in both.
             const iframed = (await page.locator('iframe[name="editor-canvas"]').count()) > 0;

From 83d76e913db8d1b3941d8f5614976ab7904d03a6 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 17:35:50 -0700
Subject: [PATCH 06/10] fix(migration): address the pre-merge review of the
 converter and companion

A fresh review of the whole PR (the fix pushes were never re-reviewed by
CodeRabbit) found ten defects, each now covered by a test:

- Block-level components (row, col, well, alert, lead, collapse, tabs)
  written inside a paragraph, heading or list item of a block post were
  converted in place, putting a <div> inside a <p> (broken layout, invalid
  block). They are now left in place and listed ("inline-context"); only
  Classic and Custom HTML blocks take block-level markup in place.
- html mode on a block document goes through the block walker too, so it
  never nests a div in a paragraph either.
- Skipped occurrences inside a block were listed twice (innerHTML and
  innerContent both processed); counted once now.
- Alerts as Group blocks (classes styling) no longer carry role="alert",
  which Group's save() cannot write and so made the block invalid; noted.
- A bs_col outside any bs_row now gets its own Columns parent instead of a
  bare, misplaced Column block. Drops the unused $top_level parameter.
- bs_row with a custom class keeps exactly that class in HTML output, as the
  handler did (shortcode_atts default), instead of adding "row".
- bs_citem items are grouped (<details name>) by their parent attribute, as
  Bootstrap's data-parent worked; items without one stay independent rather
  than becoming an exclusive accordion that hides open content.
- Standalone buttons that lose a type/size in the Button block say so.
- Old icon-* sprite icons depend on the Bootstrap CSS bundle (shortcodes.css),
  and the companion now ships and loads shortcodes.css plus the sprite PNG.
- With conditional loading on, the companion covers pages where Bootstrap
  Shortcodes loads nothing, and Bootstrap Shortcodes' render-time fallback
  stands down when the companion's files are already queued.
- The migrated-posts list (rollback UI) covers every type and status the
  scan covers, including reusable blocks, templates and trash.

Verified: PHPUnit 169/169 on WP 7.1.4 / PHP 8.3 and WP 6.4.7 / PHP 7.4;
Playwright 20/20 (now also asserts the companion serves shortcodes.css and
the sprite).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 bootstrap-shortcodes.php                      |  12 +-
 .../bootstrap-legacy-assets.php               |  17 +-
 companion/bootstrap-legacy-assets/readme.txt  |   4 +-
 docs/migration.md                             |  30 ++--
 inc/class-bs-admin-migration.php              |   6 +-
 inc/class-bs-companion.php                    |   3 +
 inc/class-bs-migration.php                    |  10 +-
 inc/class-bs-migrator.php                     | 146 ++++++++++++------
 specs/migration.spec.js                       |   7 +
 tests/phpunit/CompanionTest.php               |  45 ++++++
 tests/phpunit/MigrationApplyTest.php          |  10 ++
 tests/phpunit/MigratorConvertTest.php         |  79 ++++++++++
 12 files changed, 298 insertions(+), 71 deletions(-)

diff --git a/bootstrap-shortcodes.php b/bootstrap-shortcodes.php
index 8a218c9..ae578bd 100644
--- a/bootstrap-shortcodes.php
+++ b/bootstrap-shortcodes.php
@@ -182,13 +182,19 @@ function enqueue_assets() {
         }
         $this->assets_enqueued = true;
         $init_deps = array( 'jquery' );
-        if ( $this->option_on( 'chk_default_options_css' ) ) {
+        // The legacy-assets companion may already have queued the same files
+        // (conditional loading, late render-time load): never load Bootstrap twice.
+        if ( $this->option_on( 'chk_default_options_css' ) && ! wp_style_is( 'bs-legacy-bootstrap', 'enqueued' ) ) {
             wp_enqueue_style( 'bs_bootstrap', plugins_url( 'css/bootstrap.css', __FILE__ ) );
             wp_enqueue_style( 'bs_shortcodes', plugins_url( 'css/shortcodes.css', __FILE__ ) );
         }
         if ( $this->option_on( 'chk_default_options_js' ) ) {
-            wp_enqueue_script( 'bs_bootstrap', plugins_url( 'js/bootstrap.js', __FILE__ ), array( 'jquery' ) );
-            $init_deps[] = 'bs_bootstrap';
+            if ( wp_script_is( 'bs-legacy-bootstrap', 'enqueued' ) ) {
+                $init_deps[] = 'bs-legacy-bootstrap';
+            } else {
+                wp_enqueue_script( 'bs_bootstrap', plugins_url( 'js/bootstrap.js', __FILE__ ), array( 'jquery' ) );
+                $init_deps[] = 'bs_bootstrap';
+            }
         }
         wp_enqueue_script( 'bs_init', plugins_url( 'js/init.js', __FILE__ ), $init_deps );
     }
diff --git a/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php b/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php
index 94f05e3..91a17ce 100644
--- a/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php
+++ b/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php
@@ -44,13 +44,22 @@ public static function activate() {
 		}
 	}
 
-	/** True when Bootstrap Shortcodes is active and still loading its own copy. */
+	/**
+	 * True when Bootstrap Shortcodes is active and loading its own copy on every
+	 * page. With its conditional loading on it only loads where shortcodes
+	 * remain, so this plugin covers the other pages; other_bootstrap() then sees
+	 * the original's files on pages where it did load, and the original stands
+	 * down on late (render-time) loads once this plugin's files are queued.
+	 */
 	public static function original_plugin_loads_assets() {
 		if ( ! class_exists( 'BootstrapShortcodes' ) ) {
 			return false;
 		}
 		$o = get_option( 'bs_options' );
-		return is_array( $o ) && ( ! empty( $o['chk_default_options_css'] ) || ! empty( $o['chk_default_options_js'] ) );
+		if ( ! is_array( $o ) || ! empty( $o['chk_conditional_assets'] ) ) {
+			return false;
+		}
+		return ! empty( $o['chk_default_options_css'] ) || ! empty( $o['chk_default_options_js'] );
 	}
 
 	/** A theme or another plugin already registered a Bootstrap file of this kind. */
@@ -75,6 +84,8 @@ public function enqueue() {
 		$base = plugins_url( '', __FILE__ );
 		if ( ! empty( $o['css'] ) && ! self::other_bootstrap( 'css' ) ) {
 			wp_enqueue_style( 'bs-legacy-bootstrap', $base . '/css/bootstrap.css', array(), '3.4.1' );
+			// The original loaded this alongside: icon-* sprites and small layout fixups.
+			wp_enqueue_style( 'bs-legacy-shortcodes', $base . '/css/shortcodes.css', array( 'bs-legacy-bootstrap' ), self::VERSION );
 		}
 		if ( ! empty( $o['js'] ) && ! self::other_bootstrap( 'js' ) ) {
 			wp_enqueue_script( 'bs-legacy-bootstrap', $base . '/js/bootstrap.js', array( 'jquery' ), '3.4.1' );
@@ -116,7 +127,7 @@ public function page() {
 		?>
 		<div class="wrap">
 			<h1>Bootstrap 3 Legacy Assets</h1>
-			<p><?php esc_html_e( 'This plugin exists so a site can remove Bootstrap Shortcodes without losing the Bootstrap 3 styling its remaining markup depends on. It loads the same files that plugin loaded (Bootstrap 3.4.1 CSS and JavaScript, the Glyphicons font, and a small tooltip initialiser). It registers no shortcodes.', 'bs-legacy-assets' ); ?></p>
+			<p><?php esc_html_e( 'This plugin exists so a site can remove Bootstrap Shortcodes without losing the Bootstrap 3 styling its remaining markup depends on. It loads the same files that plugin loaded (Bootstrap 3.4.1 CSS and JavaScript, the Glyphicons font, that plugin\'s small shortcodes.css, and a tooltip initialiser). It registers no shortcodes.', 'bs-legacy-assets' ); ?></p>
 			<div class="notice notice-warning inline"><p><strong><?php esc_html_e( 'Bootstrap 3 is end-of-life.', 'bs-legacy-assets' ); ?></strong> <?php esc_html_e( 'Version 3.4.1 (2019) is the last release; the Bootstrap project publishes no fixes for it. Keeping it is a deliberate compatibility choice. Treat this plugin as temporary: migrate the remaining markup to your theme or to blocks, then deactivate it.', 'bs-legacy-assets' ); ?></p></div>
 			<form method="post" action="options.php">
 				<?php settings_fields( 'bs_legacy_assets' ); ?>
diff --git a/companion/bootstrap-legacy-assets/readme.txt b/companion/bootstrap-legacy-assets/readme.txt
index 6eb6ec0..eba5cb4 100644
--- a/companion/bootstrap-legacy-assets/readme.txt
+++ b/companion/bootstrap-legacy-assets/readme.txt
@@ -16,7 +16,9 @@ A compatibility bridge, generated by the Bootstrap Shortcodes plugin's migration
 
 **Bootstrap 3 is end-of-life.** 3.4.1 (February 2019) is its last release. Keeping it running is a deliberate choice made for content that still depends on it; the plan should be to migrate that content and deactivate this plugin.
 
-It avoids double loading: while Bootstrap Shortcodes is active with its asset settings on, this plugin does nothing; if the theme registers its own bootstrap.css or bootstrap.js, the matching file here is skipped.
+It avoids double loading: while Bootstrap Shortcodes is active and loading its assets on every page, this plugin does nothing; with that plugin's conditional loading on, this plugin covers the pages it skips. If the theme registers its own bootstrap.css or bootstrap.js, the matching file here is skipped.
+
+The CSS switch also loads Bootstrap Shortcodes' small shortcodes.css (old icon-* sprite icons and layout fixups), as that plugin did.
 
 == Changelog ==
 
diff --git a/docs/migration.md b/docs/migration.md
index 3feda1f..54cf51d 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -25,8 +25,11 @@ Then deactivate the plugin, check the pages the report listed, and delete it.
   `wp_update_post()` records a revision as usual. **Roll back** restores the stored
   original and removes the custom field. Rollback does not depend on revisions.
 - Leaves in place, and lists: occurrences whose opening and closing tags do not match
-  (an unclosed `[bs_well]`), escaped `[[bs_x]]` examples, and `bs_` tags the plugin
-  never registered (typos, other plugins). Nothing in a post is dropped silently;
+  (an unclosed `[bs_well]`), escaped `[[bs_x]]` examples, `bs_` tags the plugin
+  never registered (typos, other plugins), and block-level components (row, column,
+  well, alert, lead, collapse, tabs) written *inside* a paragraph, heading or list
+  item of a block post, where a `<div>` would break the block; put the shortcode on
+  its own line and migrate again. Nothing in a post is dropped silently;
   every approximation is reported as a note in the preview and stored with the post.
 - Never runs on activation, update or a schedule. Needs `manage_options`, a nonce
   and a button press (or `edit_post` for each post).
@@ -53,16 +56,16 @@ behaviourally different; "Needs" what the output still depends on.
 
 | Shortcode | Blocks destination | HTML destination | WP | Keeps | Changes | Needs |
 | --- | --- | --- | --- | --- | --- | --- |
-| `bs_row` + `bs_col` | Columns > Column, width from the first `col-*-N` class (N/12 as %) | `<div class="row"><div class="col-sm-6">` unchanged | 5.0 | content, nesting, column proportions, extra classes (as block className) | responsive breakpoints become the Columns block's own (stack on mobile); `offset`/`push`/`pull` dropped and noted; theme spacing | HTML output needs Bootstrap CSS |
-| `bs_button` standalone | Buttons > Button with url/text/target (`rel="noopener noreferrer"` for `_blank`) | `<a class="btn btn-primary">` identical to today | 5.4 | text, link, target | theme button style instead of Bootstrap colours/sizes | HTML output needs Bootstrap CSS |
+| `bs_row` + `bs_col` | Columns > Column, width from the first `col-*-N` class (N/12 as %); a `bs_col` outside any `bs_row` gets its own Columns block (noted) | `<div class="row"><div class="col-sm-6">` unchanged (a custom `class` on `bs_row` replaces `row`, as the shortcode did) | 5.0 | content, nesting, column proportions, extra classes (as block className) | responsive breakpoints become the Columns block's own (stack on mobile); `offset`/`push`/`pull` dropped and noted; theme spacing | HTML output needs Bootstrap CSS |
+| `bs_button` standalone | Buttons > Button with url/text/target (`rel="noopener noreferrer"` for `_blank`) | `<a class="btn btn-primary">` identical to today | 5.4 | text, link, target | theme button style instead of Bootstrap colours/sizes (noted when a `type` or `size` was set) | HTML output needs Bootstrap CSS |
 | `bs_button` inline in a sentence | stays an inline `<a class="btn ...">` (noted) | same | – | everything | – | Bootstrap CSS |
 | `bs_well` | self-contained: Custom HTML block with inline well styling; classes: Group block with `well` class | `<div class="well" style="...">` or `<div class="well">` | 5.0 | content (paragraphs baked in for the HTML block) | editable as HTML rather than blocks (self-contained); small sizing differences | classes variant needs Bootstrap CSS |
-| `bs_notification` | same shape as wells with alert colours and `role="alert"` | same | 5.0 | message, type colour | **dismiss (×) button removed** (needs Bootstrap JS), noted | classes variant needs Bootstrap CSS |
+| `bs_notification` | same shape as wells with alert colours and `role="alert"` (the classes variant's Group block cannot store `role`, so it is dropped there, noted) | same | 5.0 | message, type colour | **dismiss (×) button removed** (needs Bootstrap JS), noted | classes variant needs Bootstrap CSS |
 | `bs_lead` | Paragraph with `lead` class and the theme's `large` font size | `<p class="lead" style="font-size:1.3em;font-weight:300">` | 5.0 | text | exact size follows the theme | classes variant needs Bootstrap CSS |
 | `bs_label` | inline `<span class="label label-x">` with inline colours | same | – | text, type colour | – | classes variant needs Bootstrap CSS |
-| `bs_icon` | inline SVG built from the bundled Glyphicons font (`<svg class="bs-icon bs-icon-star">`, `currentColor`, 1em) | same | – | the glyph, size relative to text, extra classes | none visible; unknown glyph names keep `<i class="glyphicon ...">` and are noted | classes variant, or unknown glyphs, need the Glyphicons font (Bootstrap CSS) |
+| `bs_icon` | inline SVG built from the bundled Glyphicons font (`<svg class="bs-icon bs-icon-star">`, `currentColor`, 1em) | same | – | the glyph, size relative to text, extra classes | none visible; unknown glyph names keep `<i class="glyphicon ...">` and are noted; old `icon-*` sprite names keep their `<i>` and are noted | classes variant, or unknown glyphs, need the Glyphicons font (Bootstrap CSS); `icon-*` names need the plugin's `shortcodes.css` sprite, which the companion ships |
 | `bs_tooltip` | `<span class="bs-tooltip" title="...">` (dotted underline when self-contained) | same | – | the text and the tooltip text (they were always identical) | native browser tooltip: no placement/trigger, none on touch devices; noted | – |
-| `bs_collapse` + `bs_citem` | one Details block per item, `name` = group id so one opens at a time (WP 6.6+; ignored earlier), `open` for `open="true"`, element `id` kept so `#anchor` links work | `<div class="bs-collapse"><details name><summary>` | 6.3 (Details block); HTML works everywhere | titles, content, initial open state, one-at-a-time behaviour, anchor ids | Bootstrap panel chrome gone (theme styles the Details block); keyboard: native `<summary>` | – |
+| `bs_collapse` + `bs_citem` | one Details block per item; items with a `parent` (what the editor button writes) share `name` = that parent so one opens at a time (WP 6.6+; ignored earlier), items without one stay independent, as Bootstrap's `data-parent` worked; `open` for `open="true"`, element `id` kept so `#anchor` links work | `<div class="bs-collapse"><details name><summary>` | 6.3 (Details block); HTML works everywhere | titles, content, initial open state, one-at-a-time behaviour, anchor ids | Bootstrap panel chrome gone (theme styles the Details block); keyboard: native `<summary>` | – |
 | `bs_tabs` + `bs_thead` + `bs_tab` + `bs_dropdown` + `bs_tcontents` + `bs_tcontent` | one Details block per pane, titled by the matching tab (`href="#id"` ↔ `id`), active pane open; dropdown tabs flattened as "Dropdown: Tab" | `<div class="bs-tabs"><details>` per pane | 6.3 / any | every pane's content, titles, order, initial pane, anchor ids | **tabs become stacked collapsible sections** (semantic alternative, noted). On WordPress 7.1+ the editor's Tabs block can be built from them by hand if tabs are wanted back | – |
 
 Attributes the plugin never used (anything not in the table above, such as a
@@ -84,12 +87,15 @@ in the bundled set, the site still needs Bootstrap 3 after this plugin is gone.
 **Bootstrap 3 Legacy Assets** is a separate, minimal plugin (`companion/` in this
 repository; the migration page builds its zip from this plugin's own files). It:
 
-- loads the same Bootstrap 3.4.1 CSS, JS, Glyphicons font and tooltip initialiser
-  this plugin loads, with three on/off switches (Settings > Legacy Bootstrap);
+- loads the same Bootstrap 3.4.1 CSS (with this plugin's `shortcodes.css` and its
+  `icon-*` sprite), JS, Glyphicons font and tooltip initialiser this plugin loads,
+  with three on/off switches (Settings > Legacy Bootstrap);
 - registers **no** shortcodes and has no other behaviour;
-- stays idle while Bootstrap Shortcodes is active with its asset settings on, and
-  skips its CSS or JS when the theme registers its own `bootstrap.css` / `bootstrap.js`,
-  so nothing loads twice;
+- stays idle while Bootstrap Shortcodes is active and loading its assets on every
+  page, and skips its CSS or JS when the theme (or Bootstrap Shortcodes itself)
+  registers a `bootstrap.css` / `bootstrap.js`, so nothing loads twice. With
+  Bootstrap Shortcodes' conditional loading on, the companion covers the pages
+  without shortcodes and Bootstrap Shortcodes covers the rest;
 - is installed only from the migration page after ticking an explicit statement, or
   by uploading the downloaded zip yourself. Its settings start as copies of this
   plugin's CSS/JS settings.
diff --git a/inc/class-bs-admin-migration.php b/inc/class-bs-admin-migration.php
index 65f6e2c..ed0d506 100644
--- a/inc/class-bs-admin-migration.php
+++ b/inc/class-bs-admin-migration.php
@@ -239,7 +239,11 @@ private function render_result_lists( $r ) {
 			<?php
 			$parts = array();
 			foreach ( $r['skipped'] as $s ) {
-				$parts[] = sprintf( '[%s] (%s)', $s['tag'], 'unbalanced' === $s['reason'] ? __( 'opening/closing tags do not match', 'bsshortcodes' ) : $s['reason'] );
+				$reasons = array(
+					'unbalanced'     => __( 'opening/closing tags do not match', 'bsshortcodes' ),
+					'inline-context' => __( 'a block-level component written inside a paragraph or heading; move it onto its own line, then migrate again', 'bsshortcodes' ),
+				);
+				$parts[] = sprintf( '[%s] (%s)', $s['tag'], isset( $reasons[ $s['reason'] ] ) ? $reasons[ $s['reason'] ] : $s['reason'] );
 			}
 			echo esc_html( implode( ', ', $parts ) );
 			?>
diff --git a/inc/class-bs-companion.php b/inc/class-bs-companion.php
index df347b3..b255c48 100644
--- a/inc/class-bs-companion.php
+++ b/inc/class-bs-companion.php
@@ -20,6 +20,9 @@ public static function manifest() {
 			self::SLUG . '/bootstrap-legacy-assets.php' => self::source_dir() . '/bootstrap-legacy-assets.php',
 			self::SLUG . '/readme.txt'                  => self::source_dir() . '/readme.txt',
 			self::SLUG . '/css/bootstrap.css'           => $plugin . '/css/bootstrap.css',
+			// Loaded with bootstrap.css by the original: legacy icon-* sprites and layout fixups.
+			self::SLUG . '/css/shortcodes.css'          => $plugin . '/css/shortcodes.css',
+			self::SLUG . '/images/glyphicons-halflings.png' => $plugin . '/images/glyphicons-halflings.png',
 			self::SLUG . '/js/bootstrap.js'             => $plugin . '/js/bootstrap.js',
 			self::SLUG . '/js/init.js'                  => $plugin . '/js/init.js',
 		);
diff --git a/inc/class-bs-migration.php b/inc/class-bs-migration.php
index 68d5d2b..3b082bc 100644
--- a/inc/class-bs-migration.php
+++ b/inc/class-bs-migration.php
@@ -148,11 +148,15 @@ public static function batch( $post_ids, $options ) {
 		return $out;
 	}
 
-	/** Posts that hold a stored original, newest first (bounded). */
+	/**
+	 * Posts that hold a stored original, newest first (bounded). Same types and
+	 * statuses as the scan: 'any' would leave out reusable blocks, templates
+	 * and trashed posts, which could then be migrated but never rolled back.
+	 */
 	public static function migrated_posts( $limit = 500 ) {
 		return get_posts( array(
-			'post_type'      => 'any',
-			'post_status'    => 'any',
+			'post_type'      => BS_Scanner::post_types(),
+			'post_status'    => BS_Scanner::post_statuses(),
 			'posts_per_page' => $limit,
 			'meta_key'       => self::META_ORIGINAL,
 			'orderby'        => 'modified',
diff --git a/inc/class-bs-migrator.php b/inc/class-bs-migrator.php
index 07e1372..a3406ff 100644
--- a/inc/class-bs-migrator.php
+++ b/inc/class-bs-migrator.php
@@ -28,6 +28,15 @@ class BS_Migrator {
 	private static $unbalanced;
 	private static $tab_titles;
 	private static $section_counter;
+	private static $row_depth = 0;
+	/** True while converting inside a block whose HTML only allows inline content (paragraph, heading ...). */
+	private static $inline_only = false;
+
+	/** Components that render block-level HTML (a div, p or details). */
+	private static $block_level = array( 'bs_row', 'bs_col', 'bs_well', 'bs_notification', 'bs_lead', 'bs_collapse', 'bs_citem', 'bs_tabs', 'bs_thead', 'bs_tab', 'bs_dropdown', 'bs_tcontents', 'bs_tcontent' );
+
+	/** Blocks whose saved HTML may hold block-level markup converted in place. */
+	private static $block_containers = array( 'core/freeform', 'core/html' );
 
 	public static function convert( $content, $options = array() ) {
 		$options = wp_parse_args( $options, array( 'mode' => 'auto', 'style' => 'inline' ) );
@@ -41,6 +50,8 @@ public static function convert( $content, $options = array() ) {
 		self::$converted  = 0;
 		self::$tab_titles = array();
 		self::$section_counter = 0;
+		self::$row_depth       = 0;
+		self::$inline_only     = false;
 
 		$result = array(
 			'content'      => $content,
@@ -59,13 +70,13 @@ public static function convert( $content, $options = array() ) {
 		$scan             = BS_Scanner::scan_text( $content );
 		self::$unbalanced = $scan['unbalanced'];
 
-		if ( 'blocks' === $options['mode'] && has_blocks( $content ) ) {
+		if ( has_blocks( $content ) ) {
 			// A block document: convert inside the blocks that hold shortcodes
 			// (Shortcode, Classic, Paragraph, Custom HTML ...) without breaking
-			// their structure.
+			// their structure. In html mode the replacements are plain HTML.
 			$result['content'] = serialize_blocks( self::convert_blocks( parse_blocks( $content ) ) );
 		} else {
-			$result['content'] = self::process( $content, true );
+			$result['content'] = self::process( $content );
 			if ( 'blocks' === $options['mode'] ) {
 				// Loose text between blocks becomes paragraphs (or a Classic block), as the editor would.
 				$result['content'] = self::inner_blocks( $result['content'] );
@@ -94,34 +105,40 @@ private static function convert_blocks( $blocks ) {
 			$has  = false !== strpos( $html, '[bs_' );
 			if ( null === $block['blockName'] ) {
 				if ( $has ) {
-					$block = self::raw_block( self::inner_blocks( self::process( $html, true ) ) );
+					$block = self::replacement_block( $html );
 				}
 				$out[] = $block;
 				continue;
 			}
 			if ( 'core/shortcode' === $block['blockName'] && $has ) {
-				$converted = self::inner_blocks( self::process( $html, true ) );
-				$out[]     = self::raw_block( $converted );
+				$out[] = self::replacement_block( $html );
 				continue;
 			}
 			if ( 'core/paragraph' === $block['blockName'] && $has && preg_match( '/^\s*<p[^>]*>\s*(\[bs_[\s\S]*\])\s*<\/p>\s*$/', $html, $m ) && self::is_single_shortcode( $m[1] ) ) {
-				$converted = self::inner_blocks( self::process( $m[1], true ) );
-				$out[]     = self::raw_block( $converted );
+				$out[] = self::replacement_block( $m[1] );
 				continue;
 			}
 			if ( $has ) {
-				// Inline components inside this block's own HTML (paragraph, heading,
-				// list, classic, custom HTML ...): static HTML keeps the block valid.
-				$saved_mode              = self::$options['mode'];
-				self::$options['mode']   = 'html';
-				$block['innerHTML']      = self::process( $html, false );
-				$counted                 = self::$converted;
+				// Components inside this block's own HTML (paragraph, heading, list,
+				// classic, custom HTML ...) are converted in place as static HTML. Only
+				// Classic and Custom HTML blocks may take block-level markup; inside a
+				// paragraph or heading a <div> would break the block (and the page), so
+				// block-level components there are left in place and listed.
+				$saved_mode            = self::$options['mode'];
+				self::$options['mode'] = 'html';
+				self::$inline_only     = ! in_array( $block['blockName'], self::$block_containers, true );
+				$block['innerHTML']    = self::process( $html );
+				$counted               = self::$converted;
+				$skipped               = self::$skipped;
 				foreach ( $block['innerContent'] as $i => $chunk ) {
 					if ( is_string( $chunk ) && false !== strpos( $chunk, '[bs_' ) ) {
-						$block['innerContent'][ $i ] = self::process( $chunk, false );
+						$block['innerContent'][ $i ] = self::process( $chunk );
 					}
 				}
-				self::$converted       = $counted; // innerContent repeats innerHTML; count once
+				// innerContent repeats innerHTML: count and list each occurrence once.
+				self::$converted       = $counted;
+				self::$skipped         = $skipped;
+				self::$inline_only     = false;
 				self::$options['mode'] = $saved_mode;
 			}
 			if ( ! empty( $block['innerBlocks'] ) ) {
@@ -140,6 +157,12 @@ private static function is_single_shortcode( $text ) {
 		return 1 === count( $m ) && 0 === $m[0][0][1] && strlen( $m[0][0][0] ) === strlen( $text );
 	}
 
+	/** A whole block (Shortcode, Classic text, lone-shortcode paragraph) replaced by its conversion. */
+	private static function replacement_block( $html ) {
+		$converted = self::process( $html );
+		return self::raw_block( self::blocks() ? self::inner_blocks( $converted ) : $converted );
+	}
+
 	private static function raw_block( $html ) {
 		$html = "\n" . trim( $html ) . "\n";
 		return array( 'blockName' => null, 'attrs' => array(), 'innerBlocks' => array(), 'innerHTML' => $html, 'innerContent' => array( $html ) );
@@ -149,7 +172,7 @@ private static function raw_block( $html ) {
 	/* Walking                                                             */
 	/* ------------------------------------------------------------------ */
 
-	private static function process( $text, $top_level ) {
+	private static function process( $text ) {
 		if ( false === strpos( $text, '[bs_' ) ) {
 			return $text;
 		}
@@ -175,6 +198,11 @@ private static function process( $text, $top_level ) {
 				$out .= $whole;
 				continue;
 			}
+			if ( self::$inline_only && in_array( $tag, self::$block_level, true ) ) {
+				self::$skipped[] = array( 'tag' => $tag, 'reason' => 'inline-context', 'offset' => $start );
+				$out .= $whole;
+				continue;
+			}
 			$attrs   = shortcode_parse_atts( $m[3][0] );
 			$attrs   = is_array( $attrs ) ? $attrs : array();
 			$content = isset( $m[5][0] ) ? $m[5][0] : '';
@@ -187,7 +215,7 @@ private static function process( $text, $top_level ) {
 			$after      = substr( $text, $last );
 			$standalone = (bool) preg_match( '/(^|\n)[ \t]*$/', $before ) && (bool) preg_match( '/^[ \t]*(\n|$)/', $after );
 
-			$replacement = self::convert_one( $tag, $attrs, $content, $standalone, $top_level );
+			$replacement = self::convert_one( $tag, $attrs, $content, $standalone );
 			if ( null === $replacement ) {
 				$out .= $whole;
 				continue;
@@ -221,12 +249,12 @@ private static function attr( $value ) {
 		return esc_attr( (string) $value );
 	}
 
-	private static function convert_one( $tag, $attrs, $content, $standalone, $top_level ) {
+	private static function convert_one( $tag, $attrs, $content, $standalone ) {
 		switch ( $tag ) {
 			case 'bs_row':
 				return self::row( $attrs, $content );
 			case 'bs_col':
-				return self::col( $attrs, $content, $top_level );
+				return self::col( $attrs, $content );
 			case 'bs_well':
 				return self::well( $attrs, $content );
 			case 'bs_notification':
@@ -254,7 +282,7 @@ private static function convert_one( $tag, $attrs, $content, $standalone, $top_l
 				self::$notes[] = sprintf( 'A stray [%s] outside [bs_tabs] was removed (it rendered an empty tab strip).', $tag );
 				return '';
 			case 'bs_tcontents':
-				return self::process( $content, false );
+				return self::process( $content );
 			case 'bs_tcontent':
 				return self::tcontent( $attrs, $content );
 		}
@@ -319,7 +347,7 @@ private static function wrap_block( $name, $attrs, $html ) {
 
 	/** Static HTML keeps classic behaviour: wpautop runs later, as it always did. */
 	private static function inner_html( $html ) {
-		return self::process( $html, false );
+		return self::process( $html );
 	}
 
 	/* ------------------------------------------------------------------ */
@@ -327,13 +355,16 @@ private static function inner_html( $html ) {
 	/* ------------------------------------------------------------------ */
 
 	private static function row( $attrs, $content ) {
-		$classes = isset( $attrs['class'] ) ? preg_split( '/\s+/', trim( $attrs['class'] ) ) : array( 'row' );
-		$extra   = array_values( array_diff( array_filter( $classes ), array( 'row' ) ) );
+		// The handler used `class` instead of "row" (shortcode_atts default), never in addition.
+		$classes = isset( $attrs['class'] ) ? array_values( array_filter( preg_split( '/\s+/', trim( $attrs['class'] ) ) ) ) : array( 'row' );
+		$extra   = array_values( array_diff( $classes, array( 'row' ) ) );
 		if ( ! self::blocks() ) {
 			self::$deps[] = 'bootstrap-css';
-			return '<div class="' . self::attr( implode( ' ', array_merge( array( 'row' ), $extra ) ) ) . '">' . self::inner_html( $content ) . '</div>';
+			return '<div class="' . self::attr( implode( ' ', $classes ) ) . '">' . self::inner_html( $content ) . '</div>';
 		}
-		$inner = self::process( $content, false );
+		self::$row_depth++;
+		$inner = self::process( $content );
+		self::$row_depth--;
 		// Inner must be columns only; stray text between columns is kept as its own column.
 		$columns = array();
 		foreach ( parse_blocks( trim( $inner ) ) as $block ) {
@@ -349,7 +380,7 @@ private static function row( $attrs, $content ) {
 		return self::wrap_block( 'columns', $block_attrs, '<div class="' . self::attr( $class ) . '">' . implode( '', $columns ) . '</div>' );
 	}
 
-	private static function col( $attrs, $content, $top_level ) {
+	private static function col( $attrs, $content ) {
 		$classes = isset( $attrs['class'] ) ? preg_split( '/\s+/', trim( $attrs['class'] ) ) : array( 'col-sm-1' );
 		$classes = array_values( array_filter( $classes ) );
 		if ( ! self::blocks() ) {
@@ -379,9 +410,15 @@ private static function col( $attrs, $content, $top_level ) {
 		if ( $extra ) {
 			$block_attrs['className'] = implode( ' ', $extra );
 		}
-		$class = 'wp-block-column' . ( $extra ? ' ' . implode( ' ', $extra ) : '' );
-		$inner = self::inner_blocks( self::process( $content, false ) );
-		return self::wrap_block( 'column', $block_attrs, '<div class="' . self::attr( $class ) . '"' . $style . '>' . $inner . '</div>' );
+		$class  = 'wp-block-column' . ( $extra ? ' ' . implode( ' ', $extra ) : '' );
+		$inner  = self::inner_blocks( self::process( $content ) );
+		$column = self::wrap_block( 'column', $block_attrs, '<div class="' . self::attr( $class ) . '"' . $style . '>' . $inner . '</div>' );
+		if ( 0 === self::$row_depth ) {
+			// A Column block is only valid inside Columns.
+			self::$notes[] = 'A [bs_col] outside a [bs_row] was given its own Columns block.';
+			return self::wrap_block( 'columns', array(), '<div class="wp-block-columns">' . $column . '</div>' );
+		}
+		return $column;
 	}
 
 	private static function well( $attrs, $content ) {
@@ -412,12 +449,16 @@ private static function alert( $attrs, $content ) {
 	private static function box( $class, $style, $content, $extra_attrs ) {
 		if ( self::blocks() ) {
 			if ( self::inline_style() ) {
-				$inner = self::process( $content, false );
+				$inner = self::process( $content );
 				$html  = '<div class="' . self::attr( $class ) . '"' . $extra_attrs . ' style="' . self::attr( $style ) . '">' . self::bake_paragraphs( $inner ) . '</div>';
 				return self::wrap_block( 'html', array(), $html );
 			}
 			self::$deps[] = 'bootstrap-css';
-			return self::wrap_block( 'group', array( 'className' => $class ), '<div class="wp-block-group ' . self::attr( $class ) . '"' . $extra_attrs . '>' . self::inner_blocks( self::process( $content, false ) ) . '</div>' );
+			if ( '' !== $extra_attrs ) {
+				// The Group block's save() writes no role attribute; keeping it would make the block invalid.
+				self::$notes[] = 'The alert role is not kept: the Group block cannot store it. The message and colours are kept.';
+			}
+			return self::wrap_block( 'group', array( 'className' => $class ), '<div class="wp-block-group ' . self::attr( $class ) . '">' . self::inner_blocks( self::process( $content ) ) . '</div>' );
 		}
 		$inner = self::inner_html( $content );
 		if ( self::inline_style() ) {
@@ -443,7 +484,7 @@ private static function bake_paragraphs( $html ) {
 	}
 
 	private static function lead( $content ) {
-		$inner = self::process( $content, false );
+		$inner = self::process( $content );
 		if ( self::blocks() ) {
 			if ( trim( $inner ) === wp_strip_all_tags( trim( $inner ) ) || self::is_simple_inline_html( trim( $inner ) ) ) {
 				return self::wrap_block( 'paragraph', array( 'className' => 'lead', 'fontSize' => 'large' ), '<p class="lead has-large-font-size">' . trim( $inner ) . '</p>' );
@@ -466,6 +507,16 @@ private static function button( $attrs, $standalone ) {
 			$target_attr = ' target="' . self::attr( $target ) . '"' . ( '_blank' === $target ? ' rel="noopener noreferrer"' : '' );
 		}
 		if ( self::blocks() && $standalone ) {
+			$dropped = array();
+			if ( 'default' !== $a['type'] && '' !== $a['type'] ) {
+				$dropped[] = 'btn-' . $a['type'];
+			}
+			if ( '' !== $a['size'] && $a['size'] !== $a['type'] ) {
+				$dropped[] = 'btn-' . $a['size'];
+			}
+			if ( $dropped ) {
+				self::$notes[] = sprintf( 'Button style "%s" is not carried over: the Button block uses your theme\'s button style. Restyle it in the editor if the colour or size mattered.', implode( ' ', $dropped ) );
+			}
 			$link = '<a class="wp-block-button__link wp-element-button" href="' . esc_url( $a['href'] ) . '"' . $target_attr . '>' . esc_html( $a['value'] ) . '</a>';
 			$inner = self::wrap_block( 'button', array(), '<div class="wp-block-button">' . $link . '</div>' );
 			return self::wrap_block( 'buttons', array(), '<div class="wp-block-buttons">' . $inner . '</div>' );
@@ -485,7 +536,7 @@ private static function label( $attrs, $content ) {
 		$type   = isset( $attrs['type'] ) ? sanitize_html_class( $attrs['type'], 'default' ) : 'default';
 		$colors = array( 'default' => '#777', 'primary' => '#337ab7', 'success' => '#5cb85c', 'info' => '#5bc0de', 'warning' => '#f0ad4e', 'danger' => '#d9534f' );
 		$bg     = isset( $colors[ $type ] ) ? $colors[ $type ] : '#777';
-		$inner  = self::process( $content, false );
+		$inner  = self::process( $content );
 		if ( self::inline_style() ) {
 			return '<span class="label label-' . $type . '" style="display:inline-block;padding:.2em .6em .3em;font-size:75%;font-weight:700;line-height:1;color:#fff;background-color:' . $bg . ';border-radius:.25em;white-space:nowrap;vertical-align:baseline">' . $inner . '</span>';
 		}
@@ -503,6 +554,13 @@ private static function icon( $attrs ) {
 			}
 		}
 		$fallback = '<i class="' . self::attr( $name ) . '" aria-hidden="true"></i>';
+		if ( ! $glyph && preg_match( '/(^|\s)icon-[a-z0-9-]+/', $name ) ) {
+			// Bootstrap 2 style icon-* classes: a PNG sprite styled by the plugin's
+			// shortcodes.css, which loads with the Bootstrap CSS (and the companion's).
+			self::$deps[]  = 'bootstrap-css';
+			self::$notes[] = sprintf( 'Icon "%s" uses the old icon-* sprite; its markup was kept and still needs the Bootstrap 3 CSS bundle (theme or companion).', $name );
+			return $fallback;
+		}
 		if ( ! self::inline_style() || ! $glyph ) {
 			self::$deps[] = 'glyphicons';
 			return $fallback;
@@ -527,25 +585,17 @@ private static function tooltip( $attrs, $content ) {
 
 	private static function collapse( $attrs, $content ) {
 		$group = isset( $attrs['id'] ) ? sanitize_html_class( $attrs['id'] ) : '';
-		// Children need the group name; pass it through a static so citem() sees it.
-		$inner = self::process_with_group( $content, $group );
+		$inner = self::process( $content );
 		if ( self::blocks() ) {
 			return trim( $inner );
 		}
 		return '<div class="bs-collapse"' . ( $group ? ' id="' . self::attr( $group ) . '"' : '' ) . '>' . $inner . '</div>';
 	}
 
-	private static $group_stack = array();
-
-	private static function process_with_group( $content, $group ) {
-		self::$group_stack[] = $group;
-		$out = self::process( $content, false );
-		array_pop( self::$group_stack );
-		return $out;
-	}
-
 	private static function citem( $attrs, $content, $unused ) {
-		$group = self::$group_stack ? end( self::$group_stack ) : ( isset( $attrs['parent'] ) ? sanitize_html_class( $attrs['parent'] ) : '' );
+		// Bootstrap made items exclusive only through data-parent (the `parent`
+		// attribute); without it each item toggled on its own, so no group name.
+		$group = isset( $attrs['parent'] ) ? sanitize_html_class( ltrim( trim( $attrs['parent'] ), '#' ) ) : '';
 		$id    = isset( $attrs['id'] ) ? sanitize_html_class( $attrs['id'] ) : '';
 		$title = isset( $attrs['title'] ) ? $attrs['title'] : 'Collapse title';
 		$open  = isset( $attrs['open'] ) && 'true' === $attrs['open'];
@@ -562,7 +612,7 @@ private static function details( $title, $content, $open, $id, $group ) {
 			if ( $group ) {
 				$block_attrs['name'] = $group;
 			}
-			$html = '<details class="wp-block-details"' . ( $group ? ' name="' . self::attr( $group ) . '"' : '' ) . ( $id ? ' id="' . self::attr( $id ) . '"' : '' ) . ( $open ? ' open' : '' ) . '><summary>' . $title_html . '</summary>' . self::inner_blocks( self::process( $content, false ) ) . '</details>';
+			$html = '<details class="wp-block-details"' . ( $group ? ' name="' . self::attr( $group ) . '"' : '' ) . ( $id ? ' id="' . self::attr( $id ) . '"' : '' ) . ( $open ? ' open' : '' ) . '><summary>' . $title_html . '</summary>' . self::inner_blocks( self::process( $content ) ) . '</details>';
 			return self::wrap_block( 'details', $block_attrs, $html );
 		}
 		return '<details' . ( $group ? ' name="' . self::attr( $group ) . '"' : '' ) . ( $id ? ' id="' . self::attr( $id ) . '"' : '' ) . ( $open ? ' open' : '' ) . '><summary>' . $title_html . '</summary>' . self::inner_html( $content ) . '</details>';
@@ -585,7 +635,7 @@ private static function tabs( $content ) {
 		self::$section_counter = 0;
 		// Strip the head: its tabs are now titles. Convert the panes.
 		$panes = preg_replace( '/' . get_shortcode_regex( array( 'bs_thead' ) ) . '/', '', $content );
-		$panes = self::process( $panes, false );
+		$panes = self::process( $panes );
 		self::$tab_titles = $previous;
 		if ( self::blocks() ) {
 			return trim( $panes );
diff --git a/specs/migration.spec.js b/specs/migration.spec.js
index 432ad57..1f86f3e 100644
--- a/specs/migration.spec.js
+++ b/specs/migration.spec.js
@@ -220,6 +220,13 @@ test.describe('Migration end to end', () => {
         await expectMigratedPageWorks(page, classic.link);
         await expect(page.locator('link#bs_bootstrap-css')).toHaveCount(0);
         await expect(page.locator('link#bs-legacy-bootstrap-css')).toHaveCount(companionInstalled ? 1 : 0);
+        await expect(page.locator('link#bs-legacy-shortcodes-css')).toHaveCount(companionInstalled ? 1 : 0);
+        if (companionInstalled) {
+            // shortcodes.css points its icon-* sprite at ../images/; the companion must ship it.
+            const css = await page.locator('link#bs-legacy-shortcodes-css').getAttribute('href');
+            const sprite = await page.request.get(new URL('../images/glyphicons-halflings.png', css).href);
+            expect(sprite.ok()).toBeTruthy();
+        }
         await page.goto(blocks.link);
         await expect(page.locator('.wp-block-columns .wp-block-column').first()).toContainText('Block left');
 
diff --git a/tests/phpunit/CompanionTest.php b/tests/phpunit/CompanionTest.php
index b288701..4c3745e 100644
--- a/tests/phpunit/CompanionTest.php
+++ b/tests/phpunit/CompanionTest.php
@@ -12,6 +12,9 @@ public function test_manifest_points_at_existing_files() {
 		$this->assertArrayHasKey( 'bootstrap-legacy-assets/js/bootstrap.js', $files );
 		$this->assertArrayHasKey( 'bootstrap-legacy-assets/js/init.js', $files );
 		$this->assertArrayHasKey( 'bootstrap-legacy-assets/fonts/glyphicons-halflings-regular.woff2', $files );
+		// The original loaded shortcodes.css with bootstrap.css; legacy icon-* sprites live there.
+		$this->assertArrayHasKey( 'bootstrap-legacy-assets/css/shortcodes.css', $files );
+		$this->assertArrayHasKey( 'bootstrap-legacy-assets/images/glyphicons-halflings.png', $files );
 		foreach ( $files as $src ) {
 			$this->assertFileExists( $src );
 		}
@@ -94,4 +97,46 @@ public function test_install_and_activate_puts_a_working_plugin_in_place() {
 			$wp_filesystem->delete( $dir, true );
 		}
 	}
+
+	public function test_companion_loads_shortcodes_css_with_bootstrap_css() {
+		require_once dirname( dirname( __DIR__ ) ) . '/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php';
+		update_option( 'bs_options', array( 'chk_default_options_grid' => '1' ) );
+		update_option( 'bs_legacy_assets', array( 'css' => '1' ) );
+		$GLOBALS['wp_styles'] = new WP_Styles();
+		( new BS_Legacy_Assets() )->enqueue();
+		$this->assertContains( 'bs-legacy-bootstrap', $GLOBALS['wp_styles']->queue );
+		$this->assertContains( 'bs-legacy-shortcodes', $GLOBALS['wp_styles']->queue );
+		delete_option( 'bs_options' );
+		delete_option( 'bs_legacy_assets' );
+	}
+
+	public function test_with_conditional_loading_the_companion_covers_pages_the_original_skips() {
+		require_once dirname( dirname( __DIR__ ) ) . '/companion/bootstrap-legacy-assets/bootstrap-legacy-assets.php';
+		update_option( 'bs_options', array_merge( BootstrapShortcodes::default_options(), array( 'chk_conditional_assets' => '1' ) ) );
+		update_option( 'bs_legacy_assets', array( 'css' => '1', 'js' => '1' ) );
+		$this->assertFalse( BS_Legacy_Assets::original_plugin_loads_assets() );
+
+		// A page without shortcodes: the original queues nothing, the companion loads.
+		$GLOBALS['wp_styles']  = new WP_Styles();
+		$GLOBALS['wp_scripts'] = new WP_Scripts();
+		( new BS_Legacy_Assets() )->enqueue();
+		$this->assertContains( 'bs-legacy-bootstrap', $GLOBALS['wp_styles']->queue );
+		$this->assertContains( 'bs-legacy-bootstrap', $GLOBALS['wp_scripts']->queue );
+
+		// The original's render-time fallback then stands down instead of loading Bootstrap twice.
+		$plugin = new BootstrapShortcodes();
+		$plugin->enqueue_assets();
+		$this->assertNotContains( 'bs_bootstrap', $GLOBALS['wp_styles']->queue );
+		$this->assertNotContains( 'bs_bootstrap', $GLOBALS['wp_scripts']->queue );
+
+		// A page where the original already queued its copy: the companion stays out.
+		$GLOBALS['wp_styles']  = new WP_Styles();
+		$GLOBALS['wp_scripts'] = new WP_Scripts();
+		( new BootstrapShortcodes() )->enqueue_assets();
+		( new BS_Legacy_Assets() )->enqueue();
+		$this->assertNotContains( 'bs-legacy-bootstrap', $GLOBALS['wp_styles']->queue );
+		$this->assertNotContains( 'bs-legacy-bootstrap', $GLOBALS['wp_scripts']->queue );
+		delete_option( 'bs_options' );
+		delete_option( 'bs_legacy_assets' );
+	}
 }
diff --git a/tests/phpunit/MigrationApplyTest.php b/tests/phpunit/MigrationApplyTest.php
index 23ba82d..57440a3 100644
--- a/tests/phpunit/MigrationApplyTest.php
+++ b/tests/phpunit/MigrationApplyTest.php
@@ -175,4 +175,14 @@ public function test_users_whose_markup_would_be_filtered_are_refused_and_nothin
 		$this->assertSame( $original, get_post( $id )->post_content );
 		$this->assertFalse( BS_Migration::is_migrated( $id ) );
 	}
+
+	public function test_migrated_list_includes_every_type_and_status_the_scan_covers() {
+		$block = self::factory()->post->create( array( 'post_type' => 'wp_block', 'post_content' => '[bs_well]reusable[/bs_well]' ) );
+		$trash = self::factory()->post->create( array( 'post_status' => 'trash', 'post_content' => '[bs_well]binned[/bs_well]' ) );
+		$this->assertIsArray( BS_Migration::apply( $block, $this->opts ) );
+		$this->assertIsArray( BS_Migration::apply( $trash, $this->opts ) );
+		$listed = BS_Migration::migrated_posts();
+		$this->assertContains( $block, $listed );
+		$this->assertContains( $trash, $listed );
+	}
 }
diff --git a/tests/phpunit/MigratorConvertTest.php b/tests/phpunit/MigratorConvertTest.php
index b7ef55f..ae8582f 100644
--- a/tests/phpunit/MigratorConvertTest.php
+++ b/tests/phpunit/MigratorConvertTest.php
@@ -280,4 +280,83 @@ public function test_shortcodes_inside_nested_blocks_are_reached() {
 		$this->assertStringNotContainsString( 'wp:shortcode', $r['content'] );
 		$this->assertSame( 'core/paragraph', parse_blocks( $r['content'] )[0]['innerBlocks'][0]['innerBlocks'][0]['blockName'] );
 	}
+
+	/* ---- fixes from the pre-merge review ---------------------------------- */
+
+	public function test_block_level_component_inside_a_paragraph_is_left_in_place_and_listed() {
+		$doc = "<!-- wp:paragraph -->\n<p>See [bs_well]x[/bs_well] and [bs_label]ok[/bs_label]</p>\n<!-- /wp:paragraph -->";
+		$r   = BS_Migrator::convert( $doc, array( 'mode' => 'auto' ) );
+		$this->assertStringContainsString( '<p>See [bs_well]x[/bs_well] and <span class="label label-default"', $r['content'] );
+		$this->assertStringNotContainsString( '<div', $r['content'] );
+		$this->assertSame( 1, $r['converted'] );
+		$this->assertSame( array( array( 'tag' => 'bs_well', 'reason' => 'inline-context' ) ), array_map( function ( $s ) { return array( 'tag' => $s['tag'], 'reason' => $s['reason'] ); }, $r['skipped'] ) );
+	}
+
+	public function test_block_level_component_inside_a_heading_is_left_in_place() {
+		$doc = "<!-- wp:heading -->\n<h2 class=\"wp-block-heading\">[bs_lead]Big[/bs_lead]</h2>\n<!-- /wp:heading -->";
+		$r   = BS_Migrator::convert( $doc, array( 'mode' => 'auto' ) );
+		$this->assertSame( $doc, $r['content'] );
+		$this->assertSame( 'inline-context', $r['skipped'][0]['reason'] );
+	}
+
+	public function test_html_mode_on_a_block_document_never_puts_a_div_inside_a_paragraph() {
+		$doc = "<!-- wp:paragraph -->\n<p>[bs_well]x[/bs_well]</p>\n<!-- /wp:paragraph -->\n\n<!-- wp:paragraph -->\n<p>Text [bs_well]y[/bs_well]</p>\n<!-- /wp:paragraph -->";
+		$r   = $this->html( $doc );
+		$this->assertStringNotContainsString( '<p><div', $r['content'] );
+		$this->assertStringNotContainsString( 'Text <div', $r['content'] );
+		$this->assertStringContainsString( '<div class="well" style="', $r['content'] );
+		$this->assertStringContainsString( 'Text [bs_well]y[/bs_well]', $r['content'] );
+		$this->assertSame( 1, $r['converted'] );
+	}
+
+	public function test_skipped_items_in_a_block_are_reported_once() {
+		$doc = "<!-- wp:paragraph -->\n<p>Broken [bs_well]never closed</p>\n<!-- /wp:paragraph -->";
+		$r   = BS_Migrator::convert( $doc, array( 'mode' => 'auto' ) );
+		$this->assertCount( 1, $r['skipped'] );
+	}
+
+	public function test_alert_as_group_block_carries_no_attribute_the_block_cannot_save() {
+		$r = $this->blocks( '[bs_notification type="info"]Msg[/bs_notification]', 'classes' );
+		$this->assertStringContainsString( '<div class="wp-block-group alert alert-info">', $r['content'] );
+		$this->assertStringNotContainsString( 'role=', $r['content'] );
+		$this->assertContains( 'The alert role is not kept: the Group block cannot store it. The message and colours are kept.', $r['notes'] );
+		// Inline styling keeps it: a Custom HTML block saves whatever it holds.
+		$this->assertStringContainsString( 'role="alert"', $this->blocks( '[bs_notification type="info"]Msg[/bs_notification]' )['content'] );
+	}
+
+	public function test_a_column_outside_a_row_gets_a_columns_parent() {
+		$r      = $this->blocks( '[bs_col class="col-sm-6"]Hello[/bs_col]' );
+		$blocks = array_values( array_filter( parse_blocks( $r['content'] ), function ( $b ) { return null !== $b['blockName']; } ) );
+		$this->assertSame( 'core/columns', $blocks[0]['blockName'] );
+		$this->assertSame( 'core/column', $blocks[0]['innerBlocks'][0]['blockName'] );
+		$this->assertSame( $r['content'], serialize_blocks( parse_blocks( $r['content'] ) ) );
+		// Columns inside a row are not double-wrapped.
+		$row = $this->blocks( '[bs_row][bs_col class="col-sm-6"]a[/bs_col][/bs_row]' );
+		$this->assertSame( 1, substr_count( $row['content'], '<!-- wp:columns' ) );
+	}
+
+	public function test_row_with_a_custom_class_keeps_exactly_that_class_in_html_mode() {
+		$this->assertSame( '<div class="container">x</div>', $this->html( '[bs_row class="container"]x[/bs_row]' )['content'] );
+		$this->assertSame( '<div class="row">x</div>', $this->html( '[bs_row]x[/bs_row]' )['content'] );
+	}
+
+	public function test_collapse_items_without_a_parent_stay_independent() {
+		$c = $this->html( '[bs_collapse id="g"][bs_citem id="a" title="A" open="true"]1[/bs_citem][bs_citem id="b" title="B" open="true"]2[/bs_citem][/bs_collapse]' )['content'];
+		$this->assertStringNotContainsString( 'name=', $c );
+		$this->assertSame( 2, substr_count( $c, ' open>' ) );
+	}
+
+	public function test_standalone_button_style_that_the_block_drops_is_noted() {
+		$r = $this->blocks( '[bs_button type="danger" size="lg" value="Buy" href="/buy"]' );
+		$this->assertStringContainsString( '<!-- wp:buttons -->', $r['content'] );
+		$this->assertContains( 'Button style "btn-danger btn-lg" is not carried over: the Button block uses your theme\'s button style. Restyle it in the editor if the colour or size mattered.', $r['notes'] );
+		$this->assertSame( array(), $this->blocks( '[bs_button value="Plain" href="/p"]' )['notes'] );
+	}
+
+	public function test_legacy_sprite_icons_depend_on_the_bootstrap_css_bundle() {
+		$r = $this->html( '[bs_icon name="icon-star"]' );
+		$this->assertSame( '<i class="icon-star" aria-hidden="true"></i>', $r['content'] );
+		$this->assertSame( array( 'bootstrap-css' ), $r['dependencies'] );
+		$this->assertNotEmpty( $r['notes'] );
+	}
 }

From 314dbe2b59fe3331d99ae5a6372246488ba3c958 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 17:51:23 -0700
Subject: [PATCH 07/10] fix(review): address CodeRabbit's review of the
 pre-merge fixes

- Refuse before writing when kses would alter the converted markup (users
  without unfiltered_html), instead of writing and then restoring: no
  revision, no modified date change. Rollback does the same check, so a
  restore can no longer strip markup the original held (an embed, a
  script) that the current user may not save. Both writes are verified
  afterwards; if any other filter changed them, the stored original is
  kept and the error says where it is. The message no longer promises
  that an administrator can run it (DISALLOW_UNFILTERED_HTML).
- Details output matches what the installed WordPress can save: the
  block's `name` attribute exists only from 6.8, so on 6.3-6.7 grouping is
  left out and noted (the editor would flag the block as invalid); below
  6.3, where there is no Details block, each item is a Custom HTML block
  holding a <details>. Checked against the registered block type, not the
  version string.
- Playwright restores the Classic Editor settings in a finally block, so a
  failed editor check cannot break the TinyMCE specs that follow.
- docs/migration.md: list items need the shortcode moved out of the list;
  companion settings are copied only when installed from the migration
  page; Details version notes.
- docs/reporting-receiver.md: derived count/stats keys get TTLs; the KV
  ingestion counter is documented as approximate, with the account's
  1,000 writes/day as the hard ceiling and a Durable Object counter as the
  exact option.

Verified: PHPUnit 173/173 on WP 7.1.4 / PHP 8.3, 173 (1 skipped: the
6.8+ name assertion) on WP 6.4.7 / PHP 7.4; Playwright 20/20.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/migration.md                     | 13 +++++---
 docs/reporting-receiver.md            |  6 ++--
 inc/class-bs-migration.php            | 41 ++++++++++++++++++++---
 inc/class-bs-migrator.php             | 12 +++++++
 specs/migration.spec.js               | 48 +++++++++++++++------------
 tests/phpunit/MigrationApplyTest.php  | 41 ++++++++++++++++++++++-
 tests/phpunit/MigratorConvertTest.php | 46 +++++++++++++++++++++++++
 7 files changed, 172 insertions(+), 35 deletions(-)

diff --git a/docs/migration.md b/docs/migration.md
index 54cf51d..f4d36f1 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -28,8 +28,9 @@ Then deactivate the plugin, check the pages the report listed, and delete it.
   (an unclosed `[bs_well]`), escaped `[[bs_x]]` examples, `bs_` tags the plugin
   never registered (typos, other plugins), and block-level components (row, column,
   well, alert, lead, collapse, tabs) written *inside* a paragraph, heading or list
-  item of a block post, where a `<div>` would break the block; put the shortcode on
-  its own line and migrate again. Nothing in a post is dropped silently;
+  item of a block post, where a `<div>` would break the block. For a paragraph,
+  put the shortcode in its own paragraph (or a Shortcode block) and migrate again;
+  inside a list, move it out of the list block or convert that list by hand. Nothing in a post is dropped silently;
   every approximation is reported as a note in the preview and stored with the post.
 - Never runs on activation, update or a schedule. Needs `manage_options`, a nonce
   and a button press (or `edit_post` for each post).
@@ -65,7 +66,7 @@ behaviourally different; "Needs" what the output still depends on.
 | `bs_label` | inline `<span class="label label-x">` with inline colours | same | – | text, type colour | – | classes variant needs Bootstrap CSS |
 | `bs_icon` | inline SVG built from the bundled Glyphicons font (`<svg class="bs-icon bs-icon-star">`, `currentColor`, 1em) | same | – | the glyph, size relative to text, extra classes | none visible; unknown glyph names keep `<i class="glyphicon ...">` and are noted; old `icon-*` sprite names keep their `<i>` and are noted | classes variant, or unknown glyphs, need the Glyphicons font (Bootstrap CSS); `icon-*` names need the plugin's `shortcodes.css` sprite, which the companion ships |
 | `bs_tooltip` | `<span class="bs-tooltip" title="...">` (dotted underline when self-contained) | same | – | the text and the tooltip text (they were always identical) | native browser tooltip: no placement/trigger, none on touch devices; noted | – |
-| `bs_collapse` + `bs_citem` | one Details block per item; items with a `parent` (what the editor button writes) share `name` = that parent so one opens at a time (WP 6.6+; ignored earlier), items without one stay independent, as Bootstrap's `data-parent` worked; `open` for `open="true"`, element `id` kept so `#anchor` links work | `<div class="bs-collapse"><details name><summary>` | 6.3 (Details block); HTML works everywhere | titles, content, initial open state, one-at-a-time behaviour, anchor ids | Bootstrap panel chrome gone (theme styles the Details block); keyboard: native `<summary>` | – |
+| `bs_collapse` + `bs_citem` | one Details block per item; items with a `parent` (what the editor button writes) share `name` = that parent so one opens at a time (the block's `name` needs WP 6.8+; on 6.3 to 6.7 it is left out and the lost grouping is noted; below 6.3 each item is a Custom HTML block holding a `<details>`), items without one stay independent, as Bootstrap's `data-parent` worked; `open` for `open="true"`, element `id` kept so `#anchor` links work | `<div class="bs-collapse"><details name><summary>` | 6.3 (Details block); HTML works everywhere | titles, content, initial open state, one-at-a-time behaviour, anchor ids | Bootstrap panel chrome gone (theme styles the Details block); keyboard: native `<summary>` | – |
 | `bs_tabs` + `bs_thead` + `bs_tab` + `bs_dropdown` + `bs_tcontents` + `bs_tcontent` | one Details block per pane, titled by the matching tab (`href="#id"` ↔ `id`), active pane open; dropdown tabs flattened as "Dropdown: Tab" | `<div class="bs-tabs"><details>` per pane | 6.3 / any | every pane's content, titles, order, initial pane, anchor ids | **tabs become stacked collapsible sections** (semantic alternative, noted). On WordPress 7.1+ the editor's Tabs block can be built from them by hand if tabs are wanted back | – |
 
 Attributes the plugin never used (anything not in the table above, such as a
@@ -97,8 +98,10 @@ repository; the migration page builds its zip from this plugin's own files). It:
   Bootstrap Shortcodes' conditional loading on, the companion covers the pages
   without shortcodes and Bootstrap Shortcodes covers the rest;
 - is installed only from the migration page after ticking an explicit statement, or
-  by uploading the downloaded zip yourself. Its settings start as copies of this
-  plugin's CSS/JS settings.
+  by uploading the downloaded zip yourself. Installed from the migration page, its
+  settings start as copies of this plugin's CSS/JS settings; uploaded by hand, it
+  starts with its own defaults (CSS, JS and tooltips on), so check Settings > Legacy
+  Bootstrap.
 
 Be honest with yourself about what that means: the site no longer depends on
 Bootstrap Shortcodes, but it still depends on **end-of-life Bootstrap 3** (see
diff --git a/docs/reporting-receiver.md b/docs/reporting-receiver.md
index 7c6ca80..afc58a9 100644
--- a/docs/reporting-receiver.md
+++ b/docs/reporting-receiver.md
@@ -50,6 +50,8 @@ Cloudflare's own request logs exist and are retained per their policy.
 - **Stored:** the payload, the server-generated id, and the received date (day).
 - **Not stored:** IP, user agent, headers, referrer.
 - **Retention:** 12 months (KV TTL), then deleted; or sooner on request quoting the id.
+  The derived keys hold counts only and expire too: `count:YYYY-MM-DD` after 2 days,
+  `stats:YYYY-MM-DD` after 12 months (both set with a per-key TTL on write).
 - **Access:** the maintainer only; used to decide which components the migration
   tools must cover; aggregate counts may be published in the repository.
 - **Deletion:** the id shown after sending is the only key; an email or GitHub
@@ -65,10 +67,10 @@ Cloudflare's own request logs exist and are retained per their policy.
 | Per-IP rate limit | Workers Rate Limiting binding with a supported period (60 s; e.g. 3 requests / 60 s per IP). Counters are approximate and per Cloudflare location, so this is a brake, not a guarantee; one WAF rate-limiting rule (free plan allows one) backs it up at the edge | no cost |
 | Kill switch | KV key `paused`; checked first; set from the dashboard or `wrangler kv` | one KV read per request (100,000/day free) |
 | Payload cap | reject bodies > 2 KB (a full payload with every component is about 1 KB), non-JSON, `schema !== 1`, unknown keys, non-integer counts, counts > 10^7 | Worker CPU only |
-| Ingestion cap | at most 300 accepted records per UTC day (a KV counter `count:YYYY-MM-DD`); beyond that reply `429` without storing | KV Free writes 1,000/day |
+| Ingestion cap | about 300 accepted records per UTC day, read from a KV counter `count:YYYY-MM-DD` (2-day TTL); beyond that reply `429` without storing. KV is eventually consistent and allows one write per key per second, so under a concurrent burst this cap is **approximate** (it can overshoot, and counter writes can fail). The hard ceiling is the account's 1,000 KV writes/day, which bounds storage whatever the counter says. If an exact cap is wanted, use a Durable Object counter (SQLite-backed Durable Objects are on the Free plan), decided when the receiver is built | KV Free writes 1,000/day |
 | Method/path allowlist | `POST /v1/summary` (public) and `GET /v1/stats` (bearer secret, see Monitoring); everything else 404 with no body | – |
 | No egress | the Worker calls nothing (no email, no third parties) | – |
-| Storage growth | one KV value per record, TTL 12 months, key = random id; a daily cron summarises counts into one `stats:YYYY-MM-DD` key. Worst case 300 × 2 KB × 365 ≈ 220 MB, inside the 1 GB KV Free limit | KV Free 1 GB |
+| Storage growth | one KV value per record, TTL 12 months, key = random id; a daily cron summarises counts into one `stats:YYYY-MM-DD` key. Worst case, using the hard 1,000 writes/day rather than the soft 300: 1,000 × 2 KB × 365 ≈ 730 MB, inside the 1 GB KV Free limit | KV Free 1 GB |
 | Monitoring | `GET /v1/stats` behind a bearer secret (wrangler secret) returning per-day counts; Cloudflare dashboard Workers metrics; `wrangler tail` for live logs; Cloudflare Notifications for Worker error rate | no cost |
 | Upgrade path | if the trial outgrows Free, move to Workers Paid only after adding a hard spend ceiling in the dashboard and re-reviewing this table | – |
 
diff --git a/inc/class-bs-migration.php b/inc/class-bs-migration.php
index 3b082bc..88ef2e4 100644
--- a/inc/class-bs-migration.php
+++ b/inc/class-bs-migration.php
@@ -57,6 +57,13 @@ public static function apply( $post_id, $options, $expected_modified_gmt = null
 		if ( 0 === $result['converted'] ) {
 			return new WP_Error( 'bs_nothing', $result['skipped'] ? __( 'Nothing could be converted automatically; see the skipped list.', 'bsshortcodes' ) : __( 'No shortcodes to convert in this post.', 'bsshortcodes' ) );
 		}
+		// Users without unfiltered_html have their content passed through kses on
+		// save, which strips the inline SVG icons (and, before WordPress 6.9, the
+		// <details name> grouping). The preview shows the unfiltered markup, so
+		// refuse before writing anything rather than save a different post.
+		if ( self::would_be_filtered( $preview['converted'] ) ) {
+			return self::filtered_error();
+		}
 		$backup_created = false;
 		if ( ! $preview['already'] ) {
 			// add_post_meta() and wp_update_post() both wp_unslash() their input, so
@@ -79,17 +86,20 @@ public static function apply( $post_id, $options, $expected_modified_gmt = null
 			}
 			return $updated;
 		}
-		// Users without unfiltered_html get their content passed through kses on
-		// save, which can strip the inline SVG icons or the <details name> grouping.
-		// The preview showed the unfiltered markup, so never leave a silently
-		// different version behind: put the original back and say why.
+		// Backstop for any other content_save_pre filter: never leave a silently
+		// different version behind. Put the original back, and keep the stored
+		// copy unless the restore is verified exact.
 		$saved = get_post_field( 'post_content', $post_id, 'raw' );
 		if ( $saved !== $preview['converted'] ) {
 			wp_update_post( wp_slash( array( 'ID' => $post_id, 'post_content' => $preview['original'] ) ) );
+			if ( get_post_field( 'post_content', $post_id, 'raw' ) !== $preview['original'] ) {
+				// The stored original (created above, or from an earlier migration) stays.
+				return new WP_Error( 'bs_restore_failed', __( 'A filter on this site changed the post on save and the original could not be written back exactly. The original is kept in the custom field _bs_migration_original; roll back from the Migrated posts list, or restore it from the revisions.', 'bsshortcodes' ) );
+			}
 			if ( $backup_created ) {
 				delete_post_meta( $post_id, self::META_ORIGINAL );
 			}
-			return new WP_Error( 'bs_filtered', __( 'WordPress filtered the converted markup on save because your account cannot publish unfiltered HTML, so the post would not match the preview. Nothing was changed; ask an administrator with that capability to run the migration.', 'bsshortcodes' ) );
+			return new WP_Error( 'bs_filtered', __( 'A filter on this site changed the converted markup on save, so the post would not match the preview. The original was put back.', 'bsshortcodes' ) );
 		}
 		update_post_meta( $post_id, self::META_RESULT, array(
 			'converted'    => $result['converted'],
@@ -122,15 +132,36 @@ public static function rollback( $post_id ) {
 		if ( ! is_array( $backup ) || ! isset( $backup['content'] ) ) {
 			return new WP_Error( 'bs_no_backup', __( 'No stored original for this post.', 'bsshortcodes' ) );
 		}
+		// Restoring as a user whose HTML is filtered would strip whatever the
+		// original held that kses disallows (an embed, a script): refuse instead.
+		if ( self::would_be_filtered( $backup['content'] ) ) {
+			return self::filtered_error();
+		}
 		$updated = wp_update_post( wp_slash( array( 'ID' => $post->ID, 'post_content' => $backup['content'] ) ), true );
 		if ( is_wp_error( $updated ) ) {
 			return $updated;
 		}
+		if ( get_post_field( 'post_content', $post->ID, 'raw' ) !== $backup['content'] ) {
+			// Some other filter changed it: keep the stored original so nothing is lost.
+			return new WP_Error( 'bs_restore_failed', __( 'A filter on this site changed the content on save, so the original was not restored exactly. The stored original is kept; restore it from the revisions or the custom field _bs_migration_original.', 'bsshortcodes' ) );
+		}
 		delete_post_meta( $post->ID, self::META_ORIGINAL );
 		delete_post_meta( $post->ID, self::META_RESULT );
 		return true;
 	}
 
+	/** Would saving $content as the current user change it? (kses runs for users without unfiltered_html.) */
+	private static function would_be_filtered( $content ) {
+		if ( false === has_filter( 'content_save_pre', 'wp_filter_post_kses' ) ) {
+			return false;
+		}
+		return wp_unslash( wp_filter_post_kses( wp_slash( $content ) ) ) !== $content;
+	}
+
+	private static function filtered_error() {
+		return new WP_Error( 'bs_filtered', __( 'Your account cannot save this markup unchanged: WordPress filters HTML for users without the "unfiltered_html" capability, so the post would not match the preview. Nothing was changed. Run this as a user who has that capability; if no account on this site has it, this post cannot be converted automatically.', 'bsshortcodes' ) );
+	}
+
 	/**
 	 * Apply to several posts. Each post is read fresh and converted from its
 	 * current content, so a post edited after the scan is converted as it is
diff --git a/inc/class-bs-migrator.php b/inc/class-bs-migrator.php
index a3406ff..347ab30 100644
--- a/inc/class-bs-migrator.php
+++ b/inc/class-bs-migrator.php
@@ -605,6 +605,18 @@ private static function citem( $attrs, $content, $unused ) {
 	private static function details( $title, $content, $open, $id, $group ) {
 		$title_html = esc_html( wp_strip_all_tags( $title ) );
 		if ( self::blocks() ) {
+			// Match what this WordPress's Details block can save, or the editor
+			// flags the block as invalid: no block before 6.3, no `name` before 6.8.
+			$type = WP_Block_Type_Registry::get_instance()->get_registered( 'core/details' );
+			if ( ! $type ) {
+				self::$notes[] = 'Collapsible sections are saved as Custom HTML blocks: this WordPress version has no Details block (it arrived in 6.3).';
+				$html = '<details' . ( $group ? ' name="' . self::attr( $group ) . '"' : '' ) . ( $id ? ' id="' . self::attr( $id ) . '"' : '' ) . ( $open ? ' open' : '' ) . '><summary>' . $title_html . '</summary>' . self::bake_paragraphs( self::process( $content ) ) . '</details>';
+				return self::wrap_block( 'html', array(), $html );
+			}
+			if ( $group && ! isset( $type->attributes['name'] ) ) {
+				self::$notes[] = 'Collapse items no longer close each other when one opens: the Details block\'s grouping needs WordPress 6.8 or later. Re-migrate after updating WordPress to keep that behaviour.';
+				$group = '';
+			}
 			$block_attrs = array();
 			if ( $open ) {
 				$block_attrs['showContent'] = true;
diff --git a/specs/migration.spec.js b/specs/migration.spec.js
index 1f86f3e..26a6f66 100644
--- a/specs/migration.spec.js
+++ b/specs/migration.spec.js
@@ -163,29 +163,33 @@ test.describe('Migration end to end', () => {
         await page.locator('input[name="classic-editor-replace"][value="block"]').check();
         await page.locator('input[name="classic-editor-allow-users"][value="allow"]').check();
         await page.locator('#submit').click();
-        for (const id of [blocks.id, classic.id]) {
-            // classic-editor__forget is what the plugin's own "Edit (Block editor)" link
-            // uses; without it a post with no blocks opens in TinyMCE.
-            await admin.visitAdminPage('post.php', `post=${id}&action=edit&classic-editor__forget`);
-            // The block editor boots slowly on CI runners; wait for its canvas, not a heading.
-            await page.locator('iframe[name="editor-canvas"], .block-editor-writing-flow').first().waitFor({ timeout: 60000 });
-            // The block list lives in an iframe only when every block supports it; a
-            // Classic block (HTML-mode output) keeps the editor inline. Look in both.
-            const iframed = (await page.locator('iframe[name="editor-canvas"]').count()) > 0;
-            const root = iframed ? page.frameLocator('iframe[name="editor-canvas"]') : page;
-            await expect(root.locator('.is-root-container')).toBeVisible();
-            await expect(root.locator('.wp-block').first()).toBeVisible();
-            await expect(root.locator('.block-editor-warning')).toHaveCount(0);
-            await expect(page.locator('.block-editor-warning')).toHaveCount(0);
-            await expect(root.locator('body')).not.toContainText('unexpected or invalid content');
+        try {
+            for (const id of [blocks.id, classic.id]) {
+                // classic-editor__forget is what the plugin's own "Edit (Block editor)" link
+                // uses; without it a post with no blocks opens in TinyMCE.
+                await admin.visitAdminPage('post.php', `post=${id}&action=edit&classic-editor__forget`);
+                // The block editor boots slowly on CI runners; wait for its canvas, not a heading.
+                await page.locator('iframe[name="editor-canvas"], .block-editor-writing-flow').first().waitFor({ timeout: 60000 });
+                // The block list lives in an iframe only when every block supports it; a
+                // Classic block (HTML-mode output) keeps the editor inline. Look in both.
+                const iframed = (await page.locator('iframe[name="editor-canvas"]').count()) > 0;
+                const root = iframed ? page.frameLocator('iframe[name="editor-canvas"]') : page;
+                await expect(root.locator('.is-root-container')).toBeVisible();
+                await expect(root.locator('.wp-block').first()).toBeVisible();
+                await expect(root.locator('.block-editor-warning')).toHaveCount(0);
+                await expect(page.locator('.block-editor-warning')).toHaveCount(0);
+                await expect(root.locator('body')).not.toContainText('unexpected or invalid content');
+            }
+        } finally {
+            // Put the Classic Editor plugin back exactly as the editor specs expect,
+            // even when a check above failed: classic by default and no per-user
+            // switching (otherwise this user's last-used editor, now "block", would
+            // win on post-new.php).
+            await admin.visitAdminPage('options-writing.php');
+            await page.locator('input[name="classic-editor-replace"][value="classic"]').check();
+            await page.locator('input[name="classic-editor-allow-users"][value="disallow"]').check();
+            await page.locator('#submit').click();
         }
-        // Put the Classic Editor plugin back exactly as the editor specs expect:
-        // classic by default and no per-user switching (otherwise this user's
-        // last-used editor, now "block", would win on post-new.php).
-        await admin.visitAdminPage('options-writing.php');
-        await page.locator('input[name="classic-editor-replace"][value="classic"]').check();
-        await page.locator('input[name="classic-editor-allow-users"][value="disallow"]').check();
-        await page.locator('#submit').click();
         await admin.visitAdminPage(TOOLS.path, TOOLS.query);
 
         // Hand off the assets: consent is required, then install + activate.
diff --git a/tests/phpunit/MigrationApplyTest.php b/tests/phpunit/MigrationApplyTest.php
index 57440a3..0648b20 100644
--- a/tests/phpunit/MigrationApplyTest.php
+++ b/tests/phpunit/MigrationApplyTest.php
@@ -138,7 +138,10 @@ public function test_migrated_content_renders_without_the_shortcode_handlers() {
 		$rendered = apply_filters( 'the_content', get_post( $id )->post_content );
 		$shortcode_tags = $saved;
 
-		$this->assertMatchesRegularExpression( '#<details class="wp-block-details[^"]*" name="g" id="a"><summary>Q</summary>#', $rendered );
+		// The Details block stores `name` from WordPress 6.8; earlier the grouping is left out (and noted).
+		$type = WP_Block_Type_Registry::get_instance()->get_registered( 'core/details' );
+		$name = isset( $type->attributes['name'] ) ? ' name="g"' : '';
+		$this->assertMatchesRegularExpression( '#<details class="wp-block-details[^"]*"' . $name . ' id="a"><summary>Q</summary>#', $rendered );
 		$this->assertStringContainsString( '<svg class="bs-icon bs-icon-ok"', $rendered );
 		$this->assertStringNotContainsString( '[bs_', $rendered );
 	}
@@ -185,4 +188,40 @@ public function test_migrated_list_includes_every_type_and_status_the_scan_cover
 		$this->assertContains( $block, $listed );
 		$this->assertContains( $trash, $listed );
 	}
+
+	public function test_a_filtered_migration_writes_nothing_at_all() {
+		$author   = self::factory()->user->create( array( 'role' => 'author' ) );
+		$original = 'Done [bs_icon name="glyphicon glyphicon-ok"]';
+		$id       = self::factory()->post->create( array( 'post_content' => $original, 'post_author' => $author ) );
+		$before   = get_post( $id );
+		$revs     = count( wp_get_post_revisions( $id ) );
+		wp_set_current_user( $author );
+
+		$r = BS_Migration::apply( $id, array( 'mode' => 'html', 'style' => 'inline' ) );
+
+		$this->assertSame( 'bs_filtered', $r->get_error_code() );
+		$this->assertStringNotContainsString( 'administrator', $r->get_error_message() );
+		$this->assertSame( $revs, count( wp_get_post_revisions( $id ) ) );
+		$this->assertSame( $before->post_modified_gmt, get_post( $id )->post_modified_gmt );
+	}
+
+	public function test_rollback_refuses_rather_than_strip_markup_the_user_cannot_save() {
+		$author   = self::factory()->user->create( array( 'role' => 'author' ) );
+		$original = "<iframe src=\"https://video.test/embed/1\"></iframe>\n\n[bs_well]x[/bs_well]";
+		$id       = self::factory()->post->create( array( 'post_content' => $original, 'post_author' => $author ) );
+		$this->assertIsArray( BS_Migration::apply( $id, $this->opts ) ); // as the administrator
+		$migrated = get_post( $id )->post_content;
+
+		wp_set_current_user( $author );
+		$r = BS_Migration::rollback( $id );
+
+		$this->assertWPError( $r );
+		$this->assertSame( 'bs_filtered', $r->get_error_code() );
+		$this->assertSame( $migrated, get_post( $id )->post_content );
+		$this->assertTrue( BS_Migration::is_migrated( $id ) );
+
+		wp_set_current_user( $this->admin );
+		$this->assertTrue( BS_Migration::rollback( $id ) );
+		$this->assertSame( $original, get_post( $id )->post_content );
+	}
 }
diff --git a/tests/phpunit/MigratorConvertTest.php b/tests/phpunit/MigratorConvertTest.php
index ae8582f..fa36621 100644
--- a/tests/phpunit/MigratorConvertTest.php
+++ b/tests/phpunit/MigratorConvertTest.php
@@ -180,7 +180,33 @@ public function test_tooltip_becomes_a_native_title() {
 
 	/* ---- collapse and tabs ------------------------------------------------- */
 
+	/** Run $fn with core/details registered with $attributes (null: not registered), as on older WordPress. */
+	private function with_details_block( $attributes, $fn ) {
+		$registry = WP_Block_Type_Registry::get_instance();
+		$original = $registry->get_registered( 'core/details' );
+		if ( $original ) {
+			$registry->unregister( 'core/details' );
+		}
+		if ( null !== $attributes ) {
+			$registry->register( 'core/details', array( 'attributes' => $attributes ) );
+		}
+		try {
+			return $fn();
+		} finally {
+			if ( $registry->is_registered( 'core/details' ) ) {
+				$registry->unregister( 'core/details' );
+			}
+			if ( $original ) {
+				$registry->register( $original );
+			}
+		}
+	}
+
 	public function test_collapse_becomes_details_blocks_sharing_a_name() {
+		$type = WP_Block_Type_Registry::get_instance()->get_registered( 'core/details' );
+		if ( ! $type || ! isset( $type->attributes['name'] ) ) {
+			$this->markTestSkipped( 'this WordPress has no Details name attribute (6.8+); covered by the version tests below' );
+		}
 		$r = $this->blocks( '[bs_collapse id="faq"][bs_citem id="q1" parent="faq" title="First?"]A1[/bs_citem][bs_citem id="q2" parent="faq" title="Second?" open="true"]A2[/bs_citem][/bs_collapse]' );
 		$c = $r['content'];
 		$this->assertStringContainsString( '<!-- wp:details {"name":"faq"} -->' . "\n" . '<details class="wp-block-details" name="faq" id="q1"><summary>First?</summary>', $c );
@@ -359,4 +385,24 @@ public function test_legacy_sprite_icons_depend_on_the_bootstrap_css_bundle() {
 		$this->assertSame( array( 'bootstrap-css' ), $r['dependencies'] );
 		$this->assertNotEmpty( $r['notes'] );
 	}
+
+	public function test_details_group_name_is_left_out_before_wordpress_6_8() {
+		$r = $this->with_details_block( array( 'showContent' => array( 'type' => 'boolean' ), 'summary' => array( 'type' => 'string' ) ), function () {
+			return $this->blocks( '[bs_collapse id="faq"][bs_citem id="q1" parent="faq" title="First?"]A1[/bs_citem][/bs_collapse]' );
+		} );
+		$this->assertStringContainsString( '<!-- wp:details -->' . "\n" . '<details class="wp-block-details" id="q1"><summary>First?</summary>', $r['content'] );
+		$this->assertStringNotContainsString( 'name', $r['content'] );
+		$this->assertContains( 'Collapse items no longer close each other when one opens: the Details block\'s grouping needs WordPress 6.8 or later. Re-migrate after updating WordPress to keep that behaviour.', $r['notes'] );
+	}
+
+	public function test_details_become_custom_html_where_there_is_no_details_block() {
+		$r = $this->with_details_block( null, function () {
+			return $this->blocks( '[bs_collapse id="faq"][bs_citem id="q1" parent="faq" title="First?" open="true"]A1[/bs_citem][/bs_collapse]' );
+		} );
+		$blocks = array_values( array_filter( parse_blocks( $r['content'] ), function ( $b ) { return null !== $b['blockName']; } ) );
+		$this->assertSame( array( 'core/html' ), wp_list_pluck( $blocks, 'blockName' ) );
+		$this->assertStringContainsString( '<details name="faq" id="q1" open><summary>First?</summary><p>A1</p>', $r['content'] );
+		$this->assertStringNotContainsString( 'wp:details', $r['content'] );
+		$this->assertNotEmpty( preg_grep( '/no Details block/', $r['notes'] ) );
+	}
 }

From cc743d2a4ae5a0f815768f0fddafc98a991b02a1 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 20:38:47 -0700
Subject: [PATCH 08/10] docs(receiver): note the KV kill switch's propagation
 delay

CodeRabbit's nitpick on the first review: a paused flag in KV can take
up to about 60 seconds to reach other locations, so say so and name the
immediate stop (disable the route or delete the Worker).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/reporting-receiver.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reporting-receiver.md b/docs/reporting-receiver.md
index afc58a9..653a597 100644
--- a/docs/reporting-receiver.md
+++ b/docs/reporting-receiver.md
@@ -65,7 +65,7 @@ Cloudflare's own request logs exist and are retained per their policy.
 | --- | --- | --- |
 | Account daily cap (shared) | Workers Free: 100,000 requests/day **per account**, then requests error; KV Free: 1,000 writes/day **per account**, then writes fail. Other Workers on the same account eat into these, so the receiver gets its own Cloudflare account (free) or the shared-quota risk is accepted knowingly | the cap is the bill: there is none |
 | Per-IP rate limit | Workers Rate Limiting binding with a supported period (60 s; e.g. 3 requests / 60 s per IP). Counters are approximate and per Cloudflare location, so this is a brake, not a guarantee; one WAF rate-limiting rule (free plan allows one) backs it up at the edge | no cost |
-| Kill switch | KV key `paused`; checked first; set from the dashboard or `wrangler kv` | one KV read per request (100,000/day free) |
+| Kill switch | KV key `paused`; checked first; set from the dashboard or `wrangler kv`. KV is eventually consistent, so other Cloudflare locations can keep accepting for up to about 60 seconds after it is set; for an immediate stop, also disable the route in the dashboard (or `wrangler delete` the Worker) | one KV read per request (100,000/day free) |
 | Payload cap | reject bodies > 2 KB (a full payload with every component is about 1 KB), non-JSON, `schema !== 1`, unknown keys, non-integer counts, counts > 10^7 | Worker CPU only |
 | Ingestion cap | about 300 accepted records per UTC day, read from a KV counter `count:YYYY-MM-DD` (2-day TTL); beyond that reply `429` without storing. KV is eventually consistent and allows one write per key per second, so under a concurrent burst this cap is **approximate** (it can overshoot, and counter writes can fail). The hard ceiling is the account's 1,000 KV writes/day, which bounds storage whatever the counter says. If an exact cap is wanted, use a Durable Object counter (SQLite-backed Durable Objects are on the Free plan), decided when the receiver is built | KV Free writes 1,000/day |
 | Method/path allowlist | `POST /v1/summary` (public) and `GET /v1/stats` (bearer secret, see Monitoring); everything else 404 with no body | – |

From 29246a7775a558736f986b0c0abe6f31bf9a2d29 Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 20:49:00 -0700
Subject: [PATCH 09/10] docs(receiver): delete the Worker for an immediate
 stop; define write order

CodeRabbit on cc743d2: disabling a route leaves version, preview and
deployment URLs reachable, so the immediate stop is deleting the Worker;
and the record and counter writes need a defined order and failure
handling (record first, 202 only after both, 503 on a failed record).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/reporting-receiver.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/reporting-receiver.md b/docs/reporting-receiver.md
index 653a597..9c88326 100644
--- a/docs/reporting-receiver.md
+++ b/docs/reporting-receiver.md
@@ -65,9 +65,9 @@ Cloudflare's own request logs exist and are retained per their policy.
 | --- | --- | --- |
 | Account daily cap (shared) | Workers Free: 100,000 requests/day **per account**, then requests error; KV Free: 1,000 writes/day **per account**, then writes fail. Other Workers on the same account eat into these, so the receiver gets its own Cloudflare account (free) or the shared-quota risk is accepted knowingly | the cap is the bill: there is none |
 | Per-IP rate limit | Workers Rate Limiting binding with a supported period (60 s; e.g. 3 requests / 60 s per IP). Counters are approximate and per Cloudflare location, so this is a brake, not a guarantee; one WAF rate-limiting rule (free plan allows one) backs it up at the edge | no cost |
-| Kill switch | KV key `paused`; checked first; set from the dashboard or `wrangler kv`. KV is eventually consistent, so other Cloudflare locations can keep accepting for up to about 60 seconds after it is set; for an immediate stop, also disable the route in the dashboard (or `wrangler delete` the Worker) | one KV read per request (100,000/day free) |
+| Kill switch | KV key `paused`; checked first; set from the dashboard or `wrangler kv`. KV is eventually consistent, so other Cloudflare locations can keep accepting for up to about 60 seconds after it is set; the immediate stop is `wrangler delete` (or deleting the Worker in the dashboard), because disabling one route leaves its version, preview and deployment URLs reachable | one KV read per request (100,000/day free) |
 | Payload cap | reject bodies > 2 KB (a full payload with every component is about 1 KB), non-JSON, `schema !== 1`, unknown keys, non-integer counts, counts > 10^7 | Worker CPU only |
-| Ingestion cap | about 300 accepted records per UTC day, read from a KV counter `count:YYYY-MM-DD` (2-day TTL); beyond that reply `429` without storing. KV is eventually consistent and allows one write per key per second, so under a concurrent burst this cap is **approximate** (it can overshoot, and counter writes can fail). The hard ceiling is the account's 1,000 KV writes/day, which bounds storage whatever the counter says. If an exact cap is wanted, use a Durable Object counter (SQLite-backed Durable Objects are on the Free plan), decided when the receiver is built | KV Free writes 1,000/day |
+| Ingestion cap | about 300 accepted records per UTC day, read from a KV counter `count:YYYY-MM-DD` (2-day TTL); beyond that reply `429` without storing. KV is eventually consistent and allows one write per key per second, so under a concurrent burst this cap is **approximate** (it can overshoot, and counter writes can fail). The hard ceiling is the account's 1,000 KV writes/day, which bounds storage whatever the counter says. Write order: store the record first and increment the counter only if that succeeded; a failed record write returns `503` and leaves the counter alone, and `202` is returned only after both writes. A failed counter write after a stored record is logged and tolerated (it makes the cap looser, which the hard ceiling still bounds). If an exact cap, or both writes as one transaction, is wanted, use a Durable Object counter (SQLite-backed Durable Objects are on the Free plan), decided when the receiver is built | KV Free writes 1,000/day |
 | Method/path allowlist | `POST /v1/summary` (public) and `GET /v1/stats` (bearer secret, see Monitoring); everything else 404 with no body | – |
 | No egress | the Worker calls nothing (no email, no third parties) | – |
 | Storage growth | one KV value per record, TTL 12 months, key = random id; a daily cron summarises counts into one `stats:YYYY-MM-DD` key. Worst case, using the hard 1,000 writes/day rather than the soft 300: 1,000 × 2 KB × 365 ≈ 730 MB, inside the 1 GB KV Free limit | KV Free 1 GB |

From d6928ed1d5a1892a9b178780958ca8df0db4bf3e Mon Sep 17 00:00:00 2001
From: Kevin <k.attfield@gmail.com>
Date: Sat, 31 Oct 2026 21:07:15 -0700
Subject: [PATCH 10/10] docs(readme): describe the migration tools as shipped,
 not upcoming

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 readme.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readme.txt b/readme.txt
index 7945132..23a770e 100644
--- a/readme.txt
+++ b/readme.txt
@@ -14,7 +14,7 @@ WordPress plugin to add shortcodes for Bootstrap 3. In maintenance mode: kept sa
 
 ## Maintenance mode
 
-This plugin was written in 2013 for Bootstrap 3 and the TinyMCE editor. It is still maintained for **security and compatibility** so the sites that use it keep working, but no new components will be added. If you are starting a new site, use the block editor's own Columns, Buttons, Details, Accordion and Tabs blocks instead. If you already use it, a component-by-component migration guide and tooling ship in the next release; the [compatibility policy](https://github.com/TheWebShop/bootstrap-shortcodes/blob/master/docs/compatibility.md) says what is tested today.
+This plugin was written in 2013 for Bootstrap 3 and the TinyMCE editor. It is still maintained for **security and compatibility** so the sites that use it keep working, but no new components will be added. If you are starting a new site, use the block editor's own Columns, Buttons, Details, Accordion and Tabs blocks instead. If you already use it, Tools > Bootstrap Shortcodes finds where it is used and migrates that content to blocks, with a preview and rollback (see the [migration guide](https://github.com/TheWebShop/bootstrap-shortcodes/blob/master/docs/migration.md)); the [compatibility policy](https://github.com/TheWebShop/bootstrap-shortcodes/blob/master/docs/compatibility.md) says what is tested today.
 
 Bootstrap Shortcodes allow quick and easy implementation of Bootstrap 3 components through the TinyMCE rich-editor (Classic Editor). In the block editor the shortcodes still render; the toolbar buttons do not appear.