@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

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.

ts
function parseAriaSnapshot(snapshot: string): RoleNode[];

Uses: RoleNode.

textOf

The text a node shows: its name, else its own and its children's text.

ts
function textOf(node: RoleNode): string;

Uses: RoleNode.

walk

Every node, depth first, with its ancestors.

ts
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.

PropertyTypeDescription
rolestringIts ARIA role, such as button or navigation.
namestringThe accessible name.
attributesReadonly<Record<string, string>>Flags such as level=1 or checked.
propertiesReadonly<Record<string, string>>Properties such as url for links and placeholder for text boxes.
textstringText inside the node, such as a paragraph's.
childrenRoleNode[]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.

ts
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.

ts
function discoveryText(discovery: Discovery): string;

Uses: Discovery.

factsOf

What a page offers, read from its accessibility tree. Structure only: rows are never read.

ts
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".

ts
function matchAction(
  button: string,
  action: {
    id: string;
    label: string;
  },
  about?: readonly string[],
): number;

pathOf

The path of a URL, without origin, query or fragment.

ts
function pathOf(url: string): string;

templateOf

A path as a route template: /orders/ord_01H... becomes /orders/:id.

ts
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.

ts
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[];
  }[];
}
PropertyDescription
routesRoutes from the paths visited, with row keys turned into parameters.
regionsOne per route: its page as it is, to start every page as a region.
listsNavigation and toolbars that could become lists.
actionsButtons that look like the contract's actions, to send through useAction.
unmappedButtons no action matches.
menusButtons that open menus or panels, which discovery doesn't open: look inside for lists.

FactsOptions

What the page itself says, besides its accessibility tree.

PropertyTypeDefaultDescription
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.

PropertyTypeDescription
urlstringThe page's URL.
pathstringIts path, without origin, query or fragment.
titlestringThe 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.

ts
const ADAPTER_FORMAT = 'uitive.adapter';

ADAPTER_VERSION

The adapter format's version.

ts
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.

ts
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.

ts
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.

ts
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.

ts
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.

ts
type Adapter = z.infer<typeof adapterSchema>;

Uses: adapterSchema.

AdapterInput

An adapter as written, before defaults fill in.

ts
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.

ts
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.

ts
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.

ts
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.

ts
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.

ts
type Strategy = Anchor['match'][number];

Uses: Anchor.

Values

The interface as the client holds it now, by surface.

Uses: AnyPage.

PropertyTypeDescription
listsReadonly<Record<string, { visible: readonly string[]; overflow: readonly string[] }>>Each list's visible and overflow actions.
pagesReadonly<Record<string, { value: AnyPage; standard: AnyPage }>>Each page's value, and its standard.