@plurid/uitive-adapter
On this page
What pages Uitive doesn't own need: accessibility trees, discovery, and adapters as data. It runs anywhere, for the CLI and the extension alike.
Install: pnpm add @plurid/uitive-adapter, with zod ^4.2.0 as a peer. Guides: Coding agents.
- Accessibility trees:
parseAriaSnapshot,textOf,walk,RoleNode - Discovering pages:
discoverApp,discoveryText,factsOf,matchAction,pathOf,templateOf,Discovery,FactsOptions,PageFacts - Adapters:
ADAPTER_FORMAT,ADAPTER_VERSION,adapterSchema,checkAdapter,compileEffects,routeOf,Adapter,AdapterInput,Anchor,Checked,Connector,Effect,Strategy,Values
Accessibility trees
Source: aria.ts
parseAriaSnapshot
Reads an ARIA snapshot, the YAML-like text Playwright's ariaSnapshot() writes:
- role "name" [flag=value]: text, nested by two spaces, with /url: style properties.
function parseAriaSnapshot(snapshot: string): RoleNode[];Uses: RoleNode.
textOf
The text a node shows: its name, else its own and its children's text.
function textOf(node: RoleNode): string;Uses: RoleNode.
walk
Every node, depth first, with its ancestors.
function walk(
nodes: readonly RoleNode[],
ancestors?: readonly RoleNode[],
): Generator<{
node: RoleNode;
ancestors: readonly RoleNode[];
}>;Uses: RoleNode.
RoleNode
One node of an accessibility tree: what assistive technology, and Uitive, see of a page.
| Property | Type | Description |
|---|---|---|
role | string | Its ARIA role, such as button or navigation. |
name | string | The accessible name. |
attributes | Readonly<Record<string, string>> | Flags such as level=1 or checked. |
properties | Readonly<Record<string, string>> | Properties such as url for links and placeholder for text boxes. |
text | string | Text inside the node, such as a paragraph's. |
children | RoleNode[] | The nodes inside it, in order. |
Discovering pages
Source: discover.ts
discoverApp
What an application's pages suggest for its contract: routes from the paths visited, a region per route, lists from navigation and toolbars, and buttons matched to actions by name.
function discoverApp(
pages: readonly PageFacts[],
contract?: Pick<AnyContract, 'actions' | 'actionIds' | 'sourceIds'>,
): Discovery;Uses: AnyContract, Discovery, PageFacts.
discoveryText
A discovery as text, for people and coding agents: routes, lists, matches with their scores, and buttons left over.
function discoveryText(discovery: Discovery): string;Uses: Discovery.
factsOf
What a page offers, read from its accessibility tree. Structure only: rows are never read.
function factsOf(tree: readonly RoleNode[], url: string, options?: FactsOptions): PageFacts;Uses: FactsOptions, PageFacts, RoleNode.
matchAction
How well an action explains a button, from 0 to 1. Every word of the button must appear in the action's label or id, or in what the page is about; the fewer words beyond the button's, the better, and words the page supplies count half. "Create draft order" matches no action that says nothing of drafts; "Create" alone needs the page to say what; "Cancel" only matches "Cancel".
function matchAction(
button: string,
action: {
id: string;
label: string;
},
about?: readonly string[],
): number;pathOf
The path of a URL, without origin, query or fragment.
function pathOf(url: string): string;templateOf
A path as a route template: /orders/ord_01H... becomes /orders/:id.
function templateOf(path: string): string;Discovery
What an application's pages suggest for its contract: routes, a region per route, lists, buttons matched to actions, and what is left over.
interface Discovery {
routes: {
id: string;
path: string;
examples: string[];
title: string;
entity?: string;
key?: string;
}[];
regions: {
name: string;
label: string;
description: string;
route: string;
entity?: string;
}[];
lists: {
name: string;
label: string;
route: string | null;
items: string[];
}[];
actions: {
route: string;
button: string;
action: string;
score: number;
}[];
unmapped: {
route: string;
buttons: string[];
}[];
menus: {
route: string;
buttons: string[];
}[];
}| Property | Description |
|---|---|
routes | Routes from the paths visited, with row keys turned into parameters. |
regions | One per route: its page as it is, to start every page as a region. |
lists | Navigation and toolbars that could become lists. |
actions | Buttons that look like the contract's actions, to send through useAction. |
unmapped | Buttons no action matches. |
menus | Buttons that open menus or panels, which discovery doesn't open: look inside for lists. |
FactsOptions
What the page itself says, besides its accessibility tree.
| Property | Type | Default | Description |
|---|---|---|---|
menus? | readonly string[] | [] | Names of the controls that open a menu or a panel, read from the page (aria-haspopup and aria-expanded): an ARIA snapshot marks one only while it is open, as [expanded]. |
PageFacts
What one page offers, read from its accessibility tree: its title, landmarks, headings, buttons, links, tables, toolbars, navigation and menu triggers. Structure only, never rows.
| Property | Type | Description |
|---|---|---|
url | string | The page's URL. |
path | string | Its path, without origin, query or fragment. |
title | string | The page's main heading. |
landmarks | { role: string; name: string }[] | Its landmarks, such as the main region and named navigation. |
headings | { level: number; text: string }[] | Its headings, with their levels. |
buttons | { name: string; landmark: string; opens?: boolean }[] | Buttons outside navigation, tables, toolbars and dialogs; opens for menu triggers. |
links | { name: string; url: string; landmark: string }[] | Its links, with where they go and the landmark they sit in. |
tables | { name: string; columns: string[]; rowActions: string[] }[] | Its tables: their columns and the buttons repeated on their rows, never the rows' data. |
toolbars | { name: string; landmark: string; items: string[] }[] | Explicit toolbars, and runs of three or more buttons side by side. |
navigation | { name: string; items: { name: string; url?: string }[] }[] | Its navigation, with each item's name and where it goes. |
Adapters
Source: checks.ts, effects.ts, format.ts
ADAPTER_FORMAT
What an adapter says it is, in its format field.
const ADAPTER_FORMAT = 'uitive.adapter';ADAPTER_VERSION
The adapter format's version.
const ADAPTER_VERSION = 2;adapterSchema
An adapter's shape: a JSON contract plus anchors, routes, lists, regions, pages and official API connectors for one site.
const adapterSchema: ZodObject;checkAdapter
Checks an adapter before it touches a page: its shape, its contract, and that every anchor, route, list, region, page and connector it names resolves. Required anchors, such as notices, must sit outside regions a redesign may replace.
function checkAdapter(input: unknown): Checked;Uses: Checked.
compileEffects
The effects that make a page show the person's interface. Lists hide what moved to overflow and order what stays; a redesigned page on the current route overlays its region. Required anchors are never hidden, and a region holding one is never replaced, only augmented.
function compileEffects(
adapter: Pick<Adapter, 'anchors' | 'lists' | 'regions' | 'pages'>,
values: Values,
route: string | null,
): Effect[];Uses: Adapter, Effect, Values.
routeOf
The route a path is, and its params: the first of the adapter's routes that matches.
function routeOf(
adapter: Pick<Adapter, 'routes'>,
path: string,
):
| {
route: string;
params: Record<string, string>;
}
| undefined;Uses: Adapter.
Adapter
An adapter, checked: how Uitive applies a contract to a site it doesn't own.
type Adapter = z.infer<typeof adapterSchema>;Uses: adapterSchema.
AdapterInput
An adapter as written, before defaults fill in.
type AdapterInput = z.input<typeof adapterSchema>;Uses: adapterSchema.
Anchor
How an adapter finds one part of a page: where to look, and strategies tried in order until exactly one element matches.
type Anchor = Adapter['anchors'][string];Uses: Adapter.
Checked
What checking an adapter gives: the adapter and its contract, ready to apply, or every problem found.
type Checked =
| {
adapter: Adapter;
contract: AnyContract;
}
| {
problems: string[];
};Uses: Adapter, AnyContract.
Connector
An official API an adapter reads with the person's own key: its endpoints, how it sends the key, what keys it takes and its rate.
type Connector = Adapter['connectors'][string];Uses: Adapter.
Effect
What to do to a page Uitive doesn't own. Pure data: the DOM side only applies it.
type Effect =
| {
kind: 'hide';
anchor: string;
}
| {
kind: 'order';
container: string;
items: string[];
}
| {
kind: 'more';
container: string;
items: {
action: string;
anchor: string;
}[];
}
| {
kind: 'overlay';
surface: string;
region: string;
mode: 'replace' | 'augment';
page: AnyPage;
};Uses: AnyPage.
Strategy
One way of finding an element: by its link, test ID, role and name, text or CSS selector.
type Strategy = Anchor['match'][number];Uses: Anchor.
Values
The interface as the client holds it now, by surface.
Uses: AnyPage.
| Property | Type | Description |
|---|---|---|
lists | Readonly<Record<string, { visible: readonly string[]; overflow: readonly string[] }>> | Each list's visible and overflow actions. |
pages | Readonly<Record<string, { value: AnyPage; standard: AnyPage }>> | Each page's value, and its standard. |