Danila Poyarkov f2ef9c976d

* Add XPath query for node selection

- packages/core/src/xpath.ts: XPath engine using fontoxpath with custom
  DOM facade over SceneGraph nodes
- RPC command: 'query' with selector, page, limit params
- CLI command: 'open-pencil query <file> <xpath>' with --json, --page, --limit
- AI/MCP tool: 'query_nodes' with XPath examples in description
- Queryable attributes: name, width, height, x, y, visible, opacity,
  cornerRadius, fontSize, fontFamily, fontWeight, layoutMode, itemSpacing,
  padding*, strokeWeight, rotation, locked, blendMode, text, lineHeight,
  letterSpacing

* Add tests and docs for XPath query

- 9 unit tests for queryByXPath/matchByXPath core functions
- 6 tool tests for query_nodes AI/MCP tool
- README: query examples in CLI section
- VitePress docs: patterns, queryable attributes, example output
- CHANGELOG: feature entry

* Lazy-load fontoxpath to avoid bundling in desktop app

- Dynamic import() instead of static import for fontoxpath
- queryByXPath/matchByXPath now async (they were sync before)
- RpcCommand.execute allows R | Promise<R> for async commands
- Fix 2 lint errors (unnecessary optional chain, always-truthy)
- Update all tests and CLI to await results

2026-03-09 15:32:27 +03:00

3.7 KiB

Raw Blame History

title	description
Inspecting Files	Browse node trees, search by name or type, and dig into properties from the terminal.

Inspecting Files

The CLI lets you explore .fig files without opening the editor. Every command also works on the live app — just omit the file argument.

::: tip Install

bun add -g @open-pencil/cli
# or
brew install open-pencil/tap/open-pencil

:::

Document Info

Get a quick overview — page count, total nodes, fonts used, file size:

open-pencil info design.fig

Node Tree

Print the full node hierarchy:

open-pencil tree design.fig

[0] [page] "Getting started" (0:46566)
  [0] [section] "" (0:46567)
    [0] [frame] "Body" (0:46568)
      [0] [frame] "Introduction" (0:46569)
        [0] [frame] "Introduction Card" (0:46570)
          [0] [frame] "Guidance" (0:46571)

Find Nodes

Search by type:

open-pencil find design.fig --type TEXT

Search by name:

open-pencil find design.fig --name "Button"

Both flags can be combined to narrow results further.

Query with XPath

Use XPath selectors to find nodes by type, attributes, and tree structure:

open-pencil query design.fig "//FRAME"

Useful patterns

By type:

open-pencil query design.fig "//TEXT"                    # All text nodes
open-pencil query design.fig "//COMPONENT"               # All components
open-pencil query design.fig "//INSTANCE"                # All instances

By attributes:

open-pencil query design.fig "//FRAME[@width < 300]"                # Frames under 300px wide
open-pencil query design.fig "//*[@cornerRadius > 0]"               # Rounded corners
open-pencil query design.fig "//*[@visible = false]"                # Hidden nodes
open-pencil query design.fig "//TEXT[@fontSize >= 24]"              # Large text
open-pencil query design.fig "//*[@opacity < 1]"                    # Semi-transparent nodes

By name and text content:

open-pencil query design.fig "//TEXT[contains(@name, 'Button')]"    # Name contains 'Button'
open-pencil query design.fig "//TEXT[contains(@text, 'Hello')]"     # Text content contains 'Hello'

By hierarchy:

open-pencil query design.fig "//SECTION//TEXT"            # Text inside sections
open-pencil query design.fig "//FRAME/TEXT"               # Direct text children of frames
open-pencil query design.fig "//COMPONENT_SET//INSTANCE"  # Instances inside component sets

Queryable attributes

name, width, height, x, y, visible, opacity, cornerRadius, fontSize, fontFamily, fontWeight, layoutMode, itemSpacing, paddingTop, paddingRight, paddingBottom, paddingLeft, strokeWeight, rotation, locked, blendMode, text, lineHeight, letterSpacing

Example output

  Found 5 nodes

[0] [frame] "Logo  92×32" (0:9)
[1] [frame] "logo-short-6  31×32" (0:10)
[2] [frame] "wrapper  128×73" (0:20)
[3] [frame] "pen-drawing  148×52" (0:21)
[4] [frame] "surprised-emoji  32×32" (0:26)

Node Details

Inspect all properties of a specific node by its ID:

open-pencil node design.fig --id 1:23

Pages

List all pages in the document:

open-pencil pages design.fig

Variables

List design variables and their collections:

open-pencil variables design.fig

Live App Mode

When the desktop app is running, omit the file argument — the CLI connects via RPC and operates on the live canvas:

open-pencil tree              # inspect the live document
open-pencil eval -c "..."     # query the editor

JSON Output

All commands support --json for machine-readable output — pipe into jq, feed to CI scripts, or process with other tools:

open-pencil tree design.fig --json | jq '.[] | .name'

3.7 KiB Raw Blame History Unescape Escape