Referencing images, groups, and the @[uuid].images shortcut

A short guide to mention pills, plural shortcuts, and what happens behind the scenes

---

Every prompt in Vilva can reference other nodes on your canvas using a small grammar — the @ mention. When you type @, you get a picker; when you select a node and a field, the editor renders it as an interactive pill. The pill is atomic, hover-previewable, and (most importantly) the model sees a clean structured reference instead of a long URL.

This post is the quick tour: what the syntax actually is, what the new plural form does, and why repeat references collapse the way they do.

---

The grammar in one paragraph

A mention is @[<uuid>].<field>. The UUID identifies the node on your canvas (the editor inserts it for you — you never type it by hand). The optional field after the dot picks what you want from that node:

@[<uuid>]            // the whole node (title + preview + prompt)
@[<uuid>].title      // just the node's title
@[<uuid>].preview    // the node's summary
@[<uuid>].prompt     // the node's main content
@[<uuid>].image1     // the 1st image attached to the node
@[<uuid>].audio2     // the 2nd audio file
@[<uuid>].child2.image1  // chain: walk into child 2 of a group, pick image 1

Text fields substitute inline. Media fields turn into positional markers — @image1, @image2, @audio1 — that the provider pairs with the matching URL.

---

The plural shortcut: .images

When you want all the images on a node — or, more usefully, every image inside a group node like a mood board — the indexed form is awkward. You'd have to enumerate .image1 .image2 .image3 … and remember to update the list every time you add a reference.

The plural form does it for you:

@[<mood-board-uuid>].images

This expands at generate time to every image the group contains — across all child nodes, sorted deterministically by file date — and inserts one positional marker per file. Same shape for the other media kinds: .audios, .videos, .files.

The picker surfaces .images at the top of the field list whenever the target node (or its children) holds at least one image. If the group is still empty, the entry stays visible but greyed, so the affordance is discoverable even before there's anything to reference.

---

Repeat references just work

A subtle thing that used to bite people: if you mentioned the same image twice — once directly via @[hero].image1 and once through a group that happened to contain it — the provider would receive two positional slots and the same URL twice. That bloats the payload and confuses models that key off positional slots.

That's now handled automatically. Within a single prompt, the same underlying file always resolves to the same positional tag. If @image3 is the hero's image on first encounter, every later reference to that file — direct, via a group, via a variable — renders as @image3 and the URL appears in the provider's reference list exactly once. You don't need to track positions manually; the deduplication is silent and per-prompt.

---

A worked example

Say you have:

• A Hero node with one image, harry.png.
• A Mood Board group node containing three images: harry.png, noir-skyline.png, wet-streets.png.

You write:

Wide shot of @[hero].image1 against @[mood-board].images,
moody noir tone.

What the provider gets:

Wide shot of @image1 against @image1 @image2 @image3,
moody noir tone.

image_urls = [
  harry.png,
  noir-skyline.png,
  wet-streets.png,
]

Three unique URLs, one positional slot per unique file, and the hero appears as @image1 in both positions because it's the same file.

---

TL;DR

• Type @, pick a node, pick a field. The editor handles the UUID.
• .images (plural) expands to every image on the node — including everything inside a group.
• Same file, mentioned twice in one prompt = same positional tag, one URL on the wire.

Everything above is part of Vilva's mention package and runs the same way whether you're editing a node's prompt directly or asking the AI agent to do it for you.