Finding things by sight with Vibium
find takes a description, an exact locator, or a picture, and hands back
an @eN ref that the next command can act on. This walk uses
var.parts, a small demo shop, and a local fixture page
for the part the shop cannot show. Every output below is real; the refs and
box numbers on your run will differ.
No AI provider is needed for any step here. Where a vision model would have been consulted, the output says so.
1. Open the shop
Section titled “1. Open the shop”vibium go https://var.partsvibium viewport 1280 9002. Find by description
Section titled “2. Find by description”$ vibium find "the Vibium Battery Pack heading"@e1 [h3] "Vibium Battery Pack"
$ vibium find "the Shop link"@e4 [a] "Shop"The page’s own names and roles answered both. When a description fits
several elements equally, find says so rather than picking one:
$ vibium find "the Add to Cart button"Error: 12 elements match "the Add to Cart button" equally; use --all, add a distinguishing word, or use a css or role locator
$ vibium find "the Vibium Battery Pack link" --all@e2 [a]@e3 [a] "Vibium Battery Pack"Two links lead to the battery pack: its photo and its title.
3. Act on the ref
Section titled “3. Act on the ref”$ vibium click @e1$ vibium urlhttps://var.parts/product/12$ vibium go https://var.partsThe heading sits inside the product link, so clicking it opens the product
page. A navigation forgets the page’s refs; the next find starts at @e1
again.
4. Crop a thumbnail
Section titled “4. Crop a thumbnail”Take a screenshot and crop a piece of the battery-pack photo. Any image editor works; so does a clipped screenshot from an SDK:
const img = await vibe.find({ css: "img[alt='Vibium Battery Pack']" });const { x, y } = img.info.box;fs.writeFileSync('thumbnail.png', await vibe.screenshot({ clip: { x: x + 60, y: y + 60, width: 140, height: 140 } }));A 140×140 crop from inside the photo is plenty. A crop that is one flat
color, or just a few pixels, has nothing to match on and find will say
so.
5. Find the picture
Section titled “5. Find the picture”$ vibium find image thumbnail.png@e1 [img] src="/assets/swag-battery-DBOObBdF.jpeg"
$ vibium find image thumbnail.png --json{"ok":true,"result":[{"ref":"@e1","role":"img","tag":"img","name":"Vibium Battery Pack","box":{"x":33,"y":206,"width":284,"height":284},"source":"image","selector":"#root > div:nth-of-type(2) > div > div:nth-of-type(2) > div:nth-of-type(1) > a > div > img"}]}
$ vibium find image thumbnail.png --details@e1 [img] src="/assets/swag-battery-DBOObBdF.jpeg"{"elapsedMs":1916,"method":"sift","vlm":false}The crop was matched locally against the screenshot (method: sift,
vlm: false) and the match landed on the <img> under it, so the ref is a
real element. The box is the whole photo, not just the crop: the ref points
at what you would click. Only the visible viewport is searched; scroll
first for something below the fold.
6. Every copy, with --all
Section titled “6. Every copy, with --all”The shop shows each photo once. The repository’s test server has a page with three copies of one thumbnail and a decoy:
node tests/helpers/test-server.js # prints http://127.0.0.1:PORTvibium go http://127.0.0.1:PORT/find-imagescurl -s http://127.0.0.1:PORT/fixtures/pattern.png -o pattern.png$ vibium find image pattern.png --all@e1 [img] src="/fixtures/pattern.png"@e2 [img] src="/fixtures/pattern.png"@e3 [img] src="/fixtures/pattern.png"
$ vibium find image pattern.png --all --json{"ok":true,"result":[{"ref":"@e1","box":{"x":20,"y":112,"width":96,"height":96},...},{"ref":"@e2","box":{"x":156,"y":112,...}},{"ref":"@e3","box":{"x":20,"y":248,...}}]}The decoy, a different pattern in the same style, is not reported. A picture that is on no page is an empty list:
$ vibium find image other.png --all --json{"ok":true,"result":[]}7. Descriptions and CSS are different questions
Section titled “7. Descriptions and CSS are different questions”$ vibium find css h1@e2 [h1] "VAR Parts & Upgrades"
$ vibium find "h1"Error: "h1" reads like a CSS selector, and find takes a description; for the selector use `vibium find css "h1"`, `find({css: "h1"})` in JavaScript, `find(css="h1")` in Python, or `new SelectorOptions().css("h1")` in Java; for an element actually named "h1" use `vibium find description "h1"` or the description optionA bare string is a description. One that reads like a selector is refused
at once, before any wait and before any model call. find css h1 is the
selector.
8. The same in a script
Section titled “8. The same in a script”const { browser } = require('vibium');const bro = await browser.start();const vibe = await bro.page();await vibe.go('https://var.parts');
const heading = await vibe.find('the Vibium Battery Pack heading');console.log(heading.info.ref, heading.info.text); // @e1 Vibium Battery Packawait heading.click();
await vibe.go('https://var.parts');const photo = await vibe.find({ image: 'thumbnail.png' });console.log(photo.info.box, photo.info.source); // { x: 33, y: 206, ... } imageconst h1 = await vibe.find({ css: 'h1' });await bro.stop();from vibium import browser
bro = browser.start()vibe = bro.page()vibe.go("https://var.parts")
heading = vibe.find("the Vibium Battery Pack heading")print(heading.info.ref, heading.info.text) # @e1 Vibium Battery Packheading.click()
vibe.go("https://var.parts")photo = vibe.find(image="thumbnail.png")print(photo.info.box, photo.info.source) # BoundingBox(...) imageh1 = vibe.find(css="h1")bro.stop()import com.vibium.*;import com.vibium.types.SelectorOptions;import java.nio.file.Path;
Browser bro = Vibium.start();Page vibe = bro.page();vibe.go("https://var.parts");Element heading = vibe.find("the Vibium Battery Pack heading");System.out.println(heading.info().ref() + " " + heading.info().text());heading.click();
vibe.go("https://var.parts");Element photo = vibe.find(new SelectorOptions().image(Path.of("thumbnail.png")));Element h1 = vibe.find(new SelectorOptions().css("h1"));bro.stop();If the shop changes
Section titled “If the shop changes”The fixture page in step 6 is part of the repository and does not change.
Run the whole walk against it instead: its heading is “Gallery”, its
button is “Add to Cart”, its link is “Learn more”, and pattern.png is the
thumbnail. See Vibium Find: Natural Language by Default
for every locator form and How find by intent works
for what happens underneath.