Vuejs For Spatial computing #827

Amiya167 · 2026-03-21T11:34:47Z

Amiya167
Mar 21, 2026

Start Date: 2026-03-21
Target Major Version: 3.x
Reference Issues: N/A
Implementation PR: (pending)

Summary

Introduce a spatial computing compilation target for Vue Single-File Components, enabling developers to write Vue SFCs that compile to native SwiftUI views running on Apple visionOS. This is achieved through:

A new spatial attribute on <script setup> and <template> blocks
A new compiler-spatial package that compiles Vue templates into SwiftUI @ViewBuilder code
A runtime-spatial package that runs Vue's reactivity system inside JavaScriptCore and bridges to SwiftUI via IPC
An Electron-inspired dual-process architecture: Main Process (JavaScriptCore, runs Vue logic) and Renderer Process (SwiftUI, renders native spatial UI)

Basic example

<template spatial>
  <spatial-window title="Hello visionOS">
    <v-stack spacing="16">
      <text font="largeTitle">{{ greeting }}</text>
      <text font="body" opacity="0.7">Count: {{ count }}</text>
      <button @tap="count++">
        <label>Increment</label>
        <sf-symbol name="plus.circle.fill" />
      </button>
    </v-stack>
  </spatial-window>
</template>

<script setup spatial>
import { ref } from 'vue'

const greeting = ref('Hello from Vue Spatial')
const count = ref(0)
</script>

<style spatial>
.card {
  padding: 20;
  corner-radius: 16;
  glass-background: regular;
}
</style>

Compiles to:

// Auto-generated by @vue/compiler-spatial — do not edit
import SwiftUI

struct HelloVisionOS: View {
    @ObservedObject var vm: VueViewModel

    var body: some View {
        WindowGroup("Hello visionOS") {
            VStack(spacing: 16) {
                Text(vm.get("greeting"))
                    .font(.largeTitle)
                Text("Count: \(vm.get("count"))")
                    .font(.body)
                    .opacity(0.7)
                Button(action: { vm.emit("tap:button_0") }) {
                    Label {
                        Text("Increment")
                    } icon: {
                        Image(systemName: "plus.circle.fill")
                    }
                }
            }
        }
    }
}

A more advanced example with spatial-specific features:

<template spatial>
  <spatial-volume>
    <reality-view>
      <model3d
        src="./assets/earth.usdz"
        :scale="modelScale"
        v-spatial-drag="onDrag"
        v-spatial-rotate="onRotate"
      />
    </reality-view>
  </spatial-volume>

  <spatial-window ornament placement="bottom">
    <h-stack>
      <slider :value="modelScale" @change="modelScale = $event" :range="[0.1, 3.0]" />
      <text>Scale: {{ modelScale.toFixed(1) }}x</text>
    </h-stack>
  </spatial-window>
</template>

<script setup spatial>
import { ref } from 'vue'
import { useSpatialGesture } from '@vue/runtime-spatial'

const modelScale = ref(1.0)
const { onDrag, onRotate } = useSpatialGesture()
</script>

Motivation

The Spatial Computing Gap

Apple Vision Pro and visionOS represent a new paradigm in computing — spatial computing, where applications exist in three-dimensional space around the user. Currently, building for visionOS requires:

Writing SwiftUI natively (steep learning curve for web developers)
Using Unity (heavy runtime, game-engine mental model)
Using WebXR in Safari (limited access to native APIs, no spatial containers)

None of these options leverage the existing Vue ecosystem — the components, state management patterns, composables, and developer tooling that millions of developers already know.

Why Vue is Uniquely Positioned

Vue's architecture is already conceptually aligned with spatial computing:

Compiler-first approach: Vue's SFC compiler already transforms templates into render functions. Adding a SwiftUI codegen target is a natural extension of this architecture — the same way compiler-ssr extends compiler-dom.
Reactivity is runtime-agnostic: Vue's reactivity system (@vue/reactivity) has no DOM dependency. It can run in JavaScriptCore on visionOS, driving SwiftUI state updates through a bridge.
SFC as the unit of composition: A .vue file already encapsulates template + logic + style. For spatial computing, this maps perfectly to: SwiftUI View (template) + ViewModel (script) + View Modifiers (style).
Existing precedent: Projects like Vue Native (Vue → React Native) and Weex demonstrated that Vue's template syntax can target non-DOM renderers. This RFC proposes a first-party, compiler-level approach rather than a runtime abstraction layer.

The Electron Analogy

Electron succeeded because it gave web developers access to native desktop capabilities through a familiar model: write web code, render in Chromium, communicate with Node.js via IPC.

Vue Spatial follows the same principle:

Electron	Vue Spatial
Main Process (Node.js)	Main Process (JavaScriptCore + Vue Runtime)
Renderer Process (Chromium)	Renderer Process (SwiftUI)
`ipcMain` / `ipcRenderer`	`spatialBridge.main` / `spatialBridge.renderer`
HTML/CSS → pixels	Vue template → SwiftUI views
`BrowserWindow`	`SpatialWindow` / `SpatialVolume` / `ImmersiveSpace`

This gives Vue developers native spatial computing capabilities without leaving the Vue mental model.

Constraints

Must not break existing Vue SFC compilation — spatial is opt-in per-component
Must produce native SwiftUI — not a WebView wrapper
Must support visionOS scene types: Window, Volume, ImmersiveSpace
Must allow spatial-specific APIs (hand tracking, eye gaze, RealityKit) through composables
Must preserve Vue's reactivity semantics — ref(), computed(), watch() work identically
Must support existing Vue ecosystem tooling (Vite plugin, DevTools concept)

Detailed design

1. SFC Parsing: The `spatial` Attribute

1.1 Grammar Extension

The spatial attribute is valid on <script setup>, <template>, and <style> blocks:

<script setup spatial>        <!-- spatial + setup mode -->
<script setup spatial lang="ts">  <!-- with TypeScript -->
<template spatial>             <!-- spatial template compilation target -->
<style spatial>                <!-- spatial style (SwiftUI modifiers) -->
<style spatial scoped>         <!-- scoped to this component's SwiftUI view -->

A component is considered a spatial component if any of its blocks carry the spatial attribute. In practice, if <script setup spatial> is present, the compiler treats the entire SFC as spatial.

1.2 Parser Changes (`compiler-sfc/parse.ts`)

The SFCDescriptor interface gains a new field:

export interface SFCDescriptor {
  // ... existing fields
  spatial: boolean                         // true if any block has spatial attribute
  scriptSetupSpatial: SFCScriptBlock | null // <script setup spatial> block
}

In the parse() function, when processing <script> nodes:

case 'script':
  const scriptBlock = createBlock(node, source, pad) as SFCScriptBlock
  const isSetup = !!scriptBlock.attrs.setup
  const isSpatial = !!scriptBlock.attrs.spatial

  if (isSetup && isSpatial) {
    descriptor.scriptSetupSpatial = scriptBlock
    descriptor.spatial = true
  } else if (isSetup && !descriptor.scriptSetup) {
    descriptor.scriptSetup = scriptBlock
  }
  // ... existing logic

1.3 Validation Rules

<script setup spatial> and <script setup> cannot coexist in the same SFC. A spatial component is fully spatial.
<script spatial> (without setup) is not supported. Spatial components must use Composition API.
<template spatial> without <script setup spatial> is a warning — script determines the compilation target.
Non-spatial <template> with <script setup spatial> is an error — ambiguous target.

2. Template Compilation: `compiler-spatial`

2.1 Package Structure

A new package @vue/compiler-spatial is added alongside existing compiler packages:

packages/
  compiler-core/       # Existing — shared AST, transforms
  compiler-dom/        # Existing — DOM codegen
  compiler-ssr/        # Existing — SSR codegen
  compiler-spatial/    # NEW — SwiftUI codegen
    src/
      index.ts
      codegen.ts              # SwiftUI code generation
      transforms/
        transformElement.ts   # Element → SwiftUI View mapping
        transformDirective.ts # v-if/v-for/v-model → Swift control flow
        transformEvent.ts     # @tap/@drag → gesture/action binding
        transformStyle.ts     # style → SwiftUI modifiers
        transformSlot.ts      # slot → @ViewBuilder
      components/
        spatialWindow.ts      # <spatial-window> → WindowGroup
        spatialVolume.ts      # <spatial-volume> → RealityView
        spatialImmersive.ts   # <spatial-immersive> → ImmersiveSpace
      runtime/
        bridgeProtocol.ts     # IPC message type definitions

2.2 Element Mapping

Core element mapping table:

Vue Spatial Element	SwiftUI Output	Notes
`<v-stack>`	`VStack`	`spacing`, `alignment` props
`<h-stack>`	`HStack`
`<z-stack>`	`ZStack`
`<text>`	`Text`	`font`, `color` as modifiers
`<button>`	`Button`	`@tap` → action closure
`<image>`	`Image`	`src` → `Image(systemName:)` or `AsyncImage`
`<sf-symbol>`	`Image(systemName:)`	SF Symbols
`<text-field>`	`TextField`	`v-model` → `@Binding`
`<toggle>`	`Toggle`
`<slider>`	`Slider`	`:range` → `in:`
`<list>`	`List`	`v-for` child → `ForEach`
`<scroll-view>`	`ScrollView`	`axis` prop
`<navigation-stack>`	`NavigationStack`
`<tab-view>`	`TabView`
`<label>`	`Label`	icon + text pattern
`<divider>`	`Divider`
`<spacer>`	`Spacer`
`<group>`	`Group`
`<model3d>`	`Model3D`	RealityKit model loading
`<reality-view>`	`RealityView`	RealityKit container
`<spatial-window>`	`WindowGroup`	visionOS window
`<spatial-volume>`	`WindowGroup` + `.windowStyle(.volumetric)`
`<spatial-immersive>`	`ImmersiveSpace`

2.3 Directive Compilation

v-if / v-else-if / v-else

<text v-if="isLoggedIn">Welcome</text>
<text v-else>Please log in</text>

Compiles to:

if vm.get("isLoggedIn") {
    Text("Welcome")
} else {
    Text("Please log in")
}

v-for

<text v-for="item in items" :key="item.id">{{ item.name }}</text>

Compiles to:

ForEach(vm.getArray("items"), id: \.id) { item in
    Text(item.get("name"))
}

v-model

<text-field v-model="username" placeholder="Enter name" />

Compiles to:

TextField("Enter name", text: vm.binding("username"))

The vm.binding() method returns a SwiftUI Binding<String> that reads/writes through the IPC bridge.

v-show

<text v-show="visible">Hello</text>

Compiles to:

Text("Hello")
    .opacity(vm.get("visible") ? 1 : 0)

2.4 Spatial Directives (New)

v-spatial-drag

<model3d src="box.usdz" v-spatial-drag="onDrag" />

Compiles to:

Model3D(named: "box.usdz")
    .gesture(DragGesture().onChanged { value in
        vm.emit("spatial:drag", value.asBridgePayload())
    })

v-spatial-rotate

<model3d src="globe.usdz" v-spatial-rotate="onRotate" />

Compiles to:

Model3D(named: "globe.usdz")
    .gesture(RotateGesture3D().onChanged { value in
        vm.emit("spatial:rotate", value.asBridgePayload())
    })

v-spatial-look (eye tracking hover)

<button v-spatial-look="highlight">
  <label>Tap me</label>
</button>

Compiles to:

Button(action: { ... }) {
    Label("Tap me")
}
.hoverEffect(.highlight)

2.5 Style Compilation

<style spatial> uses a CSS-like syntax that maps to SwiftUI view modifiers:

/* Input */
.card {
  padding: 20;
  corner-radius: 16;
  glass-background: regular;
  shadow-radius: 10;
  frame-width: 300;
  frame-height: 200;
}

Compiles to a modifier chain:

.padding(20)
.clipShape(RoundedRectangle(cornerRadius: 16))
.glassBackgroundEffect(in: .rect(cornerRadius: 16))
.shadow(radius: 10)
.frame(width: 300, height: 200)

Style property mapping:

CSS-like Property	SwiftUI Modifier
`padding`	`.padding()`
`corner-radius`	`.clipShape(RoundedRectangle(...))`
`glass-background`	`.glassBackgroundEffect()`
`opacity`	`.opacity()`
`shadow-radius`	`.shadow(radius:)`
`frame-width` / `frame-height`	`.frame(width:height:)`
`foreground-color`	`.foregroundStyle()`
`background-color`	`.background()`
`font`	`.font()`
`depth`	`.offset(z:)` — spatial depth in points
`hover-effect`	`.hoverEffect()`

2.6 Codegen Output Structure

For each spatial .vue file, the compiler produces:

ComponentName.swift        # SwiftUI View struct
ComponentName.vm.js        # Vue setup function (runs in JavaScriptCore)
ComponentName.bridge.json  # IPC binding manifest (props, events, bindings)

The .bridge.json describes the contract between JS and Swift:

{
  "component": "HelloVisionOS",
  "reactiveState": {
    "greeting": { "type": "String", "default": "Hello from Vue Spatial" },
    "count": { "type": "Int", "default": 0 }
  },
  "events": {
    "tap:button_0": { "handler": "count_increment" }
  },
  "bindings": [],
  "spatialGestures": []
}

3. Runtime Architecture: `runtime-spatial`

3.1 Dual-Process Model

┌──────────────────────────────────────────────────┐
│  visionOS Application                             │
│                                                    │
│  ┌─ Main Process ──────────────────────────────┐  │
│  │  JavaScriptCore VM                           │  │
│  │  ┌────────────────────────────────────────┐ │  │
│  │  │ @vue/runtime-spatial                    │ │  │
│  │  │ - createSpatialApp()                    │ │  │
│  │  │ - Reactivity (ref, computed, watch)     │ │  │
│  │  │ - Component lifecycle (setup, mounted)  │ │  │
│  │  │ - Composables                           │ │  │
│  │  └──────────────────┬─────────────────────┘ │  │
│  │                     │ SpatialBridge          │  │
│  │                     │ (bidirectional IPC)    │  │
│  └─────────────────────┼───────────────────────┘  │
│                        │                           │
│  ┌─────────────────────▼───────────────────────┐  │
│  │  Renderer Process (SwiftUI)                  │  │
│  │  ┌────────────────────────────────────────┐ │  │
│  │  │ VueViewModel: ObservableObject          │ │  │
│  │  │ - @Published state: [String: Any]       │ │  │
│  │  │ - func get(_ key: String) -> Any        │ │  │
│  │  │ - func emit(_ event: String, ...)       │ │  │
│  │  │ - func binding(_ key: String) -> ...    │ │  │
│  │  └────────────────────────────────────────┘ │  │
│  │  ┌────────────────────────────────────────┐ │  │
│  │  │ Generated SwiftUI Views                 │ │  │
│  │  │ (compiled from <template spatial>)      │ │  │
│  │  └────────────────────────────────────────┘ │  │
│  └─────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

3.2 SpatialBridge IPC Protocol

The bridge communicates via JSON messages over a synchronous JSContext ↔ Swift channel:

// Message types
interface BridgeMessage {
  type: 'patch' | 'event' | 'lifecycle' | 'gesture' | 'navigate'
  id: string          // message ID for correlation
  component: string   // component name
  payload: any
}

// Main → Renderer: state patch
{
  type: 'patch',
  component: 'HelloVisionOS',
  payload: {
    path: 'count',
    value: 42
  }
}

// Renderer → Main: user event
{
  type: 'event',
  component: 'HelloVisionOS',
  payload: {
    name: 'tap:button_0',
    data: {}
  }
}

// Renderer → Main: spatial gesture
{
  type: 'gesture',
  component: 'ModelViewer',
  payload: {
    name: 'spatial:drag',
    translation: { x: 0.1, y: 0, z: -0.05 },
    velocity: { x: 0, y: 0, z: 0 }
  }
}

3.3 Swift-Side Bridge Implementation

@MainActor
class VueViewModel: ObservableObject {
    @Published var state: [String: AnyCodable] = [:]
    private let jsContext: JSContext
    private let componentName: String

    init(component: String, jsContext: JSContext) {
        self.componentName = component
        self.jsContext = jsContext
        setupBridge()
    }

    func get<T>(_ key: String) -> T {
        state[key]?.value as! T
    }

    func binding(_ key: String) -> Binding<String> {
        Binding(
            get: { self.state[key]?.value as? String ?? "" },
            set: { newValue in
                self.sendToJS(.init(
                    type: .event,
                    component: self.componentName,
                    payload: ["name": "update:\(key)", "value": newValue]
                ))
            }
        )
    }

    func emit(_ event: String, data: Any? = nil) {
        sendToJS(.init(
            type: .event,
            component: componentName,
            payload: ["name": event, "data": data ?? NSNull()]
        ))
    }

    private func setupBridge() {
        // JS → Swift: receive patches
        let onPatch: @convention(block) (String) -> Void = { [weak self] json in
            guard let msg = BridgeMessage.decode(json) else { return }
            Task { @MainActor in
                self?.applyPatch(msg.payload)
            }
        }
        jsContext.setObject(onPatch, forKeyedSubscript: "__vue_spatial_patch__" as NSString)
    }

    private func applyPatch(_ payload: [String: Any]) {
        if let path = payload["path"] as? String,
           let value = payload["value"] {
            state[path] = AnyCodable(value)
        }
    }
}

3.4 JavaScript-Side Runtime

// @vue/runtime-spatial

import { reactive, watch, type App } from '@vue/reactivity'

export function createSpatialApp(rootComponent: SpatialComponent): SpatialApp {
  const bridge = createSpatialBridge()
  const app: SpatialApp = {
    component: rootComponent,
    bridge,
    mount() {
      const state = setupComponent(rootComponent, bridge)
      // Watch all reactive state and send patches to SwiftUI
      for (const [key, value] of Object.entries(state)) {
        watch(
          () => state[key],
          (newVal) => {
            bridge.send({
              type: 'patch',
              component: rootComponent.name,
              payload: { path: key, value: newVal }
            })
          },
          { deep: true }
        )
      }
      // Listen for events from SwiftUI
      bridge.on('event', (msg) => {
        const handler = rootComponent.__eventHandlers__[msg.payload.name]
        handler?.(msg.payload.data)
      })
      // Send initial state
      bridge.send({
        type: 'patch',
        component: rootComponent.name,
        payload: { path: '__initial__', value: state }
      })
    }
  }
  return app
}

function createSpatialBridge(): SpatialBridge {
  // In JavaScriptCore environment
  const callbacks = new Map<string, Function[]>()
  return {
    send(message: BridgeMessage) {
      // Call Swift-side function registered on globalThis
      ;(globalThis as any).__vue_spatial_patch__(JSON.stringify(message))
    },
    on(type: string, callback: Function) {
      if (!callbacks.has(type)) callbacks.set(type, [])
      callbacks.get(type)!.push(callback)
    },
    // Called by Swift to deliver events to JS
    __receive__(json: string) {
      const msg: BridgeMessage = JSON.parse(json)
      callbacks.get(msg.type)?.forEach(cb => cb(msg))
    }
  }
}

3.5 Application Entry Point

A spatial Vue app's entry is a Swift @main struct that bootstraps both processes:

// Auto-generated App.swift
import SwiftUI

@main
struct VueSpatialApp: App {
    @StateObject private var runtime = VueSpatialRuntime()

    var body: some Scene {
        // Scenes are declared based on <spatial-window>, <spatial-volume>, etc.
        WindowGroup {
            RootView(vm: runtime.viewModel(for: "App"))
        }

        ImmersiveSpace(id: "immersive") {
            ImmersiveView(vm: runtime.viewModel(for: "ImmersiveScene"))
        }
    }
}

class VueSpatialRuntime: ObservableObject {
    private let jsContext = JSContext()!
    private var viewModels: [String: VueViewModel] = [:]

    init() {
        // Load compiled Vue JS bundle into JavaScriptCore
        let bundle = Bundle.main.url(forResource: "vue-app", withExtension: "js")!
        let code = try! String(contentsOf: bundle)
        jsContext.evaluateScript(code)
    }

    func viewModel(for component: String) -> VueViewModel {
        if let existing = viewModels[component] { return existing }
        let vm = VueViewModel(component: component, jsContext: jsContext)
        viewModels[component] = vm
        return vm
    }
}

3.6 Lifecycle Mapping

Vue Lifecycle	Spatial Behavior
`onMounted`	Fires when SwiftUI `onAppear` triggers → IPC → JS
`onUnmounted`	Fires when SwiftUI `onDisappear` triggers → IPC → JS
`onActivated`	When scene moves to foreground
`onDeactivated`	When scene moves to background
`onSpatialEnter` (new)	When entering immersive space
`onSpatialExit` (new)	When exiting immersive space

3.7 Spatial-Specific Composables

// @vue/runtime-spatial composables

/** Access hand tracking data */
export function useHandTracking(): {
  leftHand: Readonly<Ref<HandAnchor | null>>
  rightHand: Readonly<Ref<HandAnchor | null>>
}

/** Access spatial gestures */
export function useSpatialGesture(): {
  onDrag: (event: SpatialDragEvent) => void
  onRotate: (event: SpatialRotateEvent) => void
  onMagnify: (event: SpatialMagnifyEvent) => void
}

/** Open/close scenes */
export function useSpatialScene(): {
  openWindow: (id: string, options?: WindowOptions) => void
  openVolume: (id: string, options?: VolumeOptions) => void
  openImmersive: (id: string, options?: ImmersiveOptions) => void
  dismissScene: (id: string) => void
}

/** Spatial audio */
export function useSpatialAudio(): {
  playAt: (source: string, position: Vector3) => void
  setAmbient: (source: string) => void
}

/** Access ARKit scene understanding */
export function useSceneUnderstanding(): {
  planes: Readonly<Ref<PlaneAnchor[]>>
  meshes: Readonly<Ref<MeshAnchor[]>>
}

4. Build Pipeline

4.1 Vite Plugin

// vite-plugin-vue-spatial
export default function vueSpatial(): Plugin {
  return {
    name: 'vue-spatial',
    transform(code, id) {
      if (!id.endsWith('.vue')) return
      const { descriptor } = parse(code)
      if (!descriptor.spatial) return // pass through to normal vue plugin

      const swiftCode = compileSpatialTemplate(descriptor)
      const jsCode = compileSpatialScript(descriptor)
      const bridgeManifest = generateBridgeManifest(descriptor)

      // Emit Swift files to output directory
      this.emitFile({ type: 'asset', fileName: `${name}.swift`, source: swiftCode })
      this.emitFile({ type: 'asset', fileName: `${name}.bridge.json`, source: bridgeManifest })

      // Return JS module for bundling (runs in JavaScriptCore)
      return { code: jsCode, map: null }
    }
  }
}

4.2 End-to-End Build Flow

*.vue (spatial)
    │
    ├──► vite-plugin-vue-spatial
    │       ├── compiler-spatial → *.swift files
    │       ├── compiler-sfc → *.vm.js files
    │       └── manifest → *.bridge.json
    │
    ├──► vite bundle → vue-app.js (all JS, runs in JavaScriptCore)
    │
    └──► xcodebuild
            ├── Generated *.swift (SwiftUI views)
            ├── VueSpatialRuntime.swift (bridge framework)
            └── vue-app.js (bundled as resource)
            │
            ▼
        MyApp.app (visionOS)

5. TypeScript Support

5.1 Type Augmentation

// In @vue/runtime-spatial
declare module 'vue' {
  interface ComponentCustomProperties {
    $spatial: {
      openWindow: (id: string) => void
      openVolume: (id: string) => void
      openImmersive: (id: string) => void
    }
  }
}

5.2 Template Type Checking

Spatial components have their own set of intrinsic elements. vue-tsc is extended to type-check spatial templates using a separate intrinsic element map:

// Spatial intrinsic elements
interface SpatialIntrinsicElements {
  'v-stack': { spacing?: number; alignment?: HAlignment }
  'h-stack': { spacing?: number; alignment?: VAlignment }
  'z-stack': { alignment?: Alignment }
  'text': { font?: FontType; color?: string }
  'button': { onTap?: () => void; disabled?: boolean }
  'text-field': { modelValue?: string; placeholder?: string }
  'spatial-window': { title?: string; id?: string; defaultSize?: Size }
  'spatial-volume': { id?: string; defaultSize?: Size3D }
  'spatial-immersive': { id?: string; style?: ImmersionStyle }
  'model3d': { src: string; scale?: number }
  'reality-view': {}
  // ...
}

Drawbacks

Implementation Complexity

This is the largest compilation target extension in Vue's history. compiler-spatial is comparable in scope to compiler-ssr, and the runtime bridge adds an entirely new process model. The implementation spans:

Compiler modifications: ~5,000-8,000 lines
Runtime bridge (JS): ~2,000 lines
Runtime bridge (Swift): ~3,000 lines
Vite plugin: ~1,000 lines

Platform Lock-in

This RFC targets Apple visionOS specifically. SwiftUI codegen only runs on Apple platforms. However:

The compiler-spatial architecture is designed as a pluggable codegen target. Future targets (Android XR / Jetpack Compose Spatial, WebXR) could reuse the same template AST transforms with different output backends.
The <template spatial> syntax and composable APIs are platform-agnostic. Only the generated code is platform-specific.

Two-Language Boundary

The JS ↔ Swift IPC bridge introduces serialization overhead and debugging complexity. Compared to pure SwiftUI:

State updates incur JSON serialization cost (~0.1ms per patch for typical payloads)
Stack traces span two runtimes
Hot reload requires bridging both JS and Swift toolchains

Mitigations:

Batch multiple patches per frame (coalesce within requestAnimationFrame equivalent)
Bridge inspector tooling in Vue DevTools concept
Swift side uses @MainActor to ensure thread safety

Learning Curve

Developers need to learn:

Spatial computing concepts (windows, volumes, immersive spaces)
SwiftUI layout model differences (no CSS box model)
New composables for spatial features

However, the core Vue knowledge (reactivity, Composition API, SFC structure) transfers directly.

Alternatives

1. Pure WebView on visionOS

Safari on visionOS supports WebXR and can display web content in spatial windows. However:

No access to native scene types (Volume, ImmersiveSpace)
No hand tracking, scene understanding, or RealityKit
Performance limitations of web rendering in spatial context
Cannot leverage native system UI patterns (glass material, ornaments)

2. Runtime Abstraction Layer (like Vue Native)

Instead of compile-time codegen, use a runtime that creates SwiftUI views dynamically:

Pro: More flexible, no build step for Swift
Con: Significant performance overhead, SwiftUI's @ViewBuilder is compile-time; dynamic view construction is limited and loses type safety

The compile-time approach was chosen because SwiftUI is fundamentally a compile-time DSL — its @ViewBuilder result builder pattern generates view hierarchies at compile time. A runtime approach would require reimplementing SwiftUI's diffing, which is impractical.

3. Separate `.spatial` File Format

Instead of extending .vue files, create a new file format:

Pro: Clean separation, no SFC parser modifications
Con: Loses the entire Vue ecosystem (Volar, vue-tsc, Vite plugin, syntax highlighting), fragments the developer experience

4. WASM-based Renderer

Compile Vue runtime to WASM running on visionOS:

Pro: Single language (JS/TS throughout)
Con: No access to native SwiftUI views, RealityKit, or visionOS APIs; essentially a sandboxed web view

Adoption strategy

Opt-in, Non-breaking

Adding spatial is purely opt-in. Existing Vue apps are unaffected.
compiler-spatial is a separate package — not bundled unless explicitly used.
No changes to runtime-dom, compiler-dom, or any existing API.

Scaffolding

npm create vue-spatial@latest my-vision-app

Scaffolds a project with:

Vite + vite-plugin-vue-spatial
Xcode project template
Example spatial components
Dev server with visionOS Simulator hot reload

Incremental Adoption in Existing Apps

Spatial components can coexist with DOM components in the same project:

src/
  components/
    Header.vue            # Normal DOM component
    Dashboard.vue         # Normal DOM component
    SpatialViewer.vue     # <script setup spatial> — compiled to SwiftUI

The Vite plugin routes .vue files to the appropriate compiler based on the spatial attribute.

Migration from Existing visionOS Apps

For teams with existing SwiftUI visionOS apps, Vue Spatial can be adopted incrementally:

Wrap existing SwiftUI views as "native components" importable in spatial templates
Gradually move business logic into Vue's reactivity system
Use the bridge to pass data between legacy Swift code and Vue-managed components

Ecosystem Impact

Tool	Required Changes
Volar	Language service support for spatial intrinsic elements
vue-tsc	Type checking for spatial template elements
Vue DevTools	Adapted for JavaScriptCore inspection (or new Spatial DevTools)
Vue Router	Spatial navigation integration (provided by framework, e.g. Taraxacum)
Pinia	Works as-is (runs in JavaScriptCore)
VueUse	Spatial composable counterparts needed for DOM-dependent utilities

Unresolved questions

Hot Module Replacement: How to implement HMR for spatial components? The JS side can use standard Vite HMR via JavaScriptCore reloading, but the Swift side requires either Xcode Previews integration or a dynamic view replacement mechanism.
Component Interop: Can a spatial component use a non-spatial child component, and vice versa? The current design assumes a clean boundary, but cross-target composition would be valuable.
Animations: SwiftUI has its own animation system (.animation(), withAnimation {}). Should Vue's <Transition> and <TransitionGroup> be mapped to SwiftUI animations, or should spatial components use SwiftUI's animation API directly?
State Persistence: When a visionOS app is backgrounded and resumed, should Vue component state be automatically persisted and restored? This is important for spatial apps where users may switch between immersive and shared spaces.
Multi-Window State Sharing: visionOS apps can have multiple windows open simultaneously. How should Vue's app-level state (Pinia stores) be shared across windows that each run in their own scene?
Performance Budgets: What is the acceptable latency for IPC round-trips? Initial measurements suggest <1ms for simple patches, but complex state trees may need optimization strategies (diffing, batching, binary protocols instead of JSON).
Testing: How should spatial components be unit tested? Options include a mock SwiftUI renderer (like runtime-test for DOM), JavaScriptCore-based test runner, or Xcode XCTest integration.
Accessibility: SwiftUI has built-in accessibility support. Should Vue's accessibility directives (aria-*) be mapped to SwiftUI accessibility modifiers, or should spatial components use SwiftUI's native .accessibilityLabel() etc. directly?

Amiya167 · 2026-03-21T11:37:16Z

Amiya167
Mar 21, 2026
Author

Sorry, the merge request link is incorrect. It's here: vuejs/core#14612

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Vuejs For Spatial computing #827

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Vuejs For Spatial computing #827

Uh oh!

Uh oh!

Amiya167 Mar 21, 2026

Summary

Basic example

Motivation

The Spatial Computing Gap

Why Vue is Uniquely Positioned

The Electron Analogy

Constraints

Detailed design

1. SFC Parsing: The spatial Attribute

1.1 Grammar Extension

1.2 Parser Changes (compiler-sfc/parse.ts)

1.3 Validation Rules

2. Template Compilation: compiler-spatial

2.1 Package Structure

2.2 Element Mapping

2.3 Directive Compilation

2.4 Spatial Directives (New)

2.5 Style Compilation

2.6 Codegen Output Structure

3. Runtime Architecture: runtime-spatial

3.1 Dual-Process Model

3.2 SpatialBridge IPC Protocol

3.3 Swift-Side Bridge Implementation

3.4 JavaScript-Side Runtime

3.5 Application Entry Point

3.6 Lifecycle Mapping

3.7 Spatial-Specific Composables

4. Build Pipeline

4.1 Vite Plugin

4.2 End-to-End Build Flow

5. TypeScript Support

5.1 Type Augmentation

5.2 Template Type Checking

Drawbacks

Implementation Complexity

Platform Lock-in

Two-Language Boundary

Learning Curve

Alternatives

1. Pure WebView on visionOS

2. Runtime Abstraction Layer (like Vue Native)

3. Separate .spatial File Format

4. WASM-based Renderer

Adoption strategy

Opt-in, Non-breaking

Scaffolding

Incremental Adoption in Existing Apps

Migration from Existing visionOS Apps

Ecosystem Impact

Unresolved questions

Replies: 1 comment

Uh oh!

Amiya167 Mar 21, 2026 Author

Amiya167
Mar 21, 2026

1. SFC Parsing: The `spatial` Attribute

1.2 Parser Changes (`compiler-sfc/parse.ts`)

2. Template Compilation: `compiler-spatial`

3. Runtime Architecture: `runtime-spatial`

3. Separate `.spatial` File Format

Amiya167
Mar 21, 2026
Author