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 sightmap and match packages give consumers the same types and matching logic as the CLI.
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`	The spec model in one import, with no dependency on any other package here: corpus loading (`Load`, the `Corpus` type and its definitions), `Validate`, `Lint`, `LoadConfig`, the component tree (`ComponentNode`, `Element`, `SelectorPart`, `Bounds`, `Walk`, `Collect`, `Filter`), match results (`ComponentMatch`, `Conflict`), and selector parsing and single-node matching (`ParseSightmapSelector`, `Matches`)
`match`	NFA multi-query matcher that applies component definitions in one tree traversal (`NewMatcher`, `Matcher.Match`, `Matcher.Conflicts`, `FindAllMatches`)
`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

sightmap.Load parses a .sightmap/ directory into a Corpus, which is plain data. To match against it, wrap it in a match.Matcher, which compiles the component definitions per page URL and caches them.

main.go

package main

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

	"github.com/sightmap/sightmap/go/match"
	"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 := &sightmap.ComponentNode{}
	if err := json.Unmarshal(data, root); err != nil {
		log.Fatal(err)
	}

	// Build a Matcher once per Corpus and apply it to the tree for this page URL.
	m := match.NewMatcher(corpus)
	matches := m.Match(root, "https://example.com/")

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

Match returns map[*sightmap.ComponentNode]*sightmap.ComponentMatch. Each match carries the component Name, Memory, resolved Tags (a union across matching ancestors), the node’s effective Privacy (nearest enclosing declaration), the component’s own Watch, and extracted Properties. A property read from a block or mask node is already withheld. The library selects the most specific view whose route matches the URL pathname, using declaration order only to break equal-specificity ties. Trailing slashes are normalized away before matching. If no view matches, global components still apply. Matcher is safe for concurrent use. Create one per Corpus and reuse it so the compiled-query cache is shared. Matcher.Conflicts(root, url) returns nodes claimed by more than one component definition; each sightmap.Conflict carries Names and the index-aligned Defs, since two definitions can share a name.

The Corpus

sightmap.Corpus holds the loaded definitions. Hold it for the life of a run; to pick up on-disk edits in a long-lived process, call Load again and swap it (and its Matcher). Its json.Marshal output is the wire sightmap export prints.

Method	Purpose
`ViewForURL(pageURL) *ViewDef`	The most specific matching view, or `nil`
`ViewByName(name) *ViewDef`	The view with this name, or `nil`
`TiedViews(pageURL) []string`	Views that tie on specificity for a URL
`ComponentsForURL(pageURL) []ComponentDef`	The merged global and view-scoped component list for a URL
`AllComponents() []ComponentDef`	Every component definition, flattened
`GlobalComponentNames() map[string]bool`	Names declared at global scope
`TagsForURL(pageURL) []string`	View tags unioned across every matching view
`RequestsForURL(url, method) []RequestDef`	Every request definition that matches
`RequestsForRecord(rec Request) []RequestMatch`	Matching requests for an observed request, with extracted properties
`MessagesForRecord(rec Message) []MessageMatch`	Matching messages for a console record, with stack properties
`TagsForRecord(rec Message) []string`	Message tags unioned across every matching entry
`SignalByName`, `ResolveSignal`, `ResolveSignalRef`, `TagsForSignal`	Look up a signal and the component or view its `ref` names
`EnvironmentByName(name) *EnvironmentDef`	An environment from the project-wide registry
`ResolveOrigin(environment, origin) (string, bool)`	An origin’s URL in an environment: its own map, then its backend’s, then the shared map
`Stats() Stats`	The counts `sightmap stats` prints

Package-level helpers include RequestEnvironments(view, request), which intersects a view-scoped request’s environments with its view’s, and SplitFieldPath, which splits a body path with \. and \\ escapes. Every property definition (ComponentPropertyDef, RequestPropertyDef, MessagePropertyDef, URLPropertyDef) carries one Extract value. 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(e.Severity, e.Code, e.Message)
}
for _, w := range sightmap.Lint(corpus) {
	fmt.Println("warning:", w)
}

Each ValidationError has a Code and a Severity (error or warning; empty means error). 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 *sightmap.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

​Design goals

​Package map

​Load a corpus and match a tree

​The Corpus

​Validate and lint from Go

​Where component trees come from

​Related

Design goals

Package map

Load a corpus and match a tree

The Corpus

Validate and lint from Go

Where component trees come from

Related