create-visualbuild-app 0.1.0 → 1.0.1

package/visual-app-builder/server/parseReactPage.ts

@@ -1,571 +1,776 @@
-import { randomUUID } from 'node:crypto'
-import { parse } from '@babel/parser'
-
-export interface ImportedVisualNode {
-  id: string
-  type: string
-  label?: string
-  props: Record<string, unknown>
-  children: ImportedVisualNode[]
-}
-
-export interface ImportedPageTree {
-  root: ImportedVisualNode
-  components: ImportedVisualNode[]
-}
-
-type AstNode = {
-  type: string
-  [key: string]: unknown
-}
-
-const supportedVisualTags = new Set([
-  'header',
-  'main',
-  'div',
-  'section',
-  'nav',
-  'article',
-  'aside',
-  'footer',
-  'address',
-  'hgroup',
-  'h1',
-  'h2',
-  'h3',
-  'h4',
-  'h5',
-  'h6',
-  'p',
-  'br',
-  'hr',
-  'pre',
-  'blockquote',
-  'span',
-  'strong',
-  'b',
-  'em',
-  'i',
-  'u',
-  's',
-  'small',
-  'mark',
-  'sub',
-  'sup',
-  'code',
-  'kbd',
-  'samp',
-  'var',
-  'abbr',
-  'cite',
-  'q',
-  'time',
-  'a',
-  'ul',
-  'ol',
-  'li',
-  'dl',
-  'dt',
-  'dd',
-  'menu',
-  'button',
-  'img',
-  'picture',
-  'source',
-  'figure',
-  'figcaption',
-  'video',
-  'audio',
-  'iframe',
-  'canvas',
-  'svg',
-  'form',
-  'label',
-  'input',
-  'textarea',
-  'select',
-  'option',
-  'optgroup',
-  'fieldset',
-  'legend',
-  'datalist',
-  'output',
-  'progress',
-  'meter',
-  'table',
-  'caption',
-  'thead',
-  'tbody',
-  'tfoot',
-  'tr',
-  'th',
-  'td',
-  'colgroup',
-  'col',
-  'details',
-  'summary',
-  'dialog',
-])
-
-export class StaticJsxImportError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'StaticJsxImportError'
-  }
-}
-
-export function parseReactPageSource(
-  source: string,
-  filename = 'Page.tsx'
-): ImportedPageTree {
-  let program: AstNode
-
-  try {
-    program = parse(source, {
-      sourceType: 'module',
-      sourceFilename: filename,
-      plugins: ['jsx', 'typescript'],
-    }).program as unknown as AstNode
-  } catch (error) {
-    throw new StaticJsxImportError(formatParserError(error))
-  }
-
-  const returnedJsx = findReturnedJsx(program)
-
-  if (!returnedJsx) {
-    throw new StaticJsxImportError(
-      'The managed page must return one static JSX element or fragment.'
-    )
-  }
-
-  return convertReturnedJsx(returnedJsx)
-}
-
-export function reconcileImportedTree(
-  imported: ImportedPageTree,
-  current: ImportedPageTree
-): ImportedPageTree {
-  return {
-    root: reconcileNode(imported.root, current.root, current.root.id),
-    components: reconcileNodeList(imported.components, current.components),
-  }
-}
-
-export function visualTreesEqual(
-  first: ImportedPageTree,
-  second: ImportedPageTree
-) {
-  return JSON.stringify(canonicalize(first)) === JSON.stringify(canonicalize(second))
-}
-
-function findReturnedJsx(program: AstNode) {
-  const body = asNodeArray(program.body)
-  const defaultExport = body.find(
-    (node) => node.type === 'ExportDefaultDeclaration'
-  )
-
-  if (defaultExport) {
-    const declaration = asNode(defaultExport.declaration)
-    const resolved = resolveExportedDeclaration(declaration, body)
-    const result = findJsxInFunction(resolved)
-
-    if (result) return result
-  }
-
-  for (const statement of body) {
-    const result = findJsxInFunction(statement)
-
-    if (result) return result
-  }
-
-  return null
-}
-
-function resolveExportedDeclaration(
-  declaration: AstNode | null,
-  body: AstNode[]
-) {
-  if (!declaration || declaration.type !== 'Identifier') {
-    return declaration
-  }
-
-  const name = String(declaration.name ?? '')
-
-  for (const statement of body) {
-    if (
-      statement.type === 'FunctionDeclaration' &&
-      asNode(statement.id)?.name === name
-    ) {
-      return statement
-    }
-
-    if (statement.type === 'VariableDeclaration') {
-      for (const item of asNodeArray(statement.declarations)) {
-        if (asNode(item.id)?.name === name) {
-          return asNode(item.init)
-        }
-      }
-    }
-  }
-
-  return declaration
-}
-
-function findJsxInFunction(node: AstNode | null): AstNode | null {
-  if (!node) return null
-
-  if (
-    node.type === 'ArrowFunctionExpression' ||
-    node.type === 'FunctionExpression' ||
-    node.type === 'FunctionDeclaration'
-  ) {
-    const body = unwrapExpression(asNode(node.body))
-
-    if (isJsx(body)) return body
-    return findReturnStatement(body)
-  }
-
-  if (node.type === 'ExportNamedDeclaration') {
-    return findJsxInFunction(asNode(node.declaration))
-  }
-
-  if (node.type === 'VariableDeclaration') {
-    for (const item of asNodeArray(node.declarations)) {
-      const result = findJsxInFunction(asNode(item.init))
-      if (result) return result
-    }
-  }
-
-  return null
-}
-
-function findReturnStatement(node: AstNode | null): AstNode | null {
-  if (!node) return null
-
-  if (node.type === 'ReturnStatement') {
-    const argument = unwrapExpression(asNode(node.argument))
-    return isJsx(argument) ? argument : null
-  }
-
-  for (const value of Object.values(node)) {
-    if (Array.isArray(value)) {
-      for (const child of value) {
-        const result = findReturnStatement(asNode(child))
-        if (result) return result
-      }
-    } else {
-      const child = asNode(value)
-      const result = findReturnStatement(child)
-      if (result) return result
-    }
-  }
-
-  return null
-}
-
-function unwrapExpression(node: AstNode | null): AstNode | null {
-  if (
-    node &&
-    [
-      'ParenthesizedExpression',
-      'TSAsExpression',
-      'TSTypeAssertion',
-      'TSSatisfiesExpression',
-    ].includes(node.type)
-  ) {
-    return unwrapExpression(asNode(node.expression))
-  }
-
-  return node
-}
-
-function isJsx(node: AstNode | null): node is AstNode {
-  return Boolean(
-    node &&
-      ['JSXElement', 'JSXFragment'].includes(node.type)
-  )
-}
-
-function convertReturnedJsx(jsx: AstNode): ImportedPageTree {
-  if (jsx.type === 'JSXFragment') {
-    return {
-      root: createImportedNode('main', { className: 'min-h-screen' }),
-      components: convertJsxChildren(asNodeArray(jsx.children)),
-    }
-  }
-
-  const root = convertJsxElement(jsx)
-  const components = [...root.children]
-  const text = String(root.props.text ?? '').trim()
-
-  if (text) {
-    components.unshift(createImportedNode('span', { text, className: '' }))
-    delete root.props.text
-  }
-
-  root.children = []
-  return { root, components }
-}
-
-function convertJsxElement(jsx: AstNode): ImportedVisualNode {
-  const opening = asNode(jsx.openingElement)
-  const nameNode = asNode(opening?.name)
-
-  if (!opening || !nameNode || nameNode.type !== 'JSXIdentifier') {
-    throw new StaticJsxImportError(
-      'Namespaced tags and member-expression components are not supported.'
-    )
-  }
-
-  const tagName = String(nameNode.name ?? '')
-
-  if (!supportedVisualTags.has(tagName)) {
-    throw new StaticJsxImportError(
-      `Unsupported JSX element <${tagName}>. Reverse sync currently accepts standard HTML tags only.`
-    )
-  }
-
-  const props = convertJsxAttributes(asNodeArray(opening.attributes))
-  const rawChildren = asNodeArray(jsx.children)
-  const childItems = convertChildItems(rawChildren)
-  const hasElementChild = childItems.some(
-    (item) => typeof item !== 'string'
-  )
-  const children = childItems.flatMap((item) =>
-    typeof item === 'string'
-      ? hasElementChild
-        ? [createImportedNode('span', { text: item, className: '' })]
-        : []
-      : [item]
-  )
-  const directText = childItems
-    .filter((item): item is string => typeof item === 'string')
-    .join(' ')
-    .trim()
-
-  if (directText && !hasElementChild) {
-    props.text = directText
-  }
-
-  return createImportedNode(tagName, props, children)
-}
-
-function convertJsxAttributes(attributes: AstNode[]) {
-  const props: Record<string, unknown> = {}
-
-  for (const attribute of attributes) {
-    if (attribute.type === 'JSXSpreadAttribute') {
-      throw new StaticJsxImportError(
-        'Spread attributes are not supported by reverse sync.'
-      )
-    }
-
-    if (attribute.type !== 'JSXAttribute') continue
-    const nameNode = asNode(attribute.name)
-
-    if (!nameNode || nameNode.type !== 'JSXIdentifier') {
-      throw new StaticJsxImportError('Only standard JSX attributes are supported.')
-    }
-
-    const rawName = String(nameNode.name ?? '')
-    const name = rawName === 'class' ? 'className' : rawName
-    const valueNode = asNode(attribute.value)
-
-    if (!valueNode) {
-      props[name] = true
-      continue
-    }
-
-    if (valueNode.type === 'StringLiteral') {
-      props[name] = valueNode.value
-      continue
-    }
-
-    if (valueNode.type === 'JSXExpressionContainer') {
-      const value = getStaticExpressionValue(asNode(valueNode.expression))
-
-      if (value === undefined) {
-        throw new StaticJsxImportError(
-          `Attribute "${name}" must use a static string, number, boolean, or null.`
-        )
-      }
-
-      props[name] = value
-      continue
-    }
-
-    throw new StaticJsxImportError(
-      `Attribute "${name}" uses unsupported JSX syntax.`
-    )
-  }
-
-  return props
-}
-
-function getStaticExpressionValue(node: AstNode | null): unknown {
-  const value = unwrapExpression(node)
-
-  if (!value) return undefined
-  if (value.type === 'StringLiteral' || value.type === 'NumericLiteral') {
-    return value.value
-  }
-  if (value.type === 'BooleanLiteral') return value.value
-  if (value.type === 'NullLiteral') return null
-  if (
-    value.type === 'TemplateLiteral' &&
-    asNodeArray(value.expressions).length === 0
-  ) {
-    return asNodeArray(value.quasis)
-      .map((quasi) => String(asNode(quasi.value)?.cooked ?? ''))
-      .join('')
-  }
-  if (value.type === 'UnaryExpression' && value.operator === '-') {
-    const argument = asNode(value.argument)
-    if (argument?.type === 'NumericLiteral') {
-      return -Number(argument.value)
-    }
-  }
-
-  return undefined
-}
-
-function convertJsxChildren(children: AstNode[]) {
-  return convertChildItems(children).flatMap((item) =>
-    typeof item === 'string'
-      ? [createImportedNode('span', { text: item, className: '' })]
-      : [item]
-  )
-}
-
-function convertChildItems(children: AstNode[]) {
-  const result: Array<string | ImportedVisualNode> = []
-
-  for (const child of children) {
-    if (child.type === 'JSXElement') {
-      result.push(convertJsxElement(child))
-      continue
-    }
-
-    if (child.type === 'JSXFragment') {
-      result.push(...convertChildItems(asNodeArray(child.children)))
-      continue
-    }
-
-    if (child.type === 'JSXText') {
-      const text = normalizeJsxText(String(child.value ?? ''))
-      if (text) result.push(text)
-      continue
-    }
-
-    if (child.type === 'JSXExpressionContainer') {
-      const expression = asNode(child.expression)
-
-      if (expression?.type === 'JSXEmptyExpression') continue
-      const value = getStaticExpressionValue(expression)
-
-      if (typeof value === 'string' || typeof value === 'number') {
-        result.push(String(value))
-        continue
-      }
-
-      throw new StaticJsxImportError(
-        'Dynamic JSX expressions are not supported by reverse sync.'
-      )
-    }
-
-    if (child.type === 'JSXSpreadChild') {
-      throw new StaticJsxImportError(
-        'Spread children are not supported by reverse sync.'
-      )
-    }
-  }
-
-  return result
-}
-
-function normalizeJsxText(value: string) {
-  return value.replace(/\s+/g, ' ').trim()
-}
-
-function canonicalize(value: unknown): unknown {
-  if (Array.isArray(value)) {
-    return value.map(canonicalize)
-  }
-
-  if (value && typeof value === 'object') {
-    return Object.fromEntries(
-      Object.entries(value)
-        .filter(([, entryValue]) => entryValue !== undefined)
-        .sort(([firstKey], [secondKey]) => firstKey.localeCompare(secondKey))
-        .map(([key, entryValue]) => [key, canonicalize(entryValue)])
-    )
-  }
-
-  return value
-}
-
-function reconcileNodeList(
-  imported: ImportedVisualNode[],
-  current: ImportedVisualNode[]
-) {
-  const used = new Set<number>()
-
-  return imported.map((node, index) => {
-    let matchIndex =
-      current[index]?.type === node.type
-        ? index
-        : current.findIndex(
-            (candidate, candidateIndex) =>
-              !used.has(candidateIndex) && candidate.type === node.type
-          )
-
-    if (matchIndex < 0 || used.has(matchIndex)) matchIndex = -1
-    if (matchIndex >= 0) used.add(matchIndex)
-
-    return reconcileNode(node, current[matchIndex] ?? null)
-  })
-}
-
-function reconcileNode(
-  imported: ImportedVisualNode,
-  current: ImportedVisualNode | null,
-  forcedId?: string
-): ImportedVisualNode {
-  return {
-    ...imported,
-    id: forcedId ?? current?.id ?? imported.id,
-    label: current?.label ?? imported.label,
-    children: reconcileNodeList(imported.children, current?.children ?? []),
-  }
-}
-
-function createImportedNode(
-  type: string,
-  props: Record<string, unknown>,
-  children: ImportedVisualNode[] = []
-): ImportedVisualNode {
-  return {
-    id: randomUUID(),
-    type,
-    props,
-    children,
-  }
-}
-
-function asNode(value: unknown): AstNode | null {
-  return value && typeof value === 'object' && 'type' in value
-    ? (value as AstNode)
-    : null
-}
-
-function asNodeArray(value: unknown): AstNode[] {
-  return Array.isArray(value)
-    ? value.map(asNode).filter((node): node is AstNode => Boolean(node))
-    : []
-}
-
-function formatParserError(error: unknown) {
-  if (!(error instanceof Error)) return 'The page contains invalid JSX.'
-  const location = error.message.match(/\(\d+:\d+\)/)?.[0]
-  return `Unable to parse the managed page${location ? ` at ${location}` : ''}: ${error.message}`
-}
+import { randomUUID } from 'node:crypto'
+import { parse } from '@babel/parser'
+
+export interface ImportedVisualNode {
+  id: string
+  type: string
+  label?: string
+  props: Record<string, unknown>
+  children: ImportedVisualNode[]
+}
+
+export interface ImportedPageTree {
+  root: ImportedVisualNode
+  components: ImportedVisualNode[]
+}
+
+export interface ImportedComponentPreview {
+  rootTag: string
+  rootProps: Record<string, unknown>
+  children: ImportedVisualNode[]
+  rendersChildren: boolean
+}
+
+export const componentChildrenSlotType =
+  '__visualbuild_children_slot__'
+
+type AstNode = {
+  type: string
+  [key: string]: unknown
+}
+
+const supportedVisualTags = new Set([
+  'header',
+  'main',
+  'div',
+  'section',
+  'nav',
+  'article',
+  'aside',
+  'footer',
+  'address',
+  'hgroup',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'br',
+  'hr',
+  'pre',
+  'blockquote',
+  'span',
+  'strong',
+  'b',
+  'em',
+  'i',
+  'u',
+  's',
+  'small',
+  'mark',
+  'sub',
+  'sup',
+  'code',
+  'kbd',
+  'samp',
+  'var',
+  'abbr',
+  'cite',
+  'q',
+  'time',
+  'a',
+  'ul',
+  'ol',
+  'li',
+  'dl',
+  'dt',
+  'dd',
+  'menu',
+  'button',
+  'img',
+  'picture',
+  'source',
+  'figure',
+  'figcaption',
+  'video',
+  'audio',
+  'iframe',
+  'canvas',
+  'svg',
+  'form',
+  'label',
+  'input',
+  'textarea',
+  'select',
+  'option',
+  'optgroup',
+  'fieldset',
+  'legend',
+  'datalist',
+  'output',
+  'progress',
+  'meter',
+  'table',
+  'caption',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'th',
+  'td',
+  'colgroup',
+  'col',
+  'details',
+  'summary',
+  'dialog',
+])
+
+export class StaticJsxImportError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'StaticJsxImportError'
+  }
+}
+
+export function parseReactPageSource(
+  source: string,
+  filename = 'Page.tsx',
+  customComponentNames: Iterable<string> = []
+): ImportedPageTree {
+  let program: AstNode
+
+  try {
+    program = parse(source, {
+      sourceType: 'module',
+      sourceFilename: filename,
+      plugins: ['jsx', 'typescript'],
+    }).program as unknown as AstNode
+  } catch (error) {
+    throw new StaticJsxImportError(formatParserError(error))
+  }
+
+  const returnedJsx = findReturnedJsx(program)
+
+  if (!returnedJsx) {
+    throw new StaticJsxImportError(
+      'The managed page must return one static JSX element or fragment.'
+    )
+  }
+
+  return convertReturnedJsx(returnedJsx, new Set(customComponentNames))
+}
+
+export function parseReactComponentPreview(
+  source: string,
+  filename = 'Component.tsx',
+  customComponentNames: Iterable<string> = []
+): ImportedComponentPreview {
+  let program: AstNode
+
+  try {
+    program = parse(source, {
+      sourceType: 'module',
+      sourceFilename: filename,
+      plugins: ['jsx', 'typescript'],
+    }).program as unknown as AstNode
+  } catch (error) {
+    throw new StaticJsxImportError(formatParserError(error))
+  }
+
+  const returnedJsx = findReturnedJsx(program)
+
+  if (!returnedJsx) {
+    throw new StaticJsxImportError(
+      'The component must return one static JSX element or fragment.'
+    )
+  }
+
+  const tree = convertReturnedJsx(
+    returnedJsx,
+    new Set(customComponentNames),
+    true
+  )
+
+  return {
+    rootTag: tree.root.type,
+    rootProps: tree.root.props,
+    children: tree.components,
+    rendersChildren: containsNodeType(
+      tree.components,
+      componentChildrenSlotType
+    ),
+  }
+}
+
+export function reconcileImportedTree(
+  imported: ImportedPageTree,
+  current: ImportedPageTree,
+  customComponentNames: Iterable<string> = []
+): ImportedPageTree {
+  const customTypes = new Set(customComponentNames)
+
+  return {
+    root: reconcileNode(
+      imported.root,
+      current.root,
+      current.root.id,
+      customTypes
+    ),
+    components: reconcileNodeList(
+      imported.components,
+      current.components,
+      customTypes
+    ),
+  }
+}
+
+export function visualTreesEqual(
+  first: ImportedPageTree,
+  second: ImportedPageTree
+) {
+  return JSON.stringify(canonicalize(first)) === JSON.stringify(canonicalize(second))
+}
+
+function findReturnedJsx(program: AstNode) {
+  const body = asNodeArray(program.body)
+  const defaultExport = body.find(
+    (node) => node.type === 'ExportDefaultDeclaration'
+  )
+
+  if (defaultExport) {
+    const declaration = asNode(defaultExport.declaration)
+    const resolved = resolveExportedDeclaration(declaration, body)
+    const result = findJsxInFunction(resolved)
+
+    if (result) return result
+  }
+
+  for (const statement of body) {
+    const result = findJsxInFunction(statement)
+
+    if (result) return result
+  }
+
+  return null
+}
+
+function resolveExportedDeclaration(
+  declaration: AstNode | null,
+  body: AstNode[]
+) {
+  if (!declaration || declaration.type !== 'Identifier') {
+    return declaration
+  }
+
+  const name = String(declaration.name ?? '')
+
+  for (const statement of body) {
+    if (
+      statement.type === 'FunctionDeclaration' &&
+      asNode(statement.id)?.name === name
+    ) {
+      return statement
+    }
+
+    if (statement.type === 'VariableDeclaration') {
+      for (const item of asNodeArray(statement.declarations)) {
+        if (asNode(item.id)?.name === name) {
+          return asNode(item.init)
+        }
+      }
+    }
+  }
+
+  return declaration
+}
+
+function findJsxInFunction(node: AstNode | null): AstNode | null {
+  if (!node) return null
+
+  if (
+    node.type === 'ArrowFunctionExpression' ||
+    node.type === 'FunctionExpression' ||
+    node.type === 'FunctionDeclaration'
+  ) {
+    const body = unwrapExpression(asNode(node.body))
+
+    if (isJsx(body)) return body
+    return findReturnStatement(body)
+  }
+
+  if (node.type === 'ExportNamedDeclaration') {
+    return findJsxInFunction(asNode(node.declaration))
+  }
+
+  if (node.type === 'VariableDeclaration') {
+    for (const item of asNodeArray(node.declarations)) {
+      const result = findJsxInFunction(asNode(item.init))
+      if (result) return result
+    }
+  }
+
+  return null
+}
+
+function findReturnStatement(node: AstNode | null): AstNode | null {
+  if (!node) return null
+
+  if (node.type === 'ReturnStatement') {
+    const argument = unwrapExpression(asNode(node.argument))
+    return isJsx(argument) ? argument : null
+  }
+
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        const result = findReturnStatement(asNode(child))
+        if (result) return result
+      }
+    } else {
+      const child = asNode(value)
+      const result = findReturnStatement(child)
+      if (result) return result
+    }
+  }
+
+  return null
+}
+
+function unwrapExpression(node: AstNode | null): AstNode | null {
+  if (
+    node &&
+    [
+      'ParenthesizedExpression',
+      'TSAsExpression',
+      'TSTypeAssertion',
+      'TSSatisfiesExpression',
+    ].includes(node.type)
+  ) {
+    return unwrapExpression(asNode(node.expression))
+  }
+
+  return node
+}
+
+function isJsx(node: AstNode | null): node is AstNode {
+  return Boolean(
+    node &&
+      ['JSXElement', 'JSXFragment'].includes(node.type)
+  )
+}
+
+function convertReturnedJsx(
+  jsx: AstNode,
+  customComponentNames: Set<string>,
+  allowChildrenSlot = false
+): ImportedPageTree {
+  if (jsx.type === 'JSXFragment') {
+    return {
+      root: createImportedNode('main', { className: 'min-h-screen' }),
+      components: convertJsxChildren(
+        asNodeArray(jsx.children),
+        customComponentNames,
+        allowChildrenSlot
+      ),
+    }
+  }
+
+  const root = convertJsxElement(
+    jsx,
+    customComponentNames,
+    allowChildrenSlot
+  )
+  const components = [...root.children]
+  const text = String(root.props.text ?? '').trim()
+
+  if (text) {
+    components.unshift(createImportedNode('span', { text, className: '' }))
+    delete root.props.text
+  }
+
+  root.children = []
+  return { root, components }
+}
+
+function convertJsxElement(
+  jsx: AstNode,
+  customComponentNames: Set<string>,
+  allowChildrenSlot = false
+): ImportedVisualNode {
+  const opening = asNode(jsx.openingElement)
+  const nameNode = asNode(opening?.name)
+
+  if (!opening || !nameNode || nameNode.type !== 'JSXIdentifier') {
+    throw new StaticJsxImportError(
+      'Namespaced tags and member-expression components are not supported.'
+    )
+  }
+
+  const tagName = String(nameNode.name ?? '')
+
+  if (
+    !supportedVisualTags.has(tagName) &&
+    !customComponentNames.has(tagName)
+  ) {
+    throw new StaticJsxImportError(
+      `Unsupported JSX element <${tagName}>. Register the component before using it in a managed page.`
+    )
+  }
+
+  const props = convertJsxAttributes(asNodeArray(opening.attributes))
+  const rawChildren = asNodeArray(jsx.children)
+  const childItems = convertChildItems(
+    rawChildren,
+    customComponentNames,
+    allowChildrenSlot
+  )
+  const hasElementChild = childItems.some(
+    (item) => typeof item !== 'string'
+  )
+  const children = childItems.flatMap((item) =>
+    typeof item === 'string'
+      ? hasElementChild
+        ? [createImportedNode('span', { text: item, className: '' })]
+        : []
+      : [item]
+  )
+  const directText = childItems
+    .filter((item): item is string => typeof item === 'string')
+    .join(' ')
+    .trim()
+
+  if (directText && !hasElementChild) {
+    props.text = directText
+  }
+
+  const wrappedComponentName = String(
+    props['data-visualbuild-component'] ?? ''
+  )
+  const wrappedComponent = children.find(
+    (child) =>
+      child.type === wrappedComponentName &&
+      customComponentNames.has(child.type)
+  )
+
+  if (wrappedComponent) {
+    const additionalAttributes = Object.fromEntries(
+      Object.entries(props).filter(
+        ([name]) =>
+          ![
+            'data-visualbuild-component',
+            'id',
+            'className',
+            'text',
+          ].includes(name)
+      )
+    )
+
+    return createImportedNode(
+      wrappedComponent.type,
+      {
+        ...wrappedComponent.props,
+        wrapperTag: tagName,
+        id: props.id ?? '',
+        className: props.className ?? '',
+        attributes: additionalAttributes,
+      },
+      wrappedComponent.children
+    )
+  }
+
+  return createImportedNode(tagName, props, children)
+}
+
+function convertJsxAttributes(attributes: AstNode[]) {
+  const props: Record<string, unknown> = {}
+
+  for (const attribute of attributes) {
+    if (attribute.type === 'JSXSpreadAttribute') {
+      throw new StaticJsxImportError(
+        'Spread attributes are not supported by reverse sync.'
+      )
+    }
+
+    if (attribute.type !== 'JSXAttribute') continue
+    const nameNode = asNode(attribute.name)
+
+    if (!nameNode || nameNode.type !== 'JSXIdentifier') {
+      throw new StaticJsxImportError('Only standard JSX attributes are supported.')
+    }
+
+    const rawName = String(nameNode.name ?? '')
+    const name = rawName === 'class' ? 'className' : rawName
+    const valueNode = asNode(attribute.value)
+
+    if (!valueNode) {
+      props[name] = true
+      continue
+    }
+
+    if (valueNode.type === 'StringLiteral') {
+      props[name] = valueNode.value
+      continue
+    }
+
+    if (valueNode.type === 'JSXExpressionContainer') {
+      const value = getStaticExpressionValue(asNode(valueNode.expression))
+
+      if (value === undefined) {
+        throw new StaticJsxImportError(
+          `Attribute "${name}" must use a static string, number, boolean, or null.`
+        )
+      }
+
+      props[name] = value
+      continue
+    }
+
+    throw new StaticJsxImportError(
+      `Attribute "${name}" uses unsupported JSX syntax.`
+    )
+  }
+
+  return props
+}
+
+function getStaticExpressionValue(node: AstNode | null): unknown {
+  const value = unwrapExpression(node)
+
+  if (!value) return undefined
+  if (value.type === 'StringLiteral' || value.type === 'NumericLiteral') {
+    return value.value
+  }
+  if (value.type === 'BooleanLiteral') return value.value
+  if (value.type === 'NullLiteral') return null
+  if (
+    value.type === 'TemplateLiteral' &&
+    asNodeArray(value.expressions).length === 0
+  ) {
+    return asNodeArray(value.quasis)
+      .map((quasi) => String(asNode(quasi.value)?.cooked ?? ''))
+      .join('')
+  }
+  if (value.type === 'UnaryExpression' && value.operator === '-') {
+    const argument = asNode(value.argument)
+    if (argument?.type === 'NumericLiteral') {
+      return -Number(argument.value)
+    }
+  }
+
+  return undefined
+}
+
+function convertJsxChildren(
+  children: AstNode[],
+  customComponentNames: Set<string>,
+  allowChildrenSlot = false
+) {
+  return convertChildItems(
+    children,
+    customComponentNames,
+    allowChildrenSlot
+  ).flatMap((item) =>
+      typeof item === 'string'
+        ? [createImportedNode('span', { text: item, className: '' })]
+        : [item]
+    )
+}
+
+function convertChildItems(
+  children: AstNode[],
+  customComponentNames: Set<string>,
+  allowChildrenSlot = false
+) {
+  const result: Array<string | ImportedVisualNode> = []
+
+  for (const child of children) {
+    if (child.type === 'JSXElement') {
+      result.push(
+        convertJsxElement(
+          child,
+          customComponentNames,
+          allowChildrenSlot
+        )
+      )
+      continue
+    }
+
+    if (child.type === 'JSXFragment') {
+      result.push(
+        ...convertChildItems(
+          asNodeArray(child.children),
+          customComponentNames,
+          allowChildrenSlot
+        )
+      )
+      continue
+    }
+
+    if (child.type === 'JSXText') {
+      const text = normalizeJsxText(String(child.value ?? ''))
+      if (text) result.push(text)
+      continue
+    }
+
+    if (child.type === 'JSXExpressionContainer') {
+      const expression = asNode(child.expression)
+
+      if (expression?.type === 'JSXEmptyExpression') continue
+      if (
+        allowChildrenSlot &&
+        expression?.type === 'Identifier' &&
+        expression.name === 'children'
+      ) {
+        result.push(createImportedNode(componentChildrenSlotType, {}))
+        continue
+      }
+      const value = getStaticExpressionValue(expression)
+
+      if (typeof value === 'string' || typeof value === 'number') {
+        result.push(String(value))
+        continue
+      }
+
+      throw new StaticJsxImportError(
+        'Dynamic JSX expressions are not supported by reverse sync.'
+      )
+    }
+
+    if (child.type === 'JSXSpreadChild') {
+      throw new StaticJsxImportError(
+        'Spread children are not supported by reverse sync.'
+      )
+    }
+  }
+
+  return result
+}
+
+function normalizeJsxText(value: string) {
+  return value.replace(/\s+/g, ' ').trim()
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize)
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([firstKey], [secondKey]) => firstKey.localeCompare(secondKey))
+        .map(([key, entryValue]) => [key, canonicalize(entryValue)])
+    )
+  }
+
+  return value
+}
+
+function reconcileNodeList(
+  imported: ImportedVisualNode[],
+  current: ImportedVisualNode[],
+  customComponentNames: Set<string>
+) {
+  const used = new Set<number>()
+
+  return imported.map((node, index) => {
+    let matchIndex =
+      current[index]?.type === node.type
+        ? index
+        : current.findIndex(
+            (candidate, candidateIndex) =>
+              !used.has(candidateIndex) && candidate.type === node.type
+          )
+
+    if (matchIndex < 0 || used.has(matchIndex)) matchIndex = -1
+    if (matchIndex >= 0) used.add(matchIndex)
+
+    return reconcileNode(
+      node,
+      current[matchIndex] ?? null,
+      undefined,
+      customComponentNames
+    )
+  })
+}
+
+function reconcileNode(
+  imported: ImportedVisualNode,
+  current: ImportedVisualNode | null,
+  forcedId: string | undefined,
+  customComponentNames: Set<string>
+): ImportedVisualNode {
+  const props =
+    current &&
+    customComponentNames.has(imported.type) &&
+    current.type === imported.type
+      ? preserveCustomRootProps(imported.props, current.props)
+      : imported.props
+
+  return {
+    ...imported,
+    id: forcedId ?? current?.id ?? imported.id,
+    label: current?.label ?? imported.label,
+    props,
+    children: reconcileNodeList(
+      imported.children,
+      current?.children ?? [],
+      customComponentNames
+    ),
+  }
+}
+
+const customRootPropNames = [
+  'wrapperTag',
+  'id',
+  'className',
+  'attributes',
+  'componentTree',
+] as const
+
+function preserveCustomRootProps(
+  imported: Record<string, unknown>,
+  current: Record<string, unknown>
+) {
+  const rootProps = Object.fromEntries(
+    customRootPropNames
+      .filter((name) => Object.hasOwn(current, name))
+      .map((name) => [name, current[name]])
+  )
+
+  return {
+    ...imported,
+    ...rootProps,
+  }
+}
+
+function createImportedNode(
+  type: string,
+  props: Record<string, unknown>,
+  children: ImportedVisualNode[] = []
+): ImportedVisualNode {
+  return {
+    id: randomUUID(),
+    type,
+    props,
+    children,
+  }
+}
+
+function containsNodeType(nodes: ImportedVisualNode[], type: string): boolean {
+  return nodes.some(
+    (node) =>
+      node.type === type || containsNodeType(node.children, type)
+  )
+}
+
+function asNode(value: unknown): AstNode | null {
+  return value && typeof value === 'object' && 'type' in value
+    ? (value as AstNode)
+    : null
+}
+
+function asNodeArray(value: unknown): AstNode[] {
+  return Array.isArray(value)
+    ? value.map(asNode).filter((node): node is AstNode => Boolean(node))
+    : []
+}
+
+function formatParserError(error: unknown) {
+  if (!(error instanceof Error)) return 'The page contains invalid JSX.'
+  const location = error.message.match(/\(\d+:\d+\)/)?.[0]
+  return `Unable to parse the managed page${location ? ` at ${location}` : ''}: ${error.message}`
+}