@jxsuite/import 0.40.1 → 0.40.2

package/README.md

@@ -1,9 +1,6 @@
 # @jxsuite/import
 
-Clone a live website into a Jx project: capture the rendered DOM with headless Chrome, diff
-computed styles against UA defaults, extract design tokens and responsive breakpoints, download
-assets, detect the shared layout across pages, componentize recurring subtrees (optionally refined
-by an OpenAI-compatible LLM), and emit a ready-to-edit Jx project.
+Clone a live website into a Jx project: capture the rendered DOM with headless Chrome, diff computed styles against UA defaults, extract design tokens and responsive breakpoints, download assets, detect the shared layout across pages, componentize recurring subtrees (optionally refined by an OpenAI-compatible LLM), and emit a ready-to-edit Jx project.
 
 ## CLI
 
@@ -32,31 +29,15 @@ jx-import <url> [options]
 
 ### What `--verify` can fail on
 
-`--verify` builds the emitted project, serves it, screenshots every page and pixel-diffs each
-against a reference captured during the import. The run exits non-zero when any of three things is
-true: the project did not build cleanly, a page could not be rendered, or the average fidelity is
-below `--min-fidelity`.
+`--verify` builds the emitted project, serves it, screenshots every page and pixel-diffs each against a reference captured during the import. The run exits non-zero when any of three things is true: the project did not build cleanly, a page could not be rendered, or the average fidelity is below `--min-fidelity`.
 
-`--verify-threshold` is **not** that bar. It is pixelmatch's per-pixel colour tolerance: it decides
-when two pixels count as the same colour, so it moves the score without ever deciding the outcome.
-`--min-fidelity` is the bar, and it defaults to a deliberately low `25`, a floor for "this is not a
-clone of anything" rather than a quality target. A faithful import of a complicated site still
-lands well under 100 for reasons no importer can fix (a rotating hero, a font rendering a hair
-differently).
+`--verify-threshold` is **not** that bar. It is pixelmatch's per-pixel colour tolerance: it decides when two pixels count as the same colour, so it moves the score without ever deciding the outcome. `--min-fidelity` is the bar, and it defaults to a deliberately low `25`, a floor for "this is not a clone of anything" rather than a quality target. A faithful import of a complicated site still lands well under 100 for reasons no importer can fix (a rotating hero, a font rendering a hair differently).
 
-`verify/report.json` carries the whole picture: per-page fidelity, the console errors and failed or
-404'd requests each rendered page produced, and any build errors. When a page scores badly, read
-`failedRequests` first, because a percentage cannot tell you that fifteen images 404'd and that
-list can.
+`verify/report.json` carries the whole picture: per-page fidelity, the console errors and failed or 404'd requests each rendered page produced, and any build errors. When a page scores badly, read `failedRequests` first, because a percentage cannot tell you that fifteen images 404'd and that list can.
 
-**Comparing two runs.** The reference screenshot is captured fresh each time, so two runs of the
-same URL are not directly comparable. On a site with a rotating hero the spread across identical
-runs has been measured at around 4 points, which is wide enough to hide a small regression. Compare
-a fidelity number against another run of the same code, not against one from a different session.
+**Comparing two runs.** The reference screenshot is captured fresh each time, so two runs of the same URL are not directly comparable. On a site with a rotating hero the spread across identical runs has been measured at around 4 points, which is wide enough to hide a small regression. Compare a fidelity number against another run of the same code, not against one from a different session.
 
-Environment: `CHROME_PATH` (explicit browser binary; otherwise `google-chrome-stable`,
-`google-chrome`, `chromium-browser`, or `chromium` is discovered on PATH), `OPENAI_API_KEY` and
-`OPENAI_BASE_URL` for `--ai-components`.
+Environment: `CHROME_PATH` (explicit browser binary; otherwise `google-chrome-stable`, `google-chrome`, `chromium-browser`, or `chromium` is discovered on PATH), `OPENAI_API_KEY` and `OPENAI_BASE_URL` for `--ai-components`.
 
 ## Programmatic API
 
@@ -77,9 +58,6 @@ const result = await importSite(
 );
 ```
 
-Lower-level building blocks (capture, style diffing, crawling, layout detection, componentization,
-emit, verify) are exported from the package root; `./capture`, `./to-jx`, `./emit`, `./run` and
-`./verify` are also addressable as subpaths. See `src/index.ts`.
+Lower-level building blocks (capture, style diffing, crawling, layout detection, componentization, emit, verify) are exported from the package root; `./capture`, `./to-jx`, `./emit`, `./run` and `./verify` are also addressable as subpaths. See `src/index.ts`.
 
-Verification (`verify` option / `--verify`) additionally needs `@jxsuite/compiler` (an optional
-dependency) to build the emitted project before screenshot-diffing it.
+Verification (`verify` option / `--verify`) additionally needs `@jxsuite/compiler` (an optional dependency) to build the emitted project before screenshot-diffing it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/import",
-  "version": "0.40.1",
+  "version": "0.40.2",
   "description": "Clone a live website into a Jx project",
   "license": "MIT",
   "repository": {
@@ -35,8 +35,8 @@
     "import": "bun run src/cli.ts"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.9",
-    "@jxsuite/schema": "^2.1.0",
+    "@jxsuite/markup": "^0.4.10",
+    "@jxsuite/schema": "^2.2.0",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "puppeteer-core": "^24.9.0"
@@ -46,6 +46,6 @@
     "happy-dom": "^20.10.6"
   },
   "optionalDependencies": {
-    "@jxsuite/compiler": "^3.1.0"
+    "@jxsuite/compiler": "^4.0.0"
   }
 }

package/src/apply-accordions.ts

@@ -0,0 +1,304 @@
+/**
+ * Turn a recognised framework accordion into native `<details name>`, preserving every node.
+ *
+ * The importer used to carry an accordion across as inert markup: the framework's directives
+ * survived as text, nothing was left to execute them, and the closed rows kept the `hidden`
+ * attribute and `display: none` the capture found them under. On the reference corpus that trapped
+ * 178 elements of real content behind widgets that could never open again.
+ *
+ * `<details name="…">` is the whole answer for this shape. Same-named details are mutually
+ * exclusive natively, which is what the source accordion's single scalar state meant, so the
+ * behaviour is preserved rather than approximated. It needs no runtime, no component state and no
+ * expressions — it prerenders, it is keyboard accessible, and there is nothing left to wire wrong.
+ *
+ * **The transform MOVES nodes; it never rebuilds them.** Every original element is reparented, not
+ * recreated, and {@link countLeaves} checks the leaf census across the rewrite. A mismatch abandons
+ * the whole widget and leaves the markup exactly as it was — losing a paragraph is far worse than
+ * failing to modernise a widget, so the invariant is enforced rather than trusted.
+ *
+ * Bound to no framework: everything structural comes from `toggle-algebra.ts`, which reads the
+ * open/closed logic out of attribute values without naming Alpine, Vue or anything else.
+ */
+
+import type { JxElement } from "@jxsuite/schema/types";
+import { roleOfElement } from "./toggle-algebra.ts";
+import type { ToggleRole } from "./toggle-algebra.ts";
+
+/**
+ * Attribute-name prefixes belonging to a client framework the clone does not ship.
+ *
+ * Left in place they are dead weight that nothing warns about: no attribute allowlist exists in the
+ * schema, and the compiler emits any string attribute verbatim, so a stale `x-show` travels all the
+ * way into the built site. `on*` is included only for STRING values, because a Jx handler is always
+ * an object and so cannot be hit by this.
+ */
+const DEAD_DIRECTIVE_PREFIXES = ["x-", "@", ":", "v-", "wire:", "data-wp-", "hx-", "data-bs-"];
+
+/** Attributes that conceal a node, and mean nothing once `<details>` owns the open state. */
+const CONCEALING_ATTRIBUTES = new Set(["hidden", "inert", "aria-hidden"]);
+
+/** Style declarations that were the widget's closed state rather than its design. */
+const CONCEALING_STYLE = new Set(["display", "height", "maxHeight", "overflow", "visibility"]);
+
+/** Names that must survive whatever else is stripped. */
+const PROTECTED_ATTRIBUTES = new Set(["id", "role", "href", "src", "alt", "class", "title"]);
+
+function isDeadDirective(name: string, value: unknown): boolean {
+  if (PROTECTED_ATTRIBUTES.has(name) || name.startsWith("aria-")) {
+    return false;
+  }
+  if (name.startsWith("on") && typeof value === "string") {
+    return true;
+  }
+  return DEAD_DIRECTIVE_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+/**
+ * A node's children as a plain array.
+ *
+ * `children` may also be a `$prototype: "Array"` repeater rather than a list, and a repeater has no
+ * literal rows to read. Treating one as empty is right for this pass: a widget whose rows are
+ * generated cannot have per-row toggle keys in its markup, so it could never close the algebra
+ * anyway, and returning nothing makes it fall through untouched.
+ */
+function childrenOf(node: JxElement): (JxElement | string)[] {
+  return Array.isArray(node.children) ? (node.children as (JxElement | string)[]) : [];
+}
+
+/**
+ * The content census of a subtree: every text run and every media element it holds.
+ *
+ * This is what the rewrite is checked against. Counting nodes would not do — a rewrite legitimately
+ * adds a `<details>` and a `<summary>` — but the LEAVES are exactly what a reader loses if the
+ * transform goes wrong, so they must be conserved exactly.
+ *
+ * @param {JxElement | string} node
+ * @returns {string[]} One entry per leaf, sorted, so ordering changes do not read as loss
+ */
+export function countLeaves(node: JxElement | string): string[] {
+  const leaves: string[] = [];
+  const visit = (current: JxElement | string): void => {
+    if (typeof current === "string") {
+      if (current.trim().length > 0) {
+        leaves.push(`t:${current.trim()}`);
+      }
+      return;
+    }
+    if (typeof current.textContent === "string" && current.textContent.trim().length > 0) {
+      leaves.push(`t:${current.textContent.trim()}`);
+    }
+    const source = (current.attributes as Record<string, unknown> | undefined)?.["src"];
+    if (typeof source === "string") {
+      leaves.push(`m:${source}`);
+    }
+    for (const child of childrenOf(current)) {
+      visit(child);
+    }
+  };
+  visit(node);
+  return leaves.toSorted();
+}
+
+/** Remove dead framework directives and concealment from one node, in place. */
+function cleanNode(node: JxElement, unconceal: boolean): void {
+  const attributes = node.attributes as Record<string, unknown> | undefined;
+  if (attributes) {
+    for (const name of Object.keys(attributes)) {
+      if (isDeadDirective(name, attributes[name])) {
+        delete attributes[name];
+      } else if (unconceal && CONCEALING_ATTRIBUTES.has(name)) {
+        delete attributes[name];
+      }
+    }
+  }
+  if (unconceal && node.style) {
+    const style = node.style as Record<string, unknown>;
+    for (const property of Object.keys(style)) {
+      if (CONCEALING_STYLE.has(property)) {
+        delete style[property];
+      }
+    }
+  }
+}
+
+/** Strip directives from a whole subtree; only the row's own body is unconcealed. */
+function cleanSubtree(node: JxElement | string, unconceal: boolean): void {
+  if (typeof node === "string") {
+    return;
+  }
+  cleanNode(node, unconceal);
+  for (const child of childrenOf(node)) {
+    cleanSubtree(child, false);
+  }
+}
+
+interface RowParts {
+  row: JxElement;
+  title: JxElement;
+  body: JxElement;
+  key: string;
+}
+
+/** The first descendant-or-self whose role matches, depth-first, narrowed to the kind asked for. */
+function findRole<K extends ToggleRole["kind"]>(
+  node: JxElement,
+  idents: ReadonlySet<string>,
+  want: K,
+): { node: JxElement; role: Extract<ToggleRole, { kind: K }> } | null {
+  const role = roleOfElement(node.attributes as Record<string, unknown> | undefined, idents);
+  if (role?.kind === want) {
+    return { node, role: role as Extract<ToggleRole, { kind: K }> };
+  }
+  for (const child of childrenOf(node)) {
+    if (typeof child === "string") {
+      continue;
+    }
+    const found = findRole(child, idents, want);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read the rows out of a candidate root, or null when the algebra does not close.
+ *
+ * Closure is the safety property. Every row must contribute exactly one toggle and one predicate
+ * over the SAME declared ident, and their keys must agree and be unique across the widget. Anything
+ * looser — a stray predicate, two rows claiming one key, a toggle over an ident nobody declared —
+ * means this is not the widget it looks like, and nothing is rewritten.
+ */
+export function readAccordionRows(root: JxElement, idents: ReadonlySet<string>): RowParts[] | null {
+  const rows: RowParts[] = [];
+  const seenKeys = new Set<string>();
+
+  for (const child of childrenOf(root)) {
+    if (typeof child === "string") {
+      if (child.trim().length > 0) {
+        return null;
+      }
+      continue;
+    }
+    const row = child as JxElement;
+    const toggle = findRole(row, idents, "assign");
+    const predicate = findRole(row, idents, "compare");
+    if (!toggle || !predicate) {
+      return null;
+    }
+    const { role: toggleRole } = toggle;
+    const { role: predicateRole } = predicate;
+    if (
+      toggleRole.ident !== predicateRole.ident ||
+      toggleRole.key !== predicateRole.key ||
+      !idents.has(toggleRole.ident) ||
+      seenKeys.has(toggleRole.key)
+    ) {
+      return null;
+    }
+    seenKeys.add(toggleRole.key);
+    rows.push({ body: predicate.node, key: toggleRole.key, row, title: toggle.node });
+  }
+
+  return rows.length >= 2 ? rows : null;
+}
+
+/** A stable, readable `name` so one widget's rows are mutually exclusive and another's are not. */
+function groupName(ident: string, index: number): string {
+  const base = ident
+    .replaceAll(/[^a-zA-Z0-9]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
+    .toLowerCase();
+  return `${base || "disclosure"}-${index}`;
+}
+
+/**
+ * Rewrite one candidate root's rows into `<details name>`, or return false to leave it alone.
+ *
+ * The row element itself becomes the `<details>` — keeping its attributes, classes and styles — so
+ * the site's own spacing and borders survive. Its title subtree moves inside a `<summary>` and its
+ * body subtree follows, both intact.
+ */
+function rewriteRoot(
+  root: JxElement,
+  rows: readonly RowParts[],
+  idents: ReadonlySet<string>,
+  index: number,
+): boolean {
+  const before = countLeaves(root);
+  const name = groupName([...idents][0] ?? "disclosure", index);
+  const rewritten: JxElement[] = [];
+
+  for (const { row, title, body } of rows) {
+    cleanSubtree(row, false);
+    cleanNode(body, true);
+
+    const summary: JxElement = { children: [title] as JxElement[], tagName: "summary" };
+    const others = childrenOf(row).filter(
+      (child) => child !== title && child !== body,
+    ) as JxElement[];
+
+    rewritten.push({
+      ...row,
+      attributes: { ...(row.attributes as Record<string, string>), name },
+      children: [summary, body, ...others] as JxElement[],
+      tagName: "details",
+    });
+  }
+
+  const candidate: JxElement = { ...root, children: rewritten };
+
+  /* The invariant, enforced rather than trusted: if a single text run or image would go missing,
+     abandon the widget entirely. A stale accordion is a much smaller defect than a deleted
+     paragraph, so this failure mode is the safe one. */
+  if (countLeaves(candidate).join("") !== before.join("")) {
+    return false;
+  }
+
+  root.children = rewritten;
+  cleanNode(root, false);
+  return true;
+}
+
+export interface AccordionResult {
+  /** How many widgets were converted. */
+  converted: number;
+  /** How many rows those widgets held. */
+  rows: number;
+}
+
+/**
+ * Convert every recognisable accordion in a page tree to native `<details name>`.
+ *
+ * Runs on the per-page tree BEFORE layout detection, because that step replaces the pages it
+ * extracts a layout from — a pass placed after it would see a site's widgets in neither.
+ *
+ * @param {JxElement} root - The page tree, mutated in place
+ * @returns {AccordionResult}
+ */
+export function applyAccordions(root: JxElement): AccordionResult {
+  const result: AccordionResult = { converted: 0, rows: 0 };
+  let index = 0;
+
+  const visit = (node: JxElement): void => {
+    const role = roleOfElement(node.attributes as Record<string, unknown> | undefined);
+    if (role?.kind === "declare") {
+      const idents = new Set(role.idents.keys());
+      const rows = readAccordionRows(node, idents);
+      if (rows && rewriteRoot(node, rows, idents, index)) {
+        index += 1;
+        result.converted += 1;
+        result.rows += rows.length;
+        return;
+      }
+    }
+    for (const child of childrenOf(node)) {
+      if (typeof child !== "string") {
+        visit(child);
+      }
+    }
+  };
+
+  visit(root);
+  return result;
+}

package/src/apply-disclosures.ts

@@ -0,0 +1,275 @@
+/**
+ * Turn a control that says it expands something into a real `<details>`.
+ *
+ * This is the reading that needs no framework knowledge at all: a site that ships correct
+ * accessibility markup has already told us which control opens which panel, in `aria-expanded` plus
+ * `aria-controls`, and that contract is identical across Bootstrap, jQuery, Webflow and
+ * hand-written markup. Where `toggle-algebra.ts` recognises the Alpine and Vue family by the shape
+ * of their expressions, this recognises everything that ships WAI-ARIA, which is most of the rest.
+ *
+ * The panel is concealed and the script that would reveal it is gone, so the content is on disk and
+ * unreachable — the single largest body of trapped text on the reference corpus.
+ *
+ * **A disclosure is not an overlay, and the difference is the flow.** `apply-popovers.ts` claims a
+ * concealed panel that is positioned, because being lifted out of the flow is what makes a thing
+ * draw ON TOP. A concealed panel still IN the flow is content that belongs where it sits and simply
+ * is not shown yet, which is exactly what `<details>` means. The two passes are disjoint by that
+ * test rather than by ordering luck.
+ *
+ * The rewrite MOVES both subtrees and conserves the leaf census, on the same terms as
+ * `apply-accordions.ts`: a stale widget is a far smaller defect than deleted content, so a rewrite
+ * that would lose a text run or an image is abandoned whole.
+ */
+
+import type { JxElement } from "@jxsuite/schema/types";
+import { countLeaves } from "./apply-accordions.ts";
+
+/** Attributes that made the old control a control, and mean nothing once `<summary>` is one. */
+const CONTROL_ATTRIBUTES = ["aria-expanded", "aria-controls", "role", "tabindex"];
+
+/** A panel lifted out of the flow is an overlay, and belongs to the popover pass instead. */
+const POSITIONED = new Set(["absolute", "fixed"]);
+
+function attributesOf(node: JxElement): Record<string, unknown> | undefined {
+  return node.attributes as Record<string, unknown> | undefined;
+}
+
+function childrenOf(node: JxElement): (JxElement | string)[] {
+  return Array.isArray(node.children) ? (node.children as (JxElement | string)[]) : [];
+}
+
+function elementChildren(node: JxElement): JxElement[] {
+  return childrenOf(node).filter((child) => typeof child !== "string") as JxElement[];
+}
+
+/** Whether this control declares that it expands a named panel. */
+export function isDisclosureInvoker(node: JxElement): boolean {
+  const attributes = attributesOf(node);
+  if (!attributes) {
+    return false;
+  }
+  const controls = attributes["aria-controls"];
+  return (
+    attributes["aria-expanded"] !== undefined && typeof controls === "string" && controls.length > 0
+  );
+}
+
+/**
+ * Whether this panel is closed content in the flow, rather than an overlay or ordinary content.
+ *
+ * The corpus's panels carry no style at all: they are hidden by the `hidden` ATTRIBUTE, which is
+ * why a detector looking only at computed style would miss every one of them.
+ */
+export function isDisclosurePanel(node: JxElement): boolean {
+  const style = node.style as Record<string, unknown> | undefined;
+  if (POSITIONED.has(String(style?.["position"] ?? ""))) {
+    return false;
+  }
+  const attributes = attributesOf(node);
+  return attributes?.["hidden"] !== undefined || style?.["display"] === "none";
+}
+
+/** Every element carrying an `id`, so `aria-controls` can be resolved. */
+function indexById(root: JxElement): Map<string, JxElement> {
+  const index = new Map<string, JxElement>();
+  const visit = (node: JxElement): void => {
+    const id = attributesOf(node)?.["id"];
+    if (typeof id === "string" && !index.has(id)) {
+      index.set(id, node);
+    }
+    for (const child of elementChildren(node)) {
+      visit(child);
+    }
+  };
+  visit(root);
+  return index;
+}
+
+/**
+ * What an element actually holds, whether that is children or a collapsed `textContent`.
+ *
+ * `htmlToJx` folds a lone text child into `textContent` and emits no `children` array at all, so a
+ * control whose label is bare text — which is most of them — looks empty to a children-only reader.
+ * Unwrapping one through `childrenOf` alone silently drops the label, and the leaf census then
+ * abandons the whole rewrite. Correct, but the wrong outcome.
+ */
+function contentOf(node: JxElement): (JxElement | string)[] {
+  const children = childrenOf(node);
+  if (children.length > 0) {
+    return children;
+  }
+  return typeof node.textContent === "string" && node.textContent.length > 0
+    ? [node.textContent]
+    : [];
+}
+
+/**
+ * Replace the invoker element with its own children, wherever it sits inside `node`.
+ *
+ * `<summary>` IS the control once the rewrite lands, so leaving the old one inside it would nest an
+ * interactive element in another. Unwrapping rather than deleting keeps the label text, which is
+ * the only part of the control a reader ever saw. Safe here because these controls carry no `href`:
+ * a real link would lose its destination and is refused before this point.
+ */
+function unwrapInvoker(node: JxElement, invoker: JxElement): JxElement {
+  const children = childrenOf(node);
+  if (children.length === 0) {
+    return node;
+  }
+  const rebuilt: (JxElement | string)[] = [];
+  for (const child of children) {
+    if (child === invoker) {
+      rebuilt.push(...contentOf(child as JxElement));
+    } else if (typeof child === "string") {
+      rebuilt.push(child);
+    } else {
+      rebuilt.push(unwrapInvoker(child as JxElement, invoker));
+    }
+  }
+  return { ...node, children: rebuilt as JxElement[] };
+}
+
+export interface DisclosureResult {
+  /** How many control/panel pairs became a `<details>`. */
+  converted: number;
+  /** Controls left pointing at a panel another control had already claimed. */
+  duplicateInvokers: number;
+}
+
+/**
+ * Convert every ARIA-declared disclosure in a page tree into `<details>`.
+ *
+ * @param {JxElement} root - The page tree, mutated in place
+ * @returns {DisclosureResult}
+ */
+export function applyDisclosures(root: JxElement): DisclosureResult {
+  const result: DisclosureResult = { converted: 0, duplicateInvokers: 0 };
+  const byId = indexById(root);
+  const claimedPanels = new Set<JxElement>();
+
+  /*
+   * Walk parents rather than invokers. The rewrite replaces TWO of a parent's children with one
+   * `<details>`, so the parent is the unit of work — and the corpus puts the panel BEFORE the
+   * control it belongs to ("… hidden extra copy … Read more"), so neither is reliably first.
+   */
+  const visit = (parent: JxElement): void => {
+    for (;;) {
+      const children = childrenOf(parent);
+      let applied = false;
+
+      for (let index = 0; index < children.length && !applied; index += 1) {
+        const branch = children[index];
+        if (typeof branch === "string") {
+          continue;
+        }
+
+        const invoker = findInvokerIn(branch as JxElement);
+        if (!invoker) {
+          continue;
+        }
+        const panelId = String(attributesOf(invoker)!["aria-controls"]);
+        const panel = byId.get(panelId);
+        if (!panel || !isDisclosurePanel(panel)) {
+          continue;
+        }
+        if (claimedPanels.has(panel)) {
+          /* A second control for a panel already inside a `<details>` is now a lie to a screen
+             reader: it reports a collapsed state it no longer governs. Strip what made it a
+             control and leave the text. */
+          const attributes = attributesOf(invoker)!;
+          for (const name of CONTROL_ATTRIBUTES) {
+            delete attributes[name];
+          }
+          result.duplicateInvokers += 1;
+          continue;
+        }
+
+        const panelIndex = children.indexOf(panel);
+        if (panelIndex === -1 || panelIndex === index) {
+          continue;
+        }
+
+        const before = countLeaves(parent);
+        const panelAttributes = { ...attributesOf(panel) };
+        delete panelAttributes["hidden"];
+        delete panelAttributes["aria-hidden"];
+
+        /* When the control IS the branch, there is no enclosing element to unwrap it out of, so
+           its own attributes would ride onto the `<summary>`. Stripping them here covers both
+           shapes: `<summary>` is the control now, and a leftover `aria-expanded` on it would report
+           a state the element no longer owns. */
+        const summaryBranch = unwrapInvoker(branch as JxElement, invoker);
+        const summaryAttributes = { ...attributesOf(summaryBranch) };
+        for (const name of CONTROL_ATTRIBUTES) {
+          delete summaryAttributes[name];
+        }
+        const summary: JxElement = {
+          ...summaryBranch,
+          ...(Object.keys(summaryAttributes).length > 0
+            ? { attributes: summaryAttributes as Record<string, string> }
+            : {}),
+          tagName: "summary",
+        };
+        if (Object.keys(summaryAttributes).length === 0) {
+          delete summary.attributes;
+        }
+        const details: JxElement = {
+          children: [summary, { ...panel, attributes: panelAttributes }] as JxElement[],
+          tagName: "details",
+        };
+
+        /* Placed where the FIRST of the pair sat, so the disclosure keeps the position the reader
+           already associated with it. `<details>` always renders its summary above its content, so
+           a panel that came first moves below the label it was always labelled by. */
+        const rebuilt = children.filter((child) => child !== branch && child !== panel) as (
+          | JxElement
+          | string
+        )[];
+        rebuilt.splice(Math.min(index, panelIndex), 0, details);
+
+        const candidate: JxElement = { ...parent, children: rebuilt as JxElement[] };
+        if (countLeaves(candidate).join(" ") !== before.join(" ")) {
+          continue;
+        }
+
+        parent.children = rebuilt as JxElement[];
+        claimedPanels.add(panel);
+        result.converted += 1;
+        applied = true;
+      }
+
+      if (!applied) {
+        break;
+      }
+    }
+
+    for (const child of elementChildren(parent)) {
+      visit(child);
+    }
+  };
+
+  visit(root);
+  return result;
+}
+
+/**
+ * The first disclosure control at or under `node`, but never one already inside a `<details>`.
+ *
+ * Without that second condition a converted disclosure's own summary would be offered back as a
+ * candidate on the next pass over the same parent, and the loop would not terminate.
+ */
+function findInvokerIn(node: JxElement): JxElement | null {
+  if (String(node.tagName ?? "").toLowerCase() === "details") {
+    return null;
+  }
+  if (isDisclosureInvoker(node)) {
+    return node;
+  }
+  for (const child of elementChildren(node)) {
+    const found = findInvokerIn(child);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}