From 422ce7f6c7164364f4d148fc0d47792aa0572757 Mon Sep 17 00:00:00 2001
From: Danila Poyarkov <dev@dannote.net>
Date: Sat, 3 Oct 2026 11:32:14 +0400
Subject: [PATCH 1/2] Link Vue's docs for Vapor mode, SFCs, and SSR

---
 README.md                            | 2 +-
 guides/features/sfc.md               | 2 ++
 guides/features/templates-and-ssr.md | 2 +-
 guides/features/vapor.md             | 2 +-
 4 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index bf3be7c..5d11f9d 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 [![Hex.pm](https://img.shields.io/hexpm/v/vize.svg)](https://hex.pm/packages/vize) [![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/vize)
 
-Elixir bindings for [Vize](https://vizejs.dev), a Vue.js toolchain written in Rust. Parse, analyze, lint, and compile Vue single-file components from Elixir, including Vapor mode and its intermediate representation, plus a LightningCSS-based CSS pipeline.
+Elixir bindings for [Vize](https://vizejs.dev), a [Vue.js](https://vuejs.org) toolchain written in Rust. Parse, analyze, lint, and compile Vue [single-file components](https://vuejs.org/guide/scaling-up/sfc.html) from Elixir, including [Vapor mode](https://github.com/vuejs/core/releases/tag/v3.6.0-beta.1#about-vapor-mode) and its intermediate representation, plus a [LightningCSS](https://lightningcss.dev)-based CSS pipeline.
 
 ```elixir
 {:ok, result} =
diff --git a/guides/features/sfc.md b/guides/features/sfc.md
index b275f14..13ddc8a 100644
--- a/guides/features/sfc.md
+++ b/guides/features/sfc.md
@@ -1,5 +1,7 @@
 # Single-File Components
 
+A [single-file component](https://vuejs.org/guide/scaling-up/sfc.html) is a `.vue` file with a template, scripts, and styles. Vue's [SFC syntax specification](https://vuejs.org/api/sfc-spec.html) describes the blocks.
+
 ## Parsing
 
 `Vize.parse_sfc/1` returns the descriptor: the template, `<script>`, `<script setup>`, styles, and custom blocks, each with its content, `lang`, attributes, and location.
diff --git a/guides/features/templates-and-ssr.md b/guides/features/templates-and-ssr.md
index 4183bab..6ded903 100644
--- a/guides/features/templates-and-ssr.md
+++ b/guides/features/templates-and-ssr.md
@@ -19,7 +19,7 @@ Options:
 
 ## Server-side rendering
 
-`Vize.compile_ssr/1` compiles a template to code that writes HTML with `_push()`. Run it in a JavaScript runtime such as [QuickBEAM](https://github.com/elixir-volt/quickbeam).
+`Vize.compile_ssr/1` compiles a template for Vue's [server-side rendering](https://vuejs.org/guide/scaling-up/ssr.html), to code that writes HTML with `_push()`. Run it in a JavaScript runtime such as [QuickBEAM](https://github.com/elixir-volt/quickbeam).
 
 ```elixir
 {:ok, result} = Vize.compile_ssr("<div>{{ msg }}</div>")
diff --git a/guides/features/vapor.md b/guides/features/vapor.md
index 6a9415d..ef260d2 100644
--- a/guides/features/vapor.md
+++ b/guides/features/vapor.md
@@ -1,6 +1,6 @@
 # Vapor Mode
 
-Vapor is Vue's compilation mode without a virtual DOM: a template compiles to code that creates and updates DOM nodes directly.
+[Vapor mode](https://github.com/vuejs/core/releases/tag/v3.6.0-beta.1#about-vapor-mode) is Vue's compilation mode without a virtual DOM: a template compiles to code that creates and updates DOM nodes directly. It is new in Vue 3.6.
 
 ## Compiling
 

From d5ebe7dbca5061225e5472aaa8ae471950c681bb Mon Sep 17 00:00:00 2001
From: Danila Poyarkov <dev@dannote.net>
Date: Sat, 3 Oct 2026 11:45:31 +0400
Subject: [PATCH 2/2] vapor_split: locate elements by DOM node position

Vapor's child and next references count every DOM child node, text runs
and anchors included, but the split's tag mapping counted element
children only. After a text node it looked for the wrong element, found
none, and silently skipped the slot: in
<li>a<ul><li>{{ b }}</li></ul></li> the interpolation disappeared.

Record each tag's node index while scanning the template and resolve
references with it. If an element still can't be located, return an
error instead of dropping its slot or binding.
---
 CHANGELOG.md                          |  5 ++
 native/vize_ex_nif/src/html_inject.rs | 70 +++++++++++++++++----------
 native/vize_ex_nif/src/lib.rs         |  5 +-
 native/vize_ex_nif/src/vapor_split.rs | 65 ++++++++++++++++++-------
 test/vize/vapor_split_test.exs        | 24 +++++++++
 5 files changed, 124 insertions(+), 45 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ffbf25..7421f61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Fixed
+
+- `vapor_split/1` no longer drops slots when a text node comes before an element. Vapor counts text nodes when it navigates the template, so in `<li>a<ul><li>{{ b }}</li></ul></li>` the split looked for the wrong element and silently left `{{ b }}` out. Elements are now located by their DOM node position.
+- `vapor_split/1` returns an error if it can't locate an element a slot or binding belongs to, instead of leaving the slot out.
+
 ## 0.16.0 - 2026-10-01
 
 ### Added
diff --git a/native/vize_ex_nif/src/html_inject.rs b/native/vize_ex_nif/src/html_inject.rs
index 255d9ba..007a80c 100644
--- a/native/vize_ex_nif/src/html_inject.rs
+++ b/native/vize_ex_nif/src/html_inject.rs
@@ -3,7 +3,9 @@ pub(crate) struct TagEntry {
     pub(crate) tag: String,
     pub(crate) pos: usize,
     pub(crate) parent: Option<usize>,
-    pub(crate) child_index: usize,
+    /// Position among the parent's child nodes, counting text runs and anchors
+    /// as the DOM does. Vapor's `child`/`next` offsets count the same way.
+    pub(crate) node_index: usize,
     pub(crate) open_start: usize,
     pub(crate) open_end: usize,
     pub(crate) close_start: Option<usize>,
@@ -61,11 +63,14 @@ fn skip_declaration(bytes: &[u8], i: &mut usize) {
     }
 }
 
-fn sibling_count(entries: &[TagEntry], parent: Option<usize>) -> usize {
-    entries
-        .iter()
-        .filter(|entry| entry.parent == parent)
-        .count()
+fn next_node_index(
+    node_counts: &mut std::collections::HashMap<Option<usize>, usize>,
+    parent: Option<usize>,
+) -> usize {
+    let count = node_counts.entry(parent).or_default();
+    let index = *count;
+    *count += 1;
+    index
 }
 
 pub(crate) fn parse_tag_tree(html: &str) -> Vec<TagEntry> {
@@ -73,24 +78,32 @@ pub(crate) fn parse_tag_tree(html: &str) -> Vec<TagEntry> {
     let len = bytes.len();
     let mut entries: Vec<TagEntry> = Vec::new();
     let mut stack: Vec<usize> = Vec::new();
+    let mut node_counts: std::collections::HashMap<Option<usize>, usize> =
+        std::collections::HashMap::new();
+    let mut in_text = false;
     let mut i = 0;
 
     while i < len {
         if bytes[i] != b'<' {
+            if !in_text {
+                *node_counts.entry(stack.last().copied()).or_default() += 1;
+                in_text = true;
+            }
             i += 1;
             continue;
         }
+        in_text = false;
 
         if html[i..].starts_with(VAPOR_ANCHOR) {
             // Anchors are DOM nodes at runtime, so child/next offsets count them.
             let parent = stack.last().copied();
-            let child_index = sibling_count(&entries, parent);
+            let node_index = next_node_index(&mut node_counts, parent);
             let pos = entries.len();
             entries.push(TagEntry {
                 tag: VAPOR_ANCHOR_TAG.to_string(),
                 pos,
                 parent,
-                child_index,
+                node_index,
                 open_start: i,
                 open_end: i + VAPOR_ANCHOR.len(),
                 close_start: None,
@@ -159,14 +172,14 @@ pub(crate) fn parse_tag_tree(html: &str) -> Vec<TagEntry> {
         let open_end = i;
 
         let parent = stack.last().copied();
-        let child_index = sibling_count(&entries, parent);
+        let node_index = next_node_index(&mut node_counts, parent);
 
         let pos = entries.len();
         entries.push(TagEntry {
             tag: tag_name.clone(),
             pos,
             parent,
-            child_index,
+            node_index,
             open_start,
             open_end,
             close_start: None,
@@ -200,11 +213,9 @@ pub(crate) fn build_elem_to_tag(
             match op {
                 vize_atelier_vapor::ir::OperationNode::ChildRef(node) => {
                     if let Some(&parent_tag_pos) = map.get(&node.parent_id) {
-                        let children: Vec<_> = tags
-                            .iter()
-                            .filter(|tag| tag.parent == Some(parent_tag_pos))
-                            .collect();
-                        if let Some(child) = children.get(node.offset) {
+                        if let Some(child) = tags.iter().find(|tag| {
+                            tag.parent == Some(parent_tag_pos) && tag.node_index == node.offset
+                        }) {
                             map.insert(node.child_id, child.pos);
                         }
                     }
@@ -212,12 +223,10 @@ pub(crate) fn build_elem_to_tag(
                 vize_atelier_vapor::ir::OperationNode::NextRef(node) => {
                     if let Some(&prev_tag_pos) = map.get(&node.prev_id) {
                         if let Some(prev_entry) = tags.get(prev_tag_pos) {
-                            let siblings: Vec<_> = tags
-                                .iter()
-                                .filter(|tag| tag.parent == prev_entry.parent)
-                                .collect();
-                            let target_idx = prev_entry.child_index + node.offset;
-                            if let Some(sibling) = siblings.get(target_idx) {
+                            let target = prev_entry.node_index + node.offset;
+                            if let Some(sibling) = tags.iter().find(|tag| {
+                                tag.parent == prev_entry.parent && tag.node_index == target
+                            }) {
                                 map.insert(node.child_id, sibling.pos);
                             }
                         }
@@ -379,9 +388,18 @@ mod tests {
         assert_eq!(tags[1].close_start, None);
         assert_eq!(tags[2].close_start, None);
         assert_eq!(tags[3].close_start, Some(html.find("</span>").unwrap()));
-        assert_eq!(tags[1].child_index, 0);
-        assert_eq!(tags[2].child_index, 1);
-        assert_eq!(tags[3].child_index, 2);
+        assert_eq!(tags[1].node_index, 0);
+        assert_eq!(tags[2].node_index, 1);
+        assert_eq!(tags[3].node_index, 2);
+    }
+
+    #[test]
+    fn parse_tag_tree_counts_text_runs_in_node_indices() {
+        let tags = parse_tag_tree("<p>a<b></b>c<!----><i></i></p>");
+
+        assert_eq!(tags[1].node_index, 1);
+        assert_eq!(tags[2].node_index, 3);
+        assert_eq!(tags[3].node_index, 4);
     }
 
     #[test]
@@ -403,8 +421,8 @@ mod tests {
         assert_eq!(tags.len(), 2);
         assert_eq!(tags[0].parent, None);
         assert_eq!(tags[1].parent, None);
-        assert_eq!(tags[0].child_index, 0);
-        assert_eq!(tags[1].child_index, 1);
+        assert_eq!(tags[0].node_index, 0);
+        assert_eq!(tags[1].node_index, 1);
     }
 
     #[test]
diff --git a/native/vize_ex_nif/src/lib.rs b/native/vize_ex_nif/src/lib.rs
index fef74a8..a6190f0 100644
--- a/native/vize_ex_nif/src/lib.rs
+++ b/native/vize_ex_nif/src/lib.rs
@@ -1013,7 +1013,10 @@ fn vapor_split_nif_impl<'a>(env: Env<'a>, source: &str) -> NifResult<Term<'a>> {
 
     let ir = transform_to_ir(&allocator, &root, source);
 
-    let (statics, slots, bindings) = process_block(env, &ir.block, &ir, source);
+    let (statics, slots, bindings) = match process_block(env, &ir.block, &ir, source) {
+        Ok(split) => split,
+        Err(message) => return Ok(error_term(env, vec![message])),
+    };
 
     let split = EncodedVaporSplit {
         statics,
diff --git a/native/vize_ex_nif/src/vapor_split.rs b/native/vize_ex_nif/src/vapor_split.rs
index fc58708..2ad9ad7 100644
--- a/native/vize_ex_nif/src/vapor_split.rs
+++ b/native/vize_ex_nif/src/vapor_split.rs
@@ -34,13 +34,13 @@ fn split_block<'a, 'b>(
     block: &'b BlockIRNode<'b>,
     ir: &'b RootIRNode<'b>,
     source: &str,
-) -> EncodedSplitBlock<'a> {
-    let (statics, slots, bindings) = process_block(env, block, ir, source);
-    EncodedSplitBlock {
+) -> Result<EncodedSplitBlock<'a>, String> {
+    let (statics, slots, bindings) = process_block(env, block, ir, source)?;
+    Ok(EncodedSplitBlock {
         statics,
         slots,
         bindings,
-    }
+    })
 }
 
 fn encode_slot_if_split<'a, 'b>(
@@ -48,20 +48,22 @@ fn encode_slot_if_split<'a, 'b>(
     if_node: &'b IfIRNode<'b>,
     ir: &'b RootIRNode<'b>,
     source: &str,
-) -> Term<'a> {
+) -> Result<Term<'a>, String> {
     let negative = match &if_node.negative {
-        Some(NegativeBranch::Block(block)) => Some(split_block(env, block, ir, source).encode(env)),
-        Some(NegativeBranch::If(nested)) => Some(encode_slot_if_split(env, nested, ir, source)),
+        Some(NegativeBranch::Block(block)) => {
+            Some(split_block(env, block, ir, source)?.encode(env))
+        }
+        Some(NegativeBranch::If(nested)) => Some(encode_slot_if_split(env, nested, ir, source)?),
         None => None,
     };
 
-    EncodedIfSlot {
+    Ok(EncodedIfSlot {
         kind: atoms::if_node(),
         condition: encode_simple_expr(env, &if_node.condition),
-        positive: split_block(env, &if_node.positive, ir, source),
+        positive: split_block(env, &if_node.positive, ir, source)?,
         negative,
     }
-    .encode(env)
+    .encode(env))
 }
 
 fn encode_slot_for_split<'a, 'b>(
@@ -69,8 +71,8 @@ fn encode_slot_for_split<'a, 'b>(
     for_node: &'b ForIRNode<'b>,
     ir: &'b RootIRNode<'b>,
     source: &str,
-) -> Term<'a> {
-    EncodedForSlot {
+) -> Result<Term<'a>, String> {
+    Ok(EncodedForSlot {
         kind: atoms::for_node(),
         source: encode_simple_expr(env, &for_node.source),
         value: for_node
@@ -81,9 +83,9 @@ fn encode_slot_for_split<'a, 'b>(
             .key_prop
             .as_ref()
             .map(|key_prop| encode_simple_expr(env, key_prop)),
-        render: split_block(env, &for_node.render, ir, source),
+        render: split_block(env, &for_node.render, ir, source)?,
     }
-    .encode(env)
+    .encode(env))
 }
 
 fn encode_slot_component<'a>(env: Env<'a>, node: &CreateComponentIRNode) -> Term<'a> {
@@ -376,12 +378,14 @@ fn split_on_markers<'a>(
     (statics, ordered_slots, bindings)
 }
 
+type SplitResult<'a> = Result<(Vec<String>, Vec<Term<'a>>, Vec<EncodedSplitBinding<'a>>), String>;
+
 pub(crate) fn process_block<'a, 'b>(
     env: Env<'a>,
     block: &'b BlockIRNode<'b>,
     ir: &'b RootIRNode<'b>,
     source: &str,
-) -> (Vec<String>, Vec<Term<'a>>, Vec<EncodedSplitBinding<'a>>) {
+) -> SplitResult<'a> {
     let template_html: String = block
         .returns
         .iter()
@@ -457,6 +461,31 @@ pub(crate) fn process_block<'a, 'b>(
         }
     }
 
+    // A slot whose element can't be located would silently disappear from the
+    // output, so fail instead.
+    let bound_elements = block
+        .operation
+        .iter()
+        .filter_map(|operation| match operation {
+            OperationNode::SetEvent(event) => Some(event.element),
+            OperationNode::Directive(dir) if matches!(dir.name, "model" | "show") => {
+                Some(dir.element)
+            }
+            _ => None,
+        });
+    if let Some(element) = text_effects
+        .iter()
+        .map(|text| text.element)
+        .chain(html_effects.iter().map(|html| html.element))
+        .chain(prop_effects.iter().map(|prop| prop.element))
+        .chain(bound_elements)
+        .find(|element| !elem_to_tag.contains_key(element))
+    {
+        return Err(format!(
+            "vapor_split could not locate element {element} in the template"
+        ));
+    }
+
     for prop in &prop_effects {
         if let Some(&tag_pos) = elem_to_tag.get(&prop.element) {
             let values: Vec<Term<'a>> = prop
@@ -551,7 +580,7 @@ pub(crate) fn process_block<'a, 'b>(
         match operation {
             OperationNode::If(if_node) => {
                 let source_offset = if_node.condition.loc.span.start;
-                let slot = encode_slot_if_split(env, if_node, ir, source);
+                let slot = encode_slot_if_split(env, if_node, ir, source)?;
                 let marker = push_slot_marker(&mut slots, slot, source_offset);
                 inject_structural_marker(
                     &mut html,
@@ -565,7 +594,7 @@ pub(crate) fn process_block<'a, 'b>(
             }
             OperationNode::For(for_node) => {
                 let source_offset = for_node.source.loc.span.start;
-                let slot = encode_slot_for_split(env, for_node, ir, source);
+                let slot = encode_slot_for_split(env, for_node, ir, source)?;
                 let marker = push_slot_marker(&mut slots, slot, source_offset);
                 inject_structural_marker(
                     &mut html,
@@ -601,5 +630,5 @@ pub(crate) fn process_block<'a, 'b>(
         }
     }
 
-    split_on_markers(&html, slots, binding_nodes)
+    Ok(split_on_markers(&html, slots, binding_nodes))
 }
diff --git a/test/vize/vapor_split_test.exs b/test/vize/vapor_split_test.exs
index 46420cb..6190468 100644
--- a/test/vize/vapor_split_test.exs
+++ b/test/vize/vapor_split_test.exs
@@ -212,4 +212,28 @@ defmodule Vize.VaporSplitTest do
       assert [%{kind: :set_event, node: %{value: "off"}}] = if_slot.positive.bindings
     end
   end
+
+  describe "text nodes before elements" do
+    test "an element after a text node in a nested list keeps its slot" do
+      {:ok, split} =
+        Vize.vapor_split(~S|<ul><li>a<ul><li>{{ b }}</li></ul></li><li>c</li></ul>|)
+
+      assert split.statics == ["<ul><li>a<ul><li>", "</li></ul></li><li>c</li></ul>"]
+      assert [%{kind: :set_text, values: ["b"]}] = split.slots
+    end
+
+    test "slots after mixed text and elements" do
+      {:ok, split} = Vize.vapor_split(~S|<p>a<b>{{ x }}</b>c<i :title="t">{{ y }}</i></p>|)
+
+      assert split.statics == ["<p>a<b>", "</b>c<i title=\"", "\">", "</i></p>"]
+      assert Enum.map(split.slots, & &1.kind) == [:set_text, :set_prop, :set_text]
+    end
+
+    test "an event after a text node is bound to its element" do
+      {:ok, split} = Vize.vapor_split(~S|<div>hi<button @click="go">x</button></div>|)
+
+      assert [%{at: {0, offset}}] = split.bindings
+      assert binary_part(hd(split.statics), 0, offset) == "<div>hi<button"
+    end
+  end
 end