#Vapor Moon

#Why The Name

• Vapor Moon is a pun on Paper Moon.
• Moon reflects that the authoring model, generated code, and tooling are MoonBit-first.
• Vapor comes from Vue Vapor and reflects the direction of the compiler: emit direct DOM/SSR-oriented code instead of leaning on a Virtual DOM layer.
• .mbtv stays short, unique, and obviously tied to MoonBit plus Vapor Moon without borrowing Vue's .vue.

#Concept

• author each component in one .mbtv file
• keep <script> blocks and template expressions in plain MoonBit
• compile to raw DOM / luna SSR nodes instead of centering the runtime around a Virtual DOM
• expose island and server-component-style delivery as template syntax, not as an afterthought

#Status

• .mbtv as the default SFC extension
• parsing for <template>, <script>, <script extern>, and <style>
• client code generation for raw DOM-oriented output
• server code generation for luna SSR output
• typed defineProps(), defineEmits(), and defineSlots() contracts
• scoped styles by default
• diagnostics, hover, definition, references, formatting, and completion queries for editor tooling
• a stdio JSON-RPC LSP server plus VS Code, Zed, and Neovim integrations
• ripple-backed incremental compilation infrastructure
• snapshot-heavy compiler and tooling tests

• lang="mbt" and other per-block language switches
• CSS preprocessors
• a finalized cross-component import and linking story
• component event listeners such as @save on component tags
• component-side v-model

#Authoring Model

<script>
import {
  "mizchi/luna/js/resource" @reactivity,
  let signal = @reactivity.signal,
}

let count = signal(0)
</script>

<template>
  <div class="counter">{{ count.get() }}</div>
</template>

<style>
.counter {
  color: red;
}
</style>

• <script> is the canonical setup-scope block.
• <script extern> is for module-scope helpers that should stay outside render/setup.
• The older <script setup> spelling still works as an alias, but plain <script> is the canonical form.
• <style> blocks are scoped by default. Use <style scoped="false"> when you explicitly want global CSS.
• Reactivity is expected to come from explicit MoonBit imports such as @reactivity.signal, @reactivity.computed, and @reactivity.watch.

#Compile Output

moon run src/cmd/vapor_moon -- compile examples/basic.mbtv

import {
  "mizchi/luna/dom" @luna_dom,
  "ubugeeei/vapor_moon/src/runtime" @hlp,
  "ubugeeei/vapor_moon/src/runtime/dom" @dom,
  "mizchi/luna/js/resource" @reactivity,
}

pub fn render_dom() -> @luna_dom.DomNode {
  let signal = @reactivity.signal,
  let count = signal(0)
  (fn() {
      let n0 = @dom.el("div")
      @dom.setAttr(n0, ("class", @dom.attr("counter")))
      @dom.setAttr(n0, ("data-vm-scope", @dom.attr("vm-4048536636")))
      @dom.append(n0.as_node(), (fn() {
            let n1 = @dom.text("")
            @dom.setText(n1, fn() { count.get().to_string() })
            n1
          })())
      @dom.into(n0)
    })()
}

import {
  "mizchi/luna/core" @luna_core,
  "ubugeeei/vapor_moon/src/runtime" @hlp,
  "ubugeeei/vapor_moon/src/runtime/server" @vm_server,
  "mizchi/luna/js/resource" @reactivity,
}

pub fn render_ssr() -> @luna_core.StaticDomNode {
  let signal = @reactivity.signal,
  let count = signal(0)
  @luna_core.h("div", [("class", @luna_core.attr_static("counter")), ("data-vm-scope", @luna_core.attr_static("vm-4048536636"))], [
      @luna_core.text_dyn(fn() { count.get().to_string() })
    ])
}

[data-vm-scope="vm-4048536636"] .counter { color: red; }

component=Basic
extension=.mbtv
scope=vm-4048536636
islands=<none>
props_binding=<none>
props=<none>
emits_binding=<none>
emits=<none>
slots_binding=<none>
slots=<none>

#Script Macros And Setup Helpers

struct Props {
  title : String
  count : Int
}

struct Emits {
  save : String
  cancel : Unit
}

struct Slots {
  default : Unit
  footer : String
}

let props : Props = defineProps()
let emit : Emits = defineEmits()
let slots : Slots = defineSlots()

let props : Props = defineProps({
  count: 0,
  tone: "primary",
})

• these macros are compiler-only markers and disappear from lowered setup code
• caller-facing generated props become optional when a prop has a default
• generated render_dom and render_ssr functions take typed contracts as plain arguments
• runtime declaration literals are intentionally unsupported
• useId() and useTemplateRef("name") are supported inside setup scope

#Generic Components

<script generic="T, U : Show">
struct Props[T, U] {
  items : Array[T]
  selected : U
}

struct Emits[T] {
  choose : T
}

struct Slots[T, U] {
  default : T
  label : U
}

let props : Props[T, U] = defineProps()
let emit : Emits[T] = defineEmits()
let slots : Slots[T, U] = defineSlots()
</script>

• generic="..." is only valid on <script>
• generic parameters must appear in the local contract types referenced by defineProps() / defineEmits() / defineSlots() / defineExpose()
• the compiler threads those parameters through generated contract and render signatures
• generics stay type-level only; no runtime validation or runtime type registry is emitted

#Supported Template Features

<script>
import {
  "mizchi/luna/js/resource" @reactivity,
  let signal = @reactivity.signal,
}

let count = signal(0)
</script>

<template>
  <section class="counter">
    <button @click='count.update(fn(n) { n + 1 })'>+</button>
    <p>{{ "Count: " + count.get().to_string() }}</p>
    <CounterPanel :count="count.get()" client:visible />
  </section>
</template>

<style>
.counter {
  display: grid;
  gap: 12px;
}
</style>

#Compile output

=== client ===
pub fn render_dom() -> @luna_dom.DomNode {
  let signal = @reactivity.signal,
  let count = signal(0)
  (fn() {
      let __vm_el = @dom.el("div")
      @dom.setAttr(__vm_el, ("class", @dom.attr("counter")))
      @dom.setAttr(__vm_el, ("data-vm-scope", @dom.attr("vm-4048536636")))
      @dom.append(__vm_el.as_node(), @dom.setText(fn() { count.get().to_string() }))
      @dom.into(__vm_el)
    })()
}
=== server ===
pub fn render_ssr() -> @luna_core.StaticDomNode {
  let signal = @reactivity.signal,
  let count = signal(0)
  @luna_core.h("div", [("class", @luna_core.attr_static("counter")), ("data-vm-scope", @luna_core.attr_static("vm-4048536636"))], [
      @luna_core.text_dyn(fn() { count.get().to_string() })
    ])
}
=== css ===
[data-vm-scope="vm-4048536636"] .counter { color: red; }
=== meta ===
component=Basic
extension=.mbtv
scope=vm-4048536636

#Compiler macros

struct Props {
  title : String
  count : Int
}
struct Emits {
  save : String
  cancel : Unit
}
struct Slots {
  default : Unit
  footer : String
}
struct Expose {
  focus : Unit
}
let props : Props = defineProps()
let emit : Emits = defineEmits()
let slots : Slots = defineSlots()
let expose : Expose = defineExpose()

let props : Props = defineProps({
  count: 0,
  tone: "primary",
})

• these declarations are compiler-only and disappear from lowered setup-scope script
• the compiler generates typed component surfaces such as ExampleProps, ExampleEmits, ExampleDomSlots, and ExampleSsrSlots
• a prop with a default stays required inside the component but becomes optional in the generated caller-facing props type
• generated render_dom / render_ssr functions take those contracts as plain arguments, so the runtime does not own props, emits, or slot bags
• defineProps() / defineEmits() / defineSlots() / defineExpose() are zero-argument markers that bind to the annotated local struct
• defineProps({ ... }) is reserved for defaults only, not runtime declarations
• defineExpose() is type-first metadata for the component's exposed surface; it participates in generic validation and tooling even though it is erased from lowered setup code
• runtime-declaration literals are intentionally unsupported, so component interfaces stay type-first and MoonBit-native

#Supported template features

• text nodes and {{ expression }}
• static attributes
• dynamic attributes with :prop="expr" and v-bind:prop="expr"
• event handlers with @event="expr" and v-on:event="expr"
• Vue-style event modifiers: .stop, .prevent, .self, .capture, .once, .passive
• v-if, v-else-if, and v-else
• v-for="item in items" and v-for="(item, index) in items"
• v-show
• v-unsafe-html
• v-model on native form controls such as input, textarea, and select
• v-once
• v-match, v-case, and v-default
• ref and :ref
• named slots with v-slot, v-slot:name, and #name
• component-looking tags via uppercase names
• scoped styles

• client:load
• client:idle
• client:visible
• client:media="(max-width: 768px)"
• client:only
• server:defer

#CLI

• moon run src/cmd/vapor_moon -- compile path/to/Component.mbtv prints a compile snapshot to stdout
• moon run src/cmd/vapor_moon -- watch path/to/components recursively watches .mbtv files and writes sibling .client.mbt, .server.mbt, and .css outputs on add/change/remove

#Examples

• examples/basic.mbtv: the smallest end-to-end SFC with setup, template, and scoped style
• examples/directives.mbtv: v-if and v-for
• examples/macros.mbtv: typed defineProps() and defineEmits()
• examples/props_defaults.mbtv: prop defaults and caller-facing optional props
• examples/slots.mbtv: typed defineSlots()
• examples/reactivity_basics.mbtv: signal, computed, watch, and effect
• examples/lifecycle_refs.mbtv: useId(), useTemplateRef(), on_mount, and on_cleanup
• examples/composable_counter.mbtv: a small composable built from luna primitives
• examples/generic_list.mbtv: generic component contracts on <script generic="...">
• examples/island_visible.mbtv: client:visible
• examples/media_and_defer.mbtv: client:media(...) and server:defer

#CLI And Tooling

moon run src/cmd/vapor_moon -- compile examples/basic.mbtv
moon run src/cmd/vapor_moon -- analyze examples/basic.mbtv
moon run src/cmd/vapor_moon -- diagnostics examples/macros.mbtv
moon run src/cmd/vapor_moon -- hover examples/macros.mbtv 17 13
moon run src/cmd/vapor_moon -- definition examples/macros.mbtv 16 39
moon run src/cmd/vapor_moon -- references examples/macros.mbtv 16 39
moon run src/cmd/vapor_moon -- complete examples/macros.mbtv 17 18
moon run src/cmd/vapor_moon -- format examples/basic.mbtv
moon run --target js src/cmd/vapor_moon_lsp

• compile <file.mbtv>
• analyze <file.mbtv>
• diagnostics <file.mbtv>
• hover <file.mbtv> <line> <character>
• definition <file.mbtv> <line> <character>
• references <file.mbtv> <line> <character> [includeDeclaration]
• complete <file.mbtv> <line> <character>
• format <file.mbtv>

#Editor Integrations

• VS Code extension source lives in editors/vscode/
• Zed extension source lives in editors/zed/
• Neovim runtime files live in editors/neovim/
• quick install notes live in editors/README.md
• the repo-local launcher is bin/vapor-moon-lsp

moon run --target js src/cmd/vapor_moon_lsp

• moon on PATH
• a JS runtime such as node, bun, or deno on PATH

#Development

• MoonBit toolchain on PATH
• node on PATH for JS-targeted LSP tests and the editor-facing LSP server

bash scripts/patch_mooncakes.sh
moon fmt
moon check
moon test src/compiler
moon test src/tooling
moon build --target js src/lsp
moon test --target js src/lsp
moon build --target js src/cmd/vapor_moon_lsp
bash scripts/smoke_cli.sh
bash scripts/smoke_lsp.sh

#Publishing

moon register   # first time only
moon login
moon test
moon package --list
moon publish

• bump version in moon.mod.json using semver
• confirm name, repository, license, description, and keywords are up to date
• review the packaged files with moon package --list; this repository uses exclude in moon.mod.json to keep editor fixtures, examples, scripts, and test files out of the published archive

#Git Setup

• .gitignore for MoonBit build outputs and mooncakes cache
• .gitattributes for LF normalization
• .githooks/pre-commit to run formatting, checks, and compiler/tooling tests

git config core.hooksPath .githooks