create-visualbuild-app 0.1.0

package/visual-app-builder/src/stores/useAppStore.ts

@@ -0,0 +1,1265 @@
+import { v4 as uuid } from 'uuid'
+import { create } from 'zustand'
+import { primitiveRegistry } from '../data/primitiveRegistry'
+import type {
+  AppShell,
+  AppState,
+  ComponentType,
+  Page,
+  PrimitiveType,
+  VisualNode,
+} from '../types'
+import { createPageSourcePath } from '../utils/codegen'
+import {
+  createProjectSchema,
+  loadProjectSchema,
+  saveProjectSchema,
+  syncTailwindClasses,
+} from '../utils/projectPersistence'
+
+const generateId = () => uuid()
+const projectCacheKey = 'visualbuild:project-cache'
+
+const defaultAppShell: AppShell = {
+  header: null,
+  footer: null,
+}
+const defaultProjectName = 'my-blog'
+
+const defaultPage: Page = {
+  id: 'page-home',
+  name: 'Home',
+  route: '/',
+  sourcePath: createPageSourcePath('Home'),
+  root: createPageRoot('page-home'),
+  components: [
+    createComponentPreset('Navbar', {
+      navId: 'shell-navbar',
+      logo: 'My Blog',
+    }),
+    createComponentPreset('Hero', {
+      sectionId: 'home-hero',
+      title: 'Welcome to My Blog',
+      subtitle: 'Built visually. Owned as React code.',
+      cta: 'Start Building',
+    }),
+  ],
+}
+
+const cachedProject = readCachedProject()
+let tailwindSyncTimeout: number | null = null
+let activeProjectId = ''
+
+export const useAppStore = create<AppState>((set, get) => ({
+  projectName: cachedProject?.projectName ?? defaultProjectName,
+  appShell: cachedProject?.appShell ?? defaultAppShell,
+  pages: cachedProject?.pages ?? [],
+  activePageId: cachedProject?.activePageId ?? '',
+  selectedComponentId: null,
+  viewport: 'desktop',
+  previewMode: false,
+  isProjectLoaded: false,
+
+  loadProject: async () => {
+    const schema = await loadProjectSchema().catch((error: unknown) => {
+      console.warn('Failed to load visualbuild/pages.json', error)
+      return null
+    })
+
+    if (!schema || schema.pages.length === 0) {
+      if (cachedProject) {
+        activeProjectId = cachedProject.projectId
+        scheduleTailwindSync(cachedProject.pages, cachedProject.appShell)
+        set({
+          projectName: cachedProject.projectName,
+          appShell: cachedProject.appShell,
+          pages: cachedProject.pages,
+          activePageId: cachedProject.activePageId,
+          selectedComponentId: null,
+          isProjectLoaded: true,
+        })
+        return
+      }
+
+      activeProjectId = defaultProjectName
+      if (get().isProjectLoaded) {
+        return
+      }
+
+      cacheProject([defaultPage], defaultAppShell, false, defaultProjectName)
+
+      set({
+        projectName: defaultProjectName,
+        appShell: defaultAppShell,
+        pages: [defaultPage],
+        activePageId: defaultPage.id,
+        selectedComponentId: null,
+        isProjectLoaded: true,
+      })
+      return
+    }
+
+    const projectName = schema.meta?.projectName ?? defaultProjectName
+    activeProjectId = schema.runtimeProjectId ?? projectName
+
+    if (
+      cachedProject?.dirty &&
+      cachedProject.projectId === activeProjectId
+    ) {
+      scheduleTailwindSync(cachedProject.pages, cachedProject.appShell)
+      set({
+        projectName: cachedProject.projectName,
+        appShell: cachedProject.appShell,
+        pages: cachedProject.pages,
+        activePageId: cachedProject.activePageId,
+        selectedComponentId: null,
+        isProjectLoaded: true,
+      })
+      return
+    }
+
+    const { pages, appShell, changed } = normalizeLoadedProject(
+      schema.pages,
+      schema.appShell ?? defaultAppShell
+    )
+    cacheProject(pages, appShell, false, projectName)
+
+    set({
+      projectName,
+      appShell,
+      pages,
+      activePageId: pages[0].id,
+      selectedComponentId: null,
+      isProjectLoaded: true,
+    })
+
+    if (changed) {
+      persistProject(pages, appShell, projectName)
+    }
+  },
+
+  refreshProjectFromDisk: async (force = false) => {
+    const schema = await loadProjectSchema().catch((error: unknown) => {
+      console.warn('Failed to refresh visualbuild/pages.json', error)
+      return null
+    })
+
+    if (!schema || schema.pages.length === 0) {
+      return 'failed'
+    }
+
+    const projectName = schema.meta?.projectName ?? defaultProjectName
+    const nextProjectId = schema.runtimeProjectId ?? projectName
+    const currentCache = readCachedProject()
+
+    if (
+      !force &&
+      currentCache?.dirty &&
+      currentCache.projectId === nextProjectId
+    ) {
+      return 'skipped-dirty'
+    }
+
+    const { pages, appShell } = normalizeLoadedProject(
+      schema.pages,
+      schema.appShell ?? defaultAppShell
+    )
+    const currentActivePageId = get().activePageId
+    const activePageId = pages.some(
+      (page) => page.id === currentActivePageId
+    )
+      ? currentActivePageId
+      : pages[0].id
+
+    activeProjectId = nextProjectId
+    cacheProject(pages, appShell, false, projectName)
+    set({
+      projectName,
+      appShell,
+      pages,
+      activePageId,
+      selectedComponentId: null,
+      isProjectLoaded: true,
+    })
+
+    return 'updated'
+  },
+
+  saveProject: async () => {
+    const { pages, appShell, isProjectLoaded, projectName } = get()
+
+    if (!isProjectLoaded) {
+      return
+    }
+
+    cacheProject(pages, appShell, true, projectName)
+    await saveProjectSchema(pages, appShell, projectName)
+    cacheProject(pages, appShell, false, projectName)
+  },
+
+  addPage: (name, route) => {
+    const pageId = generateId()
+    const page: Page = {
+      id: pageId,
+      name,
+      route,
+      sourcePath: createPageSourcePath(name),
+      root: createPageRoot(pageId),
+      components: [],
+    }
+
+    set((state) => {
+      const pages = [
+        ...state.pages,
+        page,
+      ]
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return { pages }
+    })
+
+    return page
+  },
+
+  registerPage: (page) =>
+    set((state) => {
+      const pages = [...state.pages, page]
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return {
+        pages,
+        activePageId: page.id,
+        selectedComponentId: null,
+      }
+    }),
+
+  deletePage: (id) =>
+    set((state) => {
+      if (state.pages.length === 1) return state
+      const pages = state.pages.filter((page) => page.id !== id)
+      const activePageId =
+        state.activePageId === id ? pages[0].id : state.activePageId
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return {
+        pages,
+        activePageId,
+        selectedComponentId:
+          state.activePageId === id ? null : state.selectedComponentId,
+      }
+    }),
+
+  setActivePage: (id) => set({ activePageId: id, selectedComponentId: null }),
+
+  setSelectedComponent: (id) => set({ selectedComponentId: id }),
+
+  setViewport: (viewport) => set({ viewport }),
+
+  togglePreviewMode: () =>
+    set((state) => ({ previewMode: !state.previewMode })),
+
+  addComponent: (pageId, type) => {
+    get().addComponentAt(pageId, type, Number.POSITIVE_INFINITY)
+  },
+
+  addComponentAt: (pageId, type, index) =>
+    set((state) => {
+      const node = createComponentPreset(type)
+      const pages = state.pages.map((page) =>
+        page.id === pageId ? insertNodeAtRoot(page, node, index) : page
+      )
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return { pages, selectedComponentId: node.id }
+    }),
+
+  addPrimitive: (pageId, type) => {
+    get().addPrimitiveAt(pageId, type, Number.POSITIVE_INFINITY)
+  },
+
+  addPrimitiveAt: (pageId, type, index) =>
+    set((state) => {
+      const node = createPrimitive(type)
+      const pages = state.pages.map((page) =>
+        page.id === pageId ? insertNodeAtRoot(page, node, index) : page
+      )
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return { pages, selectedComponentId: node.id }
+    }),
+
+  addPrimitiveToNode: (parentNodeId, type) => {
+    get().addPrimitiveToNodeAt(parentNodeId, type, Number.POSITIVE_INFINITY)
+  },
+
+  addPrimitiveToNodeAt: (parentNodeId, type, index) =>
+    set((state) => {
+      const node = createPrimitive(type)
+      const pages = state.pages.map((page) => ({
+        ...page,
+        components: addChildNodeAt(page.components, parentNodeId, node, index),
+      }))
+      const appShell = addChildToAppShell(
+        state.appShell,
+        parentNodeId,
+        node,
+        index
+      )
+
+      persistProject(pages, appShell, state.projectName)
+
+      return { appShell, pages, selectedComponentId: node.id }
+    }),
+
+  addComponentToNode: (parentNodeId, type) => {
+    get().addComponentToNodeAt(parentNodeId, type, Number.POSITIVE_INFINITY)
+  },
+
+  addComponentToNodeAt: (parentNodeId, type, index) =>
+    set((state) => {
+      const node = createComponentPreset(type)
+      const pages = state.pages.map((page) => ({
+        ...page,
+        components: addChildNodeAt(page.components, parentNodeId, node, index),
+      }))
+      const appShell = addChildToAppShell(
+        state.appShell,
+        parentNodeId,
+        node,
+        index
+      )
+
+      persistProject(pages, appShell, state.projectName)
+
+      return { appShell, pages, selectedComponentId: node.id }
+    }),
+
+  removeNode: (nodeId) =>
+    set((state) => {
+      const appShell = removeShellNodeById(state.appShell, nodeId)
+      const pages = state.pages.map((page) => ({
+        ...page,
+        components: removeNodeById(page.components, nodeId),
+      }))
+
+      persistProject(pages, appShell, state.projectName)
+
+      return {
+        appShell,
+        pages,
+        selectedComponentId:
+          state.selectedComponentId === nodeId ? null : state.selectedComponentId,
+      }
+    }),
+
+  moveNode: (pageId, nodeId, targetParentNodeId, targetIndex) =>
+    set((state) => {
+      const movedProject = moveNodeInProject(
+        state.pages,
+        state.appShell,
+        pageId,
+        nodeId,
+        targetParentNodeId,
+        targetIndex
+      )
+
+      if (!movedProject) {
+        return state
+      }
+
+      persistProject(
+        movedProject.pages,
+        movedProject.appShell,
+        state.projectName
+      )
+
+      return {
+        pages: movedProject.pages,
+        appShell: movedProject.appShell,
+        selectedComponentId: nodeId,
+      }
+    }),
+
+  moveComponent: (pageId, nodeId, targetIndex) =>
+    set((state) => {
+      const pages = state.pages.map((page) =>
+        page.id === pageId ? moveRootNode(page, nodeId, targetIndex) : page
+      )
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return { pages }
+    }),
+
+  removeComponent: (pageId, nodeId) =>
+    set((state) => {
+      const pages = state.pages.map((page) =>
+        page.id === pageId
+          ? { ...page, components: removeNodeById(page.components, nodeId) }
+          : page
+      )
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return {
+        pages,
+        selectedComponentId:
+          state.selectedComponentId === nodeId ? null : state.selectedComponentId,
+      }
+    }),
+
+  setAppShellComponent: (_slot, type) => {
+    const slot = type === 'Footer' ? 'footer' : 'header'
+
+    set((state) => {
+      const node = createComponentPreset(type)
+      const appShell = {
+        ...state.appShell,
+        [slot]: node,
+      }
+
+      persistProject(state.pages, appShell, state.projectName)
+
+      return {
+        appShell,
+        selectedComponentId: node.id,
+      }
+    })
+  },
+
+  removeAppShellComponent: (slot) =>
+    set((state) => {
+      const removedNodeId = state.appShell[slot]?.id
+      const appShell = {
+        ...state.appShell,
+        [slot]: null,
+      }
+
+      persistProject(state.pages, appShell, state.projectName)
+
+      return {
+        appShell,
+        selectedComponentId:
+          state.selectedComponentId === removedNodeId
+            ? null
+            : state.selectedComponentId,
+      }
+    }),
+
+  updateComponentProps: (_pageId, nodeId, props) => {
+    get().updateNodeProps(nodeId, props)
+  },
+
+  updateNodeProps: (nodeId, props) =>
+    set((state) => {
+      const appShell = updateShellNodeProps(state.appShell, nodeId, props)
+      const pages = state.pages.map((page) => ({
+        ...page,
+        components: updateNodeProps(page.components, nodeId, props),
+      }))
+
+      persistProject(pages, appShell, state.projectName)
+
+      return { appShell, pages }
+    }),
+
+  updatePageRoot: (pageId, updates) =>
+    set((state) => {
+      const pages = state.pages.map((page) => {
+        if (page.id !== pageId) {
+          return page
+        }
+
+        const nextType = updates.type ?? page.root.type
+        const defaultProps =
+          updates.type && updates.type !== page.root.type
+            ? primitiveRegistry[nextType].defaultProps
+            : {}
+
+        return {
+          ...page,
+          root: {
+            ...page.root,
+            type: nextType,
+            props: {
+              ...defaultProps,
+              ...page.root.props,
+              ...(updates.props ?? {}),
+            },
+          },
+        }
+      })
+
+      persistProject(pages, state.appShell, state.projectName)
+
+      return { pages }
+    }),
+
+  updateAppShellProps: (slot, props) =>
+    set((state) => {
+      const node = state.appShell[slot]
+
+      if (!node) {
+        return state
+      }
+
+      const appShell = {
+        ...state.appShell,
+        [slot]: {
+          ...node,
+          props: {
+            ...node.props,
+            ...props,
+          },
+        },
+      }
+
+      persistProject(state.pages, appShell, state.projectName)
+
+      return { appShell }
+    }),
+}))
+
+function createPageRoot(pageId: string, type: PrimitiveType = 'div'): VisualNode {
+  return {
+    id: `${pageId}:root`,
+    type,
+    label: 'Page root',
+    props: {
+      ...primitiveRegistry[type].defaultProps,
+      className: 'min-h-screen',
+    },
+    children: [],
+  }
+}
+
+function createPrimitive(type: PrimitiveType, props = {}): VisualNode {
+  return {
+    id: generateId(),
+    type,
+    props: { ...primitiveRegistry[type].defaultProps, ...props },
+    children: [],
+  }
+}
+
+function createComponentPreset(
+  type: ComponentType,
+  overrides: Record<string, unknown> = {}
+): VisualNode {
+  if (type === 'Navbar') {
+    return {
+      id: String(overrides.navId ?? generateId()),
+      type: 'nav',
+      label: 'Navbar',
+      props: {
+        ...primitiveRegistry.nav.defaultProps,
+        className:
+          'flex items-center justify-between px-6 py-3 bg-gray-900 text-white',
+      },
+      children: [
+        createPrimitive('span', {
+          text: String(overrides.logo ?? 'My Blog'),
+          className: 'font-bold text-sm',
+        }),
+        createPrimitive('div', {
+          className: 'flex items-center gap-4',
+        }),
+        createPrimitive('div', {
+          className: 'flex items-center gap-2',
+        }),
+      ],
+    }
+  }
+
+  if (type === 'Hero') {
+    return {
+      id: String(overrides.sectionId ?? generateId()),
+      type: 'section',
+      label: 'Hero',
+      props: {
+        className:
+          'bg-gradient-to-br from-blue-600 to-indigo-700 text-white px-8 py-12 text-center',
+      },
+      children: [
+        createPrimitive('h1', {
+          text: String(overrides.title ?? 'Welcome to My Blog'),
+          className: 'text-2xl font-bold mb-2',
+        }),
+        createPrimitive('p', {
+          text: String(
+            overrides.subtitle ?? 'Built visually. Owned as React code.'
+          ),
+          className: 'text-sm text-blue-100 mb-6',
+        }),
+        createPrimitive('button', {
+          text: String(overrides.cta ?? 'Start Building'),
+          className:
+            'px-5 py-2 bg-white text-blue-700 rounded-full text-sm font-semibold',
+        }),
+      ],
+    }
+  }
+
+  if (type === 'Card') {
+    return {
+      id: generateId(),
+      type: 'article',
+      label: 'Card',
+      props: { ...primitiveRegistry.article.defaultProps },
+      children: [
+        createPrimitive('h3', {
+          text: 'Card Title',
+          className: 'font-semibold text-gray-900 mb-1',
+        }),
+        createPrimitive('p', {
+          text: 'Card description goes here.',
+          className: 'text-sm text-gray-500',
+        }),
+      ],
+    }
+  }
+
+  if (type === 'Button') {
+    return createPrimitive('button', {
+      text: 'Click me',
+      className: 'px-4 py-1.5 rounded text-sm font-medium bg-blue-600 text-white',
+    })
+  }
+
+  return {
+    id: generateId(),
+    type: 'footer',
+    label: 'Footer',
+    props: { ...primitiveRegistry.footer.defaultProps },
+    children: [
+      createPrimitive('span', {
+        text: 'Copyright 2026 MySite',
+        className: '',
+      }),
+    ],
+  }
+}
+
+function insertNodeAtRoot(page: Page, node: VisualNode, index: number): Page {
+  const components = [...page.components]
+  const safeIndex = Math.max(0, Math.min(index, components.length))
+
+  components.splice(safeIndex, 0, node)
+
+  return { ...page, components }
+}
+
+function addChildNodeAt(
+  nodes: VisualNode[],
+  parentNodeId: string,
+  child: VisualNode,
+  index: number
+): VisualNode[] {
+  return nodes.map((node) =>
+    node.id === parentNodeId
+      ? { ...node, children: insertNodeAt(node.children, child, index) }
+      : {
+          ...node,
+          children: addChildNodeAt(node.children, parentNodeId, child, index),
+        }
+  )
+}
+
+function addChildToAppShell(
+  appShell: AppShell,
+  parentNodeId: string,
+  child: VisualNode,
+  index: number
+): AppShell {
+  return {
+    header: appShell.header
+      ? insertChildIntoTree(appShell.header, parentNodeId, child, index)
+      : null,
+    footer: appShell.footer
+      ? insertChildIntoTree(appShell.footer, parentNodeId, child, index)
+      : null,
+  }
+}
+
+function removeNodeById(nodes: VisualNode[], nodeId: string): VisualNode[] {
+  return nodes
+    .filter((node) => node.id !== nodeId)
+    .map((node) => ({
+      ...node,
+      children: removeNodeById(node.children, nodeId),
+    }))
+}
+
+function removeShellNodeById(appShell: AppShell, nodeId: string): AppShell {
+  return {
+    header:
+      appShell.header?.id === nodeId
+        ? null
+        : appShell.header
+          ? {
+              ...appShell.header,
+              children: removeNodeById(appShell.header.children, nodeId),
+            }
+          : null,
+    footer:
+      appShell.footer?.id === nodeId
+        ? null
+        : appShell.footer
+          ? {
+              ...appShell.footer,
+              children: removeNodeById(appShell.footer.children, nodeId),
+            }
+          : null,
+  }
+}
+
+function updateNodeProps(
+  nodes: VisualNode[],
+  nodeId: string,
+  props: Record<string, unknown>
+): VisualNode[] {
+  return nodes.map((node) =>
+    node.id === nodeId
+      ? { ...node, props: { ...node.props, ...props } }
+      : { ...node, children: updateNodeProps(node.children, nodeId, props) }
+  )
+}
+
+function updateShellNodeProps(
+  appShell: AppShell,
+  nodeId: string,
+  props: Record<string, unknown>
+): AppShell {
+  return {
+    header: appShell.header
+      ? updateNodeInTree(appShell.header, nodeId, props)
+      : null,
+    footer: appShell.footer
+      ? updateNodeInTree(appShell.footer, nodeId, props)
+      : null,
+  }
+}
+
+function updateNodeInTree(
+  node: VisualNode,
+  nodeId: string,
+  props: Record<string, unknown>
+): VisualNode {
+  if (node.id === nodeId) {
+    return { ...node, props: { ...node.props, ...props } }
+  }
+
+  return {
+    ...node,
+    children: node.children.map((child) =>
+      updateNodeInTree(child, nodeId, props)
+    ),
+  }
+}
+
+type NodeScope = `page:${string}` | 'shell:header' | 'shell:footer'
+
+interface NodeLocation {
+  node: VisualNode
+  parentNodeId: string | null
+  index: number
+  scope: NodeScope
+}
+
+function moveNodeInProject(
+  pages: Page[],
+  appShell: AppShell,
+  pageId: string,
+  nodeId: string,
+  targetParentNodeId: string | null,
+  targetIndex: number
+) {
+  const source = findMovableNode(pages, appShell, nodeId)
+
+  if (!source) {
+    return null
+  }
+
+  if (
+    targetParentNodeId === nodeId ||
+    (targetParentNodeId !== null &&
+      containsNode(source.node, targetParentNodeId))
+  ) {
+    return null
+  }
+
+  const destination = findDestination(
+    pages,
+    appShell,
+    pageId,
+    targetParentNodeId
+  )
+
+  if (!destination) {
+    return null
+  }
+
+  if (
+    destination.parentNode &&
+    !primitiveRegistry[destination.parentNode.type].acceptsChildren
+  ) {
+    return null
+  }
+
+  let insertionIndex = targetIndex
+
+  if (
+    source.scope === destination.scope &&
+    source.parentNodeId === targetParentNodeId &&
+    source.index < targetIndex
+  ) {
+    insertionIndex -= 1
+  }
+
+  let nextPages = pages.map((page) => ({
+    ...page,
+    components: removeNodeById(page.components, nodeId),
+  }))
+  let nextAppShell: AppShell = {
+    header: appShell.header
+      ? {
+          ...appShell.header,
+          children: removeNodeById(appShell.header.children, nodeId),
+        }
+      : null,
+    footer: appShell.footer
+      ? {
+          ...appShell.footer,
+          children: removeNodeById(appShell.footer.children, nodeId),
+        }
+      : null,
+  }
+
+  if (targetParentNodeId === null) {
+    nextPages = nextPages.map((page) =>
+      page.id === pageId
+        ? insertNodeAtRoot(page, source.node, insertionIndex)
+        : page
+    )
+  } else {
+    nextPages = nextPages.map((page) => ({
+      ...page,
+      components: addChildNodeAt(
+        page.components,
+        targetParentNodeId,
+        source.node,
+        insertionIndex
+      ),
+    }))
+    nextAppShell = addChildToAppShell(
+      nextAppShell,
+      targetParentNodeId,
+      source.node,
+      insertionIndex
+    )
+  }
+
+  return { pages: nextPages, appShell: nextAppShell }
+}
+
+function findMovableNode(
+  pages: Page[],
+  appShell: AppShell,
+  nodeId: string
+): NodeLocation | null {
+  for (const page of pages) {
+    const location = findNodeLocation(
+      page.components,
+      nodeId,
+      null,
+      `page:${page.id}`
+    )
+
+    if (location) {
+      return location
+    }
+  }
+
+  if (appShell.header) {
+    const location = findNodeLocation(
+      appShell.header.children,
+      nodeId,
+      appShell.header.id,
+      'shell:header'
+    )
+
+    if (location) {
+      return location
+    }
+  }
+
+  if (appShell.footer) {
+    return findNodeLocation(
+      appShell.footer.children,
+      nodeId,
+      appShell.footer.id,
+      'shell:footer'
+    )
+  }
+
+  return null
+}
+
+function findNodeLocation(
+  nodes: VisualNode[],
+  nodeId: string,
+  parentNodeId: string | null,
+  scope: NodeScope
+): NodeLocation | null {
+  for (const [index, node] of nodes.entries()) {
+    if (node.id === nodeId) {
+      return { node, parentNodeId, index, scope }
+    }
+
+    const childLocation = findNodeLocation(
+      node.children,
+      nodeId,
+      node.id,
+      scope
+    )
+
+    if (childLocation) {
+      return childLocation
+    }
+  }
+
+  return null
+}
+
+function findDestination(
+  pages: Page[],
+  appShell: AppShell,
+  pageId: string,
+  parentNodeId: string | null
+): { scope: NodeScope; parentNode: VisualNode | null } | null {
+  if (parentNodeId === null) {
+    return pages.some((page) => page.id === pageId)
+      ? { scope: `page:${pageId}`, parentNode: null }
+      : null
+  }
+
+  for (const page of pages) {
+    const parentNode = findNodeInTreeList(page.components, parentNodeId)
+
+    if (parentNode) {
+      return { scope: `page:${page.id}`, parentNode }
+    }
+  }
+
+  if (appShell.header) {
+    const parentNode = findNodeInTree(appShell.header, parentNodeId)
+
+    if (parentNode) {
+      return { scope: 'shell:header', parentNode }
+    }
+  }
+
+  if (appShell.footer) {
+    const parentNode = findNodeInTree(appShell.footer, parentNodeId)
+
+    if (parentNode) {
+      return { scope: 'shell:footer', parentNode }
+    }
+  }
+
+  return null
+}
+
+function findNodeInTreeList(nodes: VisualNode[], nodeId: string) {
+  for (const node of nodes) {
+    const match = findNodeInTree(node, nodeId)
+
+    if (match) {
+      return match
+    }
+  }
+
+  return null
+}
+
+function findNodeInTree(
+  node: VisualNode,
+  nodeId: string
+): VisualNode | null {
+  if (node.id === nodeId) {
+    return node
+  }
+
+  return findNodeInTreeList(node.children, nodeId)
+}
+
+function containsNode(node: VisualNode, nodeId: string): boolean {
+  return (
+    node.id === nodeId ||
+    node.children.some((child) => containsNode(child, nodeId))
+  )
+}
+
+function insertChildIntoTree(
+  node: VisualNode,
+  parentNodeId: string,
+  child: VisualNode,
+  index: number
+): VisualNode {
+  if (node.id === parentNodeId) {
+    return { ...node, children: insertNodeAt(node.children, child, index) }
+  }
+
+  return {
+    ...node,
+    children: node.children.map((nestedChild) =>
+      insertChildIntoTree(nestedChild, parentNodeId, child, index)
+    ),
+  }
+}
+
+function insertNodeAt(
+  nodes: VisualNode[],
+  node: VisualNode,
+  index: number
+) {
+  const nextNodes = [...nodes]
+  const safeIndex = Math.max(0, Math.min(index, nextNodes.length))
+
+  nextNodes.splice(safeIndex, 0, node)
+
+  return nextNodes
+}
+
+function moveRootNode(page: Page, nodeId: string, targetIndex: number): Page {
+  const fromIndex = page.components.findIndex((node) => node.id === nodeId)
+
+  if (fromIndex === -1) {
+    return page
+  }
+
+  const components = [...page.components]
+  const [node] = components.splice(fromIndex, 1)
+  const safeIndex = Math.max(0, Math.min(targetIndex, components.length))
+
+  components.splice(safeIndex, 0, node)
+
+  return { ...page, components }
+}
+
+function normalizeLoadedProject(pages: Page[], appShell: AppShell) {
+  let changed = false
+  const normalizedAppShell: AppShell = {
+    header: appShell.header ? normalizeUnknownNode(appShell.header) : null,
+    footer: appShell.footer ? normalizeUnknownNode(appShell.footer) : null,
+  }
+
+  const normalizedPages = pages.map((page) => {
+    const rawPage = page as Page & { root?: unknown; sourcePath?: string }
+    const root = rawPage.root
+      ? normalizePageRoot(rawPage.root, page.id)
+      : createPageRoot(page.id)
+    const normalizedComponents: VisualNode[] = []
+
+    for (const rawNode of page.components) {
+      const node = normalizeUnknownNode(rawNode)
+
+      if (node.label === 'Navbar' && !normalizedAppShell.header) {
+        normalizedAppShell.header = node
+        changed = true
+        continue
+      }
+
+      if (node.label === 'Footer' && !normalizedAppShell.footer) {
+        normalizedAppShell.footer = node
+        changed = true
+        continue
+      }
+
+      normalizedComponents.push(node)
+    }
+
+    if (!rawPage.root) {
+      changed = true
+    }
+
+    const sourcePath =
+      rawPage.sourcePath?.replace(/\\/g, '/') ||
+      createPageSourcePath(page.name)
+
+    if (!rawPage.sourcePath || rawPage.sourcePath !== sourcePath) {
+      changed = true
+    }
+
+    return {
+      ...page,
+      sourcePath,
+      root,
+      components: normalizedComponents,
+    }
+  })
+
+  return {
+    pages: normalizedPages,
+    appShell: normalizedAppShell,
+    changed,
+  }
+}
+
+function normalizePageRoot(rawRoot: unknown, pageId: string): VisualNode {
+  const root = normalizeUnknownNode(rawRoot)
+
+  if (!primitiveRegistry[root.type].acceptsChildren) {
+    return createPageRoot(pageId)
+  }
+
+  return {
+    ...root,
+    id: root.id || `${pageId}:root`,
+    label: 'Page root',
+    children: [],
+  }
+}
+
+function normalizeUnknownNode(rawNode: unknown): VisualNode {
+  const node = rawNode as {
+    id?: string
+    type?: string
+    label?: string
+    props?: Record<string, unknown>
+    children?: unknown[]
+  }
+
+  if (isPrimitiveType(node.type)) {
+    return {
+      id: node.id ?? generateId(),
+      type: node.type,
+      label: node.label,
+      props: node.props ?? {},
+      children: (node.children ?? []).map((child) => normalizeUnknownNode(child)),
+    }
+  }
+
+  if (node.type === 'Navbar') {
+    return createComponentPreset('Navbar', {
+      navId: node.id,
+      logo: node.props?.logo,
+    })
+  }
+
+  if (node.type === 'Hero') {
+    return createComponentPreset('Hero', {
+      sectionId: node.id,
+      title: node.props?.title,
+      subtitle: node.props?.subtitle,
+      cta: node.props?.cta,
+    })
+  }
+
+  if (node.type === 'Card' || node.type === 'Button' || node.type === 'Footer') {
+    return createComponentPreset(node.type)
+  }
+
+  return createPrimitive('div')
+}
+
+function isPrimitiveType(type: unknown): type is PrimitiveType {
+  return typeof type === 'string' && type in primitiveRegistry
+}
+
+function persistProject(
+  pages: Page[],
+  appShell: AppShell,
+  projectName: string
+) {
+  cacheProject(pages, appShell, true, projectName)
+}
+
+function cacheProject(
+  pages: Page[],
+  appShell: AppShell,
+  dirty: boolean,
+  projectName: string
+) {
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    window.localStorage.setItem(
+      projectCacheKey,
+      JSON.stringify({
+        ...createProjectSchema(pages, appShell, projectName),
+        dirty,
+        cachedAt: Date.now(),
+        projectId: activeProjectId,
+      })
+    )
+    scheduleTailwindSync(pages, appShell)
+  } catch (error) {
+    console.warn('Failed to cache visualbuild project state', error)
+  }
+}
+
+function scheduleTailwindSync(pages: Page[], appShell: AppShell) {
+  if (tailwindSyncTimeout !== null) {
+    window.clearTimeout(tailwindSyncTimeout)
+  }
+
+  tailwindSyncTimeout = window.setTimeout(() => {
+    tailwindSyncTimeout = null
+    void syncTailwindClasses(pages, appShell).catch((error: unknown) => {
+      console.warn('Failed to update live Tailwind classes', error)
+    })
+  }, 100)
+}
+
+function readCachedProject() {
+  if (typeof window === 'undefined') {
+    return null
+  }
+
+  try {
+    const cached = window.localStorage.getItem(projectCacheKey)
+
+    if (!cached) {
+      return null
+    }
+
+    const schema = JSON.parse(cached) as {
+      meta?: {
+        projectName?: string
+      }
+      appShell?: AppShell
+      pages?: Page[]
+      dirty?: boolean
+      projectId?: string
+    }
+
+    if (!schema.pages || schema.pages.length === 0) {
+      return null
+    }
+
+    const { pages, appShell } = normalizeLoadedProject(
+      schema.pages,
+      schema.appShell ?? defaultAppShell
+    )
+
+    return {
+      projectName: schema.meta?.projectName ?? defaultProjectName,
+      appShell,
+      pages,
+      activePageId: pages[0].id,
+      dirty: schema.dirty === true,
+      projectId: schema.projectId ?? '',
+    }
+  } catch (error) {
+    console.warn('Failed to restore cached visualbuild project state', error)
+    return null
+  }
+}