fix(spec): escape unmatched </{ in generated MDX docs (unblock apps/docs build) (#1493)

* fix(spec): escape unmatched `<`/`{` in generated MDX docs (unblock apps/docs build)

`build-docs.ts`'s `escapeMdxDescription` only backtick-wrapped *matched*
`<…>` / `{…}` pairs. A lone `<` with no closing partner — e.g. a SemVer
range in a `.describe()` like `">=4.0 <5"` — leaked into the generated MDX,
where Turbopack/fumadocs read the `<` as the start of a JSX tag and failed
the docs build:

  ./content/docs/references/kernel/manifest.mdx
  82:97: Unexpected character `5` (U+0035) before name

Now an unmatched `<` / `{` is replaced with its HTML entity (`&lt;` / `&#123;`)
so it renders literally and never opens a JSX/expression node. Also routes
union-variant descriptions through the same escaper (previously emitted raw).

Verified: `pnpm --filter @objectstack/docs build` (gen:schema + gen:docs +
next build) now completes; no remaining unmatched `<` outside code spans
across the generated references.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: changeset for docs MDX escape fix

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.changeset/fix-docs-mdx-escape.md

@@ -0,0 +1,5 @@
+---
+"@objectstack/spec": patch
+---
+
+Fix the docs generator (`build-docs.ts`) leaking an unmatched `<` / `{` into generated MDX, which broke the `apps/docs` Turbopack build (e.g. a SemVer range `">=4.0 <5"` in a `.describe()` string was read as the start of a JSX tag). Unmatched openers are now emitted as HTML entities (`&lt;` / `&#123;`); union-variant descriptions also go through the escaper.

packages/spec/scripts/build-docs.ts

@@ -167,6 +167,12 @@ function generateMarkdown(schemaName: string, schema: any, category: string, zod
   // span are left untouched. A naive two-pass replace double-wraps nested cases
   // like `{<id>}` into `` `{`<id>`}` `` — the inner backticks close the span
   // early and leak `<id>` as raw JSX (MDX: "Expected a closing tag for `<id>`").
+  //
+  // A matched `{…}` / `<…>` pair is wrapped in an inline-code span so it renders
+  // literally. A *lone* `<` or `{` with no closing partner (e.g. a SemVer range
+  // `">=4.0 <5"`, or prose like `count < 5`) can't be wrapped, so it is replaced
+  // with its HTML entity — otherwise MDX reads the `<` as the start of a JSX tag
+  // and the build dies ("Unexpected character `5` before name").
   const escapeMdxDescription = (raw: string): string => {
     let out = '';
     let inCode = false;
@@ -185,6 +191,9 @@ function generateMarkdown(schemaName: string, schema: any, category: string, zod
           i = end;
           continue;
         }
+        // Unmatched: escape so MDX doesn't treat it as a JSX/expression opener.
+        out += ch === '<' ? '&lt;' : '&#123;';
+        continue;
       }
       out += ch;
     }
@@ -223,7 +232,7 @@ function generateMarkdown(schemaName: string, schema: any, category: string, zod
      variants.forEach((variant: any, index: number) => {
          const variantTitle = variant.title || `Option ${index + 1}`;
          md += `#### ${variantTitle}\n\n`;
-         if (variant.description) md += `${variant.description}\n\n`;
+         if (variant.description) md += `${escapeMdxDescription(variant.description)}\n\n`;
 
          if (variant.type === 'object' && variant.properties) {
               if (variant.properties.type && variant.properties.type.const) {