zudoku 0.86.0 → 0.88.0

package/dist/cli/cli.js

@@ -7552,11 +7552,166 @@ var rehype_extract_toc_with_jsx_export_default = rehypeExtractTocWithJsxExport;
 import { headingRank } from "hast-util-heading-rank";
 import { toString as hastToString } from "hast-util-to-string";
 import { visit as visit2 } from "unist-util-visit";
+var BLOCK_TAGS = /* @__PURE__ */ new Set([
+  "blockquote",
+  "details",
+  "div",
+  "figure",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "iframe",
+  "img",
+  "ol",
+  "p",
+  "pre",
+  "section",
+  "table",
+  "ul",
+  "video"
+]);
+var EMPHASIS_TAGS = /* @__PURE__ */ new Set(["b", "em", "i", "strong"]);
+var MAX_RENDERED_DEPTH = 3;
+var TOC_ANCHOR_PROPERTY = "dataTocAnchor";
+var isTocEnabled = (node) => {
+  const attribute = node.attributes.find(
+    (attr2) => attr2.type === "mdxJsxAttribute" && attr2.name === "toc"
+  );
+  if (attribute?.type !== "mdxJsxAttribute") return true;
+  if (attribute.value == null) return true;
+  const value = typeof attribute.value === "string" ? attribute.value : attribute.value.value;
+  return value.trim() !== "false";
+};
+var unwrapEmphasis = (nodes) => {
+  let current = nodes;
+  while (current.length === 1) {
+    const [only] = current;
+    if (only?.type !== "element" || !EMPHASIS_TAGS.has(only.tagName)) break;
+    current = only.children;
+  }
+  return current;
+};
+var getStepTitle = (item) => {
+  const children = item.children.filter(
+    (child) => !(child.type === "text" && child.value.trim() === "")
+  );
+  const [first] = children;
+  if (!first) return;
+  if (first.type === "element" && first.tagName === "p") {
+    return { owner: first, nodes: unwrapEmphasis(first.children) };
+  }
+  const bodyStart = children.findIndex(
+    (child) => child.type === "element" && BLOCK_TAGS.has(child.tagName)
+  );
+  const nodes = bodyStart === -1 ? children : children.slice(0, bodyStart);
+  return nodes.length > 0 ? { owner: item, nodes: unwrapEmphasis(nodes) } : void 0;
+};
+var getFrontmatterTitle = (tree) => {
+  let title;
+  visit2(tree, "mdxjsEsm", (node) => {
+    for (const statement of node.data?.estree?.body ?? []) {
+      if (statement.type !== "ExportNamedDeclaration" || statement.declaration?.type !== "VariableDeclaration") {
+        continue;
+      }
+      for (const declarator of statement.declaration.declarations) {
+        if (declarator.id.type !== "Identifier" || declarator.id.name !== "frontmatter" || declarator.init?.type !== "ObjectExpression") {
+          continue;
+        }
+        for (const property of declarator.init.properties) {
+          if (property.type !== "Property") continue;
+          const key = property.key.type === "Identifier" ? property.key.name : property.key.type === "Literal" ? String(property.key.value) : void 0;
+          if (key === "title" && property.value.type === "Literal" && typeof property.value.value === "string") {
+            title = property.value.value;
+          }
+        }
+      }
+    }
+  });
+  return title;
+};
+var createIdFactory = (tree) => {
+  const used = /* @__PURE__ */ new Set();
+  const frontmatterTitle = getFrontmatterTitle(tree);
+  if (frontmatterTitle) used.add(slugify(frontmatterTitle));
+  visit2(tree, "element", (node) => {
+    if (node.properties?.id) used.add(String(node.properties.id));
+  });
+  return (text) => {
+    const base = slugify(text) || "step";
+    let id = base;
+    for (let i = 2; used.has(id); i++) id = `${base}-${i}`;
+    used.add(id);
+    return id;
+  };
+};
+var collectSteps = (tree) => {
+  const steppers = [];
+  visit2(tree, "mdxJsxFlowElement", (node) => {
+    if (node.name === "Stepper" && isTocEnabled(node)) steppers.push(node);
+  });
+  const steps = /* @__PURE__ */ new Map();
+  const lists = /* @__PURE__ */ new Map();
+  if (steppers.length === 0) return { steps, lists };
+  const nextId = createIdFactory(tree);
+  for (const stepper of steppers) {
+    const items = stepper.children.flatMap((list) => {
+      if (list.type !== "element" || list.tagName !== "ol") return [];
+      lists.set(list, stepper);
+      return list.children;
+    });
+    for (const item of items) {
+      if (item.type !== "element" || item.tagName !== "li") continue;
+      const title = getStepTitle(item);
+      if (!title) continue;
+      const text = title.nodes.map((node) => hastToString(node)).join("").trim();
+      if (!text) continue;
+      title.owner.properties ??= {};
+      title.owner.properties.id ??= nextId(text);
+      steps.set(title.owner, {
+        stepper,
+        text,
+        id: String(title.owner.properties.id),
+        ...title.nodes.some((node) => node.type !== "text") ? { rich: title.nodes } : {}
+      });
+    }
+  }
+  return { steps, lists };
+};
 var rehypeExtractTocWithJsx = () => (tree, vfile) => {
+  const { steps, lists } = collectSteps(tree);
   const headings = [];
+  let headingDepth = 1;
+  const stepperDepths = /* @__PURE__ */ new Map();
   visit2(tree, "element", (node) => {
     const level = headingRank(node);
-    if (!level) return;
+    if (!level) {
+      const stepper = lists.get(node);
+      if (stepper) {
+        if (!stepperDepths.has(stepper)) {
+          stepperDepths.set(stepper, headingDepth + 1);
+        }
+        return;
+      }
+      const step = steps.get(node);
+      if (!step) return;
+      const depth = stepperDepths.get(step.stepper) ?? headingDepth + 1;
+      if (depth <= MAX_RENDERED_DEPTH) {
+        node.properties ??= {};
+        node.properties[TOC_ANCHOR_PROPERTY] = "";
+      }
+      headings.push({
+        depth,
+        text: step.text,
+        id: step.id,
+        ...step.rich ? { rich: step.rich } : {}
+      });
+      return;
+    }
+    headingDepth = level;
     const richChildren = node.children;
     const hasRichContent = richChildren.some((child) => child.type !== "text");
     const heading = {
@@ -8249,6 +8404,19 @@ var getAppClientEntryPath = () => path18.posix.join(getZudokuRootDir(), "src/app
 var getAppServerEntryPath = () => path18.posix.join(getZudokuRootDir(), "src/app/entry.server.tsx");
 var hasLoggedCdnInfo = false;
 var MEDIA_REGEX = /\.(a?png|jpe?g|gif|bmp|svg|webp|tiff|ico|webm|ogg|mp3|wav|m4a|avif|mp4)/i;
+var getDepScanEntries = () => {
+  const src = path18.posix.join(getZudokuRootDir(), "src");
+  return [
+    `${src}/{app,lib}/**/*.{ts,tsx}`,
+    // Client-environment scan: `entry.server.tsx` imports
+    // `virtual:zudoku-markdown-files`, which only the `ssr` environment
+    // provides. Including it fails the scan and disables pre-bundling entirely.
+    `!${getAppServerEntryPath()}`,
+    // Not published, but present in the monorepo — keeps local dev scanning the
+    // same file set an installed site does (and out of vitest's dependencies).
+    `!${src}/**/*.test.*`
+  ];
+};
 var defineEnvVars = (vars) => Object.fromEntries(
   vars.flatMap((v) => [
     [`process.env.${v}`, JSON.stringify(process.env[v])],
@@ -8396,7 +8564,7 @@ async function getViteConfig(dir, configEnv, options = {}) {
       }
     },
     optimizeDeps: {
-      entries: [path18.posix.join(getZudokuRootDir(), "src/{app,lib}/**")],
+      entries: getDepScanEntries(),
       exclude: ["zudoku"],
       include: [
         "@mdx-js/react",

package/dist/declarations/lib/ui/Stepper.d.ts

@@ -1,3 +1,6 @@
-import type { PropsWithChildren } from "react";
-declare const Stepper: ({ children }: PropsWithChildren) => import("react").JSX.Element;
+import { type PropsWithChildren } from "react";
+export type StepperProps = PropsWithChildren<{
+    toc?: boolean;
+}>;
+declare const Stepper: ({ children }: StepperProps) => import("react").JSX.Element;
 export { Stepper };

package/dist/declarations/lib/util/MdxComponents.d.ts

@@ -28,7 +28,7 @@ export declare const MdxComponents: {
         className?: string;
         icon?: boolean | import("react").ReactNode;
     }) => import("react").JSX.Element;
-    Stepper: ({ children }: import("react").PropsWithChildren) => import("react").JSX.Element;
+    Stepper: ({ children }: import("../ui/Stepper.js").StepperProps) => import("react").JSX.Element;
     Mermaid: (props: JSX.IntrinsicElements) => import("react").JSX.Element;
     SyntaxHighlight: (props: JSX.IntrinsicElements) => import("react").JSX.Element;
     tip: (props: JSX.IntrinsicElements) => import("react").JSX.Element;

package/dist/declarations/vite/mdx/rehype-extract-toc-with-jsx.d.ts

@@ -1,4 +1,4 @@
-import type { RootContent } from "hast";
+import type { Root, RootContent } from "hast";
 import type { Plugin } from "unified";
 export type TocEntry = {
     depth: number;
@@ -13,5 +13,5 @@ declare module "vfile" {
         toc: Toc;
     }
 }
-declare const rehypeExtractTocWithJsx: Plugin<[]>;
+declare const rehypeExtractTocWithJsx: Plugin<[], Root>;
 export default rehypeExtractTocWithJsx;

package/docs/components/stepper.mdx

@@ -41,7 +41,7 @@ Wrap Markdown lists with the `Stepper` component to create a vertical stepper li
   </div>
   <div className="flex-1">
 
-    <Stepper>
+    <Stepper toc={false}>
 
 1. **Identify the Problem**
 1. **Plan Your Project**
@@ -52,6 +52,39 @@ Wrap Markdown lists with the `Stepper` component to create a vertical stepper li
   </div>
 </div>
 
+## Table of Contents
+
+Steps are anchorable and show up in the "On this page" sidebar, nested one level below the heading
+they follow:
+
+| Stepper placed after…                 | Steps appear as…                                |
+| ------------------------------------- | ----------------------------------------------- |
+| The page title (or no heading at all) | Top-level entries                               |
+| An `h2`                               | Sub-entries of that `h2`                        |
+| An `h3` or deeper                     | Nothing — the same cut-off an `h4` heading hits |
+
+That means a page that is nothing but a stepper (a tutorial, for example) gets a usable table of
+contents automatically, while a stepper buried inside an existing section doesn't flood it.
+
+Each step's title — the first line of the list item — becomes the entry. A step whose first block
+isn't text (a code block, for instance) is skipped.
+
+### Opting out
+
+Set `toc={false}` for a stepper that is a quick checklist rather than a section of the page worth
+linking to:
+
+<!-- prettier-ignore -->
+```tsx
+<Stepper toc={false}>
+
+1. **Find the reason code**
+1. **Look up the code**
+1. **Re-file**
+
+</Stepper>
+```
+
 ## Advanced Example
 
 <Stepper>

package/docs/configuration/api-reference.md

@@ -276,7 +276,7 @@ Available options:
   schemes section on the info page, and the Authorize dialog in the playground). Disabled by default
   (`true`). Set to `false` to enable security scheme support
 - `disableMcpAuthInstructions`: Hide the authentication instructions on
-  [MCP server](../guides/mcp-servers.md) endpoints. The MCP card normally derives a credential
+  [MCP server](/docs/guides/mcp-servers) endpoints. The MCP card normally derives a credential
   header from the operation's security scheme and shows it in every install snippet. Set to `true`
   to render the server as unauthenticated instead — no header snippets and no "replace
   `YOUR_API_KEY`" steps

package/docs/configuration/llms.md

@@ -113,10 +113,14 @@ dist/
     └── ...
 ```
 
+::if{mode=opensource}
+
 On Vercel builds, this tree is written beneath `.vercel/output/static/` instead of `dist/`. The
 deployed public URLs remain the same. See the [Vercel deployment guide](/docs/deploy/vercel) for the
 generated routing and Markdown content-negotiation behavior.
 
+::
+
 **Important:** Individual `.md` files are only kept in the final build if `publishMarkdown: true`.
 If only `llmsTxt` or `llmsTxtFull` is enabled, the `.md` files are generated temporarily during the
 build but deleted after the `llms.txt` files are created.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "type": "module",
   "engines": {
     "node": ">=22.22.0"

package/src/app/entry.server.tsx

@@ -186,6 +186,12 @@ export const handleRequest = async ({
 
   try {
     const reactStream = await renderToReadableStream(App, {
+      // The stream is only read after `allReady`, so nothing is streamed
+      // progressively anyway. Without this, React outlines completed Suspense
+      // boundaries larger than the default chunk size (12.8 kB) into a hidden
+      // segment swapped in by an inline script, leaving only the fallback
+      // visible to clients that don't run JS (AI crawlers, curl, reader mode).
+      progressiveChunkSize: Number.MAX_SAFE_INTEGER,
       onError(error) {
         status = 500;
         logger.error(`SSR Error (${request.method} ${request.url}):`, error);

package/src/lib/ui/Stepper.tsx

@@ -1,8 +1,44 @@
-import type { PropsWithChildren } from "react";
+import { type PropsWithChildren, useEffect, useRef } from "react";
+import { useViewportAnchor } from "../components/context/ViewportAnchorContext.js";
+
+export type StepperProps = PropsWithChildren<{
+  /**
+   * Whether the steps appear in the table of contents. Defaults to `true`.
+   *
+   * Read at build time by `rehype-extract-toc-with-jsx`, which also assigns the
+   * step anchors — it's declared here so MDX authors get the prop typed.
+   */
+  toc?: boolean;
+}>;
 
 // "stepper" class is defined in main.css
-const Stepper = ({ children }: PropsWithChildren) => {
-  return <div className="stepper">{children}</div>;
+const Stepper = ({ children }: StepperProps) => {
+  const ref = useRef<HTMLDivElement>(null);
+  const { observe, unobserve } = useViewportAnchor();
+
+  useEffect(() => {
+    // `rehype-extract-toc-with-jsx` marks the step anchors the toc renders —
+    // on the title paragraph of a loose step, or on the `<li>` of a tight one.
+    // Steps too deep to appear in the toc keep their id but aren't marked, so
+    // scrolling through them can't blank out the enclosing heading.
+    const anchors = ref.current?.querySelectorAll<HTMLElement>(
+      ":scope > ol > li[data-toc-anchor], :scope > ol > li > p[data-toc-anchor]",
+    );
+
+    if (!anchors?.length) return;
+
+    for (const anchor of anchors) observe(anchor);
+
+    return () => {
+      for (const anchor of anchors) unobserve(anchor);
+    };
+  }, [observe, unobserve]);
+
+  return (
+    <div className="stepper" ref={ref}>
+      {children}
+    </div>
+  );
 };
 
 export { Stepper };

package/src/vite/config.ts

@@ -40,6 +40,35 @@ let hasLoggedCdnInfo = false;
 const MEDIA_REGEX =
   /\.(a?png|jpe?g|gif|bmp|svg|webp|tiff|ico|webm|ogg|mp3|wav|m4a|avif|mp4)/i;
 
+/**
+ * Seeds Vite's dependency scanner with Zudoku's own source.
+ *
+ * `zudoku` is in `optimizeDeps.exclude`, so its source is served to the browser
+ * unbundled and its bare imports have to be pre-bundled by name. When Zudoku is
+ * installed normally its source lives inside `node_modules`, and Vite skips
+ * runtime dependency discovery for any importer under `node_modules` (it serves
+ * the raw file with a `?v=` query instead). This scan is therefore the only
+ * chance to find those dependencies — anything it misses reaches the browser as
+ * raw CommonJS and fails to parse as ESM.
+ *
+ * The scan aborts wholesale on a single unresolvable import, so the entries must
+ * not include modules that only resolve in another environment.
+ */
+export const getDepScanEntries = () => {
+  const src = path.posix.join(getZudokuRootDir(), "src");
+
+  return [
+    `${src}/{app,lib}/**/*.{ts,tsx}`,
+    // Client-environment scan: `entry.server.tsx` imports
+    // `virtual:zudoku-markdown-files`, which only the `ssr` environment
+    // provides. Including it fails the scan and disables pre-bundling entirely.
+    `!${getAppServerEntryPath()}`,
+    // Not published, but present in the monorepo — keeps local dev scanning the
+    // same file set an installed site does (and out of vitest's dependencies).
+    `!${src}/**/*.test.*`,
+  ];
+};
+
 const defineEnvVars = (vars: string[]) =>
   Object.fromEntries(
     vars.flatMap((v) => [
@@ -229,7 +258,7 @@ export async function getViteConfig(
       },
     },
     optimizeDeps: {
-      entries: [path.posix.join(getZudokuRootDir(), "src/{app,lib}/**")],
+      entries: getDepScanEntries(),
       exclude: ["zudoku"],
       include: [
         "@mdx-js/react",

package/src/vite/mdx/rehype-extract-toc-with-jsx.ts

@@ -1,8 +1,11 @@
-import type { Element, RootContent } from "hast";
+import type { Element, Root, RootContent } from "hast";
 import { headingRank } from "hast-util-heading-rank";
 import { toString as hastToString } from "hast-util-to-string";
+import type { MdxjsEsm } from "mdast-util-mdx";
+import type { MdxJsxFlowElementHast } from "mdast-util-mdx-jsx";
 import type { Plugin } from "unified";
 import { visit } from "unist-util-visit";
+import { slugify } from "../../lib/util/slugify.js";
 
 export type TocEntry = {
   depth: number;
@@ -21,13 +24,289 @@ declare module "vfile" {
   }
 }
 
-const rehypeExtractTocWithJsx: Plugin<[]> = () => (tree, vfile) => {
+/** Tags that end a step's title and start its body. */
+const BLOCK_TAGS = new Set([
+  "blockquote",
+  "details",
+  "div",
+  "figure",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "iframe",
+  "img",
+  "ol",
+  "p",
+  "pre",
+  "section",
+  "table",
+  "ul",
+  "video",
+]);
+
+/** Inline wrappers that carry no meaning once a step title is in the toc. */
+const EMPHASIS_TAGS = new Set(["b", "em", "i", "strong"]);
+
+/**
+ * `TocContent` renders two levels, so entries deeper than this are extracted
+ * but never shown — the cut-off `h4` headings already hit.
+ */
+const MAX_RENDERED_DEPTH = 3;
+
+/**
+ * Marks the step anchors the toc actually renders, so `Stepper` observes only
+ * those. Deeper steps keep their id and stay linkable, but tracking them would
+ * set an `activeAnchor` with no toc entry and blank out the highlight — the
+ * same reason `MdxPage` registers only `h2` and `h3` as navigation anchors.
+ */
+const TOC_ANCHOR_PROPERTY = "dataTocAnchor";
+
+type StepTitle = { owner: Element; nodes: RootContent[] };
+
+type Step = {
+  /** The `<Stepper>` this step belongs to, so all its steps share a depth. */
+  stepper: MdxJsxFlowElementHast;
+  text: string;
+  id: string;
+  rich?: RootContent[];
+};
+
+/**
+ * Steps opt out with `<Stepper toc={false}>`. Anything else — including a bare
+ * `toc` and `toc={true}` — keeps them in the table of contents.
+ */
+const isTocEnabled = (node: MdxJsxFlowElementHast) => {
+  const attribute = node.attributes.find(
+    (attr) => attr.type === "mdxJsxAttribute" && attr.name === "toc",
+  );
+
+  if (attribute?.type !== "mdxJsxAttribute") return true;
+  if (attribute.value == null) return true;
+
+  const value =
+    typeof attribute.value === "string"
+      ? attribute.value
+      : attribute.value.value;
+
+  return value.trim() !== "false";
+};
+
+const unwrapEmphasis = (nodes: RootContent[]): RootContent[] => {
+  let current = nodes;
+
+  while (current.length === 1) {
+    const [only] = current;
+    if (only?.type !== "element" || !EMPHASIS_TAGS.has(only.tagName)) break;
+    current = only.children;
+  }
+
+  return current;
+};
+
+/**
+ * The leading inline content of a step, plus the element the anchor belongs on.
+ *
+ * Loose list items wrap their title in a paragraph, so the anchor goes there:
+ * a step can be arbitrarily tall, and the viewport observer only reliably
+ * activates short elements. Tight list items are inline-only (and therefore
+ * short), so they anchor on the `<li>` itself.
+ */
+const getStepTitle = (item: Element): StepTitle | undefined => {
+  const children = item.children.filter(
+    (child) => !(child.type === "text" && child.value.trim() === ""),
+  );
+  const [first] = children;
+  if (!first) return;
+
+  if (first.type === "element" && first.tagName === "p") {
+    return { owner: first, nodes: unwrapEmphasis(first.children) };
+  }
+
+  const bodyStart = children.findIndex(
+    (child) => child.type === "element" && BLOCK_TAGS.has(child.tagName),
+  );
+  const nodes = bodyStart === -1 ? children : children.slice(0, bodyStart);
+
+  return nodes.length > 0
+    ? { owner: item, nodes: unwrapEmphasis(nodes) }
+    : undefined;
+};
+
+/**
+ * The frontmatter `title` never reaches this tree, but `MdxPage` renders it as
+ * an `h1` with a slugified id. Without reserving that slug a step sharing the
+ * page title produces a duplicate id, and both the anchor link and the viewport
+ * observer resolve to the heading instead of the step.
+ */
+const getFrontmatterTitle = (tree: Root): string | undefined => {
+  let title: string | undefined;
+
+  visit(tree, "mdxjsEsm", (node: MdxjsEsm) => {
+    for (const statement of node.data?.estree?.body ?? []) {
+      if (
+        statement.type !== "ExportNamedDeclaration" ||
+        statement.declaration?.type !== "VariableDeclaration"
+      ) {
+        continue;
+      }
+
+      for (const declarator of statement.declaration.declarations) {
+        if (
+          declarator.id.type !== "Identifier" ||
+          declarator.id.name !== "frontmatter" ||
+          declarator.init?.type !== "ObjectExpression"
+        ) {
+          continue;
+        }
+
+        for (const property of declarator.init.properties) {
+          if (property.type !== "Property") continue;
+
+          const key =
+            property.key.type === "Identifier"
+              ? property.key.name
+              : property.key.type === "Literal"
+                ? String(property.key.value)
+                : undefined;
+
+          if (
+            key === "title" &&
+            property.value.type === "Literal" &&
+            typeof property.value.value === "string"
+          ) {
+            title = property.value.value;
+          }
+        }
+      }
+    }
+  });
+
+  return title;
+};
+
+/** Slugs step anchors without colliding with ids already in the document. */
+const createIdFactory = (tree: Root) => {
+  const used = new Set<string>();
+
+  const frontmatterTitle = getFrontmatterTitle(tree);
+  if (frontmatterTitle) used.add(slugify(frontmatterTitle));
+
+  visit(tree, "element", (node: Element) => {
+    if (node.properties?.id) used.add(String(node.properties.id));
+  });
+
+  return (text: string) => {
+    const base = slugify(text) || "step";
+    let id = base;
+    for (let i = 2; used.has(id); i++) id = `${base}-${i}`;
+    used.add(id);
+    return id;
+  };
+};
+
+/**
+ * Assigns anchor ids to `<Stepper>` steps and indexes them by the element that
+ * carries the anchor, so the document-order pass below can place them.
+ */
+const collectSteps = (tree: Root) => {
+  const steppers: MdxJsxFlowElementHast[] = [];
+
+  visit(tree, "mdxJsxFlowElement", (node: MdxJsxFlowElementHast) => {
+    if (node.name === "Stepper" && isTocEnabled(node)) steppers.push(node);
+  });
+
+  const steps = new Map<Element, Step>();
+  /** Each stepper's list, so depth can be pinned at the list's own position. */
+  const lists = new Map<Element, MdxJsxFlowElementHast>();
+  if (steppers.length === 0) return { steps, lists };
+
+  const nextId = createIdFactory(tree);
+
+  for (const stepper of steppers) {
+    const items = stepper.children.flatMap((list) => {
+      if (list.type !== "element" || list.tagName !== "ol") return [];
+      lists.set(list, stepper);
+      return list.children;
+    });
+
+    for (const item of items) {
+      if (item.type !== "element" || item.tagName !== "li") continue;
+
+      const title = getStepTitle(item);
+      if (!title) continue;
+
+      const text = title.nodes
+        .map((node) => hastToString(node))
+        .join("")
+        .trim();
+      if (!text) continue;
+
+      title.owner.properties ??= {};
+      title.owner.properties.id ??= nextId(text);
+
+      steps.set(title.owner, {
+        stepper,
+        text,
+        id: String(title.owner.properties.id),
+        ...(title.nodes.some((node) => node.type !== "text")
+          ? { rich: title.nodes }
+          : {}),
+      });
+    }
+  }
+
+  return { steps, lists };
+};
+
+const rehypeExtractTocWithJsx: Plugin<[], Root> = () => (tree, vfile) => {
+  const { steps, lists } = collectSteps(tree);
   const headings: TocEntry[] = [];
 
+  // Steps nest one level below the heading they follow, so a stepper under an
+  // `h2` renders as sub-items and one under an `h3` ends up too deep to render
+  // — the same cut-off an `h4` already hits. Steps before any heading sit at
+  // depth 2, alongside the headings under the page title.
+  let headingDepth = 1;
+  const stepperDepths = new Map<MdxJsxFlowElementHast, number>();
+
   visit(tree, "element", (node: Element) => {
     const level = headingRank(node);
 
-    if (!level) return;
+    if (!level) {
+      // Pinned at the list itself, so neither a skipped step nor a heading
+      // buried in a step body can shift the rest of the stepper deeper.
+      const stepper = lists.get(node);
+      if (stepper) {
+        if (!stepperDepths.has(stepper)) {
+          stepperDepths.set(stepper, headingDepth + 1);
+        }
+        return;
+      }
+
+      const step = steps.get(node);
+      if (!step) return;
+
+      const depth = stepperDepths.get(step.stepper) ?? headingDepth + 1;
+
+      if (depth <= MAX_RENDERED_DEPTH) {
+        node.properties ??= {};
+        node.properties[TOC_ANCHOR_PROPERTY] = "";
+      }
+
+      headings.push({
+        depth,
+        text: step.text,
+        id: step.id,
+        ...(step.rich ? { rich: step.rich } : {}),
+      });
+      return;
+    }
+
+    headingDepth = level;
 
     const richChildren = node.children as RootContent[];
     const hasRichContent = richChildren.some((child) => child.type !== "text");