Reference

API Reference

Complete reference for all SOM element types, region roles, attributes, actions, and semantic hints.

Region Roles

Regions are the top-level grouping construct in SOM. Every element belongs to exactly one region.

Role	Description	Typical Content
main	The primary content area of the page. Corresponds to the HTML main element or role="main".	Article body, product details, form content
navigation	Navigation links and menus. Detected from nav elements, role="navigation", or high link density areas.	Top nav, sidebar nav, breadcrumbs, pagination
aside	Supplementary content tangentially related to the main content.	Sidebar, related articles, advertising
header	Introductory content, typically containing logos, titles, and primary navigation.	Site header, page banner
footer	Footer content with secondary links, copyright, and legal information.	Site footer, article footer
search	Search functionality. Detected from role="search" or search form patterns.	Site search, filter controls
form	Interactive form areas that collect user input.	Login form, checkout, contact form
dialog	Modal or non-modal dialog content overlaying the page.	Modals, alerts, popups
section	Generic named sections that do not fit other roles.	Content sections with aria-label
generic	Fallback for content that cannot be classified into another role.	Uncategorized content blocks

Element Types

Each element type below includes its description, allowed attributes, supported actions, and a JSON example.

link

click

Represents hyperlinks and anchor elements that navigate to other pages or resources.

Attributes

href(string)Target URL of the link

visited(boolean)Whether the link has been visited

Example

{
  "id": "e_1a5c8b3e7f2d",
  "role": "link",
  "text": "Documentation",
  "attrs": { "href": "/docs" },
  "actions": ["click"]
}

button

click

Represents clickable controls including submit buttons, toggle buttons, and action triggers.

Attributes

type(string)Button type: "button", "submit", or "reset"

form_action(string)Form submission URL if applicable

Example

{
  "id": "e_4b2e9f1c8a3d",
  "role": "button",
  "text": "Submit Order",
  "attrs": { "type": "submit" },
  "actions": ["click"],
  "hints": { "primary": true }
}

text_input

typeclear

Single-line text entry fields including email, password, search, URL, and tel inputs.

Attributes

value(string)Current field value

placeholder(string)Placeholder text when empty

input_type(string)Input type: "text", "email", "password", "search", "url", "tel"

Example

{
  "id": "e_7c3a1d5e9b2f",
  "role": "text_input",
  "text": "Email address",
  "attrs": { "placeholder": "you@example.com", "input_type": "email" },
  "actions": ["type", "clear"],
  "aria": { "required": true }
}

textarea

typeclear

Multi-line text entry fields for longer content input.

Attributes

value(string)Current field value

placeholder(string)Placeholder text when empty

rows(integer)Visible number of text rows

Example

{
  "id": "e_2d8f4a6c1e3b",
  "role": "textarea",
  "text": "Message",
  "attrs": { "placeholder": "Write your message...", "rows": 5 },
  "actions": ["type", "clear"]
}

select

Dropdown menus and listboxes that allow selection from predefined options.

Attributes

value(string)Currently selected value

options(array)List of available options with value and label

multiple(boolean)Whether multiple selections are allowed

Example

{
  "id": "e_5f1b3d7e9a2c",
  "role": "select",
  "text": "Country",
  "attrs": {
    "value": "us",
    "options": [
      { "value": "us", "label": "United States" },
      { "value": "uk", "label": "United Kingdom" }
    ]
  },
  "actions": ["select"]
}

checkbox

toggle

Toggle checkboxes for binary on/off selections.

Attributes

checked(boolean)Whether the checkbox is currently checked

value(string)Form submission value

Example

{
  "id": "e_8a4c2e6f1d3b",
  "role": "checkbox",
  "text": "I agree to the terms",
  "attrs": { "checked": false },
  "actions": ["toggle"]
}

radio

click

Radio button options within a mutually exclusive group.

Attributes

checked(boolean)Whether this option is selected

value(string)Option value

name(string)Radio group name for mutual exclusion

Example

{
  "id": "e_3b7d1f5a9c2e",
  "role": "radio",
  "text": "Express shipping",
  "attrs": { "checked": true, "value": "express", "name": "shipping" },
  "actions": ["click"]
}

heading

Section headings at levels 1 through 6, providing document outline structure.

Attributes

level(integer)Heading level from 1 (highest) to 6 (lowest)

Example

{
  "id": "e_6e2a8c4f1b3d",
  "role": "heading",
  "text": "Getting Started",
  "attrs": { "level": 2 }
}

image

Visual content including photographs, illustrations, diagrams, and icons.

Attributes

src(string)Image source URL

alt(string)Alternative text description

width(integer)Display width in pixels

height(integer)Display height in pixels

Example

{
  "id": "e_9c1d3f5b7a2e",
  "role": "image",
  "text": "Architecture diagram",
  "attrs": { "src": "/img/arch.png", "alt": "System architecture", "width": 800, "height": 400 }
}

list

Ordered and unordered lists with nested item content.

Attributes

items(array)Array of list item text strings

ordered(boolean)Whether the list is ordered (numbered)

Example

{
  "id": "e_4d6f8a2c1e3b",
  "role": "list",
  "text": "Features",
  "attrs": { "items": ["Fast", "Typed", "Compact"], "ordered": false }
}

table

Tabular data with headers and rows.

Attributes

headers(array)Column header labels

rows(array)Array of row arrays containing cell values

Example

{
  "id": "e_1b3d5f7a9c2e",
  "role": "table",
  "text": "Pricing",
  "attrs": {
    "headers": ["Plan", "Price", "Requests"],
    "rows": [["Free", "$0", "1,000/mo"], ["Pro", "$29", "100,000/mo"]]
  }
}

paragraph

Block-level text content. The most common element type for body text.

Example

{
  "id": "e_2e4f6a8c1d3b",
  "role": "paragraph",
  "text": "SOM provides a compact, typed representation of web pages."
}

section

Content grouping containers that provide additional structural context.

Example

{
  "id": "e_5a7c9e1b3d2f",
  "role": "section",
  "text": "Related Articles"
}

separator

Visual dividers that separate content sections, typically rendered from hr elements.

Example

{
  "id": "e_8b1d3f5a7c2e",
  "role": "separator",
  "text": ""
}

details

toggle

Collapsible disclosure widgets that can be toggled open and closed.

Attributes

open(boolean)Whether the details element is currently expanded

summary(string)The visible summary text shown when collapsed

Example

{
  "id": "e_3c5e7a9b1d2f",
  "role": "details",
  "text": "Full error details...",
  "attrs": { "open": false, "summary": "Show error details" },
  "actions": ["toggle"]
}

Actions

Actions describe what an agent can do with an element. Each action maps to a specific interaction pattern.

click

Triggers the element. For links, navigates to the href. For buttons, submits forms or triggers handlers. For radio buttons, selects the option.

type

Enters text into the element. Valid for text_input and textarea. Replaces any existing value.

select

Selects an option from a dropdown. Valid for select elements. The agent specifies the option value to select.

toggle

Toggles the element state. For checkboxes, switches checked/unchecked. For details, opens/closes.

clear

Clears the current value of the element. Valid for text_input and textarea.

Hints

Hints are CSS-inferred semantic signals that provide additional context about an element's visual presentation and likely purpose.

Hint	Type	Description
visually_hidden	boolean	Element is visually hidden but present in the accessibility tree (screen-reader only content)
primary	boolean	Element appears to be a primary/prominent action based on visual styling (size, color, position)
destructive	boolean	Element appears to be a destructive action based on red/warning styling
disabled_visual	boolean	Element appears visually disabled (grayed out, reduced opacity) even without aria-disabled
truncated	boolean	Text content appears to be truncated with ellipsis or overflow hidden

ARIA States

ARIA states capture dynamic widget state from ARIA attributes. These are included in the element's aria field.

State	Type	Source	Description
expanded	boolean	aria-expanded	Whether a collapsible section is currently expanded
checked	boolean \| "mixed"	aria-checked	Check state of checkboxes and radio buttons
selected	boolean	aria-selected	Whether an option or tab is currently selected
disabled	boolean	aria-disabled	Whether the element is disabled for interaction
pressed	boolean \| "mixed"	aria-pressed	Toggle button pressed state
invalid	boolean	aria-invalid	Whether the element has a validation error
required	boolean	aria-required	Whether the element is required for form submission
readonly	boolean	aria-readonly	Whether the element value is read-only