Use Sightmap as a Go Library

The module github.com/sightmap/sightmap/go contains the packages used by the sightmap CLI. Snapshot enrichers, analysis programs, and other Go tools can import the same component model and matcher.

go get github.com/sightmap/sightmap/go

Requires Go 1.25.2 or later.

Design goals

Shared component model and matcher. The comps and match packages give consumers the same types and matching logic.
Tree-level matching. Matching operates on a component tree whose nodes carry SelectorPart values. This supports offline analysis of saved trees and synthetic selectors for native-mobile nodes.
Embedded browser probe. The probe package exposes the browser-side probe.js source as probe.ProbeJS, including its bounds, visibility, and interactivity logic.

Package map

All import paths are rooted at github.com/sightmap/sightmap/go/.

Package	Purpose
`sightmap`	Corpus loading and matching (the thread-safe `Corpus` handle), plus `Validate`, `Lint`, and `LoadConfig`
`comps`	Component model types (`ComponentNode`, `SelectorPart`, `Bounds`) and tree operations (`Walk`, `Collect`, `Filter`)
`sel`	CSS selector parsing and single-node matching for the sightmap selector subset
`match`	NFA multi-query matcher that applies component definitions in one tree traversal
`compquery`	Component-query parser and resolver for queries such as `ProductCard[name^="Weber"]`
`extract`	Post-probe pipeline that merges accessibility data with probe output and rebuilds the tree; no browser dependency
`probe`	Embedded `probe.js` browser-side extractor, exposed as `probe.ProbeJS`
`browser`	Minimal `Page` interface, a direct-CDP client for any Chrome debugging port (no chromedp), and the session `Collector` that buffers console/network
`observe`	The live acquire-and-annotate operation: `observe.Page` connects, extracts, matches the corpus, and computes coverage; `observe.Format` renders it
`coverage`	T1/T2/T3 coverage scoring, parent maps, orphan-slot analysis, and cluster traces
`viewset`	View capture sets: paths, the novelty gate, and pruning
`authoring`	Live DOM scans behind the authoring commands (`suggest` candidates, `discover` link patterns)
`render`	Tree rendering for snapshot- and inspect-style output
`atlas`	The community atlas behind `sightmap atlas`: index schema and cache, domain-ranked search, the HTTPS fetch policy, and the atomic `Install` operation
`conformance`	Fixture documentation and data used by the component-matching conformance tests

Load a corpus and match a tree

The core flow uses two API calls. sightmap.Load parses a .sightmap/ directory into a Corpus (a thread-safe handle with a compiled-query cache), and Corpus.MatchTree applies it to a component tree for a page URL.

main.go

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/sightmap/sightmap/go/comps"
	"github.com/sightmap/sightmap/go/sightmap"
)

func main() {
	// Load every YAML file under .sightmap/ into a Corpus.
	corpus, err := sightmap.Load(".sightmap")
	if err != nil {
		log.Fatal(err)
	}

	// Read a component tree saved by `sightmap snapshot --tree-out`.
	data, err := os.ReadFile("home.snap.tree.json")
	if err != nil {
		log.Fatal(err)
	}
	root := &comps.ComponentNode{}
	if err := json.Unmarshal(data, root); err != nil {
		log.Fatal(err)
	}

	// Apply the corpus to the tree for this page URL.
	matches := corpus.MatchTree(root, "https://example.com/")

	// Walk the tree and print every matched node.
	comps.Walk(root, func(n *comps.ComponentNode, depth int) bool {
		if m := matches[n]; m != nil {
			fmt.Printf("%s -> [%s]\n", n.Role, m.Name)
		}
		return true
	})
}

MatchTree returns map[*comps.ComponentNode]*match.SightmapMatch. Each match contains the component Name and Memory notes. The library selects the most specific view whose route matches the URL pathname, using declaration order only to break equal-specificity ties (per the stream 1 spec). Trailing slashes on the URL path are normalized away before matching. If no view matches, global components still apply.

The Corpus handle

sightmap.Corpus is the single operational handle: load one with Load, then hold it for the life of a run. It is safe for concurrent use and caches compiled match queries by page URL, so repeated MatchTree calls reuse the compiled queries. To pick up on-disk edits in a long-lived process, call Load again and swap the handle.

Method	Purpose
`MatchTree(root comps.ComponentNode, pageURL string) map[comps.ComponentNode]*match.SightmapMatch`	Apply the corpus to a tree for a URL
`Components(pageURL string) []match.SightmapComponent`	Return the merged component list for a URL without matching a tree
`ViewForURL(pageURL string) *sightmap.View`	Return the most specific matching view, or `nil` when no view matches
`ViewByName(name string) *sightmap.View`	Return the view with the given name, or `nil`
`GlobalComponentNames() map[string]bool`	Return the names declared at global scope

Load(dir) is shorthand for DirLoader(dir).Load(). For an existing in-memory corpus, StaticLoader(c *Corpus) Loader wraps it as a Loader; the LoaderFunc type, func() (*Corpus, error), also implements Loader. Per-site tooling defaults (.sightmap/config.yaml) load separately via sightmap.LoadConfig(dir) SiteConfig — this is tooling configuration, not part of the spec.

Validate and lint from Go

The Validate and Lint functions run the same checks as sightmap validate and sightmap lint:

corpus, err := sightmap.Load(".sightmap")
if err != nil {
	log.Fatal(err)
}
for _, e := range sightmap.Validate(corpus) {
	fmt.Println("error:", e)
}
for _, w := range sightmap.Lint(corpus) {
	fmt.Println("warning:", w)
}

LintWithCounts(c *Corpus, counts map[string]int) []LintWarning adds per-component match counts to lint results. The CLI uses it for sightmap lint --snapshot and sightmap lint --all-snapshots.

Where component trees come from

Saved captures. Auto-organized captures under .sightmap/snapshots/{view}/ include a sibling .snap.tree.json file containing the raw ComponentNode tree. sightmap snapshot --tree-out FILE writes the tree to an explicit path. Unmarshal either form into *comps.ComponentNode, as in the example above.
Live pages. Call browser.Connect(addr, tabID) to attach to a running session’s tab, then pass a browser.Page to browser.ExtractComponents — or use the higher-level observe.Page, which connects, extracts, matches the corpus, and computes coverage in one call.
Custom extraction. Call extract.BuildTree with probe, accessibility, and DOM data. Native consumers can create SelectorPart values for non-DOM trees.

The conformance directory includes component-tree fixtures, flat sightmap definitions, and expected matches. Use them to compare another implementation with the Go matcher. See Conformance fixtures.

CLI overview: the commands built on these packages
Curator vs. consumer: where a library consumer fits
Schema reference: the YAML format

The spec

Reference

Use Sightmap as a Go Library

Design goals

Package map

Load a corpus and match a tree

The Corpus handle

Validate and lint from Go

Where component trees come from

​Design goals

​Package map

​Load a corpus and match a tree

​The Corpus handle

​Validate and lint from Go

​Where component trees come from

​Related

Design goals

Package map

Load a corpus and match a tree

The Corpus handle

Validate and lint from Go

Where component trees come from

Related