# @plurid/uitive-adapter

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](https://uitive.dev/docs/coding-agents).

- [Accessibility trees](https://uitive.dev/docs/api/adapter#accessibility-trees): [`parseAriaSnapshot`](https://uitive.dev/docs/api/adapter#parseariasnapshot), [`textOf`](https://uitive.dev/docs/api/adapter#textof), [`walk`](https://uitive.dev/docs/api/adapter#walk), [`RoleNode`](https://uitive.dev/docs/api/adapter#rolenode)
- [Discovering pages](https://uitive.dev/docs/api/adapter#discovering-pages): [`discoverApp`](https://uitive.dev/docs/api/adapter#discoverapp), [`discoveryText`](https://uitive.dev/docs/api/adapter#discoverytext), [`factsOf`](https://uitive.dev/docs/api/adapter#factsof), [`matchAction`](https://uitive.dev/docs/api/adapter#matchaction), [`pathOf`](https://uitive.dev/docs/api/adapter#pathof), [`templateOf`](https://uitive.dev/docs/api/adapter#templateof), [`Discovery`](https://uitive.dev/docs/api/adapter#discovery), [`FactsOptions`](https://uitive.dev/docs/api/adapter#factsoptions), [`PageFacts`](https://uitive.dev/docs/api/adapter#pagefacts)
- [Adapters](https://uitive.dev/docs/api/adapter#adapters): [`ADAPTER_FORMAT`](https://uitive.dev/docs/api/adapter#adapter_format), [`ADAPTER_VERSION`](https://uitive.dev/docs/api/adapter#adapter_version), [`adapterSchema`](https://uitive.dev/docs/api/adapter#adapterschema), [`checkAdapter`](https://uitive.dev/docs/api/adapter#checkadapter), [`compileEffects`](https://uitive.dev/docs/api/adapter#compileeffects), [`routeOf`](https://uitive.dev/docs/api/adapter#routeof), [`Adapter`](https://uitive.dev/docs/api/adapter#adapter), [`AdapterInput`](https://uitive.dev/docs/api/adapter#adapterinput), [`Anchor`](https://uitive.dev/docs/api/adapter#anchor), [`Checked`](https://uitive.dev/docs/api/adapter#checked), [`Connector`](https://uitive.dev/docs/api/adapter#connector), [`Effect`](https://uitive.dev/docs/api/adapter#effect), [`Strategy`](https://uitive.dev/docs/api/adapter#strategy), [`Values`](https://uitive.dev/docs/api/adapter#values)

## Accessibility trees

Source: [`aria.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/adapter/src/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`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#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`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/adapter/src/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`](https://uitive.dev/docs/api/core#anycontract), [`Discovery`](https://uitive.dev/docs/api/adapter#discovery), [`PageFacts`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#factsoptions), [`PageFacts`](https://uitive.dev/docs/api/adapter#pagefacts), [`RoleNode`](https://uitive.dev/docs/api/adapter#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[];
  }[];
}
```

| 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`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/adapter/src/checks.ts), [`effects.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/adapter/src/effects.ts), [`format.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/adapter/src/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`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#adapter), [`Effect`](https://uitive.dev/docs/api/adapter#effect), [`Values`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#adapterschema).

### AdapterInput

An adapter as written, before defaults fill in.

```ts
type AdapterInput = z.input<typeof adapterSchema>;
```

Uses: [`adapterSchema`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/adapter#adapter), [`AnyContract`](https://uitive.dev/docs/api/core#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`](https://uitive.dev/docs/api/adapter#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`](https://uitive.dev/docs/api/core#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`](https://uitive.dev/docs/api/adapter#anchor).

### Values

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

Uses: [`AnyPage`](https://uitive.dev/docs/api/core#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. |
