fix: reference root block objects by name at every nested position

The #2774 memo made conversion time linear by building shared
`OfDefinition` objects, a DAG. But each named type's single expansion
still inlined the expansions of every type not on its first-visit
ancestor path, so the emitted definition was factorial in the number
of mutually-embedding types AS A TREE, which is the shape every
consumer walks: `compileSchema`, React reconciliation, any clone or
serialization. On the mutually-embedding benchmark's own 12-type
schema, conversion measured 2.5ms (test green) while the output
serialized to 57 MB; at a field-reported ~25 types with several
recursion edges, studios exhausted the heap on document open. The
blow-up lived one package boundary downstream of every profiler frame
and benchmark assertion, which is why conversion-only repros passed.

`scheduleOfMember` now emits a bare `{type: name}` reference
whenever the member is one of the root block-object instances, at
every position, not just on ancestor cycles. The root `blockObjects`
entry materializes the fields exactly once, and `getSubSchema`
resolves bare references against exactly that collection (the
`@portabletext/schema` 2.2.3 contract). The check is keyed by
canonical instance rather than name, so an inline declaration that
merely shares a name with a root type keeps its own inline shape. The
oracle's vendored recursive reference gains the same emission rule,
keeping the oracle pinned to what it exists to check: that the
iterative mechanics match the recursive ones.

The mutually-embedding benchmark now also bounds
`JSON.stringify(schema).length`, the assertion whose absence let a
57 MB output ship green, and a new pipeline test runs
convert-then-`compileSchema` on the reported shape (25 containers,
recursive, annotation-rich) and bounds both tree size and end-to-end
time.

Author: christianhg

.changeset/bridge-definition-tree-size.md

@@ -0,0 +1,9 @@
+---
+'@portabletext/sanity-bridge': patch
+---
+
+fix: reference root block objects by name at every nested position
+
+Converting a Sanity schema whose types recurse back into the shared Portable Text array (containers, table cells, sidebars embedding `blockContent`) produced a definition that was cheap to build but factorially large as a tree: each type's single expansion inlined the expansions of every other type not on its first-visit path. Studios with wide mutually recursive schemas froze and ran out of memory on document open, not during the conversion itself but when the result was compiled, rendered, or serialized downstream.
+
+Members that are root block objects now emit a bare `{type: name}` reference at every nested position, and their fields are materialized exactly once in the root `blockObjects`. The emitted definition is linear in the schema size, and `getSubSchema` (which has resolved bare references against root block objects since `@portabletext/schema` 2.2.3) resolves them as before. Inline declarations that merely share a name with a root type keep their own inline shape. Resolving these references requires `@portabletext/schema` 2.2.3 or later in the tree: guaranteed from `@portabletext/editor` 7.10.7, and satisfied by any fresh install of earlier 7.x releases (their `^2.2.2` range accepts it), so only lockfiles that pin `@portabletext/schema` at 2.2.2 or older need a refresh.

packages/sanity-bridge/src/mutually-embedding-types-performance.test.ts

@@ -67,6 +67,17 @@ describe('mutually-embedding block objects', () => {
     // Generous bound - the conversion takes ~1ms when linear, while the
     // unmemoized walk does not finish in any practical amount of time.
     expect(durationMs).toBeLessThan(2_000)
+
+    // The emitted definition must be small AS A TREE, not merely cheap to
+    // build. The memoized walk builds shared `OfDefinition` objects (a
+    // DAG) in linear time, but before root block objects referenced by
+    // name at every position, each type's single expansion inlined the
+    // expansions of every type not on its first-visit ancestor path:
+    // 57 MB serialized for these 12 types, out-of-memory in real studios
+    // with ~25. Every consumer walks the tree (`compileSchema`, React,
+    // serialization), so tree size is the contract, and conversion time
+    // alone cannot pin it.
+    expect(JSON.stringify(schema).length).toBeLessThan(100_000)
   }, 10_000)
 
   test('a marketing-site schema converts to a PTE schema that container resolution can walk at every depth', () => {

packages/sanity-bridge/src/recursive-schema-pipeline.test.ts

@@ -0,0 +1,148 @@
+import {compileSchema} from '@portabletext/schema'
+import {Schema as SanitySchema} from '@sanity/schema'
+import {expect, test} from 'vitest'
+import {sanitySchemaToPortableTextSchema} from './sanity-schema-to-portable-text-schema'
+
+/**
+ * Regression test for the field-reported Studio freeze/OOM on doc-open
+ * with a large mutually recursive block schema: ~25 members where several
+ * container types recurse back into the shared Portable Text array.
+ *
+ * The conversion builds shared `OfDefinition` objects, so it is fast
+ * regardless of the emitted shape; the failure lived in the output's
+ * TREE size, which everything downstream walks. This test runs the
+ * pipeline a studio runs, convert from the document field's type, then
+ * `compileSchema`, and bounds both the tree size and the end-to-end
+ * time. Before root block objects referenced by name at every position,
+ * this shape exhausted the heap.
+ */
+test('a wide mutually recursive schema converts and compiles small and fast', () => {
+  const containerCount = 25
+  const types: Array<Record<string, unknown>> = []
+  const memberRefs: Array<Record<string, unknown>> = [
+    {
+      type: 'block',
+      marks: {
+        annotations: Array.from({length: 8}, (_, index) => ({
+          type: 'object',
+          name: `annotation${index}`,
+          fields: [{name: 'href', type: 'string'}],
+        })),
+      },
+    },
+  ]
+  for (let index = 0; index < containerCount; index++) {
+    types.push({
+      type: 'object',
+      name: `container${index}`,
+      fields: [
+        {name: 'label', type: 'string'},
+        {name: 'content', type: 'blockContent'},
+      ],
+    })
+    memberRefs.push({type: `container${index}`})
+  }
+  types.push({type: 'array', name: 'blockContent', of: memberRefs})
+  types.push({
+    type: 'document',
+    name: 'article',
+    fields: [{name: 'body', type: 'blockContent'}],
+  })
+
+  const sanitySchema = SanitySchema.compile({name: 'test', types})
+  const article = sanitySchema.get('article') as unknown as {
+    fields: Array<{name: string; type: unknown}>
+  }
+  const bodyType = article.fields.find((field) => field.name === 'body')!.type
+
+  const startedAt = performance.now()
+  const definition = sanitySchemaToPortableTextSchema(bodyType as never)
+  const compiled = compileSchema(definition as never)
+  const durationMs = performance.now() - startedAt
+
+  expect(definition.blockObjects).toHaveLength(containerCount)
+  expect(compiled.blockObjects).toHaveLength(containerCount)
+  expect(JSON.stringify(definition).length).toBeLessThan(200_000)
+  expect(durationMs).toBeLessThan(2_000)
+})
+
+/**
+ * Root block objects are referenced by name at every nested position, but
+ * the check is keyed by the compiled type instance, not the name: an
+ * inline declaration that merely shares a root type's name is a different
+ * instance and must keep its own inline shape. A name-keyed check would
+ * stub it, and resolution would silently hand back the root type's
+ * fields.
+ */
+test('an inline declaration sharing a root type name keeps its own shape', () => {
+  const sanitySchema = SanitySchema.compile({
+    name: 'test',
+    types: [
+      {
+        type: 'array',
+        name: 'blockContent',
+        of: [{type: 'block'}, {type: 'card'}, {type: 'holder'}],
+      },
+      {
+        type: 'object',
+        name: 'card',
+        fields: [{name: 'rootField', type: 'string'}],
+      },
+      {
+        type: 'object',
+        name: 'holder',
+        fields: [
+          {
+            name: 'items',
+            type: 'array',
+            of: [
+              {
+                type: 'object',
+                name: 'card',
+                fields: [{name: 'nestedField', type: 'number'}],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  })
+
+  const definition = sanitySchemaToPortableTextSchema(
+    sanitySchema.get('blockContent') as never,
+  )
+
+  const holder = definition.blockObjects.find(
+    (blockObject) => blockObject.name === 'holder',
+  )
+  expect(holder).toEqual({
+    name: 'holder',
+    title: 'Holder',
+    fields: [
+      {
+        name: 'items',
+        type: 'array',
+        title: 'Items',
+        of: [
+          {
+            type: 'object',
+            name: 'card',
+            title: 'Card',
+            fields: [
+              {name: 'nestedField', type: 'number', title: 'Nested Field'},
+            ],
+          },
+        ],
+      },
+    ],
+  })
+
+  const card = definition.blockObjects.find(
+    (blockObject) => blockObject.name === 'card',
+  )
+  expect(card).toEqual({
+    name: 'card',
+    title: 'Card',
+    fields: [{name: 'rootField', type: 'string', title: 'Root Field'}],
+  })
+})

packages/sanity-bridge/src/sanity-schema-to-portable-text-schema.oracle.test.ts

@@ -199,6 +199,8 @@ describe('conversion oracle', () => {
  *   </EditorProvider>
  * ```
  */
+let referenceRootBlockObjects = new Set<SchemaType>()
+
 function referenceSanitySchemaToPortableTextSchema(
   sanitySchema: ArraySchemaType<unknown> | ArrayDefinition,
 ): Schema {
@@ -265,6 +267,8 @@ function sanitySchemaTypeToSchema(
   // mutually-embedding types, which grows combinatorially.
   const memo = new Map<SchemaType, OfDefinition>()
 
+  referenceRootBlockObjects = new Set<SchemaType>(blockObjectTypes)
+
   return {
     block: {
       name: blockType.name,
@@ -468,9 +472,13 @@ function sanityOfMemberToOfDefinition(
     'fields' in memberType &&
     Array.isArray((memberType as ObjectSchemaType).fields)
 
-  if (!hasFields || ancestorNames.has(memberType.name)) {
-    // Bare reference. The editor's resolver looks up `memberType.name`
-    // in `blockObjects` / `inlineObjects`.
+  if (
+    !hasFields ||
+    ancestorNames.has(memberType.name) ||
+    referenceRootBlockObjects.has(memberType)
+  ) {
+    // Bare reference, mirroring the production emission rule: root block
+    // objects reference by name at every nested position.
     return {
       type: memberType.name,
       ...(memberType.title ? {title: memberType.title} : {}),

packages/sanity-bridge/src/sanity-schema-to-portable-text-schema.ts

@@ -122,6 +122,7 @@ function sanitySchemaTypeToSchema(
     distinctAncestorCount: 0,
     memo: new Map<SchemaType, OfDefinition>(),
     inFlight: new Map<unknown, Array<number>>(),
+    rootBlockObjects: new Set<SchemaType>(blockObjectTypes),
   }
   const pendingWork: Array<Work> = []
 
@@ -227,6 +228,21 @@ type Conversion = {
    * overflowed the stack.
    */
   inFlight: Map<unknown, Array<number>>
+  /**
+   * The canonical instances of the root-level block object types. Members
+   * reaching one of these at any `of` position emit a bare
+   * `{type: name}` reference instead of an inline expansion: the root
+   * `blockObjects` entry materializes the fields exactly once, and
+   * `getSubSchema` resolves bare references against that collection.
+   * Without this, each type's single memoized expansion inlines the
+   * expansions of every type not on its first-visit ancestor path, and
+   * the emitted definition, while cheap to build as a shared DAG, is
+   * factorially large as a tree, which is what every consumer
+   * (`compileSchema`, React, serialization) walks. Keyed by instance so
+   * a same-named but structurally different inline declaration keeps its
+   * own inline shape.
+   */
+  rootBlockObjects: Set<SchemaType>
 }
 
 function pushAncestor(conversion: Conversion, name: string): void {
@@ -405,9 +421,15 @@ function scheduleOfMember(
     'fields' in memberType &&
     Array.isArray((memberType as ObjectSchemaType).fields)
 
-  if (!hasFields || hasAncestor(conversion, memberType.name)) {
+  if (
+    !hasFields ||
+    hasAncestor(conversion, memberType.name) ||
+    conversion.rootBlockObjects.has(memberType)
+  ) {
     // Bare reference. The editor's resolver looks up `memberType.name`
-    // in `blockObjects` / `inlineObjects`.
+    // in the root `blockObjects`. Root block objects take this branch at
+    // every nested position, not just on cycles; see
+    // `Conversion.rootBlockObjects`.
     target[index] = {
       type: memberType.name,
       ...(memberType.title ? {title: memberType.title} : {}),