diff --git a/packages/comments/README.md b/packages/comments/README.md
index 4c65fa4..f6868f4 100644
--- a/packages/comments/README.md
+++ b/packages/comments/README.md
@@ -126,7 +126,7 @@ interface FileResult {
- StyleLint (`stylelint-disable`, `stylelint-enable`)
- Coverage tools (`v8 ignore`, `c8 ignore`, `istanbul ignore`)
- URLs (`https://...`)
-- Preserves fenced code blocks, visually indented code blocks and the code of an `@example` tag (up to the next tag or closing fence) in JSDoc.
+- Preserves fenced code blocks, visually indented code blocks and the code of an `@example` tag (up to the next known JSDoc tag or closing fence) in JSDoc.
- Structured explanation groups (regex / pattern walkthroughs) remain line‑stable to avoid unintended semantic changes.
- Protects against pathological inputs with maximum indentation and comment body size limits.
diff --git a/packages/comments/src/__tests__/lib.example-state.test.ts b/packages/comments/src/__tests__/lib.example-state.test.ts
new file mode 100644
index 0000000..b7c0a49
--- /dev/null
+++ b/packages/comments/src/__tests__/lib.example-state.test.ts
@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vitest";
+import { parseAndTransformComments } from "../lib.js";
+
+/**
+ * How an open @example body moves between states in both comment forms: a
+ * second @example, an unknown decorator and a camelCase tag (issue 745).
+ */
+const opts = { width: 80, wrapLineComments: true, mergeLineComments: true };
+const run = (input: string) =>
+ parseAndTransformComments(input, opts).transformed;
+const lines = (...l: string[]) => l.join("\n");
+
+describe("parseAndTransformComments moves through @example states", () => {
+ it("opens a second @example while one is open", () => {
+ const input = lines(
+ "/**",
+ " * @example First",
+ " * a()",
+ " * @example Second",
+ // A plain code line: it would get a period if the example closed here.
+ " * b()",
+ " * @observable c = 0",
+ " */",
+ );
+ expect(run(input)).toBe(input);
+ });
+
+ it.each([
+ // A tag name used as a call, a capitalized one, and one indented as code.
+ ["@property() name = ''"],
+ ["@Override"],
+ [" @returns x"],
+ ])("keeps %s inside the example as code", (code) => {
+ const input = lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ ` * ${code}`,
+ " * y()",
+ " */",
+ );
+ expect(run(input)).toBe(input);
+ });
+
+ it.each([["@property() name = ''"], ["@Override"], [" @returns x"]])(
+ "keeps %s inside a // example as code",
+ (code) => {
+ const input = lines(
+ "foo();",
+ "// @example",
+ "// foo()",
+ `// ${code}`,
+ "// y()",
+ "bar();",
+ );
+ expect(run(input)).toContain(` * foo()\n * ${code}\n * y()\n */`);
+ },
+ );
+
+ it("opens a second // @example while one is open", () => {
+ const input = lines(
+ "foo();",
+ "// Summary.",
+ "// @example First",
+ "// a()",
+ "// @example Second",
+ "// b()",
+ "bar();",
+ );
+ const once = run(input);
+ expect(once).toBe(
+ lines(
+ "foo();",
+ "/**",
+ " * Summary.",
+ " * @example First",
+ " * a()",
+ " * @example Second",
+ " * b()",
+ " */",
+ "bar();",
+ ),
+ );
+ expect(run(once)).toBe(once);
+ });
+
+ it("keeps an unknown decorator inside a // example as code", () => {
+ const input = lines(
+ "foo();",
+ "// @example",
+ "// @observable price = 0",
+ "// const cart = new Cart()",
+ "bar();",
+ );
+ expect(run(input)).toBe(
+ lines(
+ "foo();",
+ "/**",
+ " * @example",
+ " * @observable price = 0",
+ " * const cart = new Cart()",
+ " */",
+ "bar();",
+ ),
+ );
+ });
+
+ it("ends a // example at a camelCase TSDoc tag", () => {
+ const input = lines(
+ "foo();",
+ "// @example",
+ "// foo()",
+ "// @typeParam T the item type",
+ "// of the list",
+ "bar();",
+ );
+ const once = run(input);
+ expect(once).toBe(
+ lines(
+ "foo();",
+ "/**",
+ " * @example",
+ " * foo()",
+ " * @typeParam T the item type",
+ " * of the list.",
+ " */",
+ "bar();",
+ ),
+ );
+ expect(run(once)).toBe(once);
+ });
+
+ it("ends an example opened with one space at a JSDoc @function indented alike", () => {
+ const input = lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ " * @function add",
+ " * and the rest",
+ " */",
+ );
+ const once = run(input);
+ expect(once).toBe(
+ lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ " * @function add",
+ " * and the rest.",
+ " */",
+ ),
+ );
+ expect(run(once)).toBe(once);
+ });
+
+ /**
+ * A tag followed by "{", then the JSDoc forms of the names left out of
+ * JSDOC_BLOCK_TAGS for their Sass and CSS forms.
+ */
+ it.each([
+ ["@type{string} the value"],
+ ["@function"],
+ ["@function add"],
+ ["@function do-thing"],
+ ["@mixin"],
+ ["@mixin Reveal"],
+ ["@mixin my-mixin"],
+ ["@function $.fn.x"],
+ ["@function Cart#add"],
+ ["@function module:cart~add"],
+ ["@mixin module:foo/bar"],
+ ['@import { Foo } from "./foo"'],
+ ['@import * as bar from "bar"'],
+ ['@import{ Bar } from "./foo"'],
+ ['@import Foo from "./foo"'],
+ ['@import Foo, { Bar } from "./foo"'],
+ ])("ends an example at %s", (tag) => {
+ const input = lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ ` * ${tag}`,
+ " * and the rest",
+ " */",
+ );
+ const once = run(input);
+ expect(once).toBe(
+ lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ ` * ${tag}`,
+ " * and the rest.",
+ " */",
+ ),
+ );
+ expect(run(once)).toBe(once);
+ });
+});
diff --git a/packages/comments/src/__tests__/lib.example-tags.test.ts b/packages/comments/src/__tests__/lib.example-tags.test.ts
new file mode 100644
index 0000000..d290a6b
--- /dev/null
+++ b/packages/comments/src/__tests__/lib.example-tags.test.ts
@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+import { JSDOC_BLOCK_TAGS } from "../jsdoc-tags.js";
+import { parseAndTransformComments } from "../lib.js";
+
+/**
+ * Only a known block tag ends an @example body (issue 745).
+ */
+const opts = { width: 80, wrapLineComments: true, mergeLineComments: true };
+const run = (input: string) =>
+ parseAndTransformComments(input, opts).transformed;
+const lines = (...l: string[]) => l.join("\n");
+
+describe("parseAndTransformComments ends @example bodies at known tags", () => {
+ it.each([
+ ["@observable price = 0"],
+ ["@computed get total() {"],
+ ['@import "theme.css";'],
+ ['@import url("print.css") print;'],
+ // Left out of JSDOC_BLOCK_TAGS on purpose, so Sass stays code.
+ ["@function rem($px) {"],
+ ["@mixin center {"],
+ ["@mixin center{"],
+ ])("keeps %s inside the example as code", (code) => {
+ const input = lines(
+ "/**",
+ " * @example",
+ ` * ${code}`,
+ " * const cart = new Cart()",
+ " */",
+ );
+ expect(run(input)).toBe(input);
+ });
+
+ it("ends an example at a camelCase TSDoc tag", () => {
+ const input = lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ " * @typeParam T the item type",
+ " * of the list",
+ " */",
+ );
+ expect(run(input)).toBe(
+ lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ " * @typeParam T the item type",
+ " * of the list.",
+ " */",
+ ),
+ );
+ });
+
+ it("keeps a // sentence that wraps at a capitalized word after @example in one piece", () => {
+ const input = lines(
+ "foo();",
+ "// The reflow keeps the body of an",
+ "// @example JSDoc tag line for line, and joins the prose after it",
+ "bar();",
+ );
+ const once = run(input);
+ expect(once).toBe(
+ lines(
+ "foo();",
+ "/**",
+ " * The reflow keeps the body of an @example JSDoc tag line for line, and joins",
+ " * the prose after it.",
+ " */",
+ "bar();",
+ ),
+ );
+ expect(run(once)).toBe(once);
+ });
+
+ // TypeDoc, Closure, custom-elements manifest, Doxygen and other block tags.
+ it.each([
+ "categoryDescription",
+ "groupDescription",
+ "document",
+ "sortStrategy",
+ "inline",
+ "expandType",
+ "inlineType",
+ "mergeModuleWith",
+ "preventExpand",
+ "preventInline",
+ "primaryExport",
+ "useDeclaredType",
+ "showCategories",
+ "hideCategories",
+ "showGroups",
+ "hideGroups",
+ "disableGroups",
+ "final",
+ "export",
+ "define",
+ "suppress",
+ "nocollapse",
+ "nosideeffects",
+ "record",
+ "struct",
+ "dict",
+ "unrestricted",
+ "externs",
+ "modifies",
+ "slot",
+ "csspart",
+ "cssprop",
+ "cssproperty",
+ "cssstate",
+ "attr",
+ "attribute",
+ "element",
+ "tag",
+ "tagname",
+ "brief",
+ "details",
+ "tparam",
+ "retval",
+ "pre",
+ "post",
+ "bug",
+ "examples",
+ "preserve",
+ "usageNotes",
+ "publicApi",
+ "implicitCast",
+ "noalias",
+ "nocompile",
+ "customElement",
+ "jest-environment",
+ "jsx",
+ "jsxFrag",
+ "jsxImportSource",
+ "jsxRuntime",
+ "vitest-environment",
+ ])("ends an example at @%s", (tag) => {
+ const input = lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ ` * @${tag} the value`,
+ " * and the rest",
+ " */",
+ );
+ expect(run(input)).toBe(
+ lines(
+ "/**",
+ " * @example",
+ " * foo()",
+ ` * @${tag} the value`,
+ " * and the rest.",
+ " */",
+ ),
+ );
+ });
+
+ it("stores every tag name lowercased, as endsExample compares them", () => {
+ for (const tag of JSDOC_BLOCK_TAGS) {
+ expect(tag).toBe(tag.toLowerCase());
+ }
+ });
+
+ /**
+ * A listed name must also read as a tag in prose, or the line that ends an
+ * example would be joined to the prose around it (CSS at-rules do not).
+ */
+ it("reads every listed name as a tag in prose too", () => {
+ for (const tag of JSDOC_BLOCK_TAGS) {
+ const input = lines(
+ "/**",
+ " * Some prose that",
+ ` * @${tag} continues`,
+ " */",
+ );
+ expect(run(input)).toContain(`\n * @${tag} continues\n`);
+ }
+ });
+});
diff --git a/packages/comments/src/__tests__/lib.property.test.ts b/packages/comments/src/__tests__/lib.property.test.ts
index 0ae6e3c..f5c2b0d 100644
--- a/packages/comments/src/__tests__/lib.property.test.ts
+++ b/packages/comments/src/__tests__/lib.property.test.ts
@@ -16,6 +16,9 @@ const token = fc.oneof(
"note:",
"aNOTE:",
"@param",
+ "@returns",
+ "@example",
+ "@observable",
"@auth0/auth0-react",
"@media",
"-",
diff --git a/packages/comments/src/__tests__/realistic-source.ts b/packages/comments/src/__tests__/realistic-source.ts
index 9ef589d..f46176a 100644
--- a/packages/comments/src/__tests__/realistic-source.ts
+++ b/packages/comments/src/__tests__/realistic-source.ts
@@ -73,7 +73,10 @@ const jsDocBlock = fc.oneof(
.map(([h, p]) => [h, ...p]),
fc.constant(["```ts", "const value = run();", "```"]),
);
-// An @example body: code lines, decorators and blanks, or a closed fence.
+/**
+ * An @example, with or without a title, then code lines, decorators and blanks,
+ * or a closed fence.
+ */
const example = fc
.oneof(
fc.array(
@@ -83,13 +86,18 @@ const example = fc
"